PostgrexTextExt

Text extensions for the Postgrex driver.

Documentation: https://hexdocs.pm/postgrex_text_ext

Installation

Add postgrex_text_ext to your list of dependencies in mix.exs:

def deps do
  [
    {:postgrex_text_ext, "~> 0.1.0"}
  ]
end

About

This library allows you to control which data types Postgrex will transmit using the text protocol. It works for all available types in PostgreSQL, even if their binary protocol is not supported by Postgrex.

Some reasons you might want to do this:

• It's not easy to obtain the data's binary version. For example, to_tsvector expects an OID as its first argument. If using the binary protocol, this value will have to be sent as an integer. In general, this number can't be known without digging through system catalogs. On the other hand, the text protocol can send this value as a meaningful string. i.e. to_tsvector(1, 'some text') (binary) vs to_tsvector('english', 'some text') (text).

• You may be using a PostgreSQL extension that doesn't have a binary protocol. For instance, the ltree extension started out only having a text protocol.

• The data's text version is more readily available to you. For instance, if using Postgrex directly instead of Ecto, it may be easier for you to work with a UUID's text representation.

Caution

Postgrex can transmit a data type using either the text or the binary protocol, but not both. Specifying a type in this library will make it so that it is always transmitted using the text protocol in all queries. This may cause unexpected results if you are not careful.

Usage

Your application configuration is used to specify which data types should be transmitted using the text protocol:

  config :postgrex_text_ext,
    type_names: ["regconfig", "ltree"],
    type_outputs: ["range_out"]

There are 2 levels of granularity: type name and type output. These correspond to the typname and typoutput columns in the pg_type system catalog.

Type name is the most granular level and is unique for each data type. Type output is less granular and groups data types by the conversion function used by PostgreSQL.

For example, an array of booleans has type name _bool and an array of UUIDs has type name _uuid. However, they both have type output array_out. Use type output if you'd like an entire group of data types to use the text protocol. Otherwise, list the type names individually.

A list of type names and outputs is provided here. You may also use the pg_type system catalog: SELECT typname, typoutput FROM pg_type;.

Finally, you must define a custom type module, as required by Postgrex, with extension PostgrexTextExt:

Postgrex.Types.define(MyApp.PostgrexTypes, [PostgrexTextExt], [])

Examples

Please read through the short test suite.

Ecto

Schemas can use the text protocol by simply defining a field's type as :string. However, this won't be enough to catch invalid input during casting.

For instance, you won't be able to tell if a text array is missing a closing bracket: {1, 2, 3. In this case, you won't find out until you receive an error from PostgreSQL.

For more intelligent validation, a custom Ecto Type can be created.

License

Copyright (c) 2022 Greg Rychlewski

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.