slingshot_postgres library

slingshot_postgres — PostgreSQL driver of the slingshot family for Dart Backend.

Stage: PoC. Public API is minimal and evolving — pin to commit hashes rather than version ranges until a 1.0 milestone is published.

Three drivers share the same layered architecture over a native thread-per-conn pool: PostgreSQL (libpq), MySQL (libmysqlclient) and SQLite (libsqlite3). All reuse the Repository and UnitOfWork contracts from package:slingshot.

MongoDB moved out on 2026-09-08 into slingshot_mongo, the driver that proves the per-DBMS package split: a consumer that wants only MongoDB no longer builds libpq, libmysqlclient or libsqlite3, and the reverse holds too. The remaining three follow in their own cycle.

PostgreSQL surface (stable unless marked):

MySQL surface (simple protocol, string SQL — no bound parameters in v1):

  • Connection pool: MysqlConnectionPool, MysqlPooledConnection, MysqlPoolConfig, MysqlPoolExhaustedException.
  • Result decoding: MysqlResultSet, MysqlResultRow, MysqlType.
  • Concrete impls: MysqlUnitOfWork, MysqlRepository, MysqlQueryExecutor.
  • Transactional helpers: withMysqlTransaction, withMysqlTransactionOn.

What's NOT exported (internal — use package:slingshot_postgres/src/... only if you accept ABI/internal churn):

  • Low-level FFI binding (PostgresBinding) — subject to ABI change.
  • Native library loader (loadNativeDb).
  • Cross-isolate message types of IsolateWorkerPool (QueryRequest, QueryResult, QueryError, WorkerResponse).

Classes

Param
A bound parameter for the Postgres Extended Query Protocol.
PgBatchQuery
One statement of PostgresBatchExecutor.executeBatch: the SQL with positional placeholders ($1, $2, …) and its parameters.
PoolAcquireStats
Contention seen by PostgresConnectionPool.acquire since the previous PostgresConnectionPool.takeAcquireStats call.
PoolConfig
Static configuration for PostgresConnectionPool.
PooledConnection
A borrowed connection from a PostgresConnectionPool.
PostgresBatchExecutor
Capability: run several independent Extended statements in one network round-trip and get every result set back.
PostgresConnectionPool
Pool of native conns served by a single C-side native_pool_t.
PostgresConnInfo
A libpq connection string built from typed fields. sslMode has no default on purpose: whoever builds the connection chooses whether and how to use TLS. Every value is quoted and escaped, so passwords and paths with spaces or quotes are safe.
PostgresNumeric
A Postgres numeric value, held exactly.
PostgresOid
Catalog of stable built-in PostgreSQL type OIDs.
PostgresQueryExecutorContract
Executes SQL against an underlying Postgres connection and returns the decoded PostgresResultSet. Implementations are expected to be bound to a single connection for the duration of a transaction.
PostgresRepository<T, K>
Base class for Postgres-backed Repositorys.
PostgresResultRow
A single row of a PostgresResultSet. Decodes values lazily on access.
PostgresResultSet
Snapshot of a PGresult exposing decoded rows and column metadata.
PostgresUnitOfWork
Postgres-backed UnitOfWork over a PostgresConnectionPool.
Repository<T, K>
Domain-pure CRUD contract over an entity T keyed by K.
TxDiagnostics
UnitOfWork<E extends Object>
Frame for a single database transaction.

Enums

PostgresType
Dart-friendly tag for the most common PostgreSQL data types.
SslMode
libpq sslmode. Without one, libpq uses prefer, which encrypts when the server offers TLS but never checks the certificate, so it does not stop interception. verifyFull checks the chain and the host name, and is the mode for a database reached over a network you do not control.

Functions

withPipelinedTransaction(PostgresConnectionPool pool, List<String> queries, {Duration? timeout}) → Future<void>
Runs queries inside a single Postgres pipeline: BEGIN; <queries[0]>; ...; <queries[N-1]>; COMMIT; in one network round-trip total (vs N+1 for the sequential withTransaction pattern — the BEGIN is fused into the first statement, so it no longer costs a dedicated round-trip; the COMMIT still does).
withPostgresConnection<T>(PostgresConnectionPool pool, Future<T> body(PostgresQueryExecutorContract exec)) → Future<T>
Runs body over a connection acquired from pool, with no transaction, and always releases the connection. Returns body's value.
withTransaction<T>(PostgresConnectionPool pool, Future<T> body(PostgresQueryExecutorContract exec)) → Future<T>
Runs body inside a new PostgresUnitOfWork on a connection acquired from pool. Returns the value produced by body after a successful commit. Rolls back and rethrows on exception.
withTransactionInstrumented<T>(PostgresConnectionPool pool, Future<T> body(PostgresQueryExecutorContract exec), PoolDiagnosticsSink sink) → Future<T>
Runs body inside a fresh transaction on a connection acquired from pool, emitting a TxDiagnostics record to sink when the transaction finishes (committed or rolled back).
withTransactionOn<T>(UnitOfWork<PostgresQueryExecutorContract> uow, Future<T> body(PostgresQueryExecutorContract exec)) → Future<T>
Same lifecycle as withTransaction but uses a pre-built uow. Useful for tests that inject a fake UnitOfWork, or for callers who need to pre-configure the UoW before binding the body.

Typedefs

PoolDiagnosticsSink = void Function(TxDiagnostics diag)
Sink invoked once per transaction when instrumentation is on.
SqlStmt = (String, List<Param>)
SQL statement bundled with its bound parameters.

Exceptions / Errors

PoolExhaustedException
Thrown when PostgresConnectionPool.acquire cannot obtain a connection within PoolConfig.acquireTimeout.
QueryFailedException
Signals a SQL/protocol failure surfaced by the driver's client library during query execution.
QueryTimeoutException
Signals that a query exceeded its configured wall-clock timeout (timeout_ms in the native ABI). The worker issued PQcancel before throwing.
TransactionStateError
Signals an attempt to drive a UnitOfWork outside the lifecycle states it allows.