> For the complete documentation index, see [llms.txt](https://angel3-docs.dukefirehawk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://angel3-docs.dukefirehawk.com/databases/object-relational-mapping-orm/migrations.md).

# Migrations

Angel3 ORM ships with support for running database migrations, using a system modeled over [that of Laravel](https://laravel.com/docs/migrations).

An example is shown below:

```dart
import 'package:angel3_migration/angel3_migration.dart';

class UserMigration extends Migration {
  @override
  void up(Schema schema) {
    schema.create('users', (table) {
      table
        ..serial('id').primaryKey()
        ..varChar('username', length: 32).unique()
        ..varChar('password')
        ..boolean('account_confirmed').defaultsTo(false);
    });
  }

  @override
  void down(Schema schema) {
    schema.drop('users');
  }
}
```

Migrations can be used to either create or drop database tables; altering a table is not supported.

`defaultsTo` takes the default of a column as a value, which is written as a literal: a `String` is quoted and escaped, so it is never run as SQL. For SQL, such as the current time, give a `RawSql` of `package:angel3_orm`, such as `currentTimestamp`:

```dart
table.timeStamp('created_at').defaultsTo(currentTimestamp);
```

For more in-depth documentation, consult the `angel3_migration` documentation:

<https://github.com/dart-backend/angel/tree/master/packages/orm/migration>

If you use `angel3_orm_generator`, then a migration will be generated by default for each class annotated with `@orm`, such as `UserMigration` for `UserEntity`.

To disable this:

```dart
@Orm(generateMigrations: false)
abstract class MyModelEntity extends Model {}
```

## Running Migrations

Using `package:angel3_migration_runner`, we can create executables, such as `bin/migrate.dart`, that run our database migrations. Use `PostgresMigrationRunner` for PostgreSQL, and `MySqlMigrationRunner` or `MariaDbMigrationRunner` for MySQL and MariaDB:

```dart
import 'package:angel3_migration_runner/angel3_migration_runner.dart';
import 'package:angel3_migration_runner/postgres.dart';
import 'package:postgres/postgres.dart';

import 'package:my_app/models.dart';

void main(List<String> args) async {
  var connection = await Connection.open(
    Endpoint(
      host: 'localhost',
      database: 'demo',
      username: 'demouser',
      password: 'demo123',
    ),
    settings: ConnectionSettings(sslMode: SslMode.disable),
  );

  var runner = PostgresMigrationRunner(
    connection,
    migrations: [UserMigration(), TodoMigration()],
  );

  // `dart bin/migrate.dart up`, `rollback`, `reset` or `refresh`
  await runMigrations(runner, args);
}
```

`runMigrations` closes the runner, even when a migration fails. For MySQL and MariaDB, use `MySqlMigrationRunner` and `MariaDbMigrationRunner`.

Running this file without a command will produce output like the following:

```bash
Executes Angel3 migrations.

Usage: migration_runner <command> [arguments]

Global options:
-h, --help    Print this usage information.

Available commands:
  help       Display help information for migration_runner.
  refresh    Resets the database, and then re-runs all migrations.
  reset      Resets the database.
  rollback   Undoes the last batch of migrations.
  up         Runs outstanding migrations.

Run "migration_runner help <command>" for more information about a command.
```

The migration runner keeps track of a `migrations` table, in order to be able to keep track of which migrations it has run. Each migration is recorded by its `name`, which defaults to the name of its class. Override `name` to keep it stable when the class is renamed, or the app is compiled with `--obfuscate`:

```dart
class CreateUsersMigration extends Migration {
  @override
  String get name => 'create_users';
  ...
}
```

On PostgreSQL, each migration runs, and is recorded, in one transaction. MySQL and MariaDB commit each change of a table on its own.

Versions before 10.0.0 recorded a migration by its source file and class name. The runner renames those records on its first run; see the [README of `angel3_migration_runner`](https://pub.dev/packages/angel3_migration_runner) for the cases it cannot rename.
