{"id":13508886,"url":"https://github.com/elixir-ecto/postgrex","last_synced_at":"2025-12-12T00:12:56.709Z","repository":{"id":10498966,"uuid":"12682522","full_name":"elixir-ecto/postgrex","owner":"elixir-ecto","description":"PostgreSQL driver for Elixir","archived":false,"fork":false,"pushed_at":"2025-04-23T07:46:40.000Z","size":2085,"stargazers_count":1161,"open_issues_count":4,"forks_count":281,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-05-11T05:49:17.232Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://hexdocs.pm/postgrex/","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"hostnet/entity-plugin-lib","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elixir-ecto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-09-08T15:10:47.000Z","updated_at":"2025-05-08T20:45:37.000Z","dependencies_parsed_at":"2023-02-14T15:16:19.508Z","dependency_job_id":"f52a4170-3db0-438c-8e18-8f8285918c52","html_url":"https://github.com/elixir-ecto/postgrex","commit_stats":{"total_commits":1054,"total_committers":138,"mean_commits":7.63768115942029,"dds":0.7400379506641366,"last_synced_commit":"9eee621e3fc6f7e5759c0de167ee7542df799f50"},"previous_names":["ericmj/postgrex"],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Fpostgrex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Fpostgrex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Fpostgrex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Fpostgrex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elixir-ecto","download_url":"https://codeload.github.com/elixir-ecto/postgrex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253523732,"owners_count":21921818,"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","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":[],"created_at":"2024-08-01T02:00:59.982Z","updated_at":"2025-12-12T00:12:56.677Z","avatar_url":"https://github.com/elixir-ecto.png","language":"Elixir","funding_links":[],"categories":["ORM and Datamapping","Elixir","Compiled list","Language bindings"],"sub_categories":["plv8:"],"readme":"# Postgrex\n\n[![Build Status](https://github.com/elixir-ecto/postgrex/workflows/CI/badge.svg)](https://github.com/elixir-ecto/postgrex/actions)\n\nPostgreSQL driver for Elixir.\n\nDocumentation: http://hexdocs.pm/postgrex/\n\n## Examples\n\n```iex\niex\u003e {:ok, pid} = Postgrex.start_link(hostname: \"localhost\", username: \"postgres\", password: \"postgres\", database: \"postgres\")\n{:ok, #PID\u003c0.69.0\u003e}\n\niex\u003e Postgrex.query!(pid, \"SELECT user_id, text FROM comments\", [])\n%Postgrex.Result{command: :select, empty?: false, columns: [\"user_id\", \"text\"], rows: [[3,\"hey\"],[4,\"there\"]], size: 2}}\n\niex\u003e Postgrex.query!(pid, \"INSERT INTO comments (user_id, text) VALUES (10, 'heya')\", [])\n%Postgrex.Result{command: :insert, columns: nil, rows: nil, num_rows: 1}\n```\n\n## Features\n\n  * Automatic decoding and encoding of Elixir values to and from PostgreSQL's binary format\n  * User defined extensions for encoding and decoding any PostgreSQL type\n  * Supports transactions, prepared queries and multiple pools via [DBConnection](https://github.com/elixir-ecto/db_connection)\n  * Supports PostgreSQL 8.4, 9.0-9.6, and later (hstore is not supported on 8.4)\n\n## Data representation\n\n| PostgreSQL         | Elixir                                                                                                                                      |\n|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------|\n| `NULL`             | `nil`                                                                                                                                       |\n| `bool`             | `true`, `false`                                                                                                                             |\n| `char`             | `\"é\"`                                                                                                                                       |\n| `int`              | `42`                                                                                                                                        |\n| `float`            | `42.0`                                                                                                                                      |\n| `text`             | `\"eric\"`                                                                                                                                    |\n| `bytea`            | `\u003c\u003c42\u003e\u003e`                                                                                                                                    |\n| `numeric`          | `#Decimal\u003c42.0\u003e` (1)                                                                                                                        |\n| `date`             | `%Date{year: 2013, month: 10, day: 12}`                                                                                                     |\n| `time(tz)`         | `%Time{hour: 0, minute: 37, second: 14}` (2)                                                                                                |\n| `timestamp`        | `%NaiveDateTime{year: 2013, month: 10, day: 12, hour: 0, minute: 37, second: 14}`                                                           |\n| `timestamptz`      | `%DateTime{year: 2013, month: 10, day: 12, hour: 0, minute: 37, second: 14, time_zone: \"Etc/UTC\"}` (2)                                      |\n| `interval`         | `%Postgrex.Interval{months: 14, days: 40, secs: 10920, microsecs: 315}`                                                                     |\n| `interval`         | `%Duration{month: 2, day: 5, second: 0, microsecond: {315, 6}}` (3)                                   |\n| `array`            | `[1, 2, 3]`                                                                                                                                 |\n| `composite type`   | `{42, \"title\", \"content\"}`                                                                                                                  |\n| `range`            | `%Postgrex.Range{lower: 1, upper: 5}`                                                                                                       |\n| `multirange`       | `%Postgrex.Multirange{ranges: [%Postgrex.Range{lower: 1, upper: 5}, %Postgrex.Range{lower: 20, upper: 23}]}`                                |\n| `uuid`             | `\u003c\u003c160,238,188,153,156,11,78,248,187,109,107,185,189,56,10,17\u003e\u003e`                                                                            |\n| `hstore`           | `%{\"foo\" =\u003e \"bar\"}`                                                                                                                         |\n| `oid types`        | `42`                                                                                                                                        |\n| `enum`             | `\"ok\"` (4)                                                                                                                                  |\n| `bit`              | `\u003c\u003c 1::1, 0::1 \u003e\u003e`                                                                                                                          |\n| `varbit`           | `\u003c\u003c 1::1, 0::1 \u003e\u003e`                                                                                                                          |\n| `tsvector`         | `[%Postgrex.Lexeme{positions: [{1, :A}], word: \"a\"}]`                                                                                       |\n\n(1) [Decimal](http://github.com/ericmj/decimal)\n\n(2) Timezones will always be normalized to UTC or assumed to be UTC when no information is available, either by PostgreSQL or Postgrex\n\n(3) `%Duration{}` may only be used with Elixir 1.17+. Intervals will only be decoded into a `%Duration{}` struct if the option `interval_decode_type: Duration` is passed to `Postgrex.Types.define/3`.\n\n(4) Enumerated types (enum) are custom named database types with strings as values.\n\n(5) Anonymous composite types are decoded (read) as tuples but they cannot be encoded (written) to the database\n\nPostgrex does not automatically cast between types. For example, you can't pass a string where a date is expected. To add type casting, support new types, or change how any of the types above are encoded/decoded, you can use extensions.\n\n## JSON support\n\nPostgrex comes with JSON support out of the box via the [Jason](https://github.com/michalmuskala/jason) library. To use it, add :jason to your dependencies:\n\n```elixir\n{:jason, \"~\u003e 1.0\"}\n```\n\nYou can customize it to use another library via the `:json_library` configuration:\n\n```elixir\nconfig :postgrex, :json_library, SomeOtherLib\n```\n\nOnce you change the value, you have to recompile Postgrex, which can be done by cleaning its current build:\n\n```sh\nmix deps.clean postgrex --build\n```\n\n## Extensions\n\nExtensions are used to extend Postgrex' built-in type encoding/decoding.\n\nThe [extensions](https://github.com/elixir-ecto/postgrex/blob/master/lib/postgrex/extensions/) directory in this project provides implementation for many Postgres' built-in data types. It is also a great example of how to implement your own extensions. For example, you can look at the [`Date`](https://github.com/elixir-ecto/postgrex/blob/master/lib/postgrex/extensions/date.ex) extension as a starting point.\n\nOnce you defined your extensions, you should build custom type modules, passing all of your extensions as arguments:\n\n```elixir\nPostgrex.Types.define(MyApp.PostgrexTypes, [MyApp.Postgis.Extensions], [])\n```\n\n`Postgrex.Types.define/3` must be called on its own file, outside of any module and function, as it only needs to be defined once during compilation.\n\nOnce a type module is defined, you must specify it on `start_link`:\n\n```elixir\nPostgrex.start_link(types: MyApp.PostgrexTypes)\n```\n\n## OID type encoding\n\nPostgreSQL's wire protocol supports encoding types either as text or as binary. Unlike most client libraries Postgrex uses the binary protocol, not the text protocol. This allows for efficient encoding of types (e.g. 4-byte integers are encoded as 4 bytes, not as a string of digits) and automatic support for arrays and composite types.\n\nUnfortunately the PostgreSQL binary protocol transports [OID types](http://www.postgresql.org/docs/current/static/datatype-oid.html#DATATYPE-OID-TABLE) as integers while the text protocol transports them as string of their name, if one exists, and otherwise as integer.\n\nThis means you either need to supply oid types as integers or perform an explicit cast (which would be automatic when using the text protocol) in the query.\n\n```elixir\n# Fails since $1 is regclass not text.\nquery(\"select nextval($1)\", [\"some_sequence\"])\n\n# Perform an explicit cast, this would happen automatically when using a\n# client library that uses the text protocol.\nquery(\"select nextval($1::text::regclass)\", [\"some_sequence\"])\n\n# Determine the oid once and store it for later usage. This is the most\n# efficient way, since PostgreSQL only has to perform the lookup once. Client\n# libraries using the text protocol do not support this.\n%{rows: [{sequence_oid}]} = query(\"select $1::text::regclass\", [\"some_sequence\"])\nquery(\"select nextval($1)\", [sequence_oid])\n```\n\n## PgBouncer\n\nWhen using PgBouncer with transaction or statement pooling named prepared\nqueries can not be used because the bouncer may route requests from the same\npostgrex connection to different PostgreSQL backend processes and discards named\nqueries after the transactions closes. To force unnamed prepared queries:\n\n```elixir\nPostgrex.start_link(prepare: :unnamed)\n```\n\n## Contributing\n\nTo contribute you need to compile Postgrex from source and test it:\n\n```\n$ git clone https://github.com/elixir-ecto/postgrex.git\n$ cd postgrex\n$ mix test\n```\n\nThe tests requires some modifications to your [hba file](http://www.postgresql.org/docs/9.3/static/auth-pg-hba-conf.html). The path to it can be found by running `$ psql -U postgres -c \"SHOW hba_file\"` in your shell. Put the following above all other configurations (so that they override):\n\n```\nlocal   all             all                     trust\nhost    all             postgrex_md5_pw         127.0.0.1/32    md5\nhost    all             postgrex_cleartext_pw   127.0.0.1/32    password\nhost    all             postgrex_scram_pw       127.0.0.1/32    scram-sha-256\n```\n\nThe server needs to be restarted for the changes to take effect. Additionally you need to setup a PostgreSQL user with the same username as the local user and give it trust or ident in your hba file. Or you can export $PGUSER and $PGPASSWORD before running tests.\n\n### Testing hstore on 9.0\n\nPostgreSQL versions 9.0 does not have the `CREATE EXTENSION` commands. This means we have to locate the postgres installation and run the `hstore.sql` in `contrib` to install `hstore`. Below is an example command to test 9.0 on OS X with homebrew installed postgres:\n\n```\n$ PGVERSION=9.0 PGPATH=/usr/local/share/postgresql9/ mix test\n```\n\n## License\n\nCopyright 2013 Eric Meadows-Jönsson\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-ecto%2Fpostgrex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felixir-ecto%2Fpostgrex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-ecto%2Fpostgrex/lists"}