dorm_postgres_database

dorm_postgres_database on pub.flutter-io.cn dorm_postgres_database pub points dorm_postgres_database popularity dorm_postgres_database likes dorm_postgres_database documentation dORM repository License Dart CI

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.

Libraries

dorm_postgres_database