Skip to main content

angel3_orm_postgres 10.0.3 copy "angel3_orm_postgres: ^10.0.3" to clipboard
angel3_orm_postgres: ^10.0.3 copied to clipboard

PostgreSQL support for Angel3 ORM. Includes functionality for querying and transactions.

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 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.0.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.
4
likes
160
points
1.76k
downloads

Documentation

API reference

Publisher

verified publisherdukefirehawk.com

Weekly Downloads

PostgreSQL support for Angel3 ORM. Includes functionality for querying and transactions.

Homepage
Repository (GitHub)
View/report issues
Contributing

License

BSD-3-Clause (license)

Dependencies

angel3_orm, io, logging, optional, pool, postgres

More

Packages that depend on angel3_orm_postgres