Angel3 ORM for PostgreSQL

Pub Version (including pre-releases) Null Safety Discord License

Angel3 ORM for working with PostgreSQL database 14 or later.

For documentation about the ORM, see Developer Guide

Migrating from 9.x to 10.0.0

The breaking changes of each release are listed in the CHANGELOG. Those of 10.0.0 that may need changes in an app:

  • Errors of transactions: the error of a transaction, such as a PgException of the database or one its callback throws, is thrown as it is, where it was a StateError('The transaction was cancelled.'). Catch the error you expect instead of the StateError.
  • Nested transactions: transaction on the executor its callback is given runs in a savepoint; see Transactions.
  • Requires PostgreSQL 16 or later, angel3_orm 10 and postgres 3.5.20.

Migrating to 8.1.0 and above

postgres has been upgraded from 2.x.x to 3.x.x since version 8.1.0. This is a breaking change as postgres 3.x.x has revamped its API. Therefore when upgrading to 8.1.0 and beyond, the PostgreSQL connection settings need to be migrated. The rest should remain the same. Please see the example for the new PostgreSQL connection settings.

Installation

In your pubspec.yaml:

dependencies:
  angel3_orm_postgres: ^10.1.0

Usage

  1. Create a model with Entity suffix, i.e. CarEntity in car.dart

     import 'package:angel3_migration/angel3_migration.dart';
     import 'package:angel3_orm/angel3_orm.dart';
     import 'package:angel3_serialize/angel3_serialize.dart';
     import 'package:optional/optional.dart';
        
     part 'car.g.dart';
    
     @serializable
     @orm
     class CarEntity extends Model {
         String? make;
         String? description;
         bool? familyFriendly;
         DateTime? recalledAt;
         double? price;
     }
    
  2. Run the following command to generate the required .g.dart file for the model.

    dart run build_runner build
    
  3. Write the query program. i.e. CarPersistence.dart

    import 'package:angel3_migration_runner/postgres.dart';
    import 'package:angel3_orm_postgres/angel3_orm_postgres.dart';
    import 'package:postgres/postgres.dart';
    
    import 'car.dart';
    
    void main() async {
       
        // Setup the connections
        final conn = await Connection.open(
            Endpoint(
                host: 'localhost',
                port: 5432,
                database: 'postgres',
                username: 'postgres',
                password: 'postgres'),
            settings: ConnectionSettings(sslMode: SslMode.disable));
    
        var executor = PostgreSqlExecutor(conn);
    
        // Create the `Car` table
        var runner = PostgresMigrationRunner(conn, migrations: [CarMigration()]);
        await runner.up();
    
        var query = CarQuery();
        query.values
            ..make = 'Ferrari'
            ..description = 'Vroom vroom!'
            ..price = 1200000.00
            ..familyFriendly = false;
           
        // insert a new record into the `cars` table
        var ferrari = (await query.insert(executor)).value;
    }
    

Transactions

transaction runs its callback in a transaction, which is committed if the callback completes, and rolled back if it throws. The error is thrown as it is.

var car = await executor.transaction((tx) async {
  var query = CarQuery()..values.make = 'Ferrari';
  return (await query.insert(tx)).value;
});

PostgreSQL does not nest transactions, so transaction on the executor the callback is given runs in a savepoint instead. What it does is rolled back if it throws, even when the outer callback catches the error, and committed with the outer transaction otherwise.

await executor.transaction((tx) async {
  await insertOrder(tx);
  try {
    await tx.transaction((inner) => sendInvoice(inner));
  } on InvoiceException {
    // Only the savepoint is rolled back; the order is kept.
  }
});
  • Use the executor given to the callback. Calling transaction on the executor of the connection from inside the callback throws, as the connection is in use.
  • Savepoints at one level of nesting run one at a time. A transaction or savepoint waits for the savepoints started inside it, even those not awaited, before it is committed, released or rolled back.
  • A query on the executor of the transaction made while a savepoint is open, rather than on the executor of the savepoint, is part of that savepoint, and rolled back with it.
  • PostgreSqlPoolExecutor.transaction runs the transaction on a connection of the pool, and nests savepoints the same way.