Gerenciar alterações no esquema do banco de dados em diferentes ambientes WordPress costuma ser uma tarefa sujeita a erros e demorada. Uma única query SQL mal posicionada ou uma modificação esquecida no banco de dados pode quebrar o site durante uma implantação. Além disso, ações como scripts SQL manuais e edições diretas não oferecem controle de versão, registros de auditoria nem coordenação entre ambientes.
Uma solução para isso é utilizar o Radicle (especificamente o Acorn), que leva as migrações do Laravel para o WordPress. Com isso, você passa a ter alterações no banco de dados versionadas, implantadas junto com o código, controle automático do que já foi executado e a capacidade de reverter modificações no esquema quando necessário.
Ao combinar isso com a infraestrutura e as ferramentas da Kinsta, você obtém uma forma de automatizar a execução de migrações durante as implantações.
Por que as alterações no banco de dados do WordPress precisam de controle de versão
As modificações manuais no banco de dados tratam mudanças de esquema como operações isoladas, e não como código versionado. Por exemplo, executar uma query SQL para criar uma tabela personalizada, usar um comando ALTER TABLE para adicionar colunas ou depender de hooks de ativação de plugins para aplicar atualizações. Essas abordagens funcionam inicialmente, mas falham quando você gerencia vários ambientes ou trabalha em equipe.
Os ambientes de teste geralmente começam a divergir dos ambientes locais quando você se esquece de documentar alterações menores (como adicionar uma coluna ao banco de dados local), o que também causa falhas nas implantações de produção. Isso também significa que não há um registro de auditoria.
As migrações do Laravel resolvem esses problemas ao tratar mudanças no banco de dados como código versionado que vive no seu repositório Git. Esse código é implantado junto com a aplicação e executado na mesma ordem em todos os ambientes.
Como funcionam as migrações do Laravel no WordPress com o Acorn
As migrações do Laravel são arquivos PHP que definem alterações no esquema do banco de dados por meio de dois métodos: up() aplica as alterações e down() as reverte. Cada arquivo de migração recebe um prefixo de registro de data e hora que determina a ordem de execução. O Acorn, da Roots, traz esse sistema de migrações e outros recursos para o WordPress sem exigir uma instalação completa do Laravel.
O sistema de migração rastreia quais alterações foram executadas usando uma tabela migrations em seu banco de dados do WordPress. Quando você executa wp acorn migrate, o Acorn realiza algumas tarefas:
- Verifica a tabela para identificar migrações pendentes.
- Executa as migrações em ordem cronológica com base nos registros de data e hora.
- Registra cada migração bem-sucedida.
Esse rastreamento impede que migrações sejam executadas mais de uma vez e mostra exatamente quais alterações de esquema foram aplicadas em cada ambiente.
O Acorn integra o construtor de esquemas do Laravel, que oferece uma sintaxe PHP fluida e expressiva para criar e modificar tabelas do banco de dados. Em vez de escrever SQL bruto, você utiliza métodos como $table->string('key')->unique() ou $table->json('value')->nullable(). Essa abordagem fornece sintaxe independente de banco de dados, segurança de tipos e código mais legível do que instruções SQL com strings concatenadas manualmente.
Criando e executando sua primeira migração
Você cria migrações usando o WP-CLI:
wp acorn make:migration create_app_settings_tableIsso gera um novo arquivo de migração no diretório database/migrations/ com o registro de data e hora atual e o nome que você especificou:
<?php
use IlluminateDatabaseMigrationsMigration;
use IlluminateDatabaseSchemaBlueprint;
use IlluminateSupportFacadesSchema;
return new class extends Migration
{
public function up(): void
{
Schema::create('app_settings', function (Blueprint $table) {
$table->id();
$table->string('key')->unique();
$table->json('value')->nullable();
$table->string('group')->default('general');
$table->boolean('is_public')->default(false);
$table->text('description')->nullable();
$table->timestamps();
$table->index('group');
$table->index('is_public');
});
}
public function down(): void
{
Schema::dropIfExists('app_settings');
}
};O método up() cria a tabela com colunas para armazenar pares chave-valor, agrupar configurações e registrar quando os registros foram criados ou modificados. Os índices em group e is_public melhoram o desempenho das consultas. O método down() remove completamente a tabela, permitindo reverter a migração.
Você executa migrações pendentes com o comando wp acorn migrate. Ele executa todas as migrações que ainda não foram aplicadas, cria tabelas e modifica o esquema do banco de dados. Para verificar quais migrações já foram executadas, use wp acorn migrate:status. A saída mostra cada arquivo de migração e indica se ele já foi executado.
Quando você precisa reverter o último lote de migrações, utilize o comando wp acorn migrate:rollback. Ele executa o método down() de cada migração do último lote, desfazendo as alterações.
Verificando migrações com o Database Studio da Kinsta
Depois de executar as migrações, o Database Studio da Kinsta (ou qualquer outra ferramenta de banco de dados) permite verificar se as tabelas e colunas esperadas existem com a estrutura correta. Você acessa o Database Studio por meio do painel MyKinsta, navegando para qualquer site e clicando na aba Banco de dados:
O Console SQL incluído permite executar queries de verificação para confirmar que suas migrações criaram a estrutura esperada.
Após criar a tabela app_settings, a query DESCRIBE app_settings; permite verificar as colunas. Isso retorna a estrutura da tabela, mostrando nomes das colunas, tipos e índices. Outra query, SELECT * FROM app_settings;, permite testar se a tabela aceita inserções.
Os filtros permitem examinar registros ou colunas específicas sem escrever queries SQL. Aqui, você pode clicar nos cabeçalhos das colunas para ordenar, aplicar filtros para restringir os resultados e exportar seus dados:
Essas opções de exportação são úteis antes de você testar os procedimentos de reversão.
Executando migrações com SSH e WP-CLI na Kinsta
A Kinsta inclui acesso SSH e WP-CLI em todos os planos. Isso significa que você pode executar comandos de migração diretamente em seus ambientes de teste e produção sem nenhuma configuração adicional.
Para executar migrações em um ambiente Kinsta, primeiro você deve se conectar a ele usando SSH. As credenciais estão na tela de informações de qualquer site no MyKinsta:
Após conectar-se e autenticar-se, navegue até o diretório raiz do site. Para sites Radicle, esse diretório é o public. Em seguida, execute wp acorn migrate.
O processo de migração exibe uma saída que mostra quais migrações estão em execução e o status de conclusão de cada uma. Isso também funciona em ambientes de teste e produção porque o Acorn rastreia as migrações de forma independente no banco de dados de cada ambiente.
Testando migrações em ambientes de teste da Kinsta
Os ambientes de teste da Kinsta são um espaço seguro para testar as migrações antes de implantá-las na produção, mas você precisa de um fluxo de trabalho confiável para testá-las. Depois que você tiver verificado as alterações de migração no Database Studio, procure testar a reversão para garantir que o método down() funcione corretamente.
Para fazer isso, mude para o ambiente de teste no MyKinsta, navegue até a aba Banco de dados e inspecione as tabelas que as migrações criaram ou modificaram.
Se você encontrar problemas durante os testes no ambiente de teste, o comando wp acorn migrate:rollback permite reverter o último lote de migrações e fazer correções sem afetar a produção. Em seguida, você pode modificar seus arquivos de migração, fazer commit das alterações, implantar novamente no ambiente de teste e testar novamente.
O recurso de Mover seletivamente da Kinsta permite implantar apenas as alterações que você testou, escolhendo enviar apenas os arquivos para produção ou enviar arquivos e banco de dados:
Para fluxos de trabalho com migrações, normalmente você envia apenas os arquivos, pois as migrações são executadas no banco de dados existente em produção, em vez de sobrescrevê-lo com dados do ambiente de teste.
Fluxo de trabalho de implantação com migrações automatizadas
Fluxos de trabalho com migrações automatizadas executam alterações no esquema do banco de dados durante a implantação do código, eliminando etapas manuais e reduzindo erros. Isso é feito adicionando comandos de migração ao processo de implantação, seja por scripts manuais via SSH, automação com GitHub Actions ou ferramentas como o Trellis da Roots.
Para implantações manuais usando SSH, conecte-se ao ambiente de produção e navegue até o diretório raiz do site. Em seguida, execute os seguintes comandos em sequência:
git pull origin main
composer install --no-dev
npm install && npm run build
wp acorn optimize
wp acorn migrate --forceA flag --force instrui o Acorn a executar as migrações sem prompts de confirmação, o que é essencial para implantações automatizadas onde não há interação humana com o terminal. Executar esse comando após wp acorn optimize garante que o cache da aplicação esteja atualizado antes da execução das migrações.
Se você utiliza GitHub Actions para implantação contínua, pode automatizar as migrações no arquivo de workflow. O Radicle inclui uma configuração .github/workflows/deploy.yml que pode ser modificada para incluir uma etapa de migração após o processo de build:
- name: Run migrations
run: |
ssh user@host -p port 'cd /path/to/site && wp acorn migrate --force'O fluxo de implantação conecta via SSH, navega até o diretório do site e executa o comando de migração.
Para implantações usando o Trellis, as migrações são integradas aos hooks de implantação. Você inclui o seguinte modificando o arquivo deploy-hooks/finalize-after.yml:
- name: Run Acorn migrations
command: wp acorn migrate --force
args:
chdir: "{{ deploy_helper.new_release_path }}"Isso executa as migrações depois que o Trellis conclui outras tarefas de implantação. As migrações são executadas no diretório da nova versão, e o Trellis lida com a reversão se a implantação falhar.
Controle de versão de arquivos de migração com o Git
Os arquivos de migração ficam no diretório database/migrations/ dentro da estrutura do projeto Radicle. Esse diretório faz parte do repositório Git, o que significa que as migrações acompanham o código pelo controle de versão. O fluxo de trabalho segue o padrão de desenvolvimento: criar migrações localmente, fazer commit em uma branch de funcionalidade e mesclar na branch principal após os testes.
O fluxo de trabalho de commit para migrações segue um padrão consistente:
git add database/migrations/2025_01_03_140000_create_app_settings_table.php
git commit -m "Add app_settings table migration"
git push origin feature-branchApós revisar a migração, você mescla a branch de funcionalidade na branch principal. Isso torna a migração disponível para implantações em ambientes de teste e produção.
O comando wp acorn migrate:status verifica se todos os ambientes têm as mesmas migrações aplicadas. Você pode executar esse comando em todos os ambientes para confirmar que estão sincronizados. Se algum ambiente mostrar migrações pendentes, isso indica que ele precisa de uma implantação ou de uma execução manual de migração para se atualizar.
Estratégias de reversão e backups do banco de dados
Nem todas as migrações são totalmente reversíveis. Embora seja simples remover uma tabela para desfazer sua criação, uma migração que exclui dados é uma ação permanente. Em alguns casos, o método down() pode indicar que uma reversão não é possível:
public function down(): void
{
// This migration cannot be reversed as we're deleting data
Log::warning("Migration cannot be reversed - data permanently deleted");
}É bom que você documente essas limitações. Os backups automatizados da Kinsta fornecem uma rede de segurança, portanto, também é importante que você crie um backup manual antes de executar uma migração que possa causar problemas:
Navegue até seu site, clique em Backups e gere um backup com um nome descritivo. Se uma migração causar problemas inesperados na produção, você poderá restaurar a partir desse backup por meio do MyKinsta.
Para reversões de migração, você restaura apenas o banco de dados para o ambiente de produção. A restauração é concluída em minutos e retorna o banco de dados ao estado exato capturado no backup.
Criando fluxos de trabalho de banco de dados confiáveis para o WordPress
As migrações do Laravel, por meio da implementação do Acorn no Radicle, transformam um dos pontos mais críticos do desenvolvimento em um processo previsível e controlado por versão. A combinação de migrações como código, ambientes de teste da Kinsta e o Database Studio para verificação cria um fluxo de trabalho que permite identificar problemas de esquema antes que cheguem à produção.
Com isso, o desenvolvimento moderno em WordPress, utilizando ferramentas como Radicle e Acorn, elimina a necessidade de escolher entre o ecossistema do WordPress e frameworks profissionais. O mesmo padrão se aplica a filas do Laravel, templates Blade e comandos personalizados do WP-CLI por meio do Acorn.
Se você está pronto para adotar esse fluxo de trabalho, o próximo passo é definir convenções de migração, como padrões de nomenclatura para arquivos, documentação de processos e requisitos de teste antes de merges importantes. A hospedagem gerenciada para WordPress da Kinsta oferece ferramentas integradas para desenvolvedores, como acesso SSH, ambientes de teste e o Database Studio, que dão suporte a fluxos de trabalho modernos, incluindo migrações com Radicle e Acorn.
