72 lines
4.8 KiB
Markdown
72 lines
4.8 KiB
Markdown
# Execução, migração de dados e rollback
|
|
|
|
## Pré-requisitos
|
|
PHP 8.4.1+ para o composer.lock instalado; composer.json declara ^8.3. Runtime compatível com composer.lock, pdo_pgsql, dependências Composer, PostgreSQL/PostGIS. Referência: PostgreSQL 16 com PostGIS 3.4 ou superior compatível; confirmar no servidor.
|
|
Usar base isolada terminada em _test. Configurar DB_CONNECTION=pgsql, DB_DATABASE=investmoz_test, DB_HOST, DB_PORT, DB_USERNAME e DB_PASSWORD no ambiente seguro; nunca versionar credenciais.
|
|
O administrador pode provisionar postgis/pgcrypto antes; caso contrário a conta de migrations necessita dessa capacidade.
|
|
|
|
## Comandos Artisan
|
|
Os ficheiros já estão criados. Para futuras alterações:
|
|
php artisan make:migration descricao_da_alteracao
|
|
php artisan migrate --pretend
|
|
php artisan migrate --seed
|
|
php artisan migrate:status
|
|
|
|
Apenas numa base de desenvolvimento descartável:
|
|
php artisan migrate:fresh --seed
|
|
php artisan migrate:rollback
|
|
php artisan migrate --seed
|
|
|
|
Idempotência é assegurada pelo ledger migrations; não se usa IF NOT EXISTS para esconder deriva de tabelas. Extensões partilhadas usam IF NOT EXISTS. Funções próprias investmoz_* usam CREATE OR REPLACE porque migrate:fresh remove tabelas, mas conserva funções PostgreSQL.
|
|
Cada migration usa a transacção gerida pelo Laravel, sem BEGIN/COMMIT embutidos. Uma falha deixa o ficheiro pendente, preservando os anteriores.
|
|
|
|
## Testes
|
|
php artisan config:clear
|
|
php artisan test
|
|
php artisan test --configuration=phpunit.investmoz.xml
|
|
python tools/investmoz/validate.py
|
|
python tools/investmoz/generate.py --source "caminho/do/documento.docx" --check
|
|
|
|
O ensaio dedicado exige INVESTMOZ_SCHEMA_TESTS=1 e base terminada em _test; executa migrate:fresh e elimina dados dessa base.
|
|
As novas migrations rejeitam SQLite explicitamente. A suite principal deve usar PostgreSQL.
|
|
Testes estáticos não equivalem a execução PostgreSQL/PostGIS. Desempenho usa EXPLAIN sem limiar inventado.
|
|
|
|
## MySQL -> PostgreSQL
|
|
1. Inventariar versão, charset, collation, contagens, moedas, fusos e ligações da origem real.
|
|
2. Obter snapshot e backup com restauração verificada e manifesto SHA-256.
|
|
3. Criar destino vazio e executar migrations sem seeds de demonstração.
|
|
4. Preservar IDs bigint do legado; atribuir UUID às novas entidades com mapa persistente origem/ID/UUID. Resolver P-08 antes de mapear opportunities para projects/CRM.
|
|
5. Transportar decimais como strings, sem float. Normalizar datas com fuso aprovado; colocar zero dates e datas inválidas em quarentena.
|
|
6. Validar JSON e geometrias 2D SRID 4326; recusar correcções geográficas silenciosas.
|
|
7. Importar por dependências em lotes transaccionais; deduplicar por source_system/external_id e comparar version_no atomicamente.
|
|
8. Guardar checkpoint na transacção do lote; não colocar dados pessoais nos logs.
|
|
9. Reconciliar contagens, somas, hashes canónicos, duplicados, órfãos e geometrias; tolerâncias ainda pendentes.
|
|
10. Ajustar sequences bigint com setval após verificar MAX(id); guardar origem para reversão.
|
|
11. Ensaiar corte, deltas e restauro antes de transferir tráfego. Esta entrega não executa importação.
|
|
|
|
## Rollback
|
|
down remove triggers, índices avançados, FKs/checks/PKs e tabelas em ordem inversa, depois funções próprias. Não remove extensões nem usa DROP CASCADE.
|
|
Reverter tabelas POPULADAS destrói os seus dados, mesmo sem CASCADE. Não é reversão sem perda.
|
|
Antes de rollback fora do ensaio: suspender escritores, exportar tabelas, verificar restauração separada e guardar ledger. Preferir migration compensatória.
|
|
Num upgrade, migrate:rollback reverte o lote novo. Após migrate:fresh, todas as migrations podem pertencer ao mesmo lote; rollback pode remover também o legado.
|
|
RESTRICT deve bloquear dependências externas; não contornar com CASCADE. Manter aplicação compatível com o esquema restaurado.
|
|
Rollback de esquema não reconverte automaticamente dados para MySQL.
|
|
|
|
## Fontes técnicas
|
|
https://www.postgresql.org/docs/16/ddl-constraints.html
|
|
https://postgis.net/docs/ST_IsValid.html
|
|
https://postgis.net/docs/ST_IsEmpty.html
|
|
|
|
## Checklist para cada ambiente
|
|
Consultar validation.md para as evidencias do ensaio local ja executado. Os itens seguintes devem ser repetidos no ambiente de destino.
|
|
- [x] Reconciliação autorizada e migrations históricas preservadas.
|
|
- [x] Catálogo, dicionário e SQL gerados da mesma representação.
|
|
- [x] UUID novos, FKs compatíveis, decimais, geometrias e índices explícitos.
|
|
- [x] Contactos N:N e documentos tipados.
|
|
- [x] Extensões preservadas no rollback.
|
|
- [x] Lacunas documentadas e fora do DDL.
|
|
- [ ] migrate:fresh --seed e rollback confirmados em PostgreSQL/PostGIS.
|
|
- [ ] Suite da aplicação executada em PostgreSQL.
|
|
- [ ] Matriz de permissões, importação real, reconciliação e restauro validados.
|
|
- [ ] Desempenho confirmado com volume e SLO aprovados.
|