Migrations de banco de dados
As migrations do Tyrus são arquivos SQL numerados que o desenvolvedor revisa antes de aplicar. Builds e conexões normais com o banco nunca criam nem aplicam migrations automaticamente. Consulte Comandos de schema do banco para ver a referência completa da CLI.
Gerar e revisar
tyrus db migrate generate <name> cria uma migration inicial a partir dos Models do projeto quando o banco configurado não existe. Migrations geradas validam cada @foreignKey contra os Models do projeto no schema inicial ou contra o catálogo SQLite atual nas alterações incrementais. Migrations iniciais também exigem tipos compatíveis nos campos do Model; migrations incrementais verificam a afinidade de tipo SQLite. Ambas verificam tabela e colunas de destino e unicidade, incluindo chaves compostas e índices únicos, no schema SQLite reproduzido. A validação de identificadores SQLite em snapshots não diferencia maiúsculas de minúsculas, mas o snapshot preserva a grafia informada pelo banco. Para um banco existente, exige um snapshot atual do schema e pode criar tabelas para Models novos, adicionar colunas opcionais ou colunas com valores padrão literais e reconstruir uma tabela quando um Model remove colunas ou altera a chave primária, constraints @unique ou chaves estrangeiras de saída. As reconstruções copiam os valores mantidos e restauram índices personalizados, triggers da tabela e views a partir do catálogo SQLite. Antes de salvar o SQL gerado, a CLI o reproduz em uma cópia em memória do schema SQLite e valida as views e os triggers resultantes; views e triggers sem relação com a coluna removida não bloqueiam a remoção, mas dependências que quebrem ou façam referência a um campo removido de trigger exigem uma migration manual. A geração também é recusada quando uma coluna removida é usada por um índice, quando outra tabela referencia a tabela reconstruída ou quando adições simultâneas impedem a preservação segura. A aplicação de uma alteração de chave ou chave estrangeira pode falhar se os registros existentes a violarem; nesse caso, a transação SQLite é revertida. Alterações em definições de colunas existentes exigem uma migration escrita manualmente. O comando grava um arquivo SQL numerado e nunca altera o banco. Nomes como initial_schema nos exemplos são ilustrativos; substitua-os por um nome descritivo para sua migration ou seed.
A comparação de migrations de Model segue as regras SQLite que não diferenciam maiúsculas de minúsculas para nomes de tabelas e colunas, incluindo destinos de chaves estrangeiras e mapeamentos físicos de colunas. Dois Models ou campos não podem mapear nomes que diferem apenas pela caixa.
Fluxo típico
Para um banco SQL existente, altere o Model, compare-o com o banco ativo e o snapshot atual, gere uma migration, revise o arquivo SQL numerado em db/migrations/, aplique-a e atualize o snapshot. PostgreSQL e MySQL geram novas tabelas de Model e adições seguras de colunas; mudanças que alterem ou removam definições existentes exigem uma migration escrita manualmente. No exemplo abaixo, add_profile é um nome escolhido pelo desenvolvedor. Para um banco novo, gere uma migration inicial a partir dos Models, revise e aplique o arquivo e então execute tyrus db introspect para criar o snapshot.
# Compare the edited Models with the snapshot and live database.
tyrus db diff
# Replace add_profile with a descriptive migration name.
tyrus db migrate generate add_profile
# Review and edit the generated SQL file before applying it.
tyrus db migrate apply
# Refresh the snapshot after the database schema changes.
tyrus db introspect# Replace `initial_schema` with a descriptive name for this migration.
tyrus db migrate generate initial_schema
tyrus db migrate status
tyrus db migrate apply
tyrus db introspect
# Replace `default_roles` with a descriptive name for this seed.
tyrus db seed create default_roles
tyrus db seed status
tyrus db seed applyInspecione e edite o SQL gerado antes de aplicá-lo. Mapeamentos de tipos SQLite que possam perder valores são recusados; campos u8[] do model são mapeados para colunas SQLite BLOB e para o tipo lógico de snapshot bytes. Depois que uma migration altera o schema, execute tyrus db introspect para atualizar o snapshot local usado pelo compilador e pelo Language Server. Snapshots PostgreSQL e MySQL incluem tabelas base visíveis, colunas, tipos nativos, engines de tabela quando disponíveis, chaves, índices, chaves estrangeiras e triggers; o snapshot armazena um identificador hash do destino sem credenciais de conexão.
Aplicar e acompanhar migrations
tyrus db migrate status lista arquivos aplicados e pendentes sem alterar SQLite, PostgreSQL ou MySQL. tyrus db migrate apply aplica migrations PostgreSQL em uma única transação e registra o checksum de cada arquivo em _tyrus_migrations; no MySQL, grava um estado de recuperação started antes de cada migration, pois DDL pode confirmar implicitamente. Aplicações concorrentes no PostgreSQL usam um lock advisory vinculado à transação e no MySQL usam um lock nomeado. O validador de migrations do servidor reconhece corpos PostgreSQL entre delimitadores dollar-quote, strings escapadas E'...' e comentários de bloco aninhados, além de comentários MySQL #, antes de verificar comandos transacionais. Assim, funções PostgreSQL podem conter pontos e vírgulas e BEGIN/END procedural sem confundir as verificações da transação gerenciada. O PostgreSQL reverte um lote com falha. Se uma migration MySQL falhar, inspecione o banco e o arquivo antes de tentar novamente; o registro incompleto bloqueia a reaplicação automática. Arquivos aplicados não podem ser editados nem removidos, e não existe comando automático de downgrade.
Migrations de Model PostgreSQL e MySQL
Para PostgreSQL e MySQL, tyrus db migrate generate <name> cria uma migration inicial a partir dos Models do projeto sem se conectar ao banco. Quando já existem migrations, a geração incremental conecta-se ao servidor configurado, verifica se o schema ativo corresponde ao snapshot e pode criar novas tabelas de Model, adicionar colunas, ampliar tipos numéricos compatíveis e tornar colunas obrigatórias em opcionais. As colunas adicionadas devem ser opcionais ou ter um default literal. Uma nova coluna @unique só é aceita quando é opcional e não tem default; adicionar @unique a uma coluna existente gera uma constraint única, cuja aplicação pode falhar se já houver valores duplicados, sem reescrever essas linhas. Novas colunas com @foreignKey devem ser opcionais e sem default; adicionar uma foreign key a uma coluna existente é permitido somente se ela for opcional e se a tabela de destino, a chave única e o tipo nativo compatível constarem no snapshot. O MySQL também exige InnoDB nas duas tabelas e larguras iguais para tipos inteiros assinados registradas pela introspecção; o PostgreSQL confere também o tipo nativo exato. Linhas existentes com valores órfãos podem fazer a constraint de foreign key gerada falhar ao ser aplicada, sem reescrever essas linhas. O widening fica limitado a smallint/integer/bigint e real/double suportados pelo backend, exige metadados nativos e é recusado para colunas que participem de chaves, índices ou relações. Tornar uma coluna opcional preserva os valores e constraints existentes; no MySQL, também são exigidos os metadados do tipo nativo porque MODIFY COLUMN reescreve a definição completa da coluna. Alterar ou remover um default literal em uma coluna existente que não seja de identidade gera ALTER COLUMN SET DEFAULT ou DROP DEFAULT; defaults de expressão, narrowing, tornar uma coluna obrigatória, mudanças em chaves primárias, remoção de colunas ou constraints, mudanças em foreign keys existentes e alterar a opção timestamps de um Model existente exigem uma migration manual. Se o snapshot não contiver os tipos nativos necessários, execute tyrus db introspect novamente antes de gerar uma migration segura ou validar foreign keys. O gerador aceita campos de inteiros com sinal, ponto flutuante, texto e arrays de bytes, campos obrigatórios e opcionais, defaults literais aceitos pelo backend, chaves primárias, constraints únicas e relações @foreignKey validadas para tabelas novas. Chaves primárias inteiras do PostgreSQL recebem geração de identidade; as do MySQL recebem AUTO_INCREMENT, e as tabelas MySQL geradas usam InnoDB. O gerador recusa tipos sem suporte e chaves/defaults de texto ou binários no MySQL. Use tyrus db migrate create <name> para criar um arquivo SQL identificado pelo backend e escrever migrations posteriores manualmente. status, apply, introspect, check e diff do schema ativo também aceitam PostgreSQL e MySQL. A comparação somente leitura entre Models e snapshot aceita SQLite, PostgreSQL e MySQL; mudanças aditivas e seguras de servidor são geradas incrementalmente, enquanto operações destrutivas ou ambíguas continuam manuais.
Seeds
Crie programas de seed manualmente como arquivos .tyr em db/seeds/. Uma seed pode usar a API de Model ou db.query; execute um arquivo com tyrus db apply default_roles.tyr e consulte o estado com tyrus db seed status. A CLI registra checksums SHA-256 em _tyrus_seeds (uma tabela no SQLite, PostgreSQL e MySQL, e uma collection no MongoDB) e recusa executar novamente um arquivo aplicado ou aceitar arquivos aplicados alterados ou ausentes. O histórico de seeds do MongoDB usa os mesmos comandos, mas migrations de schema ainda não estão disponíveis para esse banco. O programa de seed roda em um processo Tyrus separado, portanto a CLI não pode envolver operações arbitrárias em uma única transação do banco; use a API de transação do banco quando várias alterações precisarem ser atômicas. Um programa que falhar ou for interrompido permanece como started e bloqueia novas tentativas. Inspecione o banco, corrija ou reverta alterações parciais e então remova a linha ou o documento correspondente em _tyrus_seeds antes de tentar novamente; crie um novo arquivo de seed para mudanças posteriores nos dados.
