postgres
v0.0.43PostgreSQL adapter for sqlx
riot add postgres postgres = "0.0.43" - Last release
- May 15, 2026
- License
- Apache-2.0
- Dependencies
- 4
- Dependents
- 1
- Installs
- 25
- Published versions
- 33
- Owner
-
@leostera
README Expand Collapse
postgres
PostgreSQL driver for sqlx.
postgres is Riot's networked SQL driver for PostgreSQL. It implements the
database wire protocol and plugs into sqlx so application code can work
through one consistent query, pool, and transaction surface.
Install
riot add postgres
Use it when
- you want a real server database rather than a local file;
- you need concurrent readers/writers and normal production database features;
- you already plan to use PostgreSQL-specific capabilities such as JSON, arrays, or LISTEN/NOTIFY.
Minimal shape
open Sqlx
let config = {
(Postgres.Config.default ()) with
host = "127.0.0.1";
port = 5432;
database = "app";
user = "app";
password = Env.get "DATABASE_PASSWORD" |> Option.unwrap_or ~default:"";
ssl_mode = Postgres.Config.Disable;
} in
let pool = Sqlx.connect ~driver:(module Postgres.Driver) config
In practice you will usually override at least the host, database, user, and password fields on the config.
Connection strings
Postgres.Config.from_string accepts two forms:
postgresql://user:password@localhost:5432/database
postgres://user:password@localhost:5432/database
host:port:database:user:password
The parser returns Error string for malformed input instead of raising. URI
query parameters are not interpreted yet; set fields such as ssl_mode on the
returned config explicitly.
Authentication
The driver supports PostgreSQL startup plus these authentication requests:
- cleartext password;
- MD5 password;
SCRAM-SHA-256.
Unsupported authentication mechanisms return a structured driver error. SCRAM server signatures are verified before the connection is considered ready.
Parameters and NULL
Parameterized queries use PostgreSQL's extended protocol when parameters are
present. Sqlx_driver.Value.Null is encoded as a PostgreSQL NULL parameter
with a -1 value length. Empty strings are encoded as present values with a
zero byte length, so NULL and "" remain distinct on the wire.
Transactions
Sqlx.Transaction calls are sent to PostgreSQL:
begin_transactionsendsBEGIN;commitsendsCOMMIT;rollbacksendsROLLBACK;set_isolation_levelsends the matchingSET TRANSACTION ...command while a transaction is active, orSET SESSION CHARACTERISTICS ...otherwise.
The driver tracks the backend ReadyForQuery transaction status after query
execution and rejects nested begin_transaction calls on the same connection.
Current limitations
- TLS negotiation is not implemented yet.
ssl_mode = Requirefails clearly instead of silently opening a plaintext connection.Prefercurrently uses the plaintext path. connect_timeoutandkeepalives_idleare reserved in the config surface but are not wired into the TCP connection path yet.- Tests in this package focus on protocol encoding and decoding without requiring a live PostgreSQL server. End-to-end database coverage should be added with an explicit integration test harness.
Where to start
src/postgres.mlidocuments the config surface and supported protocol features.- use it through
packages/sqlxrather than calling into the driver directly.
postgres
PostgreSQL driver for sqlx.
postgres is Riot's networked SQL driver for PostgreSQL. It implements the
database wire protocol and plugs into sqlx so application code can work
through one consistent query, pool, and transaction surface.
Install
riot add postgres
Use it when
- you want a real server database rather than a local file;
- you need concurrent readers/writers and normal production database features;
- you already plan to use PostgreSQL-specific capabilities such as JSON, arrays, or LISTEN/NOTIFY.
Minimal shape
open Sqlx
let config = {
(Postgres.Config.default ()) with
host = "127.0.0.1";
port = 5432;
database = "app";
user = "app";
password = Env.get "DATABASE_PASSWORD" |> Option.unwrap_or ~default:"";
ssl_mode = Postgres.Config.Disable;
} in
let pool = Sqlx.connect ~driver:(module Postgres.Driver) config
In practice you will usually override at least the host, database, user, and password fields on the config.
Connection strings
Postgres.Config.from_string accepts two forms:
postgresql://user:password@localhost:5432/database
postgres://user:password@localhost:5432/database
host:port:database:user:password
The parser returns Error string for malformed input instead of raising. URI
query parameters are not interpreted yet; set fields such as ssl_mode on the
returned config explicitly.
Authentication
The driver supports PostgreSQL startup plus these authentication requests:
- cleartext password;
- MD5 password;
SCRAM-SHA-256.
Unsupported authentication mechanisms return a structured driver error. SCRAM server signatures are verified before the connection is considered ready.
Parameters and NULL
Parameterized queries use PostgreSQL's extended protocol when parameters are
present. Sqlx_driver.Value.Null is encoded as a PostgreSQL NULL parameter
with a -1 value length. Empty strings are encoded as present values with a
zero byte length, so NULL and "" remain distinct on the wire.
Transactions
Sqlx.Transaction calls are sent to PostgreSQL:
begin_transactionsendsBEGIN;commitsendsCOMMIT;rollbacksendsROLLBACK;set_isolation_levelsends the matchingSET TRANSACTION ...command while a transaction is active, orSET SESSION CHARACTERISTICS ...otherwise.
The driver tracks the backend ReadyForQuery transaction status after query
execution and rejects nested begin_transaction calls on the same connection.
Current limitations
- TLS negotiation is not implemented yet.
ssl_mode = Requirefails clearly instead of silently opening a plaintext connection.Prefercurrently uses the plaintext path. connect_timeoutandkeepalives_idleare reserved in the config surface but are not wired into the TCP connection path yet.- Tests in this package focus on protocol encoding and decoding without requiring a live PostgreSQL server. End-to-end database coverage should be added with an explicit integration test harness.
Where to start
src/postgres.mlidocuments the config surface and supported protocol features.- use it through
packages/sqlxrather than calling into the driver directly.