Visão geral das migrações

  • Artigo

Em projetos do mundo real, os modelos de dados mudam conforme os recursos são implementados: novas entidades ou propriedades são adicionadas e removidas, e os esquemas de banco de dados precisam ser alterados de acordo para serem mantidos em sincronia com o aplicativo. O recurso de migrações no EF Core oferece uma maneira de atualizar de forma incremental o esquema de banco de dados para mantê-lo em sincronia com o modelo de dados do aplicativo, preservando os dados existentes no banco de dados.

Em um nível alto, as migrações funcionam da seguinte maneira:

  • Quando uma alteração de modelo de dados é introduzida, o desenvolvedor usa as ferramentas do EF Core para adicionar uma migração correspondente que descreve as atualizações necessárias para manter o esquema de banco de dados em sincronia. O EF Core compara o modelo atual com um instantâneo do modelo antigo para determinar as diferenças e gera arquivos de origem de migração; os arquivos podem ser acompanhados no controle do código-fonte do projeto, como qualquer outro arquivo de origem.
  • Depois que uma nova migração é gerada, é possível aplicá-la a um banco de dados de várias maneiras. O EF Core registra todas as migrações aplicadas em uma tabela de histórico especial, permitindo que ela saiba quais migrações foram ou não aplicadas.

O restante desta página é um guia passo a passo para iniciantes sobre como usar migrações. Confira as outras páginas nessa seção para obter informações mais detalhadas.

Introdução

Vamos supor que você acabou de concluir seu primeiro aplicativo do EF Core, que contém o seguinte modelo simples:

public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
}

Durante o desenvolvimento, você pode ter usado Criar e descartar APIs para iterar rapidamente, alterando seu modelo conforme necessário; mas agora que seu aplicativo irá para a produção, você precisará de uma maneira de desenvolver o esquema com segurança sem eliminar todo o banco de dados.

Instalar as ferramentas

Primeiro, você precisará instalar as ferramentas de linha de comando do EF Core:

Criar sua primeira migração

Agora você está pronto para adicionar sua primeira migração! Instrua o EF Core a criar uma migração chamada InitialCreate:

dotnet ef migrations add InitialCreate

O EF Core criará um diretório chamado Migrações em seu projeto e gerará alguns arquivos. É uma boa ideia inspecionar o que foi gerado exatamente no EF Core e, possivelmente, corrigi-lo, mas vamos ignorar isso por enquanto.

Criar seu esquema e banco de dados

Neste ponto, você pode fazer com que o EF crie seu banco de dados e seu esquema a partir da migração. Isso pode ser feito por meio do seguinte:

dotnet ef database update

Isso é tudo. O aplicativo está pronto para ser executado no novo banco de dados, e você não precisou escrever nenhuma linha de SQL. Observe que essa maneira de aplicar migrações é ideal para o desenvolvimento local, mas é menos adequada para ambientes de produção. Confira a página Aplicar migrações para obter mais informações.

Desenvolver seu modelo

Alguns dias se passaram e você será solicitado a adicionar um carimbo de data/hora de criação aos seus blogs. Você fez as alterações necessárias em seu aplicativo, e seu modelo agora tem a seguinte aparência:

public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedTimestamp { get; set; }
}

Seu modelo e seu banco de dados de produção agora estão fora de sincronia – precisamos adicionar uma nova coluna ao esquema de banco de dados. Vamos criar uma migração para isso:

dotnet ef migrations add AddBlogCreatedTimestamp

Observe que damos um nome descritivo às migrações para facilitar a compreensão do histórico do projeto mais tarde.

Como essa não é a primeira migração do projeto, o EF Core compara agora seu modelo atualizado com um instantâneo do modelo antigo, antes de adicionar a coluna. O instantâneo do modelo é um dos arquivos gerados pelo EF Core quando você adiciona uma migração e é verificado no controle do código-fonte. Com base nessa comparação, o EF Core detecta que uma coluna foi adicionada e adiciona a migração apropriada.

Agora você pode aplicar sua migração como antes:

dotnet ef database update

Observe que, desta vez, o EF detecta que o banco de dados já existe. Além disso, quando nossa primeira migração foi aplicada acima, esse fato foi registrado em uma tabela de histórico de migrações especiais em seu banco de dados; isso permite que o EF aplique automaticamente apenas a nova migração.

Exclusão de partes do modelo

Às vezes, talvez você queira referenciar tipos de outro DbContext. Isso pode levar a conflitos de migração. Para evitar isso, exclua o tipo das migrações de um dos DbContexts.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<IdentityUser>()
        .ToTable("AspNetUsers", t => t.ExcludeFromMigrations());
}

Próximas etapas

As informações acima foram uma breve introdução às migrações. Confira as outras páginas de documentação para saber mais sobre como gerenciar migrações, aplicá-las e outros aspectos. A referência da ferramenta de CLI do .NET Core também contém informações úteis sobre os diferentes comandos

Recursos adicionais