Repository navigation
Persistencia e Banco de Dados
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/.
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 1erDiagram
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
}
Como ler o diagrama:
-
PK(primary key, chave primária): a coluna que identifica a linha. Aqui, sempre oid. -
FK(foreign key, chave estrangeira): uma coluna que aponta para a chave primária de outra tabela.policies.policyholder_idaponta parapolicyholders.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.
| 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.
| 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 |
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();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.
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.
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 chamaclaimse tem a check constraint do status. -
HasKey: oIdé 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.csnão sabe que existe uma tabelaclaims. 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.
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.
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ó porCreatedAttambém não basta, porque dois cadastros podem ter o mesmo instante; por isso o desempate peloId. -
Os limites são validados antes.
paginaprecisa ser 1 ou mais, etamanhoPaginaentre 1 e 100. Fora disso, a API responde400antes 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.
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.
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 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.
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 aoxmin. Nenhuma coluna nova é criada. A migrationAddConcurrencyTokenstem umAddColumn("xmin")só para manter o modelo do EF atualizado; o Npgsql sabe quexminé 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, oUnitOfWorka transforma emConflictException, 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.
O xmin protege uma linha. Mas algumas regras envolvem duas tabelas. Por exemplo, "não inativar um segurado com apólice em vigor". Imagine:
- A requisição de inativação verifica: o segurado não tem apólices. Pode inativar.
- Ao mesmo tempo, outra requisição emite uma apólice para ele.
- 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
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.
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:
-
É seguro contra SQL injection. Parece uma string interpolada comum, mas o
SqlQuerytransforma cada{...}em um parâmetro SQL (@p0,@p1...). O valor nunca é colado no texto do comando. - É atômico. Verificar e gravar acontecem na mesma instrução; não há janela para outra requisição entrar no meio.
-
O id original é preservado. Na reativação, o id gerado pela entidade nova é descartado, e o
201responde o id antigo, ao qual todo o histórico está ligado. -
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.
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.
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.
| 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:
-
NormalizePhonesToE164não tem volta: a formatação original dos telefones se perdeu. -
AddMoneyPrecisionarredonda 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 parapolicies).
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,ALTEReDROP. 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 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
__EFMigrationsHistorye 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.
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.
O .editorconfig marca a pasta de migrations como código gerado:
[**/Migrations/*.cs]
generated_code = trueAssim, os analisadores de estilo não reclamam de um código que ninguém escreveu à mão.
| 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 |
- Suba o
compose.dev.yml, abra o pgAdmin e rodeSELECT id, status, xmin FROM claims;. Aprove um sinistro pela API e rode de novo: oxminmudou. - No pgAdmin, tente
UPDATE claims SET status = 'Unknown';e leia o erro da check constraint. - Rode
dotnet ef migrations script --idempotent --project src/Backend/PolicyDesk.Infrastructuree leia o SQL de cada migration. - No Aspire Dashboard, abra o trace de uma listagem paginada e encontre as duas consultas: o
COUNTe oSELECTcomLIMIT/OFFSET. - Desafio: leia
ClaimConcurrencyTestse entenda como o teste dispara duas transições do mesmo sinistro ao mesmo tempo e confere que só uma é aceita.
- 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:
datepara 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
xmindetecta 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.
- 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 CONFLICTe colunas de sistema. - Próximo artigo sugerido: Referência da API.
PolicyDesk · Distribuído sob a licença MIT · Repositório
Comece aqui
Como o sistema é feito
A API
Engenharia
Prática
Consulta