Visão geral das migraçõesMigrations Overview

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.In real world projects, data models change as features get implemented: new entities or properties are added and removed, and database schemas needs to be changed accordingly to be kept in sync with the application. 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.The migrations feature in EF Core provides a way to incrementally update the database schema to keep it in sync with the application's data model while preserving existing data in the database.

Em um nível alto, as migrações funcionam da seguinte maneira:At a high level, migrations function in the following way:

  • Quando uma alteração de modelo de dados é introduzida, o desenvolvedor usa ferramentas de 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. 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.When a data model change is introduced, the developer uses EF Core tools to add a corresponding migration describing the updates necessary to keep the database schema in sync. EF Core compares the current model against a snapshot of the old model to determine the differences, and generates migration source files; the files can be tracked in your project's source control like any other source file.
  • Após a geração de uma nova migração, ela pode ser aplicada a um banco de dados de várias maneiras.Once a new migration has been generated, it can be applied to a database in various ways. EF Core registra todas as migrações aplicadas em uma tabela de histórico especial, permitindo que ela saiba quais migrações foram aplicadas e quais não.EF Core records all applied migrations in a special history table, allowing it to know which migrations have been applied and which haven't.

O restante desta página é um guia para iniciantes para o uso de migrações.The rest of this page is a step-by-step beginner's guide for using migrations. Consulte as outras páginas desta seção para obter informações mais detalhadas.Consult the other pages in this section for more in-depth information.

IntroduçãoGetting started

Vamos supor que você acabou de concluir seu primeiro EF Core aplicativo, que contém o seguinte modelo simples:Let's assume you've just completed your first EF Core application, which contains the following simple model:

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

Durante o desenvolvimento, você pode ter usado as APIs criar e soltar para iterar rapidamente, alterando seu modelo conforme necessário; Mas agora que seu aplicativo vai para a produção, você precisa de uma maneira de desenvolver o esquema com segurança sem remover todo o banco de dados.During development, you may have used the Create and Drop APIs to iterate quickly, changing your model as needed; but now that your application is going to production, you need a way to safely evolve the schema without dropping the entire database.

Instalar as ferramentasInstall the tools

Primeiro, você precisará instalar as ferramentas de linha de comando EF Core:First, you'll have to install the EF Core command-line tools:

Crie sua primeira migraçãoCreate your first migration

Agora você está pronto para adicionar sua primeira migração!You're now ready to add your first migration! Instrua EF Core a criar uma migração chamada InitialCreate:Instruct EF Core to create a migration named InitialCreate:

dotnet ef migrations add InitialCreate

EF Core criará um diretório chamado migrações em seu projeto e gerará alguns arquivos.EF Core will create a directory called Migrations in your project, and generate some files. É uma boa ideia inspecionar o que exatamente EF Core gerado – e possivelmente corrigi-lo, mas vamos ignorar isso por enquanto.It's a good idea to inspect what exactly EF Core generated - and possibly amend it - but we'll skip over that for now.

Criar seu banco de dados e esquemaCreate your database and schema

Neste ponto, você pode fazer com que o EF crie seu banco de dados e crie seu esquema a partir da migração.At this point you can have EF create your database and create your schema from the migration. Isso pode ser feito por meio do seguinte:This can be done via the following:

dotnet ef database update

Isso é tudo o que o aplicativo está pronto para ser executado no novo banco de dados, e você não precisa escrever uma única linha de SQL.That's all there is to it - your application is ready to run on your new database, and you didn't need to write a single line of SQL. Observe que essa maneira de aplicar migrações é ideal para o desenvolvimento local, mas é menos adequada para ambientes de produção – consulte a página aplicando migrações para obter mais informações.Note that this way of applying migrations is ideal for local development, but is less suitable for production environments - see the Applying Migrations page for more info.

Desenvolvendo seu modeloEvolving your model

Alguns dias passaram e você será solicitado a adicionar um carimbo de data/hora de criação aos seus Blogs.A few days have passed, and you're asked to add a creation timestamp to your blogs. Você fez as alterações necessárias em seu aplicativo, e seu modelo agora tem a seguinte aparência:You've done the necessary changes to your application, and your model now looks like this:

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 seu esquema de banco de dados.Your model and your production database are now out of sync - we must add a new column to your database schema. Vamos criar uma nova migração para isso:Let's create a new migration for this:

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.Note that we give migrations a descriptive name, to make it easier to understand the project history later.

Como essa não é a primeira migração do projeto, EF Core agora compara seu modelo atualizado com um instantâneo do modelo antigo, antes da adição da coluna; o instantâneo do modelo é um dos arquivos gerados por EF Core quando você adiciona uma migração e é verificado no controle do código-fonte.Since this isn't the project's first migration, EF Core now compares your updated model against a snapshot of the old model, before the column was added; the model snapshot is one of the files generated by EF Core when you add a migration, and is checked into source control. Com base nessa comparação, EF Core detecta que uma coluna foi adicionada e adiciona a migração apropriada.Based on that comparison, EF Core detects that a column has been added, and adds the appropriate migration.

Agora você pode aplicar sua migração como antes:You can now apply your migration as before:

dotnet ef database update

Observe que, desta vez, o EF detecta que o banco de dados já existe.Note that this time, EF detects that the database already exists. 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 a nova migração.In addition, when our first migration was applied above, this fact was recorded in a special migrations history table in your database; this allows EF to automatically apply only the new migration.

Próximas etapasNext steps

A seguir foi apenas uma breve introdução às migrações.The above was only a brief introduction to migrations. Consulte as outras páginas de documentação para saber mais sobre como gerenciar migrações, aplicá-lase outros aspectos.Please consult the other documentation pages to learn more about managing migrations, applying them, and other aspects. A referência de ferramenta de CLI do .NET Core também contém informações úteis sobre os diferentes comandosThe .NET Core CLI tool reference also contains useful information on the different commands