orbiter_postgres library

PostgreSQL kit for orbiter.

For applications that use the framework together with slingshot_postgres. The framework has no database dependency; this package holds the PostgreSQL-specific pieces for using the two together.

Classes

Migrator
Applies schema migrations: .sql files run once each, in version order.
NamedSql
SQL with @name placeholders rewritten to PostgreSQL's positional $N.
RlsTransaction
The transaction bound to one request, with the tenant already applied.
Seeder
Applies seed data with the same rules as Migrator, recorded in its own table, so seeds and migrations version independently.
SqlBatch
Independent queries to run together with SqlFirstQueries.runBatch, each read back through the typed SqlBatchResult that add returns.
SqlBatchQuery<T>
One statement of SqlFirstQueries.queryBatch: SQL with @name placeholders, its values, and the mapper for its rows.
SqlBatchResult<T>
The rows of one query of a SqlBatch, typed by its mapper.
SqlScript
One .sql file applied by Migrator or Seeder.

Extensions

RlsRequest on Request
Access to the request's RlsTransaction.
SqlFirstQueries on PostgresQueryExecutorContract
SQL-first queries with @name placeholders on any PostgreSQL executor.

Functions

commitOnSuccess(Response response) → bool
Default policy: commit for any status below 400.
inferParam(String name, Object? value) → Param
Converts a Dart value bound to placeholder @name into a Param.
namedStmt(String sql, Map<String, Object?> params) → SqlStmt
Rewrites sql and binds params into the positional statement that PostgresRepository's *SqlParams hooks return.
prefixTsQuery(String input) → String?
Builds a PostgreSQL prefix tsquery from free text typed by a user.
rlsTransaction({required PostgresConnectionPool pool, required TenantResolver tenantResolver, required Response onUnresolved(Request request), String settingName = 'app.tenant_id', CommitPredicate shouldCommit = commitOnSuccess, Response onUnavailable(Request request, PoolExhaustedException error) = _defaultUnavailable}) → InterceptorFunction
Opens one transaction per request with the tenant applied by set_config(settingName, tenant, true), and ends it deterministically.
rlsTransactionOn({required UnitOfWork<PostgresQueryExecutorContract> unitOfWorkFactory(), required TenantResolver tenantResolver, required Response onUnresolved(Request request), String settingName = 'app.tenant_id', CommitPredicate shouldCommit = commitOnSuccess, Response onUnavailable(Request request, PoolExhaustedException error) = _defaultUnavailable}) → InterceptorFunction
Same as rlsTransaction, over any unit-of-work factory. Exists so the policy can be exercised without a native library or a database; production code uses rlsTransaction.
withTenantTransaction<T>(PostgresConnectionPool pool, String? tenantId, Future<T> body(RlsTransaction tx), {String settingName = 'app.tenant_id', Map<String, String> localSettings = const {}}) → Future<T>
Runs body inside one RLS transaction opened by the caller (a repository or a use case), not by the request pipeline.
withTenantTransactionOn<T>(UnitOfWork<PostgresQueryExecutorContract> unitOfWorkFactory(), String? tenantId, Future<T> body(RlsTransaction tx), {String settingName = 'app.tenant_id', Map<String, String> localSettings = const {}}) → Future<T>
Same as withTenantTransaction, over any unit-of-work factory. Exists so the policy can be exercised without a native library or a database; production code uses withTenantTransaction.

Typedefs

CommitPredicate = bool Function(Response response)
Decides whether a response commits its transaction.
TenantResolver = FutureOr<String?> Function(Request request)
Resolves the tenant of a request, or null when there is none. The tenant must come from an authenticated source, never from the body, query or an unauthenticated header.

Exceptions / Errors

MigrationException
A Migrator or Seeder run refused to start or stopped.
RlsCommitException
COMMIT failed.
RlsContextException
Applying the tenant setting failed. The transaction was rolled back and the connection was already returned to the pool.
RlsException
Failures raised by the RLS transaction middleware.
TenantRequiredException
withTenantTransaction was called without a tenant. Thrown before the pool is touched, so no connection was taken.