{"v":{"area":"admin","slug":"migrations-sql","path":"/home/tiixcom/public_html/sistema/docs/readme/admin/migrations-sql.md","relative_path":"docs/readme/admin/migrations-sql.md","title":"Migrations SQL","html":"<h1>Migrations SQL</h1><p>O sistema possui um runner de migrations em <code>tools/migrate-sql.php</code> para aplicar os arquivos <code>.sql</code> versionados em <code>sql/</code> sem copiar e colar manualmente no banco.</p><h2>Como funciona</h2><ul><li>varre todos os arquivos <code>.sql</code> dentro de <code>sql/</code>, incluindo subpastas;</li><li>calcula checksum SHA-256 de cada arquivo;</li><li>grava o estado atual em <code>wpjy_schema_migrations</code>;</li><li>grava cada tentativa em <code>wpjy_schema_migration_runs</code>;</li><li>executa apenas migrations pendentes ou que falharam antes;</li><li>bloqueia execucoes paralelas com <code>GET_LOCK</code>;</li><li>para na primeira falha por padrao;</li><li>marca como problema quando uma migration ja aplicada foi alterada depois.</li></ul><h2>Comandos</h2><p>Ver pendentes, erros e arquivos alterados:</p><pre><code>php tools/migrate-sql.php status</code></pre><p>Ver tudo, inclusive ja aplicado:</p><pre><code>php tools/migrate-sql.php status --all</code></pre><p>Executar pendentes:</p><pre><code>php tools/migrate-sql.php run --no-interaction</code></pre><p>Por seguranca, se o controle ainda estiver vazio, o comando <code>run</code> nao executa todos os SQL antigos automaticamente. Para uma instalacao nova onde isso seja desejado, use:</p><pre><code>php tools/migrate-sql.php run --no-interaction --allow-initial-run</code></pre><p>Simular sem executar:</p><pre><code>php tools/migrate-sql.php run --dry-run</code></pre><p>Ver historico:</p><pre><code>php tools/migrate-sql.php history --limit=20</code></pre><p>Registrar baseline inicial sem executar SQL:</p><pre><code>php tools/migrate-sql.php baseline --no-interaction</code></pre><p>Use baseline quando a producao ja recebeu migrations antigas manualmente e voce quer iniciar o controle a partir do estado atual.</p><p>Para marcar somente arquivos antigos, use uma data limite. O exemplo abaixo marca como baseline apenas arquivos com data anterior a 2026-04-21:</p><pre><code>php tools/migrate-sql.php baseline --no-interaction --before=2026-04-21</code></pre><p>Se nao existir nenhum arquivo anterior a data escolhida, o sistema grava um marcador tecnico <code>__baseline__/AAAA-MM-DD</code>. Isso evita que o controle continue vazio e permite rodar as migrations posteriores normalmente.</p><h2>Deploy via GitHub</h2><p>O script <code>tools/deploy-github-repo.sh</code> ja reconhece estas variaveis:</p><ul><li><code>TIIX_DEPLOY_RUN_MIGRATIONS=1</code> habilita a execucao apos o <code>rsync</code>;</li><li><code>TIIX_DEPLOY_PHP_BIN=php</code> define o binario PHP;</li><li><code>TIIX_DEPLOY_MIGRATIONS_CMD=/caminho/tools/migrate-sql.php</code> permite trocar o script;</li><li><code>TIIX_DEPLOY_MIGRATIONS_ARGS=&quot;run --no-interaction&quot;</code> define os argumentos.</li></ul><p>Na integracao do GitHub, estas opcoes tambem podem ser salvas na configuracao de deploy:</p><ul><li><code>run_migrations</code>;</li><li><code>php_bin</code>;</li><li><code>migrations_cmd</code>;</li><li><code>migrations_args</code>.</li></ul><p>Quando a configuracao ainda nao foi salva explicitamente, <code>run_migrations</code> assume <code>1</code> por padrao para o deploy principal aplicar pendencias novas apos o <code>rsync</code>. Se for necessario pausar essa automacao, desmarque &quot;Rodar migrations apos deploy&quot; em <code>/adm/dev-repos</code> e salve a configuracao.</p><p>Quando uma migration falha, o deploy retorna erro no callback, o log do deploy registra a falha e a tabela <code>wpjy_schema_migration_runs</code> guarda a mensagem do banco.</p><p>No modal de configuracao GitHub, a opcao &quot;Rodar migrations apos deploy&quot; apenas habilita essa execucao automatica depois do deploy. Ela nao roda migrations no momento em que a configuracao e salva. Para rodar manualmente, use a pagina <code>/adm/ferramentas</code>.</p><p>Quando o deploy esta habilitado e uma seed nao aparece no sistema, confira estes pontos em ordem:</p><ul><li>se <code>/adm/ferramentas</code> mostra migrations pendentes, com erro ou alteradas;</li><li>se o historico em <code>wpjy_schema_migration_runs</code> registrou falha de tabela ou campo ausente;</li><li>se existe uma migration de estrutura anterior a seed no diretorio <code>sql/</code>;</li><li>se a configuracao <code>migrations_args</code> esta como <code>run --no-interaction</code> ou se precisa de uma acao consciente de baseline;</li><li>se ha migrations marcadas como <code>changed</code>, pois nesse caso o runner bloqueia novas execucoes ate que o estado seja resolvido.</li></ul><p>O Guia do Colaborador possui a migration <code>sql/2026-04-21-00-create-guide-knowledge-schema.sql</code>, criada para garantir as tabelas <code>wpjy_guide_*</code> antes dos seeds editoriais. Ela evita que os seeds do Guia falhem por tabela ou campo ausente em ambientes que ainda nao receberam o dump inicial.</p><h2>Pagina admin</h2><p>A pagina <code>/adm/ferramentas</code> permite:</p><ul><li>consultar o status dos arquivos de <code>sql/</code>;</li><li>ver o historico gravado em <code>wpjy_schema_migration_runs</code>;</li><li>simular a execucao;</li><li>rodar migrations pendentes;</li><li>registrar baseline inicial por data para arquivos ja aplicados manualmente.</li></ul><h2>Alerta na topbar</h2><p>Super admins recebem um alerta tecnico na topbar quando existem migrations pendentes, com erro ou alteradas depois de aplicadas.</p><ul><li>o alerta aparece como icone de banco de dados com badge numerico;</li><li>o contador soma pendentes, erros e alteradas;</li><li>erros e alteradas aparecem com destaque vermelho;</li><li>pendencias simples aparecem em amarelo;</li><li>clicar no icone abre <code>/adm/ferramentas</code>;</li><li>o estado usa cache curto no navegador e e atualizado depois de baseline ou execucao pela pagina de ferramentas.</li></ul><p>Esse alerta nao grava uma notificacao persistente no inbox, porque o estado de migrations muda assim que a execucao acontece.</p><h2>Fluxo recomendado</h2><ol><li>Subir o runner e conferir com <code>php tools/migrate-sql.php status</code>.</li><li>Se os SQL antigos ja foram aplicados manualmente, executar <code>php tools/migrate-sql.php baseline --no-interaction</code>.</li><li>Habilitar <code>run_migrations</code> na configuracao do deploy.</li><li>A cada commit com novo arquivo em <code>sql/</code>, o deploy aplica apenas o que ainda nao rodou.</li></ol>"},"exp":1780849742}