dorm_postgres_database #

dorm_postgres_database adapts dORM repositories to PostgreSQL through the postgres package. Engine accepts an opened SessionExecutor, including Connection and Pool.

Backend and runtime #

The backend is PostgreSQL through postgres. The application opens and owns a Connection or Pool before constructing the engine.

Install #

dart pub add dorm_framework
dart pub add dorm_postgres_database
dart pub add postgres
dart pub add dorm_annotations
dart pub add --dev dorm_generator
dart pub add --dev build_runner

Create the engine and Dorm facade #

import 'package:postgres/postgres.dart';
import 'package:dorm_postgres_database/dorm_postgres_database.dart';

final Connection connection = await Connection.open(
  Endpoint(
    host: '[PLACEHOLDER: host]',
    database: '[PLACEHOLDER: database]',
    username: '[PLACEHOLDER: username]',
    password: '[PLACEHOLDER: password]',
  ),
);

try {
  final engine = Engine(connection);
  final dorm = Dorm(engine);
  // Use generated repositories here.
} finally {
  await connection.close();
}

The application opens and closes the SessionExecutor. Pool can be passed in the same way when the application manages pooling.

Identities, filters, pages, and relationships #

final User user = await dorm.users.repository.put(
  Creation.auto(
    dependency: const UserDependency(),
    data: UserData(name: 'Ada'),
  ),
);

await dorm.users.repository.push(user.copyWith(name: 'Ada Lovelace'));

The engine sends values as PostgreSQL parameters. Identified writes use PostgreSQL upsert statements. DatabaseGeneratedIdSpec uses a returned identity for supported simple-key schemas; composite identities require Creation.explicit.

Relationships #

Generated relationships use grouped reads when possible and readable-operation fallbacks otherwise.

Transactions #

PostgreSQL implements TransactionalDorm and runs the callback through the SessionExecutor transaction API:

final txDorm = TransactionalDorm(engine);

await txDorm.transaction((tx) async {
  final User? user = await tx.users.repository.peek(userId);
  if (user != null) {
    await tx.users.repository.push(user.copyWith(active: false));
  }
});

The callback context is temporary and streams are unavailable inside it.

Streams #

pull and pullAll emit the initial read only. They do not subscribe to later PostgreSQL changes.

Schema, errors, and limitations #

The package does not infer migrations from generated schemas. Use PostgresMigrationAdapter from dorm_migrations for explicit, ordered SQL migrations, or keep using the application SQL deployment workflow. The adapter uses a backend advisory lock and groups a migration with its history record in one transaction when the provider honors it. See the migration guide. Provider failures are exposed through the portable DormDatabaseException contract; inspect cause and providerCode when PostgreSQL-specific details are needed.

Run the example #

See the package example for PostgreSQL environment variables, schema setup, generation, and Dart commands.

Links #

• Run with PostgreSQL
• postgres
• dorm_framework
• GitHub repository