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):
- Connection pool: PostgresConnectionPool, PooledConnection, PoolConfig, PoolExhaustedException, PoolAcquireStats.
- Result decoding: PostgresResultSet, PostgresResultRow, PostgresType, PostgresOid.
- Parameter binding (ABI MINOR 1): Param, SqlStmt.
- Domain interfaces + errors: Repository, UnitOfWork, QueryFailedException, QueryTimeoutException, TransactionStateError. The query shape is per-driver, so the Postgres executor contract (PostgresQueryExecutorContract) ships with the Postgres vertical, not with the domain.
- Concrete impls: PostgresUnitOfWork, PostgresRepository.
- Transactional helpers: withTransaction, withTransactionOn.
- Isolate worker pool (deprecated — prefer native thread/conn pool
of MAJOR 2):
IsolateWorkerPool,WorkerPoolConfig. @experimental(contract may change before 1.0): withPipelinedTransaction, withTransactionInstrumented,TxDiagnostics,PoolDiagnosticsSink.
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
numericvalue, 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
PGresultexposing decoded rows and column metadata. - PostgresUnitOfWork
- Postgres-backed UnitOfWork over a PostgresConnectionPool.
-
Repository<
T, K> -
Domain-pure CRUD contract over an entity
Tkeyed byK. - 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
queriesinside 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
bodyover a connection acquired frompool, with no transaction, and always releases the connection. Returnsbody's value. -
withTransaction<
T> (PostgresConnectionPool pool, Future< T> body(PostgresQueryExecutorContract exec)) → Future<T> -
Runs
bodyinside a new PostgresUnitOfWork on a connection acquired frompool. Returns the value produced bybodyafter a successful commit. Rolls back and rethrows on exception. -
withTransactionInstrumented<
T> (PostgresConnectionPool pool, Future< T> body(PostgresQueryExecutorContract exec), PoolDiagnosticsSink sink) → Future<T> -
Runs
bodyinside a fresh transaction on a connection acquired frompool, emitting a TxDiagnostics record tosinkwhen 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_msin the native ABI). The worker issuedPQcancelbefore throwing. - TransactionStateError
-
Signals an attempt to drive a
UnitOfWorkoutside the lifecycle states it allows.