{"id":16716957,"url":"https://github.com/tmcgilchrist/postgresql-transactional","last_synced_at":"2025-10-14T18:35:41.160Z","repository":{"id":38938243,"uuid":"46592898","full_name":"tmcgilchrist/postgresql-transactional","owner":"tmcgilchrist","description":"Transactional monadic actions on top of PostgreSQL.","archived":false,"fork":false,"pushed_at":"2022-06-02T00:42:30.000Z","size":38,"stargazers_count":59,"open_issues_count":4,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-10-14T18:35:39.051Z","etag":null,"topics":["haskell","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmcgilchrist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-20T23:42:09.000Z","updated_at":"2025-03-26T14:42:24.000Z","dependencies_parsed_at":"2022-09-18T18:26:41.471Z","dependency_job_id":null,"html_url":"https://github.com/tmcgilchrist/postgresql-transactional","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tmcgilchrist/postgresql-transactional","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmcgilchrist%2Fpostgresql-transactional","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmcgilchrist%2Fpostgresql-transactional/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmcgilchrist%2Fpostgresql-transactional/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmcgilchrist%2Fpostgresql-transactional/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmcgilchrist","download_url":"https://codeload.github.com/tmcgilchrist/postgresql-transactional/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmcgilchrist%2Fpostgresql-transactional/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020352,"owners_count":26086866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["haskell","postgresql"],"created_at":"2024-10-12T21:29:01.851Z","updated_at":"2025-10-14T18:35:41.144Z","avatar_url":"https://github.com/tmcgilchrist.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postgresql-transactional\n\n## Summary\n\n`postgresql-transactional` is a simple monadic wrapper around the SQL\nprimitives introduced by the [postgresql-simple][psqls] package. It provides\nsimple and predictable semantics for database operations, enforces awareness of\nPostgres's transactional nature at API boundaries, and obviates the need for\ntransaction boilerplate in SQL queries.\n\n## Details\n\nThough the primitives provided by the [postgresql-simple][psqls] package are\nfast and powerful, their interface is (by design) very basic: specifically, all\nquery functions take a shared `Connection` parameter and operate in the `IO`\nmonad. \n\n```haskell\nquery :: FromRow r =\u003e Connection -\u003e Query -\u003e IO [r]\nexecute :: ToRow q =\u003e Connection -\u003e Query -\u003e q -\u003e IO Int64\n```\n\nBy virtue of the fact that (usually) all queries in a given scope are routed\nthrough a single `Connection`, we can abstract away the shared `Connection`\nparameter by wrapping a `ReaderT Connection` in a monad transformer:\n\n```haskell\nnewtype PGTransactionT m a =\n    PGTransactionT (ReaderT Postgres.Connection m a)\n        deriving (Functor, Applicative, Monad, MonadTrans, MonadIO,\n                  MonadReader Postgres.Connection)\n\ntype PGTransaction a = PGTransactionT IO a\n```\n\nIn the common case, the `m` parameter will simply be `IO`. The library provides\nthe type alias `type PGTransaction a = PGTransactionT IO a` to simplify type\nsignatures in these cases.\n\nWe can then reimplement our query functions in a more natural fashion:\n\n```haskell\nquery :: (FromRow r, MonadIO m) =\u003e Query -\u003e PGTransactionT m [a]\nexecute :: (ToRow q, MonadIO m) =\u003e Query -\u003e q -\u003e PGTransactionT m Int64\n```\n\nAnd we can then use the [postgresql-simple][psqls] `withTransaction` function\nto provide `runPGTransaction`, which executes a given `PGTransactionT` block\nwith rollback semantics:\n\n```haskell\nrunPGTransaction :: MonadBaseControl IO m =\u003e PGTransactionT m a -\u003e Postgres.Connection -\u003e m a\n```\n\nUse of the `MonadBaseControl IO m` constraint leaves open the option of\nembedding additional effects with the `m` parameter, such as logging, state, or\nerror-handling.\n\nWe also provide a `PGTagged` monad transformer that is equivalent to `PGTransaction`, but includes \na phantom type in each relevant type signature that indicates whether said function has read-only \nor write-enabled effects. This can be useful when dispatching read-only queries to Postgres replicas.\n\n##  Helium Documentation and Community Support \n\n\n* **Docs** Complete documenation for all parts of Helium can be found at [docs.helium.com](https://docs/helium.com). \n\n* **chat.helium.com** - If you have questions or ideas about how to use this code - or any part of Helium - head over the [chat.helium.com](https://chat.helium.com). We're standing by to help. \n\n\n## About\n\n`postgresql-transactional` was extracted from a production Haskell project at\n[Helium][helium]. It is open-source software \u0026copy; Helium Systems, Inc., and\nreleased to the public under the terms of the MIT license.\n\n[psqls]: https://github.com/lpsmith/postgresql-simple\n[helium]: https://www.helium.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmcgilchrist%2Fpostgresql-transactional","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmcgilchrist%2Fpostgresql-transactional","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmcgilchrist%2Fpostgresql-transactional/lists"}