Creating a migration
You can create a new migration using the CLI.Sources/App/Migrations
.
Implementing Migrations
A migration conforms to theMigration
protocol and is implemented by filling out the up
and down
functions. up
is run when a migration is applied to a database. down
is run when a migration is rolled back.
up
and down
are passed a Schema
object representing the schema of the database to which this migration will be applied. The database schema is modified via functions on Schema
.
For example, this migration renames the user_todos
table to todos
. Notice the down
function does the reverse. You don’t have to fill out the down function of a migration, but it may be useful for rolling back the operation later.
Schema functions
Schema
has a variety of useful builder methods for doing various database migrations.
Creating a table
You can create a new table usingSchema.create(table: String, builder: (inout CreateTableBuilder) -> Void)
.
The CreateTableBuilder
comes packed with a variety of functions for adding columns of various types & modifiers to the new table.
Adding Columns
You may add a column onto a table builder with functions like.string()
or .int()
. These define a named column of the given type and return a column builder for adding modifiers to the column.
Supported builder functions for adding columns are
Table Builder Functions | Column Builder Functions |
---|---|
.uuid(_ column: String) | .default(expression: String) |
.int(_ column: String) | .default(val: String) |
.string(_ column: String) | .notNull() |
.increments(_ column: String) | .unique() |
.double(_ column: String) | .primary() |
.bool(_ column: String) | .references(_ column: String, on table: String) |
.date(_ column: String) | |
.json(_ column: String) |
Adding Indexes
Indexes can be added via.addIndex
. They can be on a single column or multiple columns and can be defined as unique or not.
users_email_key
.
Altering a Table
You can alter an existing table withalter(table: String, builder: (inout AlterTableBuilder) -> Void)
.
AlterTableBuilder
has the exact same interface as CreateTableBuilder
with a few extra functions for dropping columns, dropping indexes, and renaming columns.
Other schema functions
You can also drop tables, rename tables, or execute arbitrary SQL strings from a migration.Running a Migration
To begin, you need to ensure that your migrations are registered onDatabase.default
. You can should do this in your Application.boot
function.
Via Command
Applying
You can then apply all outstanding migrations in a single batch by passing themigrate
argument to your app. This will cause the app to migrate Database.default
instead of serving.
Rolling Back
You can pass the--rollback
flag to instead rollback the latest batch of migrations.
When Serving
If you’d prefer to avoid running a separate migration command, you may pass the--migrate
flag when running your server to automatically run outstanding migrations before serving.
migrations
table. You can delete this table to clear all records of migrations.