DatabaseMigrator

public struct DatabaseMigrator

A DatabaseMigrator registers and applies database migrations.

Migrations are named blocks of SQL statements that are guaranteed to be applied in order, once and only once.

When a user upgrades your application, only non-applied migration are run.

Usage:

var migrator = DatabaseMigrator()

// 1st migration
migrator.registerMigration("createLibrary") { db in
    try db.create(table: "author") { t in
        t.autoIncrementedPrimaryKey("id")
        t.column("creationDate", .datetime)
        t.column("name", .text).notNull()
    }

    try db.create(table: "book") { t in
        t.autoIncrementedPrimaryKey("id")
        t.column("authorId", .integer)
            .notNull()
            .references("author", onDelete: .cascade)
        t.column("title", .text).notNull()
    }
}

// 2nd migration
migrator.registerMigration("AddBirthYearToAuthors") { db in
    try db.alter(table: "author") { t
        t.add(column: "birthYear", .integer)
    }
}

// Migrations for future versions will be inserted here:
//
// // 3rd migration
// migrator.registerMigration("...") { db in
//     ...
// }

try migrator.migrate(dbQueue)

  • When the eraseDatabaseOnSchemaChange flag is true, the migrator will automatically wipe out the full database content, and recreate the whole database from scratch, if it detects that a migration has changed its definition.

    This flag can destroy your precious users’ data!

    But it may be useful in two situations:

    1. During application development, as you are still designing migrations, and the schema changes often.

      In this case, it is recommended that you make sure this flag does not ship in the distributed application, in order to avoid undesired data loss:

      var migrator = DatabaseMigrator()
#if DEBUG
// Speed up development by nuking the database when migrations change
migrator.eraseDatabaseOnSchemaChange = true
#endif

    2. When the database content can easily be recreated, such as a cache for some downloaded data.

    Declaration

    Swift

    public var eraseDatabaseOnSchemaChange: Bool
    Show on GitHub

  • A new migrator.

    Declaration

    Swift

    public init()
    Show on GitHub

  • Registers a migration.

    migrator.registerMigration("createAuthors") { db in
    try db.create(table: "author") { t in
        t.autoIncrementedPrimaryKey("id")
        t.column("creationDate", .datetime)
        t.column("name", .text).notNull()
    }
}

    Precondition

    No migration with the same same as already been registered.

    Declaration

    Swift

    public mutating func registerMigration(_ identifier: String, migrate: @escaping (Database) throws -> Void)

    Parameters

    identifier

    The migration identifier.
    block

    The migration block that performs SQL statements.
    Show on GitHub

  • Registers a migration.

    migrator.registerMigrationWithDeferredForeignKeyCheck("createAuthors") { db in
    try db.create(table: "author") { t in
        t.autoIncrementedPrimaryKey("id")
        t.column("creationDate", .datetime)
        t.column("name", .text).notNull()
    }
}

    Precondition

    No migration with the same same as already been registered.

    Declaration

    Swift

    @available(*, deprecated, renamed: "registerMigration(_:migrate:﹚")
public mutating func registerMigrationWithDeferredForeignKeyCheck(
    _ identifier: String,
    migrate: @escaping (Database) throws -> Void)

    Parameters

    identifier

    The migration identifier.
    block

    The migration block that performs SQL statements.
    Show on GitHub

  • Iterate migrations in the same order as they were registered. If a migration has not yet been applied, its block is executed in a transaction.

    Throws

    An eventual error thrown by the registered migration blocks.

    Declaration

    Swift

    public func migrate(_ writer: DatabaseWriter) throws

    Parameters

    writer

    A DatabaseWriter (DatabaseQueue or DatabasePool) where migrations should apply.
    Show on GitHub

  • Iterate migrations in the same order as they were registered, up to the provided target. If a migration has not yet been applied, its block is executed in a transaction.

    Throws

    An eventual error thrown by the registered migration blocks.

    Declaration

    Swift

    public func migrate(_ writer: DatabaseWriter, upTo targetIdentifier: String) throws

    Parameters

    writer

    A DatabaseWriter (DatabaseQueue or DatabasePool) where migrations should apply.
    targetIdentifier

    The identifier of a registered migration.
    Show on GitHub

  • Returns the set of applied migration identifiers.

    Throws

    An eventual database error.

    Declaration

    Swift

    public func appliedMigrations(in reader: DatabaseReader) throws -> Set<String>

    Parameters

    reader

    A DatabaseReader (DatabaseQueue or DatabasePool).
    targetIdentifier

    The identifier of a registered migration.
    Show on GitHub

  • Returns true if all migrations are applied.

    Throws

    An eventual database error.

    Declaration

    Swift

    public func hasCompletedMigrations(in reader: DatabaseReader) throws -> Bool

    Parameters

    reader

    A DatabaseReader (DatabaseQueue or DatabasePool).
    Show on GitHub

  • Returns true if all migrations up to the provided target are applied, and maybe further.

    Throws

    An eventual database error.

    Declaration

    Swift

    public func hasCompletedMigrations(in reader: DatabaseReader, through targetIdentifier: String) throws -> Bool

    Parameters

    reader

    A DatabaseReader (DatabaseQueue or DatabasePool).
    targetIdentifier

    The identifier of a registered migration.
    Show on GitHub

  • Returns the identifier of the last migration for which all predecessors have been applied.

    Throws

    An eventual database error.

    Declaration

    Swift

    public func lastCompletedMigration(in reader: DatabaseReader) throws -> String?

    Parameters

    reader

    A DatabaseReader (DatabaseQueue or DatabasePool).

    Return Value

    An eventual migration identifier.

    Show on GitHub