Skip to main content

Schema

Schema features are separated from query execution:

  • Query execution lives on DriverAdapter
  • Schema operations / introspection live on SchemaDriver
  • Schema dump/load is optional via SchemaStateProvider

SchemaDriver​

Drivers that support migrations and schema operations implement SchemaDriver. It supports:

  • applying schema plans (applySchemaPlan)
  • previewing schema plans (describeSchemaPlan)
  • introspecting live metadata (tables, columns, indexes, foreign keys)

Ormed’s migration runner builds schema plans from migrations (a list of mutations), and then asks the active driver to apply them.

SchemaInspector​

SchemaInspector is a small helper around SchemaDriver for common checks:

Future<bool> hasUsersTable(DataSource dataSource) async {
  final driver = dataSource.connection.driver;
  if (driver is! SchemaDriver) return false;
  final inspector = SchemaInspector(driver);
  return inspector.hasTable('users');
}

Schema plan previews​

For schema work, the plan type is SchemaPlan (a list of SchemaMutation entries). Drivers can preview a plan without running it:

SchemaPreview previewSchemaPlan(DataSource dataSource) {
  final driver = dataSource.connection.driver;
  if (driver is! SchemaDriver) {
    throw StateError('Driver does not support schema operations.');
  }
  final plan = SchemaPlan(
    mutations: [
      SchemaMutation.rawSql(
        'CREATE TABLE IF NOT EXISTS test_table (id INTEGER PRIMARY KEY)',
      ),
    ],
    description: 'demo plan preview',
  );
  return driver.describeSchemaPlan(plan);
}

Use previews when you want to:

  • show “what would run” without applying changes
  • log/inspect generated DDL in tests
  • build migration tooling that explains a plan

Schema dumps (SchemaStateProvider)​

Some features (like schema dumps used for migration squashing) rely on an optional interface:

  • SchemaStateProvider.createSchemaState(...) returns a SchemaState?
  • SchemaState can dump(...) and load(...) when supported
Future<void> dumpSchemaIfSupported(DataSource dataSource) async {
  final driver = dataSource.connection.driver;
  if (driver is! SchemaStateProvider) return;
  final state = driver.createSchemaState(
    connection: dataSource.connection,
    ledgerTable: 'orm_migrations',
  );
  if (state == null || !state.canDump) return;
  await state.dump(File('database/schema.sql'));
}