bloom_migrate library

Database migrations runtime and schema generation library for Bloom applications.

The bloom_migrate package provides transactional database migration capabilities, schema diffing and SQL generation from bloom_db models, automated migration file parsing, and migration rollback support.

Overview

• Schema Generation: Converts ModelMeta entity descriptors into dialect-accurate DDL statements (PostgreSQL, SQLite) including tables, constraints, foreign keys, many-to-many join tables, and indexes using generateMigrationFileContent or generateCreateTableSql.
• Topological Sorting: Resolves foreign key dependency graphs automatically using sortModelsTopologically to ensure parent tables are created before child tables and dropped in reverse order.
• File Conventions: Parses and formats SQL migration files following the standard migrations/<app>/NNNN_name.sql pattern with -- up and -- down (or -- no-down) blocks.
• Transactional Runner: MigrationRunner manages the bloom_migrations tracking table, discovers pending migrations on disk, and applies or rolls them back inside isolated database transactions.

Running Migrations

import 'package:bloom_db/bloom_db.dart';
import 'package:bloom_migrate/bloom_migrate.dart';

Future<void> runStartupMigrations(DbExecutor db) async {
  final runner = MigrationRunner(
    db: db,
    migrationsDirectory: 'migrations',
  );

  final pending = await runner.getPendingMigrations();
  print('Pending migrations: ${pending.length}');

  final applied = await runner.migrate();
  for (final record in applied) {
    print('Applied: ${record.app}/${record.name} at ${record.appliedAt}');
  }
}

Generating SQL from Models

import 'package:bloom_db/bloom_db.dart';
import 'package:bloom_migrate/bloom_migrate.dart';

void generateSql(List<ModelMeta> models, Dialect dialect) {
  final sql = generateMigrationFileContent(
    models: models,
    dialect: dialect,
  );
  print(sql);
}

Classes

AppliedMigration

Represents a migration record stored in the bloom_migrations tracking table.

BloomMigration

Represents a single parsed database migration file following the migrations/<app>/NNNN_name.sql convention with -- up and -- down sections.

BloomModelRegistry

Registry holding ModelMeta metadata definitions for migration generation.

MigrationRunner

The database migration engine for Bloom applications.

Functions

defaultValueToSql(DefaultValue defaultValue, Dialect dialect) → String?

Converts a DefaultValue to its SQL literal string for the target Dialect.

fieldToSqlType(FieldMeta field, Dialect dialect, {String? modelName}) → String

Mapping of a model field's FieldKind to the corresponding SQL column type string for a given Dialect.

generateColumnDefinition(FieldMeta field, Dialect dialect, {String? modelName}) → String

Generates a single column definition clause for CREATE TABLE.

generateCreateTableSql(ModelMeta model, Dialect dialect, {bool ifNotExists = true}) → String

Generates the CREATE TABLE DDL SQL string for a given ModelMeta.

generateDownSql(List<ModelMeta> models, Dialect dialect) → String

Generates the complete -- down section SQL for a list of ModelMetas.

generateIndexesSql(ModelMeta model, Dialect dialect) → List<String>

Generates all explicit and implied index SQL statements for a ModelMeta.

generateManyToManyTablesSql(ModelMeta model, Dialect dialect) → List<String>

Generates join tables for ManyToMany relations on a ModelMeta.

generateMigrationFileContent({required List<ModelMeta> models, required Dialect dialect}) → String

Generates a complete migration file content with -- up and -- down sections.

generateUpSql(List<ModelMeta> models, Dialect dialect) → String

Generates the complete -- up section SQL for a list of ModelMetas.

onDeleteToSql(OnDelete onDelete) → String

Converts an OnDelete referential integrity action to SQL syntax.

sortModelsTopologically(List<ModelMeta> models) → List<ModelMeta>

Topologically sorts models based on foreign key relationships.

splitSqlStatements(String sql) → List<String>

Splits a raw SQL block into executable statements, properly handling semicolons and ignoring comments and string literals.

Exceptions / Errors

MigrationCyclicDependencyException

Thrown when models have a circular foreign key dependency preventing clean topological ordering for table creation.

MigrationException

Base class for all migration-related errors in Bloom.

MigrationExecutionException

Thrown when a SQL DDL statement execution fails during a migration.

MigrationFileNotFoundException

Thrown when a migration file cannot be found or read from disk.

MigrationNonInvertibleException

Thrown when attempting to roll back a migration that has no -- down section or has explicitly opted out of reversal with -- no-down.

MissingMaxLengthException

Thrown when a field with a character kind is missing a required max_length attribute on PostgreSQL.

UnsupportedDialectOperationException

Thrown when an operation is not supported by the target SQL dialect.