Evoluir um site implementado

O EmDash armazena coleções, campos e taxonomias na base de dados, junto ao conteúdo. Implementar código novo não os altera: uma implementação substitui o código do Worker (ou servidor), enquanto o esquema e conteúdo na base de dados permanecem como estão. Esta página explica como alterar o modelo de conteúdo de um site já implementado, usando Cloudflare D1 como exemplo. Os mesmos workflows aplicam-se às outras opções de base de dados.

O que altera o quê

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

O ficheiro seed só participa na terceira linha. É aplicado uma vez, quando a base de dados está vazia e o assistente de configuração não foi completado. Implementar um ficheiro seed alterado contra uma base de dados existente não faz nada — evoluir o esquema de um site em produção acontece sempre através do painel de administração ou da API.

Alterar o esquema no painel de administração

O painel de administração é a forma principal de evoluir um site implementado. Abra Content Types no admin e adicione, edite ou remova coleções e campos. As alterações têm efeito imediato — a API de conteúdo, o loader e a interface de edição leem todos o esquema da base de dados em runtime.

Consulte Coleções & Campos para os tipos de campo disponíveis, regras de validação e opções de widget.

Após alterar o esquema, regenere os tipos TypeScript usados pelos seus templates. O comando emdash types lê o esquema de uma instância em execução, podendo apontar diretamente ao site implementado:

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

Alterar o esquema pela CLI

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

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

Em alternativa, crie um token API no admin sob Settings → API Tokens e passe-o com --token ou a variável de ambiente EMDASH_TOKEN — útil para CI.

Depois 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

Como estes comandos são simples chamadas CLI, podem ser scriptados: uma “migração” repetível para o seu modelo de conteúdo é um script shell de chamadas emdash schema, registado no seu repositório e executado contra cada ambiente sucessivamente.

Consulte a referência CLI para a lista completa de comandos.

Manter o ficheiro seed sincronizado

O ficheiro seed embutido no seu build determina com que uma base de dados nova é inicializada: um novo ambiente de pré-visualização, uma reconstrução de recuperação de desastres, ou uma segunda implementação do mesmo site. Se o seed ainda descreve o blog inicial enquanto a produção evoluiu para algo diferente, cada ambiente novo arranca com o modelo errado.

O build embute o primeiro ficheiro 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 incorporado (o modelo do blog inicial) é embutido, e astro dev regista um aviso.

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

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 definiçõ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 juntamente com o código que depende do novo esquema, para que um ambiente novo arranque sempre com um modelo que o código entende.

Ensaiar alterações num ambiente de pré-visualização

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

Recuperar de um erro

• Um campo foi removido por engano. A coluna e os seus dados desapareceram da base de dados em produção. Restaure a partir de um backup ponto-no-tempo Time Travel do D1, ou readicione o campo e restaure os seus valores a partir de um wrangler d1 export anterior.
• Um ambiente novo arrancou com o modelo errado. O seed embutido estava desatualizado ou em falta. Atualize .emdash/seed.json (veja Manter o ficheiro seed sincronizado), reconstrua e aponte o deploy para uma base de dados vazia para arrancar novamente.
• O esquema e os templates não concordam. Deploys e alterações de esquema são independentes, ordene-os deliberadamente: alterações de esquema aditivas (nova coleção, novo campo opcional) vão primeiro, depois o código que as usa. Para remoções, implemente primeiro o código que deixa de usar o campo, depois remova o campo.