Skip to main content
Version: 0.8.x

Writing Migration

Each migration contains two methods: up and down. The up method is used to alter the database schema, such as adding new tables, columns or indexes, while the down method revert the actions performed in the up method.

Creating Migrations

You can create a migration using the template below. Name the file according to the naming convention mYYYYMMDD_HHMMSS_migration_name.rs and update the MigrationName::name impl accordingly.

migration/src/m20220101_000001_create_table.rs
use sea_orm_migration::prelude::*;

pub struct Migration;

impl MigrationName for Migration {
fn name(&self) -> &str {
"m20220101_000001_create_table"
}
}

#[async_trait::async_trait]
impl MigrationTrait for Migration {
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
manager
.create_table( ... )
.await
}

async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
manager
.drop_table( ... )
.await
}
}

Additionally, you have to include the new migration in the MigratorTrait::migrations method. Note that the migrations should be sorted in chronological order.

migration/src/lib.rs
pub use sea_orm_migration::*;

mod m20220101_000001_create_table;

pub struct Migrator;

#[async_trait::async_trait]
impl MigratorTrait for Migrator {
fn migrations() -> Vec<Box<dyn MigrationTrait>> {
vec![
Box::new(m20220101_000001_create_table::Migration),
]
}
}

Defining Migration

See SchemaManager for API reference.

SeaQuery

Click here to take a quick tour of SeaQuery's DDL statements.

Schema Creation Methods

  • Create Table

    use entity::post;

    manager
    .create_table(
    sea_query::Table::create()
    .table(post::Entity)
    .if_not_exists()
    .col(
    ColumnDef::new(post::Column::Id)
    .integer()
    .not_null()
    .auto_increment()
    .primary_key(),
    )
    .col(ColumnDef::new(post::Column::Title).string().not_null())
    .col(ColumnDef::new(post::Column::Text).string().not_null())
    .to_owned()
    )
    You don't have SeaORM entities defined?
    // Define the identifiers using SeaQuery's `Iden` macro 
    #[derive(Iden)]
    pub enum Post {
    Table,
    Id,
    Title,
    Text,
    }
  • Create Index

    manager.create_index(sea_query::Index::create())
  • Create Foreign Key

    manager.create_foreign_key(sea_query::ForeignKey::create())
  • Create Data Type (PostgreSQL only)

    manager.create_type(sea_query::Type::create())

Schema Mutation Methods

  • Drop Table

    use entity::post;

    manager
    .drop_table(
    sea_query::Table::drop()
    .table(post::Entity)
    .to_owned()
    )
  • Alter Table

    manager.alter_table(sea_query::Table::alter())
  • Rename Table

    manager.rename_table(sea_query::Table::rename())
  • Truncate Table

    manager.truncate_table(sea_query::Table::truncate())
  • Drop Index

    manager.drop_index(sea_query::Index::drop())
  • Drop Foreign Key

    manager.drop_foreign_key(sea_query::ForeignKey::drop())
  • Alter Data Type (PostgreSQL only)

    manager.alter_type(sea_query::Type::alter())
  • Drop Data Type (PostgreSQL only)

    manager.drop_type(sea_query::Type::drop())

Schema Inspection Methods

  • Has Table
    manager.has_table(table_name)
  • Has Column
    manager.has_column(table_name, column_name)

Raw SQL

You can write migration files in raw SQL, but then you lost the cross-backend compatibility SeaQuery offers.

migration/src/m20220101_000001_create_table.rs
use sea_orm::Statement;
use sea_orm_migration::prelude::*;

pub struct Migration;

impl MigrationName for Migration {
fn name(&self) -> &str {
"m20220101_000001_create_table"
}
}

#[async_trait::async_trait]
impl MigrationTrait for Migration {
async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
let sql = r#"
CREATE TABLE `cake` (
`id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
`name` varchar(255) NOT NULL
)"#;
let stmt = Statement::from_string(manager.get_database_backend(), sql.to_owned());
manager.get_connection().execute(stmt).await.map(|_| ())
}

async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
let sql = "DROP TABLE `cake`";
let stmt = Statement::from_string(manager.get_database_backend(), sql.to_owned());
manager.get_connection().execute(stmt).await.map(|_| ())
}
}

Schema first or Entity first?

In the grand scheme of things, we recommend a schema first approach: you write migrations first and then generate entities from a live database.

At times, you might want to use the create_*_from_entity methods to bootstrap your database with several hand written entity files.

That's perfectly fine if you intend to never change the entity schema. Or, you can clone the original entity and rely on it in the migration file.