expose the programmatic migration api

Author: schultek

CHANGELOG.md

@@ -3,6 +3,7 @@
 - Require dart sdk `>=3.7.0`.
 - Update analyzer to `^8.1.0`, build to `^4.0.0` and source_gen to `^4.0.0`.
 - Disable linting and formatting for generated files.
+- Expose the programmatic migration api through the `'package:stormberry/migrate.dart'` import.
 
 # 0.16.0
 

build.yaml

@@ -19,6 +19,13 @@ builders:
     build_extensions: { ".dart": [ ".schema.json" ] }
     auto_apply: dependents
     build_to: cache
+  database_schema:
+    import: "package:stormberry/builder.dart"
+    builder_factories: [ "buildDatabaseSchema" ]
+    build_extensions: { "$lib$": [ "database.schema.dart" ] }
+    required_inputs: [ ".schema.json" ]
+    auto_apply: none # Needs to be enabled manually
+    build_to: source
 
 targets:
   $default:

doc/migration.md

@@ -1,6 +1,10 @@
-Stormberry comes with a database migration tool, to create or update the schema of your database.
+Stormberry comes with a database migration system, to create or update the schema of your database.
 
-To use this run the following command from the root folder of your project.
+You can either call the migration tool from your terminal, or use the programmatic migration API.
+
+## Migration CLI
+
+To use the migration CLI run the following command from the root folder of your project:
 
 ```
 dart run stormberry migrate
@@ -38,4 +42,47 @@ The tool supported the following options:
 
 ---
 
-*🎉 Congrats, you followed the tour until the end. Now you know everything about this package.*
+## Migration API
+
+To migrate your database from your own code, first enable the `database_schema` builder like this:
+
+```yaml
+// build.yaml
+targets:
+  $default:
+    builders:
+      stormberry|database_schema:
+        enabled: true
+```
+
+This will generate a `lib/database.schema.dart` file next time you run code generation, containing a global `DatabaseSchema schema` variable of your current schema.
+
+To migrate your database to this schema, do the following:
+
+```dart
+// Import the 'migrate.dart' library.
+import 'package:stormberry/migrate.dart';
+
+Future<void> migrate() async {
+  // 1. Connect to your database
+  final Database db = ...
+
+  // 2. Compute the schema diff between your live database schema and the generated target `schema`.
+  final diff = await schema.computeDiff(db);
+
+  // 3. (Optional) Print the schema diff to stdout.
+  diff.printToConsole();
+
+  try {
+    // Always use a transaction to not break your database!!
+    await db.runTx((session) async {
+
+      // 4. Apply the necessary patches to migrate to the target schema.
+      await diff.patch(session);
+    });
+    print('Migration succeeded');
+  } catch (e) {
+    print('Migration failed. All changes reverted.');
+  }
+}
+```

example/build.yaml

@@ -0,0 +1,5 @@
+targets:
+  $default:
+    builders:
+      stormberry|database_schema:
+        enabled: true

example/lib/database.schema.dart

@@ -1,5 +1,7 @@
+import 'package:stormberry/migrate.dart';
 import 'package:stormberry/stormberry.dart';
 
+import 'database.schema.dart';
 import 'models/account.dart';
 import 'models/address.dart';
 import 'models/company.dart';
@@ -16,6 +18,8 @@ Future<void> main() async {
 
   db.debugPrint = true;
 
+  await migrate(db);
+
   await db.companies.deleteOne('abc');
 
   await db.companies.insertOne(CompanyInsertRequest(id: 'abc', name: 'Minga', addresses: []));
@@ -47,3 +51,18 @@ Future<void> main() async {
 
   await db.close();
 }
+
+Future<void> migrate(Database db) async {
+  final diff = await schema.computeDiff(db);
+
+  diff.printToConsole();
+
+  try {
+    await db.runTx((session) async {
+      await diff.patch(session);
+    });
+    print('Migration succeeded');
+  } catch (e) {
+    print('Migration failed: $e');
+  }
+}

example/lib/main.dart

@@ -1,5 +1,6 @@
 import 'package:build/build.dart';
 
+import 'src/builder/builders/database_schema_builder.dart';
 import 'src/builder/builders/json_builder.dart';
 import 'src/builder/builders/schema_builder.dart';
 import 'src/builder/builders/analyzing_builder.dart';
@@ -11,3 +12,5 @@ Builder analyzeSchema(BuilderOptions options) => AnalyzingBuilder(options);
 Builder buildSchema(BuilderOptions options) => SchemaBuilder(options);
 
 Builder buildRunner(BuilderOptions options) => JsonBuilder(options);
+
+Builder buildDatabaseSchema(BuilderOptions options) => DatabaseSchemaBuilder();

lib/builder.dart

@@ -0,0 +1,7 @@
+/// A strongly-typed postgres ORM to provide easy bindings between your dart classes and postgres database.
+/// It supports all kinds of relations without any complex configuration.
+library;
+
+export 'src/cli/migration/schema.dart';
+export 'src/cli/migration/differentiator.dart';
+export 'src/cli/migration/patcher.dart';

lib/migrate.dart

@@ -0,0 +1,38 @@
+import 'dart:convert';
+
+import 'package:build/build.dart';
+import 'package:glob/glob.dart';
+
+class DatabaseSchemaBuilder implements Builder {
+  DatabaseSchemaBuilder();
+
+  @override
+  Future<void> build(BuildStep buildStep) async {
+    var allSchemas = await buildStep
+        .findAssets(Glob('lib/**.schema.json'))
+        .asyncMap((id) => buildStep.readAsString(id))
+        .map((c) => jsonDecode(c))
+        .toList();
+
+    var fullSchema = <String, dynamic>{};
+    for (var schema in allSchemas) {
+      fullSchema.addAll(schema as Map<String, dynamic>);
+    }
+
+    final output = '// GENERATED CODE - DO NOT MODIFY BY HAND\n\n'
+        '// ignore_for_file: type=lint\n'
+        '// dart format off\n\n'
+        'import \'package:stormberry/migrate.dart\';\n\n'
+        'final DatabaseSchema schema = DatabaseSchema.fromMap(${const JsonEncoder.withIndent('  ').convert(fullSchema)});\n';
+
+    await buildStep.writeAsString(
+      AssetId(buildStep.inputId.package, 'lib/database.schema.dart'),
+      output,
+    );
+  }
+
+  @override
+  Map<String, List<String>> get buildExtensions => {
+        r'$lib$': ['database.schema.dart']
+      };
+}