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:
.sqlfiles run once each, in version order. - NamedSql
-
SQL with
@nameplaceholders 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
@nameplaceholders, its values, and the mapper for its rows. -
SqlBatchResult<
T> - The rows of one query of a SqlBatch, typed by its mapper.
- SqlScript
-
One
.sqlfile applied byMigratororSeeder.
Extensions
- RlsRequest on Request
- Access to the request's RlsTransaction.
- SqlFirstQueries on PostgresQueryExecutorContract
-
SQL-first queries with
@nameplaceholders 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
@nameinto aParam. -
namedStmt(
String sql, Map< String, Object?> params) → SqlStmt -
Rewrites
sqland bindsparamsinto the positional statement thatPostgresRepository's*SqlParamshooks return. -
prefixTsQuery(
String input) → String? -
Builds a PostgreSQL prefix
tsqueryfrom 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, }) → 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, }) → 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
bodyinside 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
nullwhen there is none. The tenant must come from an authenticated source, never from the body, query or an unauthenticated header.
Exceptions / Errors
- MigrationException
-
A
MigratororSeederrun refused to start or stopped. - RlsCommitException
-
COMMITfailed. - 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
-
withTenantTransactionwas called without a tenant. Thrown before the pool is touched, so no connection was taken.