Skip to content

Persistencia e Banco de Dados

rodrigosdk edited this page Nov 11, 2026 · 2 revisions

Persistência e banco de dados: do objeto à tabela

Para quem é este artigo: para quem quer entender como o PolicyDesk guarda os dados, e para quem estuda Entity Framework Core, PostgreSQL e controle de concorrência.

Pré-requisitos: noção do que é uma tabela e um SELECT. O Modelo de Domínio ajuda a entender as classes que vão para o banco.

O que você vai aprender: o que é um ORM, como as classes viram tabelas, a diferença entre consultas rastreadas e não rastreadas, como funciona a paginação, como duas pessoas alterando o mesmo dado ao mesmo tempo são detectadas, o que é um upsert atômico e como as migrations versionam o banco.

Código: src/Backend/PolicyDesk.Infrastructure/DataAccess/.


O problema: objetos e tabelas falam línguas diferentes

No C#, um sinistro é um objeto: tem propriedades, métodos e regras. No banco, um sinistro é uma linha em uma tabela: só colunas com valores. Converter de um para o outro, nos dois sentidos, é um trabalho repetitivo e cheio de detalhes: montar o INSERT, ler cada coluna do SELECT, converter tipos, descobrir o que mudou para montar o UPDATE.

Um ORM (Object-Relational Mapper, mapeador objeto-relacional) faz essa tradução. O PolicyDesk usa o Entity Framework Core (EF Core), o ORM oficial do .NET, com o Npgsql, o "tradutor" específico para PostgreSQL.

Componente Versão Papel
PostgreSQL 17 (Docker), 16 (testes) O banco de dados relacional
Entity Framework Core 10 O ORM: mapeamento, consultas, rastreamento de mudanças e migrations
Npgsql EF Core Provider 10 Gera SQL do dialeto PostgreSQL e dá acesso a recursos próprios dele, como o xmin

Com o EF Core, buscar um sinistro fica assim:

var claim = await dbContext.Claims.FirstOrDefaultAsync(claim => claim.Id == id);

E o EF gera e executa o SQL equivalente:

SELECT c.id, c.policy_id, c.description, ... FROM claims AS c WHERE c.id = @id LIMIT 1

O esquema: como os dados estão organizados

erDiagram
    policyholders ||--o{ policies : "policyholder_id (RESTRICT)"
    policies ||--o{ claims : "policy_id (RESTRICT)"

    policyholders {
        uuid id PK
        varchar_150 name
        varchar_11 cpf UK
        date birth_date
        varchar_254 email "UK parcial: active = TRUE"
        varchar_20 phone "E.164"
        timestamptz created_at
        timestamptz updated_at
        boolean active
        xid xmin "token de concorrência"
    }
    policies {
        uuid id PK
        uuid policyholder_id FK
        varchar_500 description
        numeric_18_2 coverage_amount
        numeric_18_2 premium_amount
        date start_date
        date end_date
        varchar_20 status "CHECK: Active, Cancelled"
        timestamptz cancelled_at
        timestamptz created_at
        timestamptz updated_at
        xid xmin
    }
    claims {
        uuid id PK
        uuid policy_id FK
        varchar_500 description
        numeric_18_2 amount
        date occurred_on
        varchar_20 status "CHECK: Pending, InAnalysis..."
        timestamptz approved_at
        varchar_1000 denial_reason
        timestamptz paid_at
        timestamptz created_at
        timestamptz updated_at
        xid xmin
    }
Loading

Como ler o diagrama:

  • PK (primary key, chave primária): a coluna que identifica a linha. Aqui, sempre o id.
  • FK (foreign key, chave estrangeira): uma coluna que aponta para a chave primária de outra tabela. policies.policyholder_id aponta para policyholders.id.
  • UK (unique key): uma coluna que não pode ter valores repetidos.
  • ||--o{: "um para muitos". Um segurado tem zero ou mais apólices.
  • RESTRICT: o banco impede apagar um segurado que tenha apólices. Nada é apagado em cascata por acidente.

Convenções de nomes

Elemento Convenção Exemplo
Tabelas snake_case, no plural policyholders, claims
Colunas snake_case coverage_amount, occurred_on
Propriedades C# PascalCase CoverageAmount, OccurredOn

O C# e o PostgreSQL têm convenções diferentes, e cada lado segue a sua. O mapeamento traduz um nome para o outro explicitamente (HasColumnName("coverage_amount")). Uma alternativa seria o pacote EFCore.NamingConventions, que faz a conversão automaticamente.

Os tipos de cada coluna, e por quê

Dado Tipo da coluna Por quê
Datas de calendário (birth_date, start_date, end_date, occurred_on) date Um dia, sem horário nem fuso. No C#, DateOnly. Uma vigência "até 31/12" nunca muda de dia por causa de fuso
Instantes (created_at, approved_at, paid_at...) timestamp with time zone Um ponto exato no tempo, sempre gravado em UTC
Dinheiro (coverage_amount, premium_amount, amount) numeric(18,2) Decimal exato, com 2 casas. Nunca use float para dinheiro: em ponto flutuante, 0.1 + 0.2 dá 0.30000000000000004
Status varchar(20) com check constraint Legível e protegido; veja abaixo
Textos varchar(n) O tamanho vem do FieldLimits, o mesmo usado na validação

Dinheiro: por que numeric(18,2)

Sem precisão definida, uma coluna numeric aceitaria qualquer número de casas decimais. Com numeric(18,2), o PostgreSQL arredonda tudo para 2 casas, sem avisar. Se um cliente enviasse 1000.005, o banco gravaria 1000.01, e ninguém perceberia.

Por isso o código valida a mesma regra antes de chegar ao banco (MoneyLimits, explicado no Modelo de Domínio). O cliente recebe um 400 com uma mensagem clara, em vez de ter o valor alterado em silêncio. No mapeamento:

builder.Property(claim => claim.Amount)
    .HasColumnName("amount")
    .HasPrecision(MoneyLimits.Precision, MoneyLimits.Scale)
    .IsRequired();

Status como texto, protegido por check constraint

O status é gravado pelo nome do enum ("InAnalysis"), não por um número. E uma check constraint, uma regra que o próprio banco verifica a cada gravação, garante que só valores válidos entrem:

builder.ToTable("claims", table =>
    table.HasCheckConstraint("CK_claims_status", EnumCheckConstraint.AllowedValues<ClaimStatus>("status")));

internal static class EnumCheckConstraint
{
    public static string AllowedValues<TEnum>(string column) where TEnum : struct, Enum =>
        $"{column} IN ({string.Join(", ", Enum.GetNames<TEnum>().Select(name => $"'{name}'"))})";
}

O método monta a regra a partir do próprio enum: status IN ('Pending', 'InAnalysis', 'Approved', 'Denied', 'Paid'). Um UPDATE claims SET status = 'Unknown', mesmo feito à mão no pgAdmin, é recusado pelo banco.

Bônus: como a regra é gerada a partir do enum, acrescentar um valor ao enum muda o modelo, e o EF Core exige uma migration nova. É impossível esquecer de atualizar a constraint.

Índices

Um índice é uma estrutura auxiliar que o banco mantém para encontrar linhas rapidamente, como o índice remissivo de um livro. Um índice único também impede valores repetidos.

Índice Coluna Tipo Para quê
PK id Único A identidade de cada linha
IX_policyholders_cpf cpf Único Um CPF, um segurado, entre ativos e inativos
IX_policyholders_email_active email Único parcial (WHERE active = TRUE) E-mail único só entre os ativos
FKs policyholder_id, policy_id Comum Acelerar as buscas por relacionamento

O índice parcial merece atenção: ele só considera as linhas que atendem ao WHERE. Um segurado inativo não "ocupa" o e-mail, então outro segurado ativo pode usá-lo. Isso implementa exatamente a regra S7 do negócio, e quem garante é o banco.


O mapeamento: dizendo ao EF como cada classe vira tabela

As entidades não têm nenhuma marcação de banco de dados: nada de [Table], [Column] ou [MaxLength]. Todo o mapeamento fica em classes separadas, uma por entidade, que implementam IEntityTypeConfiguration<T>:

internal class ClaimMap : IEntityTypeConfiguration<Claim>
{
    public void Configure(EntityTypeBuilder<Claim> builder)
    {
        builder.ToTable("claims", table =>
            table.HasCheckConstraint("CK_claims_status", EnumCheckConstraint.AllowedValues<ClaimStatus>("status")));

        builder.HasKey(claim => claim.Id);
        builder.Property(claim => claim.Id).HasColumnName("id").ValueGeneratedNever();
        builder.Property(claim => claim.Description).HasColumnName("description").HasMaxLength(FieldLimits.Description).IsRequired();
        builder.Property(claim => claim.Amount).HasColumnName("amount").HasPrecision(MoneyLimits.Precision, MoneyLimits.Scale).IsRequired();
        builder.Property(claim => claim.OccurredOn).HasColumnName("occurred_on").HasColumnType("date").IsRequired();
        builder.Property(claim => claim.Status).HasColumnName("status").HasConversion<string>().HasMaxLength(FieldLimits.Status).IsRequired();
        // ...
        builder.Property<uint>("Version").IsRowVersion();

        builder.HasOne<Policy>()
            .WithMany()
            .HasForeignKey(claim => claim.PolicyId)
            .OnDelete(DeleteBehavior.Restrict);
    }
}

Lendo linha a linha:

  • ToTable("claims", ...): a tabela se chama claims e tem a check constraint do status.
  • HasKey: o Id é a chave primária.
  • ValueGeneratedNever(): o banco não gera o id; ele já vem pronto da aplicação.
  • HasMaxLength(FieldLimits.Description): o tamanho da coluna vem da mesma constante usada na validação.
  • HasConversion<string>(): o enum é gravado como texto.
  • Property<uint>("Version").IsRowVersion(): o controle de concorrência, explicado mais abaixo.
  • HasOne<Policy>().WithMany()...OnDelete(Restrict): a chave estrangeira para a apólice, sem exclusão em cascata.

Esse estilo se chama Fluent API, por causa das chamadas encadeadas. Por que usá-lo em vez de atributos nas entidades?

  • O domínio continua ignorante de persistência (persistence ignorance): Claim.cs não sabe que existe uma tabela claims. Trocar de banco não toca o domínio.
  • Algumas configurações só existem na Fluent API: filtros globais, índices parciais, check constraints, DeleteBehavior.

O DbContext, a classe central do EF Core, só aplica os mapeamentos:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyConfiguration(new PolicyholderMap());
    modelBuilder.ApplyConfiguration(new PolicyMap());
    modelBuilder.ApplyConfiguration(new ClaimMap());
}

E as entidades com private set e construtores privados? O EF Core consegue preencher propriedades privadas e usar o construtor privado sem parâmetros. O encapsulamento do domínio é mantido sem nenhuma concessão ao ORM.


Rastreamento: o EF Core está vigiando seus objetos

Quando o EF Core carrega uma entidade, por padrão ele a coloca no change tracker ("rastreador de mudanças"): uma lista das entidades carregadas, com uma cópia dos valores originais. No SaveChanges, ele compara os valores atuais com os originais e gera UPDATEs só do que mudou.

Isso é ótimo quando você vai alterar o objeto. É desperdício quando você só vai ler e responder. Por isso o PolicyDesk tem dois tipos de busca:

Método Rastreado? Quando é usado
GetByIdAsync, GetPageAsync, GetByPolicyIdAsync (repositórios de leitura) Não (AsNoTracking()) Só para ler e responder
GetByIdForUpdateAsync (repositórios de alteração) Sim Quando a entidade vai ser alterada e salva
GetByIdIncludingInactiveAsync Sim, de propósito A emissão de apólice altera o segurado que essa busca devolve

Vantagens do AsNoTracking() nas leituras:

  • Desempenho: menos memória e CPU, porque o EF não guarda cópias dos valores originais.
  • Segurança: se um caso de uso de leitura alterasse uma entidade sem querer, e alguém chamasse CommitAsync, nada seria salvo.

O nome do método deixa claro o que se pretende fazer. Veja Design Patterns › Repositórios segregados.


Paginação: não traga a tabela inteira

Uma listagem sem limite devolve todos os registros. Com 10 segurados, tudo bem; com um milhão, a API trava, o banco sofre e o cliente recebe megabytes de JSON que não vai usar. Paginar é devolver os dados em pedaços (páginas), junto com a informação de quantos existem no total.

var totalCount = await query.CountAsync(cancellationToken);
var items = await query
    .OrderBy(policy => policy.CreatedAt)
    .ThenBy(policy => policy.Id)
    .Skip((page - 1) * pageSize)
    .Take(pageSize)
    .ToListAsync(cancellationToken);

return new PagedResult<Policy>(items, totalCount);

São duas consultas: uma conta o total (COUNT), a outra busca a página. Skip pula as linhas das páginas anteriores e Take pega só as da página atual. Na página 3, com 20 itens por página, pula 40 e pega 20. O SQL gerado usa OFFSET 40 LIMIT 20.

Três detalhes importantes:

  • A ordenação precisa ser determinística. Sem ORDER BY, o PostgreSQL não garante ordem nenhuma, e o mesmo registro poderia aparecer em duas páginas, ou em nenhuma. Ordenar só por CreatedAt também não basta, porque dois cadastros podem ter o mesmo instante; por isso o desempate pelo Id.
  • Os limites são validados antes. pagina precisa ser 1 ou mais, e tamanhoPagina entre 1 e 100. Fora disso, a API responde 400 antes de consultar o banco.
  • Paginação por offset tem um custo. Para pular 100.000 linhas, o banco precisa lê-las e descartá-las, então páginas muito altas ficam lentas. Para tabelas enormes, a alternativa é a paginação por cursor (keyset): "me dê os 20 seguintes depois do id X". Para o volume do PolicyDesk, o offset é simples e suficiente.

Concorrência otimista: quando duas pessoas mexem no mesmo dado

O problema: a atualização perdida

Dois analistas abrem o mesmo sinistro, em análise, ao mesmo tempo. Um clica em "aprovar"; o outro, em "negar". Sem nenhum controle, aconteceria isto:

sequenceDiagram
    participant A as Analista A
    participant DB as Banco
    participant B as Analista B

    A->>DB: lê o sinistro (EmAnalise)
    B->>DB: lê o sinistro (EmAnalise)
    A->>DB: grava Aprovado
    B->>DB: grava Negado
    Note over DB: O sinistro fica Negado.<br/>A aprovação de A se perdeu sem ninguém saber.
Loading

Isso se chama atualização perdida (lost update). Cada analista, isoladamente, fez algo válido, mas o resultado final é inconsistente: o sistema disse para A que a aprovação deu certo.

A solução: a versão da linha

A ideia é simples: ao ler um registro, guarde a versão dele. Ao gravar, diga ao banco: "atualize só se a versão ainda for a que eu li". Se outra pessoa gravou no meio, a versão mudou, a atualização não acontece, e você fica sabendo.

Essa técnica se chama concorrência otimista. "Otimista" porque não bloqueia nada: supõe que conflitos são raros e só os detecta quando acontecem. A alternativa, pessimista, bloqueia o registro na leitura (SELECT ... FOR UPDATE), e quem chega depois espera.

Como o PolicyDesk faz isso: xmin

O PostgreSQL já mantém uma versão para cada linha, de graça: a coluna de sistema xmin, que guarda o número da transação que gravou aquela versão da linha. Todo UPDATE muda o xmin. O Npgsql permite usar essa coluna como token de concorrência:

builder.Property<uint>("Version").IsRowVersion();
  • Version é uma shadow property: existe no modelo do EF Core, mas não na classe C#. O domínio nem sabe que ela existe.
  • O Npgsql reconhece a combinação uint + IsRowVersion() e a liga ao xmin. Nenhuma coluna nova é criada. A migration AddConcurrencyTokens tem um AddColumn("xmin") só para manter o modelo do EF atualizado; o Npgsql sabe que xmin é coluna de sistema e não gera SQL para ela.

Na hora de salvar, o EF Core gera:

UPDATE claims
SET status = @p0, approved_at = @p1, updated_at = @p2
WHERE id = @p3 AND xmin = @p4      -- @p4 = o xmin lido no SELECT
RETURNING xmin;
  • 1 linha afetada: ninguém mexeu no meio. Sucesso, e o novo xmin é lido de volta.
  • 0 linhas afetadas: alguém gravou depois da leitura. O EF lança DbUpdateConcurrencyException, o UnitOfWork a transforma em ConflictException, e a API responde 409 Conflict.
catch (DbUpdateConcurrencyException)
{
    throw new ConflictException(ResourcesMessageException.CONCURRENCY_CONFLICT);
}

No exemplo dos dois analistas, o segundo a gravar recebe 409 com a mensagem "O registro foi alterado por outra operação. Consulte novamente e repita a solicitação". Ele relê o sinistro, vê que já foi aprovado, e decide o que fazer.

Protegendo regras que envolvem duas tabelas

O xmin protege uma linha. Mas algumas regras envolvem duas tabelas. Por exemplo, "não inativar um segurado com apólice em vigor". Imagine:

  1. A requisição de inativação verifica: o segurado não tem apólices. Pode inativar.
  2. Ao mesmo tempo, outra requisição emite uma apólice para ele.
  3. A inativação grava. Agora existe um segurado inativo com uma apólice ativa.

As duas operações gravaram em tabelas diferentes (policyholders e policies), então nenhum xmin detectou o conflito.

A solução é fazer a emissão da apólice também gravar na linha do segurado:

// RegisterPolicyUseCase
var policyholder = await policyholdersUpdateOnlyRepository.GetByIdIncludingInactiveAsync(...);  // rastreado
// ...
policyholder.RegisterPolicy();          // muda o UpdatedAt: o segurado entra no UPDATE
await policiesWriteOnlyRepository.AddAsync(policy);
await unitOfWork.CommitAsync(cancellationToken);

Agora as duas operações disputam a mesma linha de policyholders, e o xmin faz uma delas falhar:

sequenceDiagram
    participant E as Emissão de apólice
    participant DB as policyholders (xmin=100)
    participant I as Inativação

    E->>DB: SELECT (xmin=100, active=true)
    I->>DB: SELECT (xmin=100)
    I->>DB: verifica apólices: nenhuma
    E->>DB: INSERT policy + UPDATE policyholder WHERE xmin=100
    Note over DB: xmin vira 101
    I->>DB: UPDATE policyholder SET active=false WHERE xmin=100
    DB-->>I: 0 linhas: 409 Conflict
Loading

Qualquer que seja a ordem, só uma conclui. Se a inativação gravar primeiro, a emissão falha com 409 e a apólice não é gravada, porque o INSERT está na mesma transação do UPDATE que falhou.

O cadastro de sinistro usa a mesma técnica para o saldo da cobertura: policy.RegisterClaim(...) toca a apólice, que foi carregada rastreada. Dois sinistros simultâneos que, somados, passariam da cobertura disputam a mesma linha de policies, e só um é gravado. A soma vem de uma consulta agregada:

return dbContext.Claims
    .Where(claim => claim.PolicyId == policyId && claim.Status != ClaimStatus.Denied)
    .SumAsync(claim => claim.Amount, cancellationToken);

Uma explicação conceitual mais longa, com alternativas, está em Design Patterns › Optimistic Offline Lock.


Upsert atômico: cadastrar ou reativar em um único passo

A regra S8 diz que cadastrar o CPF de um segurado inativo deve reativá-lo. O jeito ingênuo seria:

var existente = await buscarPorCpf(cpf);
if (existente is null) inserir(novo);
else if (!existente.Active) reativar(existente);
else erro("CPF já cadastrado");

O problema: entre o "buscar" e o "inserir", outra requisição pode cadastrar o mesmo CPF. As duas acham que o CPF não existe, e as duas tentam inserir. Esse tipo de defeito, que depende do tempo exato entre duas operações, se chama condição de corrida (race condition).

O PolicyDesk resolve com uma única instrução SQL que verifica e grava ao mesmo tempo, chamada de upsert (update + insert):

savedIds = await dbContext.Database.SqlQuery<Guid>($"""
    INSERT INTO policyholders
        (id, name, cpf, birth_date, email, phone, created_at, updated_at, active)
    VALUES
        ({policyholder.Id}, {policyholder.Name}, {policyholder.Cpf}, {policyholder.BirthDate},
         {policyholder.Email}, {policyholder.Phone}, {policyholder.CreatedAt}, {policyholder.UpdatedAt},
         {policyholder.Active})
    ON CONFLICT (cpf) DO UPDATE
    SET name = EXCLUDED.name,
        birth_date = EXCLUDED.birth_date,
        email = EXCLUDED.email,
        phone = EXCLUDED.phone,
        active = TRUE,
        updated_at = CURRENT_TIMESTAMP
    WHERE policyholders.active = FALSE
    RETURNING id AS "Value"
    """).ToListAsync(cancellationToken);

Lendo em português: "tente inserir. Se já existir uma linha com esse CPF (ON CONFLICT (cpf)), atualize-a com os dados novos (EXCLUDED são os valores que se tentou inserir), mas só se ela estiver inativa (WHERE ... active = FALSE). Em qualquer caso, devolva o id da linha gravada (RETURNING id)".

Situação O que o banco faz O que volta Resultado
CPF novo INSERT O id novo Cadastrado
CPF de um inativo UPDATE (reativa) O id original Reativado
CPF de um ativo Nada (o WHERE falha) Nenhuma linha "Já existe um segurado ativo com este CPF"
E-mail de outro ativo Erro 23505 no índice de e-mail Exceção "Já existe um segurado ativo com este e-mail"

Pontos para estudar:

  1. É seguro contra SQL injection. Parece uma string interpolada comum, mas o SqlQuery transforma cada {...} em um parâmetro SQL (@p0, @p1...). O valor nunca é colado no texto do comando.
  2. É atômico. Verificar e gravar acontecem na mesma instrução; não há janela para outra requisição entrar no meio.
  3. O id original é preservado. Na reativação, o id gerado pela entidade nova é descartado, e o 201 responde o id antigo, ao qual todo o histórico está ligado.
  4. A entidade continua validando. O new Policyholder(...) acontece antes, no caso de uso. O SQL escrito à mão não pula nenhuma regra.

O custo: é SQL específico do PostgreSQL, fora do change tracker. É uma troca consciente: a garantia de atomicidade vale mais que a portabilidade.


Soft delete e filtro global

Segurados inativos não são apagados (veja Entendendo o negócio), mas também não devem aparecer nas consultas. Colocar .Where(p => p.Active) em toda consulta seria repetitivo, e um dia alguém esqueceria. O EF Core resolve com um filtro global:

builder.HasQueryFilter(ActiveFilter, policyholder => policyholder.Active);

A partir disso, toda consulta LINQ aos segurados recebe um WHERE active = TRUE automático. Quando é preciso ver os inativos, o filtro é desligado pelo nome, de forma explícita:

.IgnoreQueryFilters([PolicyholderMap.ActiveFilter])

Dois detalhes:

  • O filtro não vale para SQL escrito à mão (SqlQuery). Por isso o upsert enxerga os inativos e consegue reativá-los.
  • A verificação de apólice em vigor (HasActiveOrFuturePolicyAsync) consulta a tabela de apólices, que não tem filtro. Ela recebe o dia de hoje como parâmetro, calculado no fuso de negócio pelo caso de uso.

Migrations: versionando a estrutura do banco

O problema

O código evolui: uma propriedade nova, um tamanho de coluna diferente. O banco precisa acompanhar. Se cada pessoa alterar o banco à mão, ninguém sabe em que versão cada ambiente está, e o deploy vira loteria.

Uma migration é um arquivo de código que descreve uma mudança no banco, com um método Up (aplicar) e um Down (desfazer). As migrations ficam no Git, em ordem, como commits do banco. O EF Core guarda em uma tabela (__EFMigrationsHistory) quais já foram aplicadas, e aplica só as que faltam.

O histórico do PolicyDesk

Migration Data O que faz
InitialCreate 2026-10-22 Cria a tabela policyholders
CreatePolicies 2026-10-23 Cria policies e a chave estrangeira para segurados
CreateClaims 2026-11-01 Cria claims e a chave estrangeira para apólices
AddConcurrencyTokens 2026-11-02 Mapeia o xmin como token de concorrência nas três tabelas
RemoveUnusedActiveColumns 2026-11-02 Remove colunas active sem uso de apólices e sinistros
AddTextFieldMaxLengths 2026-11-03 Limita o tamanho das colunas de texto, a partir de FieldLimits
NormalizePhonesToE164 2026-11-04 Converte os telefones antigos para o formato E.164. Irreversível
AddMoneyPrecision 2026-11-07 Colunas de dinheiro em numeric(18,2)
StoreStatusAsText 2026-11-08 Status como texto; converte os números existentes (o Down volta aos números)
AddStatusCheckConstraints 2026-11-08 Cria CK_policies_status e CK_claims_status

Algumas migrations alteram dados, não só a estrutura, e merecem cuidado:

  • NormalizePhonesToE164 não tem volta: a formatação original dos telefones se perdeu.
  • AddMoneyPrecision arredonda para 2 casas os valores que tinham mais, e falha se algum valor tiver mais de 16 dígitos inteiros. Antes de aplicar em um banco com dados, confira: SELECT amount FROM claims WHERE amount <> round(amount, 2) (e o equivalente para policies).

Quem aplica as migrations, e quando

if (!app.Environment.IsProduction())
{
    await ExecuteMigrationsAsync();
}
Ambiente Como as migrations são aplicadas
Development e Testing Automaticamente, quando a API sobe
Production Por um passo explícito do pipeline de deploy, antes de publicar a nova versão

Por que não aplicar automaticamente em produção também?

  • Várias instâncias ao mesmo tempo. Com duas ou três cópias da API subindo juntas, todas tentariam aplicar a mesma migration.
  • Menos permissões para a aplicação. Para alterar tabelas, o usuário do banco precisaria de permissão de CREATE, ALTER e DROP. Se a aplicação for invadida, o estrago possível é muito maior.
  • Controle. Migrations que alteram dados devem ser revisadas e aplicadas de propósito, com backup, e não como efeito colateral de um deploy.

O migrations bundle

O pipeline de deploy gera um migrations bundle: um único executável, autocontido (com o runtime do .NET dentro), que aplica todas as migrations pendentes.

dotnet ef migrations bundle --self-contained -r linux-x64 \
  --project src/Backend/PolicyDesk.Infrastructure \
  --startup-project src/Backend/PolicyDesk.Infrastructure \
  --output efbundle

./efbundle --connection "$DB_CONNECTION"
  • Não precisa do SDK nem do código-fonte onde roda: é o mesmo arquivo gerado e testado no CI.
  • É idempotente: consulta o __EFMigrationsHistory e aplica só o que falta. Rodar duas vezes não causa problema.
  • Roda antes de publicar a API. Isso exige que cada migration seja compatível com a versão anterior da API, que continua no ar por alguns segundos. Remover ou renomear uma coluna é feito em duas entregas: primeiro, a API para de usar a coluna; depois, a migration a remove. Essa técnica se chama expand/contract.

Detalhes do pipeline em CI/CD e Deploy.

Migrations sem banco: a DesignTimeDbContextFactory

internal class DesignTimeDbContextFactory : IDesignTimeDbContextFactory<PolicyDeskDbContext>
{
    private const string ReferenceConnectionString = "Host=localhost;Port=5432;Database=PolicyDesk";

    public PolicyDeskDbContext CreateDbContext(string[] args)
    {
        var connectionString = Environment.GetEnvironmentVariable("ConnectionStrings__DbConnection");
        // ...
    }
}

O dotnet ef precisa de um DbContext para trabalhar. Sem essa classe, ele tentaria subir a API inteira, com toda a configuração. Com ela, os comandos migrations add, migrations script e migrations bundle funcionam sem banco e sem o projeto da API, porque não abrem conexão. Os comandos que conectam (como database update) usam a variável de ambiente, se definida.

Migrations são código gerado

O .editorconfig marca a pasta de migrations como código gerado:

[**/Migrations/*.cs]
generated_code = true

Assim, os analisadores de estilo não reclamam de um código que ninguém escreveu à mão.


Boas práticas aplicadas, em resumo

Prática Onde
Limites de tamanho iguais na validação e no banco FieldLimits usado em HasMaxLength
Precisão monetária igual na validação e no banco MoneyLimits usado em HasPrecision
Datas de calendário como DateOnly ↔ date Todas as entidades
Enums como texto, protegidos por check constraint PolicyStatus, ClaimStatus
Chaves estrangeiras sem cascata Todos os relacionamentos
Id gerado pela aplicação Todas as entidades
Leituras sem rastreamento Repositórios de leitura
Listagens paginadas com ordem determinística Segurados e apólices
CancellationToken em todas as consultas Todos os repositórios
Resultados materializados (ToListAsync), nunca IQueryable Todos os repositórios

Experimente

  1. Suba o compose.dev.yml, abra o pgAdmin e rode SELECT id, status, xmin FROM claims;. Aprove um sinistro pela API e rode de novo: o xmin mudou.
  2. No pgAdmin, tente UPDATE claims SET status = 'Unknown'; e leia o erro da check constraint.
  3. Rode dotnet ef migrations script --idempotent --project src/Backend/PolicyDesk.Infrastructure e leia o SQL de cada migration.
  4. No Aspire Dashboard, abra o trace de uma listagem paginada e encontre as duas consultas: o COUNT e o SELECT com LIMIT/OFFSET.
  5. Desafio: leia ClaimConcurrencyTests e entenda como o teste dispara duas transições do mesmo sinistro ao mesmo tempo e confere que só uma é aceita.

Resumo

  • O EF Core traduz objetos em tabelas; o mapeamento fica fora do domínio, com a Fluent API.
  • Os tipos das colunas espelham as regras: date para datas, numeric(18,2) para dinheiro, texto com check constraint para status.
  • Leituras usam AsNoTracking; alterações usam consultas rastreadas.
  • Listagens são paginadas com ordem determinística.
  • A concorrência otimista com xmin detecta atualizações perdidas; tocar a linha "pai" estende a proteção a regras entre tabelas.
  • O upsert cadastra ou reativa em uma instrução atômica.
  • Migrations versionam o banco; em produção, um bundle as aplica antes do deploy.

Para aprofundar

  • Documentação do EF Core: "Handling Concurrency Conflicts" e "Global Query Filters".
  • Patterns of Enterprise Application Architecture, Martin Fowler: capítulos sobre Optimistic Offline Lock e Unit of Work.
  • Documentação do PostgreSQL: INSERT ... ON CONFLICT e colunas de sistema.
  • Próximo artigo sugerido: Referência da API.

Clone this wiki locally