PgProtocol

An Elixir library to handle the encoding and decoding of Postgresql frontend/backend protocol messages.

# decode messages streaming from a Postgresql server over TCP
# and broadcast to GenStage consumers
defmodule PostgresConnectionProducer do
  use GenStage

  @impl GenStage
  def init(args) do
    # establish a TCP connection to the Postgresql server
    # we're ignoring any connection setup and authentication
    {:ok, conn} = :gen_tcp.connect(to_charlist(host), 5432, [active: true])

    # if we're receiving messages from a client, e.g. psql, then
    # use `PgProtocol.Decoder.frontend()`
    decoder = PgProtocol.Decoder.backend()

    {:producer, {conn, decoder}}
  end

  @impl GenStage
  def handle_info({:tcp, _conn, data}, {conn, decoder}) do
    {:ok, decoder, msgs} = PgProtocol.decode(decoder, data)
    {:noreply, msgs, {conn, decoder}}
  end
end

Status

This library is used internally by electric to de- and encode messages as part of a postgresql proxy implementation.

As such it is very much a work in progress, having only the functionality required by that project.

There are currently a few message types, PasswordMessage, SASLInitialResponse and GSSResponse that share a tag and are impossible to decode without some authentication flow context.

We currently only support the GSSResponse type and don't have any kind of context for differentiating between these messages.

Installation

This package is not currently published to Hex

This package can be installed by adding pg_protocol to your list of dependencies in mix.exs:

def deps do
  [
    {:pg_protocol, github: "electric-sql/pg_protocol"}
  ]
end

License

This Elixir library is distributed under the terms of the Apache 2.0 license.

Contributing

See the Community Guidelines including the Guide to Contributing and Contributor License Agreement.