epgsql - PostgreSQL driver for Erlang, internal documentation

This document is made mostly as internal documentation. It can be useful if you plan to contribute some patches to epgsql, want to implement custom datatypes or commands or to better understand epgsql internals.

End-user interface is described in README.md.

Interfaces

Epgsql has 3 end-user API interfaces:

epgsql - synchronous
epgsqla - asynchronous
epgsqli - incremental

Internals

All 3 interfaces communicate with epgsql_sock gen_server, which holds all the connection state. While epgsql_sock holds all the state, it doesn't know much about Client-Server communication protocol. All the communication logic between epgsql and PostgreSQL server is implemented as a Commands and epgsql_sock acts as an executor for those commands.

PostgreSQL binary communication protocol is represented by 2 modules:

epgsql_wire - codecs for on-wire communication protocol messages
epgsql_binary - interface to PostgreSQL binary data encoding protocol(see Datatypes)

epgsql_sock holds an internal state of epgsql_binary codecs as well. The main contents of this state is the mapping between PostgreSQL unique numeric datatype IDs (OIDs) and callbacks which will be used to decode this datatype. This mapping is handled by epgsql_oid_db module and is populated at connection set-up time by epgsql_cmd_connect.

Most of the connection initialization (network connection, authentication, codecs) is performed by epgsql_cmd_connect command, which is just a regular command (but quite complex one) and can be replaced by own implementation if needed.

Commands

Client can execute a number of built-in commands as well as define their own. See epgsql_command and all the epgsql_cmd_* pages. There exists a manual that explains how to implement your own command.

Datatypes

Epgsql supports both PostgreSQL text and binary data encodings to transfer the data (query placeholder parameters and result rows). There are a bunch of built-in codecs and it's possible to implement custom ones as well as fine-tune some of built-ins. See epgsql_codec and all the epgsql_codec_* pages for more details. There exists a manual that explains how to implement your own datatype codec.

Generated by EDoc