generate library Generate and automate

Source generation, catalog import and reviewed migration files.

Use generateSchema for an in-memory result or writeGeneratedSchema to update the client and physical snapshot. Use generateQueries for named SQL. These development tools analyze Dart source; applications import their generated client and a database entrypoint instead.

Classes

GeneratedQueries

Offline generated code and its fixed SQL/codec contracts. Native checks are explicit: generation does not claim that a database has accepted the SQL.

GeneratedSchema

A generated typed client and the physical schema derived from its models.

ImportedSchema

Editable declarations, physical-to-Dart names, and a separate review report. This is not a migration or permission to replace the existing schema.

SchemaImportIssue

A catalog fact that needs manual handling. Blocking issues prevent a faithful declaration of the affected table or relationship; other issues retain objects which must stay in reviewed, database-specific migrations.

Functions

checkGeneratedQueries(String source, {String? output}) → Future<GeneratedQueries>

Regenerates source in memory and rejects a stale generated output file.

checkSqlQueries(SqlDatabase<Backend> db, GeneratedQueries generated) → Future<List<Map<String, Object?>>>

Compile each declared query on one backend, without executing its SELECT. SQLite, MySQL and MariaDB report structure only. PostgreSQL additionally checks native storage families. These checks do not prove expression nullability or custom codecs.

generateQueries(String sourcePath, {String? outputPath}) → Future<GeneratedQueries>

Analyzes named SQL declarations and reads their SQL files without writing.

generateSchema(String sourcePath, {String? outputPath}) → Future<GeneratedSchema>

Analyzes sourcePath and generates a client without writing files.

importSchema(SqlDatabase<Backend> db, {List<String>? tables}) → Future<ImportedSchema>

Reads the selected database's physical catalog in one consistent catalog snapshot. No user rows are read, inferred, or changed. Omit tables to discover user tables; pass exact physical names to restrict the import. Unsupported columns exclude their whole table and produce blocking issues.

recordMigration(String id, {required String directory, required MigrationHistory history}) → Future<String>

Records a reviewed edit to the latest unpublished migration. Its source is retained verbatim apart from the fingerprint literal. Applied files must not be edited or recorded again; this offline tool cannot know deployment state.

writeGeneratedQueries(String source, {String? output}) → Future<void>

Replaces the generated query bindings only after source validation succeeds.

writeGeneratedSchema(String source, {String? output}) → Future<void>

Writes a typed client and Dart schema snapshot after validating source.

writeMigration(Migration migration, {required String directory, required MigrationHistory history}) → Future<String>

Saves a new fixed migration and updates the registry. Never replaces a file.

writeMigrationRegistry(String directory, {SqlDialect? dialect}) → Future<String>

Regenerates only static imports. Fingerprints stay in the migration files.

Exceptions / Errors

GenerationException

A declaration, generated file or migration source that cannot be processed.