Evoluir o esquema de um site implantado

O EmDash armazena coleções, campos e taxonomias no banco de dados, ao lado do conteúdo. Use este guia para alterar esse modelo de conteúdo em produção sem confundi-lo com uma implantação de código, um seed inicial ou uma migração do núcleo do EmDash. Os exemplos usam o Cloudflare D1; a mesma separação vale para todo adaptador de banco de dados.

O que muda o quê

Um site passa por quatro fluxos de trabalho distintos. Cada um afeta uma camada diferente:

O arquivo seed só participa da terceira linha. Seu esquema e sua estrutura são aplicados uma vez, na primeira requisição, antes de o assistente de configuração ser concluído. Implantar um arquivo seed alterado em um banco de dados existente não faz nada: a evolução do esquema de um site em produção sempre acontece pelo painel de administração ou pela API.

Alterar o esquema no painel de administração

O painel de administração é a principal forma de evoluir um site implantado. Abra Content Types no administrador 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.

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

Depois de alterar o esquema, gere novamente os tipos TypeScript usados pelos seus templates. 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 se comunicam com uma instância em execução pela API REST, então funcionam em um site implantado do mesmo jeito que funcionam no desenvolvimento local. Autentique-se uma vez com o device flow:

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

Como alternativa, crie um token de API no administrador em Settings → API Tokens e passe-o com --token ou com a variável de ambiente EMDASH_TOKEN, o que é útil para CI.

Depois evolua o esquema com os mesmos comandos que você 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 versionados em um script para que cada ambiente receba a mesma alteração ordenada. Os comandos não são idempotentes automaticamente: executar create ou add-field novamente em um objeto que já existe pode falhar. Inspecione o destino com emdash schema list ou get, registre qual ambiente concluiu cada etapa e pare no primeiro erro.

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

Manter o arquivo seed sincronizado

O arquivo seed incorporado ao 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, todo ambiente novo faz o bootstrap com o modelo errado.

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

Depois de evoluir o esquema de um site implantado, exporte o modelo em produção de volta para o seu repositório. O emdash export-seed lê um arquivo SQLite local. Crie os arquivos SQL conforme descrito em Criar um dump D1 offsite, carregue as tabelas e as linhas em um banco de dados local e exporte o seed:

sqlite3 prod.db < backup-schema.sql
sqlite3 prod.db < backup-folders.sql
sqlite3 prod.db < backup-data.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

O seed exportado contém as configurações, as coleções, as taxonomias, os menus, os redirecionamentos, as áreas de widgets e as seções do site em produção. Adicione --with-content para incluir as entradas. Faça o commit do .emdash/seed.json atualizado junto com o código que depende do novo esquema, para que um ambiente novo sempre faça o bootstrap 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 de ensaiar em uma cópia descartável da produção.

Recuperar de um erro

• Um campo foi removido por engano. A coluna e seus dados sumiram do banco de dados em produção. Restaure a partir de um backup de ponto no tempo com o Time Travel do D1, ou adicione o campo novamente e restaure seus valores a partir de um dump D1 offsite anterior.
• Um ambiente novo fez o bootstrap com o modelo errado. O seed incorporado estava desatualizado ou ausente. Atualize o .emdash/seed.json (consulte Manter o arquivo seed sincronizado), faça o build novamente e aponte a implantação para um banco de dados vazio para refazer o bootstrap.
• O esquema e os templates não concordam. As implantações e as alterações de esquema são independentes, então ordene-as de forma deliberada: as alterações aditivas de esquema (nova coleção, novo campo opcional) vêm primeiro, depois o código que as usa. Para remoções, implante primeiro o código que deixa de usar o campo e só depois remova o campo.