sqflite_hooks

An extension to sqflite for adding hooks to database actions.

Getting Started

In your flutter project add the dependency:

dependencies:
  ...
  sqflite_hooks: ^1.0.0

sqflite is included as part of this package but if you require a specific version, make sure this is added to your pubspec.yaml.

For help getting started with Flutter, view the online documentation.

Usage example

The usage is no different to sqflite. Just be sure to import sqflite_hooks instead of sqflite:

import 'package:sqflite_hooks/sqflite_hooks.dart';

Then you can open and create your database like so:

var databasesPath = await getDatabasesPath();
var path = join(databasesPath, 'demo.db');
var database = await openDatabase(path, version: 1,
    onCreate: (database, version) async {
    await database.execute(
        '''CREATE TABLE Users (Id INTEGER PRIMARY KEY AUTOINCREMENT, Name TEXT NOT NULL);''');
});

Using hooks

The main difference when using sqflite_hooks is that you can add hooks to a database object. This allows you to easily run Dart code when actions occur on your database.

database.addHook(
    (event) => event.table == 'Users' && event.operation == DatabaseOperation.insert,
    (event) {
        // do something when a new record is inserted on the Users table
    },
    'NewUserHook');

The addHook method is as follows:

void addHook(bool Function(DatabaseEvent) predicate, Function(DatabaseEvent) hook, String key)

• The predicate parameter is a Function which should return true if the hook should run. A predicate should not be marked as async.
• The hook parameter is a Function which will run should the predicate return true. A hook can be async.
• The key parameter is a String used for keeping track of hooks and removing them later.

The DatabaseEvent class contains the following properties:

final DatabaseOperation operation;
final String table;
final Map<String, dynamic> values;
final String where;
final List whereArgs;

The operation property is a DatabaseOperation enum which has the following values:

enum DatabaseOperation { insert, update, delete }

Hooks can be removed like so:

database.removeHook('NewUserHook');

Please note: all hooks for a predicate returning true will run and be await-ed before the database operation completes.

Transactions

Hooks on a HookedDatabase will also be fired when using a HookedTransaction. You can get a HookedTransaction object as you would usually get a Transaction:

await database.transaction((transaction) async {
    // this gives you a HookedTransaction object but the type exposed is a Transaction

    // use the transaction object as normal
});

Hooks get fired for each operation performed on a HookedTransaction

If a transaction fails and hooks have already fired, you can provide a function to the named parameter onRollBack when creating a hooked transaction. onRollBack expects a Function(List<DatabaseEvent>) argument:

await database.transaction((transaction) async {
    ...
}, onRollBack: (events) {
    for (var event in events) {
        // undo anything that might have happened from fired hooks before the transaction failed
    }
});

Batches

Hooks on a HookedDatabase will also be fired when using a HookedBatch. You can get a HookedBatch object as you would usually get a Batch:

var batch = database.batch(); // this returns a HookedBatch object but the type exposed is a Batch

Hooks get fired once the commit method has been called on the HookedBatch, but after all database operations for the batch has completed.

A HookedBatch is also provided when using transaction.batch() and has its hooks fired once the commit method is called.