Evoluir o esquema de um site implantado

EmDash armazena coleções, campos e taxonomias no banco de dados junto ao conteúdo. Use este guia para alterar o modelo de conteúdo em produção sem confundi-lo com um deploy de código, um seeding inicial ou uma migração core do EmDash. Os exemplos usam Cloudflare D1; a mesma separação se aplica a cada adaptador de banco de dados.

O que muda o quê

Um site passa por quatro workflows distintos. Cada um toca uma camada diferente:

Workflow	O que muda	Como
Edição de conteúdo	Entradas, mídia, configurações	Painel de admin ou API de conteúdo
Deploy de código	Templates, config, versão EmDash	`wrangler deploy` — pode migrar tabelas de BD gerenciadas pelo EmDash
Bootstrap inicial	Tudo, a partir do zero	Migrações + arquivo seed + assistente de configuração, automático na primeira inicialização
Evolução do esquema	Coleções, campos, taxonomias	Painel de admin ou `emdash schema` contra o site em produção (esta página)

O arquivo seed só participa na terceira linha. É aplicado uma vez, quando o banco de dados está vazio e o assistente de configuração não foi concluído. Implantar um arquivo seed alterado contra um banco de dados existente não faz nada — evoluir o esquema de um site em produção sempre acontece pelo painel de admin ou pela API.

Alterar o esquema no painel de admin

O painel de admin é a forma principal de evoluir um site implantado. Abra Content Types no admin e adicione, edite ou remova coleções e campos. As alterações entram em vigor imediatamente — a API de conteúdo, o loader e a interface de edição leem o esquema do banco de dados em tempo de execução.

Veja Coleções e campos para os tipos de campo disponíveis, regras de validação e opções de widgets.

Após alterar o esquema, regenere os tipos TypeScript que seus templates usam. O comando emdash types lê o esquema de uma instância em execução, então pode apontar diretamente para o site implantado:

npx emdash types --url https://example.com

Alterar o esquema pela CLI

Os comandos emdash schema comunicam-se com uma instância em execução pela sua API REST, então funcionam contra um site implantado da mesma forma que contra o dev local. Autentique-se uma vez com o fluxo de dispositivo:

npx emdash login --url https://example.com

Alternativamente, crie um token de API no admin em Configurações → Tokens de API e passe-o com --token ou a variável de ambiente EMDASH_TOKEN — útil para CI.

Então evolua o esquema com os mesmos comandos que usaria localmente:

npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com
npx emdash schema remove-field posts legacy_field --url https://example.com
npx emdash schema create projects --label Projects --url https://example.com

Esses comandos podem ser registrados em um script para que cada ambiente receba a mesma alteração ordenada. Os comandos não são automaticamente idempotentes: reexecutar create ou add-field contra um objeto que já existe pode falhar. Inspecione o alvo com emdash schema list ou get, registre qual ambiente completou cada passo e pare no primeiro erro.

Veja a referência da CLI para a lista completa de comandos.

Manter o arquivo seed sincronizado

O arquivo seed embutido no seu build determina com o que um banco de dados novo é inicializado: um novo ambiente de preview, uma reconstrução de recuperação de desastres ou uma segunda implantação do mesmo site. Se o seed ainda descreve o blog inicial enquanto a produção evoluiu para outra coisa, cada ambiente novo é inicializado com o modelo errado.

O build embute o primeiro arquivo seed encontrado em .emdash/seed.json, o caminho em package.json#emdash.seed ou seed/seed.json. Se nenhum estiver presente, um seed padrão embutido (o modelo do blog inicial) é embutido e astro dev registra um aviso.

Após evoluir o esquema de um site implantado, exporte o modelo em produção de volta ao seu repositório. emdash export-seed lê um arquivo SQLite local e wrangler d1 export produz um do banco de dados D1 implantado:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
sqlite3 prod.db < prod.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

O seed exportado contém as configurações, coleções, taxonomias, menus e áreas de widgets do site em produção. Adicione --with-content para incluir entradas. Faça commit do .emdash/seed.json atualizado junto com o código que depende do novo esquema, para que um ambiente novo sempre seja inicializado com um modelo que o código entende.

Ensaiar alterações em um ambiente de preview

Uma alteração destrutiva de esquema (remover um campo, reestruturar uma coleção) é mais segura quando ensaiada contra uma cópia descartável da produção.

Crie um banco de dados D1 de preview separado e deixe o Wrangler adicioná-lo ao ambiente preview:
```
npx wrangler d1 create emdash-db-preview \
  --binding DB --env preview --update-config
```
Confirme que env.preview.d1_databases contém o novo nome do banco de dados e o UUID. Bindings não são herdados da configuração Wrangler de nível superior.

Exporte a produção, então importe o SQL pelo binding DB do ambiente de preview:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
npx wrangler d1 execute DB --env preview --remote --file=./prod.sql

Construa o projeto, implante-o no ambiente de preview, então execute a alteração de esquema contra a URL de preview:

npm run build
npx wrangler deploy --env preview
npx emdash schema remove-field posts legacy_field --url https://preview.example.com

Verifique as páginas públicas, formulários do admin, tipos gerados e qualquer template que leia os campos alterados. Faça um backup fresco do banco de dados de produção, então execute os mesmos comandos uma vez contra a produção.

Recuperar de um erro

Um campo foi removido por engano. A coluna e seus dados desapareceram do banco de dados em produção. Restaure de um ponto de backup D1 Time Travel, ou readicione o campo e restaure seus valores de um wrangler d1 export anterior.
Um ambiente novo foi inicializado com o modelo errado. O seed embutido estava desatualizado ou ausente. Atualize .emdash/seed.json (veja Manter o arquivo seed sincronizado), reconstrua e aponte o deploy para um banco de dados vazio para inicializar novamente.
O esquema e os templates não concordam. Deploys e alterações de esquema são independentes, então ordene-os deliberadamente: alterações aditivas de esquema (nova coleção, novo campo opcional) primeiro, depois o código que os usa. Para remoções, implante primeiro o código que para de usar o campo, depois remova o campo.