Postgrex: binary protocol, no implicit casts, and a type table you can extend

What the driver actually is: a protocol layer under a connection pool

Postgrex is described in one line as the PostgreSQL driver for Elixir, with documentation hosted on hexdocs.pm. The feature list is four bullets, and the third one is the architecturally important one. The driver supports transactions, prepared queries and multiple pools via DBConnection, which is a separate library. So the division of labour is that Postgrex handles the wire protocol, the encoding and decoding of values, and the type extensions, while DBConnection handles the process model, the pool of connections and the checkout and return cycle. You start a connection with Postgrex.start_link and pass its pid to each query, which is the shape a supervisor and a supervision tree expect.

A first query: start a connection, then use the bang variant

The example in the README is a short IEx session. You call Postgrex.start_link with a hostname, username, password and database, get an ok tuple containing a pid, and then call Postgrex.query! with a SQL string and a parameter list. The result of a select is a Postgrex.Result struct with the command, an empty? flag, the columns, the rows and the size. An insert returns a result with the command, nil columns, nil rows and a num_rows of 1. The bang form raises on failure rather than returning an error tuple, and the non-bang form returns a tagged tuple, which is the distinction that decides how errors are handled in a supervision tree. The rows come back as plain Elixir lists, so a select returning three rows and two columns gives a list of two element lists, with no mapping step required.

iex> {:ok, pid} = Postgrex.start_link(hostname: "localhost", username: "postgres", password: "postgres", database: "postgres")
{:ok, #PID<0.69.0>}

iex> Postgrex.query!(pid, "SELECT user_id, text FROM comments", [])
%Postgrex.Result{command: :select, empty?: false, columns: ["user_id", "text"], rows: [[3,"hey"],[4,"there"]], size: 2}

Binary format in both directions, and extensions for everything else

The first feature bullet says the driver does automatic decoding and encoding of Elixir values to and from PostgreSQL's binary format. The second says user defined extensions can be provided for encoding and decoding any PostgreSQL type. Put together, those two lines describe the whole design. The common case costs nothing to set up, and the uncommon case is not a limitation because you can write the encoder and decoder yourself. The documentation is explicit about the scope of the built in support: Postgrex does not automatically cast between types, and the example given is that you cannot pass a string where a date is expected. To add type casting, to support new types, or to change how any type is encoded or decoded, you use extensions. So the driver moves the decision to the application, which is a defensible choice for a library used by a query builder, and a cost for anyone who expected the driver to paper over type mismatches.

The type table is the reference you will actually use

The README carries a full data representation table, and it is the part of the documentation worth printing. The basics are unsurprising: NULL becomes nil, bool becomes true or false, int becomes 42, float becomes 42.0, text becomes a string, and bytea becomes a binary such as <<42>>. The interesting rows are the ones where PostgreSQL has no direct Elixir equivalent. numeric becomes a Decimal struct, linked to the ericmj/decimal library, because binary floating point is not an acceptable representation for money. date, time, timestamp and timestamptz become Date, Time, NaiveDateTime and DateTime structs, with a note that timezones are always normalised to UTC or assumed to be UTC when no information is available. interval becomes a Postgrex.Interval struct with months, days, secs and microsecs. A composite type becomes a tuple, an array becomes a list, a range becomes a Postgrex.Range, a multirange becomes a Postgrex.Multirange, hstore becomes a map, uuid becomes a raw 16 byte binary, and a bit or varbit becomes a bitstring.

Two footnotes in the type table change behaviour in ways that surprise people

Two of the numbered footnotes carry real operational weight. The first is about the Duration form of an interval. The %Duration{} struct may only be used with Elixir 1.17 and above, and an interval will only be decoded into a %Duration{} struct if the option interval_decode_type: Duration is passed to Postgrex.Types.define/3. Even then, the decoded Duration keeps the coarse units PostgreSQL returns, so the time part is stored in :second and is not split into :hour and :minute, and one day two hours three minutes four seconds decodes to %Duration{day: 1, second: 7384}. A team that assumes it receives a decomposed duration will write arithmetic that is wrong by a factor of sixty. The second footnote concerns anonymous composite types, which are decoded as tuples but cannot be encoded back to the database, so a read works and a write of the same struct fails.

JSON is opt in, and the library behind it is configurable

Postgrex comes with JSON support out of the box via the Jason library, and to use it you add :jason to your dependencies with the version constraint ~> 1.0. That is a deliberate choice, because a driver that hard codes a JSON library forces every user onto that library, and JSON encoders differ enough in behaviour and performance that a project may already have a preference. If you want a different one, you set the :json_library configuration for the :postgrex application. The reason this is worth reading carefully is that the JSON library is not a direct dependency of the driver in the usual sense, it is a runtime expectation, so a project that forgets to add it gets a failure at the moment a json column is first touched rather than at compile time.

{:jason, "~> 1.0"}

config :postgrex, :json_library, SomeOtherLib

Version support, extensions and where the code lives

The driver supports PostgreSQL 8.4, 9.0 through 9.6 and later, with the caveat that hstore is not supported on 8.4. That range is long, and the hstore exception on the oldest version is the kind of detail that only appears in a compatibility table after someone has already hit it. The repository layout is small and conventional for an Elixir library, with lib/ holding the source, test/ the test suite, mix.exs and mix.lock the build definition, a .formatter.exs for the Elixir formatter, a CHANGELOG.md and the .github/ directory for CI. The README shows a CI badge, and the documentation lives on hexdocs.pm/postgrex rather than in the repository. The listed release tags are v0.5.5 on 2014-08-20, v0.6.0 on 2014-09-07 and v0.7.0 on 2015-01-20, and the last push to the repository was on 2026-10-08, so the tag list and the head of the branch are far apart in time. The licence field in the repository metadata is listed as unknown rather than a named licence, so anyone with a compliance requirement should read the terms from the published package rather than from the repository listing.

Editorial conclusion

Postgrex suits an Elixir service that wants the full PostgreSQL type system available to the application, including intervals, ranges, multiranges and tsvector, and that is willing to write an extension for anything the driver does not cover. It is the wrong choice if you want the driver to coerce a string into a date for you, because the documentation states Postgrex does not automatically cast between types, and a poor fit if you need JSON support without adding a JSON library, since the Jason dependency is opt in through the :json_library configuration. Before adopting it, read the data representation table rather than assuming, because the mapping for intervals changed with Elixir 1.17 and the %Duration{} form only decodes when the interval_decode_type option is passed, and check the licence status of the repository, which the metadata lists as unknown rather than a named licence.

Frequently asked questions

Official sources

1. elixir-ecto/postgrex on GitHub
2. Issues
3. Project website
4. README
5. Releases