sql.postgres
import sql.postgres
sqldoes not re-export this module, so it is reached only by importing it directly.
The PostgreSQL adapter.
Reach it through sql, which is what keeps a program portable:
import sql
var db = sql.open('postgres://alice:secret@localhost/app')
The module underneath is here for the parts of PostgreSQL that have no equivalent elsewhere: LISTEN and NOTIFY, the server’s own settings, and the type registry, which is how a program teaches the adapter about a type its database defines.
What this adapter speaks
Version 3 of the wire protocol, over TCP, optionally under TLS, or over
a unix domain socket. A host beginning with a slash is a socket
directory, as libpq spells it, and the socket inside it is named after
the port. TLS is neither offered nor wanted there, since nothing sits in
between, so sslmode is ignored.
Statements go through the extended protocol, which compiles them on the server and binds values rather than substituting them. Values travel in the server’s own binary form wherever this adapter has a codec for the type, and as text otherwise, so a type it has never heard of still arrives readable.
Submodules
| Module | Reached as | Summary |
|---|---|---|
sql.postgres.auth | import sql.postgres.auth | The authentication exchanges a PostgreSQL server can ask for. |
sql.postgres.connection | sql.postgres.connection.* | A PostgreSQL connection, as the layer above the adapters sees one. |
sql.postgres.cursor | sql.postgres.cursor.* | Reading a PostgreSQL result a batch at a time. |
sql.postgres.driver | sql.postgres.driver.* | Opening PostgreSQL connections: reading a connection string, establishing the socket, upgrading it to TLS… |
sql.postgres.errors | sql.postgres.errors.* | Turning PostgreSQL’s SQLSTATE codes into the shared error classes. |
sql.postgres.messages | import sql.postgres.messages | Framing for the PostgreSQL wire protocol, version 3. |
sql.postgres.notify | sql.postgres.notify.* | LISTEN and NOTIFY, PostgreSQL’s own publish and subscribe. |
sql.postgres.protocol | sql.postgres.protocol.* | The PostgreSQL frontend/backend protocol, version 3. |
sql.postgres.results | sql.postgres.results.* | Reading what the server says about a result it has just produced. |
sql.postgres.schema | import sql.postgres.schema | Introspection for PostgreSQL, through the standard information_schema views and the catalogue behind them. |
sql.postgres.statement | sql.postgres.statement.* | A PostgreSQL statement compiled once and run many times. |
sql.postgres.types | sql.postgres.types.* | Encoding and decoding PostgreSQL’s binary value formats. |
Constants
DRIVER
sql.postgres.DRIVER
The driver instance sql registers for this engine.
Functions
connect()
sql.postgres.connect(dsn) -> PostgresConnection
Opens a PostgreSQL connection directly, without going through sql.
Anything meant to stay portable should use sql.open() instead.
Parameters
dsn(string|dict) — A connection string or options.
Returns PostgresConnection
2026, Richard Ore and Zuri contributors