Migrations

Versionamento do schema do banco de dados com arquivos de migração repetíveis e ordenados - sqlx migrate e refinery são as escolhas comuns em Rust.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

sqlx migrate add create_users
# edite migrations/<timestamp>_create_users.sql
sqlx migrate run

sqlx::migrate!("./migrations").run(&pool).await?;

Quando usar isso: Qualquer serviço com um banco de dados persistente necessita de um histórico auditável de alterações de schema.

Exemplo de Trabalho

-- migrations/20240101000001_create_items.sql
CREATE TABLE items (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- migrations/20240102000001_add_items_sku.sql
ALTER TABLE items ADD COLUMN sku TEXT;
CREATE UNIQUE INDEX items_sku_key ON items (sku) WHERE sku IS NOT NULL;

#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
    let pool = sqlx::PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
    sqlx::migrate!("./migrations").run(&pool).await?;
    Ok(())
}

O que isso demonstra:

Arquivos SQL prefixados com timestamp aplicados em ordem.
Migração aditiva com coluna anulável antes do preenchimento.
Índice único parcial para sku opcional.
migrate! em tempo de execução na implantação ou inicialização.

Mergulho Profundo

Como Funciona

O runner de migração registra as versões aplicadas na tabela _sqlx_migrations.
Cada arquivo é executado uma vez; um checksum detecta arquivos históricos editados.
Migrações reversíveis são opcionais - apenas para frente é comum em produção.

Regras de Migração

Regra	Por quê
Uma preocupação por arquivo	Narrativa de rollback mais fácil
Evitar implantação destrutiva primeiro	Adicionar coluna anulável, preencher, depois NOT NULL
Testar em cópia dos dados de produção	Capturar problemas de lock/tempo
Executar em CI antes do merge	Capturar erros de SQL cedo

Notas de Rust

// Migrações Diesel (alternativa)
// diesel migration run

Armadilhas

Editar migrações aplicadas - Falha de checksum quebra implantações. Correção: Novo arquivo de migração para corrigir o schema.
Locks longos - ALTER em tabelas grandes bloqueia escritas. Correção: Estratégias de migração online, preenchimentos em lote.
Migrate ausente em CI - Drift de schema entre desenvolvimento e produção. Correção: sqlx migrate run no pipeline contra um DB efêmero.
Dados + schema em um arquivo - Correção de dados pesada executada em lock de transação. Correção: Jobs de preenchimento de dados separados.
Sem migrações de descida - Plano de rollback incerto. Correção: Documentar SQL de rollback manual no PR.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Migrações Diesel	Stack ORM Diesel	Serviços apenas sqlx
refinery	Arquivos SQL agnósticos de biblioteca	Já padronizado na CLI sqlx
Flyway/Liquibase (JVM)	Padrão de organização poliglota	Pipeline puramente Rust preferido

FAQs

Inicialização vs. job de migração?

Executar no job de implantação antes do tráfego; verificação de sanidade opcional na inicialização.

Squash de migrações?

Apenas antes da primeira implantação em produção; nunca reescreva o histórico aplicado.

Dados de seed?

Scripts de seed separados, não misturados com migrações de schema.

Múltiplos serviços um DB?

Coordenar a propriedade das migrações - um serviço executa as migrações ou um repositório de migração compartilhado.

Adição de coluna sem downtime?

Adicionar anulável -> job de preenchimento -> definir NOT NULL em migração posterior.

Relação sqlx prepare?

Regenerar dados offline .sqlx após alterações de schema que afetam query!.

SQLite dev PG prod?

Manter migrações portáteis ou manter arquivos específicos de dialeto conscientemente.

Rollback de produção?

Migração de correção para frente preferida em vez de reverter arquivos aplicados.

Checklist de revisão?

Índices, estimativa de tempo de lock, compatibilidade retroativa para implantações rolling.

Migrações SeaORM?

sea-orm-migration gera módulos de migração Rust - escolha uma ferramenta por repositório.

Relacionado

Bases de Bancos de Dados - Configuração de pool
sqlx - Macro migrate!
Transações e Isolamento - Transações de migração
Melhores Práticas de Bancos de Dados - Higiene de migração
Bases de Implantação - Ordem de implantação

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Migrations

Versionamento do schema do banco de dados com arquivos de migração repetíveis e ordenados - sqlx migrate e refinery são as escolhas comuns em Rust.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

sqlx migrate add create_users
# edite migrations/<timestamp>_create_users.sql
sqlx migrate run

sqlx::migrate!("./migrations").run(&pool).await?;

Quando usar isso: Qualquer serviço com um banco de dados persistente necessita de um histórico auditável de alterações de schema.

Exemplo de Trabalho

-- migrations/20240101000001_create_items.sql
CREATE TABLE items (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- migrations/20240102000001_add_items_sku.sql
ALTER TABLE items ADD COLUMN sku TEXT;
CREATE UNIQUE INDEX items_sku_key ON items (sku) WHERE sku IS NOT NULL;

#[tokio::main]
async fn main() -> Result<(), sqlx::Error> {
    let pool = sqlx::PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
    sqlx::migrate!("./migrations").run(&pool).await?;
    Ok(())
}

O que isso demonstra:

Arquivos SQL prefixados com timestamp aplicados em ordem.
Migração aditiva com coluna anulável antes do preenchimento.
Índice único parcial para sku opcional.
migrate! em tempo de execução na implantação ou inicialização.

Mergulho Profundo

Como Funciona

O runner de migração registra as versões aplicadas na tabela _sqlx_migrations.
Cada arquivo é executado uma vez; um checksum detecta arquivos históricos editados.
Migrações reversíveis são opcionais - apenas para frente é comum em produção.

Regras de Migração

Regra	Por quê
Uma preocupação por arquivo	Narrativa de rollback mais fácil
Evitar implantação destrutiva primeiro	Adicionar coluna anulável, preencher, depois NOT NULL
Testar em cópia dos dados de produção	Capturar problemas de lock/tempo
Executar em CI antes do merge	Capturar erros de SQL cedo

Notas de Rust

// Migrações Diesel (alternativa)
// diesel migration run

Armadilhas

Editar migrações aplicadas - Falha de checksum quebra implantações. Correção: Novo arquivo de migração para corrigir o schema.
Locks longos - ALTER em tabelas grandes bloqueia escritas. Correção: Estratégias de migração online, preenchimentos em lote.
Migrate ausente em CI - Drift de schema entre desenvolvimento e produção. Correção: sqlx migrate run no pipeline contra um DB efêmero.
Dados + schema em um arquivo - Correção de dados pesada executada em lock de transação. Correção: Jobs de preenchimento de dados separados.
Sem migrações de descida - Plano de rollback incerto. Correção: Documentar SQL de rollback manual no PR.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Migrações Diesel	Stack ORM Diesel	Serviços apenas sqlx
refinery	Arquivos SQL agnósticos de biblioteca	Já padronizado na CLI sqlx
Flyway/Liquibase (JVM)	Padrão de organização poliglota	Pipeline puramente Rust preferido

FAQs

Inicialização vs. job de migração?

Executar no job de implantação antes do tráfego; verificação de sanidade opcional na inicialização.

Squash de migrações?

Apenas antes da primeira implantação em produção; nunca reescreva o histórico aplicado.

Dados de seed?

Scripts de seed separados, não misturados com migrações de schema.

Múltiplos serviços um DB?

Coordenar a propriedade das migrações - um serviço executa as migrações ou um repositório de migração compartilhado.

Adição de coluna sem downtime?

Adicionar anulável -> job de preenchimento -> definir NOT NULL em migração posterior.

Relação sqlx prepare?

Regenerar dados offline .sqlx após alterações de schema que afetam query!.

SQLite dev PG prod?

Manter migrações portáteis ou manter arquivos específicos de dialeto conscientemente.

Rollback de produção?

Migração de correção para frente preferida em vez de reverter arquivos aplicados.

Checklist de revisão?

Índices, estimativa de tempo de lock, compatibilidade retroativa para implantações rolling.

Migrações SeaORM?

sea-orm-migration gera módulos de migração Rust - escolha uma ferramenta por repositório.

Relacionado

Bases de Bancos de Dados - Configuração de pool
sqlx - Macro migrate!
Transações e Isolamento - Transações de migração
Melhores Práticas de Bancos de Dados - Higiene de migração
Bases de Implantação - Ordem de implantação

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

Migrations

Buscar na documentação

Migrations