Migrations e Schema

Guia completo de Blueprint e definição de schema

Esta seção explica a API real de Framework\Database\Blueprint, Column e Schema, do primeiro arquivo de migration até relacionamentos e SQL gerado. O código entregue configura MySQL/InnoDB; não há suporte SQLite nesta conexão. Exemplos de tabelas como posts e profiles são modelos didáticos que você pode criar, não classes ou tabelas preexistentes.

1. Como Blueprint funciona dentro do framework

Há dois fluxos distintos. No fluxo de schema, a migration chama Schema; a facade cria um Blueprint, o callback registra objetos Column e índices, e o framework monta SQL DDL e o entrega a Database::execMigration(). No uso cotidiano, Models consultam e alteram as tabelas já criadas.

Migrations/arquivo.php → Migration::up()
                       → Schema::create() ou Schema::table()
                       → Blueprint + Column / índices / FKs
                       → SQL DDL → Database::execMigration() → MySQL/InnoDB

Aplicação em execução: Model ou Database → SQL de leitura/escrita → tabelas

Blueprint não executa queries de domínio nem insere registros. Use Models ou Database/PDO para dados; use este builder para a estrutura do banco. O Migrator da CLI carrega apenas arquivos .php em database/migrations/, ordenados pelo nome.

2. Criar uma tabela do zero: exemplo iniciante

Cenário e objetivo. Você está começando uma pequena aplicação de catálogo e precisa guardar produtos com nome, preço e datas de auditoria. Vamos criar uma migration reversível, entender cada arquivo e verificar o resultado. O nome e as colunas abaixo são exemplos; os métodos usados existem em Blueprint.php.

1. Configure as variáveis do banco em .env (por exemplo DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME e DB_PASSWORD). A conexão ativa está em config/database.php; no código atual é MySQL.
2. Na raiz do projeto, gere o esqueleto: php mvc make:migration CreateProductsTable. O comando cria um arquivo com prefixo de data/hora em database/migrations/. O stub inicial usa Schema::create(); revise e complete o conteúdo antes de executar.
3. Edite o arquivo gerado para que tenha esta forma:

<?php

use Framework\Database\Blueprint;
use Framework\Database\Migration;
use Framework\Database\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('products', function (Blueprint $table): void {
            $table->id();
            $table->string('name', 150);
            $table->decimal('price', 10, 2);
            $table->boolean('active')->default(1);
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('products');
    }
};

O que foi feito. O arquivo retorna uma instância anônima de Migration, com up() para aplicar e down() para desfazer. Schema::create() recebe o nome literal da tabela e um callback com Blueprint. id() cria um INT UNSIGNED AUTO_INCREMENT PRIMARY KEY; string(), decimal() e boolean() registram colunas; timestamps() cria created_at e updated_at.

Resultado esperado. Ao chamar php mvc migrate, o Migrator carrega o arquivo, chama up() e registra a migration e seu batch na tabela migrations. Para esta tabela, Blueprint produz um CREATE TABLE IF NOT EXISTS InnoDB com charset utf8mb4 e collation utf8mb4_unicode_ci. O SQL exato depende das colunas declaradas; mais adiante há uma saída real de exemplo.

3. Alterar uma tabela existente

Cenário e objetivo. A tabela products já existe e agora precisa de um SKU opcional. Para alteração usa-se Schema::table(); o callback ainda recebe um Blueprint, mas o framework gera uma sequência de ALTER TABLE, não um CREATE TABLE.

<?php

use Framework\Database\Blueprint;
use Framework\Database\Migration;
use Framework\Database\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::table('products', function (Blueprint $table): void {
            $table->string('sku', 64)->nullable();
        });
    }

    public function down(): void
    {
        Schema::table('products', function (Blueprint $table): void {
            $table->dropColumn('sku');
        });
    }
};

Como funciona. Schema::table() compila as operações e executa cada statement em sequência, imediatamente. No exemplo, up() adiciona sku VARCHAR(64) NULL; o rollback remove a coluna. A migration só é registrada pelo Migrator depois que up() termina. Em MySQL, DDL pode fazer commit implícito, então uma falha no meio pode deixar parte das alterações aplicada.

dropColumn(string|array $columns) aceita um nome ou uma lista e gera um ALTER TABLE ... DROP COLUMN por coluna. Para desfazer uma remoção, down() pode recriar a coluna com tipo e nulabilidade equivalentes, mas não recupera os valores apagados. Faça backup antes de migrations destrutivas.

4. Catálogo completo de tipos de coluna

Todos os métodos abaixo pertencem a Blueprint. Salvo os métodos de conveniência indicados depois, cada método de coluna retorna Framework\Database\Column, permitindo encadear os modificadores descritos na próxima seção. Os tamanhos/valores são colocados no SQL; Blueprint não verifica se cabem nos limites do tipo nem se precisão e escala são coerentes.

Números

Texto

Data e hora

Booleanos e tipos especiais

Convenções adicionais: timestamps(): void cria created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP e updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP. Não retorna Column e não pode ser encadeado. softDeletes(): Column cria deleted_at DATETIME NULL e retorna essa Column. A coluna só participa da exclusão lógica do Model se o Model correspondente usar $softDelete = true; criar a coluna, por si só, não ativa esse comportamento. O Model base tem $timestamps = true por padrão; verifique também as colunas na tabela.

5. Column: nulabilidade, padrões e modificadores encadeáveis

Uma coluna normal retorna Column. Estes métodos alteram a definição guardada e retornam a própria instância (static), exceto os métodos internos de compilação. O SQL final é montado na ordem fixa: tipo, NULL/NOT NULL, DEFAULT, depois texto de rawExtra, independentemente da ordem em que os modificadores foram chamados.

Exemplo: $table->string('nickname', 80)->nullable()->default('guest'); gera uma coluna VARCHAR(80) NULL DEFAULT 'guest'. Um default e a nulabilidade são conceitos distintos: permitir NULL não cria um default, e definir um default não torna a coluna nullable.

6. Índices, unique e remoção de coluna

index(string|array $columns, ?string $name = null): void cria índice comum. unique(string|array $columns, ?string $name = null): void cria índice/constraint único. Com uma string, é um índice de uma coluna; com array, a ordem define um índice composto. Se não informar o nome, os nomes são idx_{tabela}_{colunas} e uniq_{tabela}_{colunas}. Os dois métodos retornam void: não encadeie modificadores após eles.

$table->string('email', 180);
$table->unique('email', 'uniq_customers_email');

$table->index(['status', 'created_at'], 'idx_orders_status_created');

unique() impede duplicidade conforme a regra do banco; index() não garante unicidade. Um índice composto em (status, created_at) não equivale automaticamente a índices independentes para qualquer ordem de busca. O builder não inspeciona dados existentes: adicionar unique a uma coluna com duplicatas pode fazer a migration falhar. Identificadores e nomes fornecidos são interpolados sem escape.

dropColumn(string|array $columns): void registra colunas a remover; é aplicado por Schema::table() via um ALTER TABLE ... DROP COLUMN para cada nome. toCreateSql() não usa essa lista, então chamar dropColumn() dentro de Schema::create() não remove nada.

7. Chaves estrangeiras: exatamente como configurar

foreignId($name) produz INT UNSIGNED e marca a coluna como foreign ID. O FK é compilado para essa marca, e constrained() informa o destino. Exemplo recomendado com a tabela explícita:

$table->foreignId('user_id')
      ->constrained('users')
      ->onDelete('cascade');

O SQL gerado contém CONSTRAINT fk_{tabela}_{coluna} FOREIGN KEY (...) REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT. O nome da constraint é criado automaticamente; não há parâmetro para personalizá-lo. Sem chamadas a onDelete()/onUpdate(), ambas as ações ficam em RESTRICT. A implementação converte o texto recebido para maiúsculas, mas não valida nem limita as ações: use apenas ações aceitas pelo MySQL/InnoDB e deixe o banco rejeitar opções inválidas.

Obrigatório na prática: chame constrained() para cada coluna criada por foreignId(). A implementação emite a constraint sempre que encontra esse tipo, mesmo que uma tabela referenciada não tenha sido configurada; nesse caso pode produzir SQL inválido. Informe explicitamente a tabela, pois a inferência automática apenas remove _id e acrescenta s (user_id → users, mas nomes irregulares não são singularizados corretamente).

Tipos/chaves precisam ser compatíveis e o alvo deve existir quando o DDL for executado. Como id() é INT UNSIGNED, foreignId() combina com essa convenção. Apesar de haver unsignedBigInteger(), não há método separado para marcar um BIGINT como foreign ID; chamar constrained() sobre outra Column não basta para gerar a FK. Chaves estrangeiras compostas também não têm método próprio. Coloque migrations das tabelas-pai antes das tabelas-filhas (a execução é ordenada pelo nome do arquivo).

onDelete('cascade') apaga fisicamente os filhos quando o registro pai é apagado. SET NULL exige que a coluna FK seja nullable; caso contrário a ação não consegue gravar o resultado. Uma exclusão lógica do Model apenas atualiza deleted_at, portanto não aciona ON DELETE CASCADE. A tabela real api_tokens do projeto usa foreignId('user_id')->constrained('users')->onDelete('CASCADE') como exemplo implementado.

SQL efetivamente gerado por Blueprint

Para deixar o resultado concreto, este CREATE TABLE foi conferido executando em PHP os mesmos métodos de Blueprint (ID, FK para users, string, decimal, timestamps, soft delete, unique e índice composto). Os identificadores e valores são inseridos diretamente como código; a saída mostra também que o builder não envolve os nomes em backticks.

CREATE TABLE IF NOT EXISTS posts (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY NOT NULL,
    user_id INT UNSIGNED NOT NULL,
    title VARCHAR(150) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at DATETIME NULL,
    UNIQUE KEY uniq_posts_title (title),
    INDEX idx_posts_user_title (user_id, title),
    CONSTRAINT fk_posts_user_id FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_unicode_ci;

toAlterSql() também retorna statements em vez de uma única alteração; Schema::table() chama execMigration() para cada item, na ordem abaixo. A lista foi gerada com as operações indicadas:

ALTER TABLE posts ADD COLUMN published_at DATETIME NULL;
ALTER TABLE posts ADD COLUMN team_id INT UNSIGNED NOT NULL;
ALTER TABLE posts ADD CONSTRAINT fk_posts_team_id FOREIGN KEY (team_id) REFERENCES teams(id) ON DELETE RESTRICT ON UPDATE CASCADE;
ALTER TABLE posts DROP COLUMN old_code;
ALTER TABLE posts DROP COLUMN old_note;
ALTER TABLE posts ADD INDEX idx_posts_published_at (published_at);

Essa ordenação importa: colunas novas são adicionadas primeiro, uma FK de foreignId() vem logo após sua coluna, depois as colunas registradas para remoção e, por fim, índices. Cada statement é executado separadamente; uma falha pode deixar as operações anteriores aplicadas.

8. Modelagem das relações comuns

As relações abaixo são constraints no banco, não métodos de associação no Model. O código do Model confirma que não há hasOne(), hasMany(), belongsTo() ou belongsToMany(). Models podem fazer joins/queries explícitas; para relações automáticas ou carregamento eager, essa implementação não fornece essa API.

1:1 — usuário e perfil

Cenário e objetivo. Cada perfil pertence a um usuário e, no máximo, um perfil pode apontar para o mesmo usuário. A FK sozinha permitiria vários perfis; a restrição unique em user_id é o que limita a um.

<?php

use Framework\Database\Blueprint;
use Framework\Database\Migration;
use Framework\Database\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('profiles', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('user_id')->constrained('users')->onDelete('cascade');
            $table->string('display_name', 120)->nullable();
            $table->unique('user_id', 'uniq_profiles_user');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('profiles');
    }
};

O resultado garante que um perfil tenha um usuário existente e que um usuário tenha no máximo um perfil. Não obriga cada usuário a ter perfil. Para tabela existente, mova esse callback para up() de uma migration; não cole-o diretamente fora da migration.

1:N e N:1 — usuário e publicações

Cenário e objetivo. Um usuário pode criar várias publicações; cada publicação pertence a um usuário. A FK fica no lado “muitos”, em posts.user_id. Do ponto de vista do post, a mesma estrutura é N:1 (muitos posts para um user), sem uma segunda constraint.

<?php

use Framework\Database\Blueprint;
use Framework\Database\Migration;
use Framework\Database\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('user_id')->constrained('users')->onDelete('cascade');
            $table->string('title', 150);
            $table->text('body')->nullable();
            $table->timestamps();
            $table->index('user_id', 'idx_posts_user');
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

Ao terminar up(), cada linha de posts exige um user_id existente. Não existe lista automática $user->posts; faça a consulta de forma explícita, por exemplo com o wrapper Database:

$posts = \Framework\Database\Database::getInstance()
    ->query('SELECT posts.id, posts.title, users.name AS author_name
             FROM posts
             INNER JOIN users ON users.id = posts.user_id
             WHERE posts.user_id = :user_id')
    ->bind(':user_id', $userId)
    ->fetchAll();

O valor variável é vinculado como parâmetro; não concatene $userId na SQL. Para a API fluente do Model e seus joins explícitos, consulte Query Builder e Database/PDO.

N:N — usuários e papéis por tabela pivô

Cenário e objetivo. Um usuário pode ter vários papéis e cada papel pode pertencer a vários usuários. O framework não cria pivô nem métodos N:N automaticamente: declare uma tabela intermediária com duas FKs. A chave unique composta evita repetir o mesmo par.

<?php

use Framework\Database\Blueprint;
use Framework\Database\Migration;
use Framework\Database\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('roles', function (Blueprint $table): void {
            $table->id();
            $table->string('name', 60);
            $table->unique('name', 'uniq_roles_name');
        });

        Schema::create('role_user', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('user_id')->constrained('users')->onDelete('cascade');
            $table->foreignId('role_id')->constrained('roles')->onDelete('cascade');
            $table->unique(['user_id', 'role_id'], 'uniq_role_user_pair');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('role_user');
        Schema::dropIfExists('roles');
    }
};

Crie as tabelas-pai antes da pivô. No down(), remova primeiro role_user, depois roles; a tabela users pertence a outra migration e não deve ser apagada por esta. Se o par precisar ter atributos adicionais (por exemplo assigned_at), coloque-os na pivô.

9. Exemplo integrado: catálogo, pedidos e itens

Cenário e objetivo. Um pequeno sistema de vendas terá produtos, pedidos feitos por usuários já existentes e itens associados a cada pedido. Isso cobre 1:N (users → orders e orders → order_items) e, conceitualmente, N:N entre pedidos e produtos, representada pela tabela order_items. Uma única migration mostra ordem de criação e reversão.

<?php

use Framework\Database\Blueprint;
use Framework\Database\Migration;
use Framework\Database\Schema;

return new class extends Migration {
    public function up(): void
    {
        // A tabela products não depende de outra tabela deste exemplo.
        Schema::create('products', function (Blueprint $table): void {
            $table->id();
            $table->string('sku', 64);
            $table->string('name', 150);
            $table->decimal('price', 10, 2);
            $table->boolean('active')->default(1);
            $table->timestamps();
            $table->unique('sku', 'uniq_products_sku');
        });

        // users é criada pela migration existente do projeto.
        Schema::create('orders', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('user_id')->constrained('users')->onDelete('restrict');
            $table->string('status', 30)->default('pending');
            $table->timestamps();
            $table->index('user_id', 'idx_orders_user');
        });

        // Tabela de associação: cada linha liga um pedido a um produto.
        Schema::create('order_items', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('order_id')->constrained('orders')->onDelete('cascade');
            $table->foreignId('product_id')->constrained('products')->onDelete('restrict');
            $table->unsignedInteger('quantity')->default(1);
            $table->decimal('unit_price', 10, 2);
            $table->unique(['order_id', 'product_id'], 'uniq_order_product');
        });
    }

    public function down(): void
    {
        // Desfaz primeiro as dependências e só então a tabela-pai do exemplo.
        Schema::dropIfExists('order_items');
        Schema::dropIfExists('orders');
        Schema::dropIfExists('products');
    }
};

Como ler o resultado. Um usuário pode ter vários pedidos por orders.user_id. Cada pedido pode ter várias linhas em order_items; cada linha aponta para um produto. O unique composto permite apenas uma linha por par pedido/produto. Se seu domínio permite linhas separadas para o mesmo produto (variações, lote, preço ou desconto), altere a chave unique para incluir a variação ou retire a unique conforme as regras do domínio. unit_price preserva o preço usado naquele pedido; consultar apenas o preço atual de products não substituiria esse dado histórico.

Resultado esperado. Se todas as operações forem aceitas pelo MySQL, serão criadas três tabelas InnoDB com as colunas, defaults, índices e constraints declaradas. A migration assume que users já existe. O rollback remove as tabelas na ordem inversa das dependências. Nenhum Model Order, Product ou relação ORM é criado automaticamente; esses arquivos e consultas são responsabilidade da aplicação.

10. Executar, verificar e testar uma migration

1. Gere/edite o arquivo em database/migrations/; confira namespace/imports, up(), down(), nomes de tabela e dependências.
2. Confirme que o banco de desenvolvimento está configurado em .env e acessível.
3. Execute php mvc migrate. O Migrator processa arquivos .php em ordem alfabética do prefixo timestamp, pula nomes já registrados e registra o batch somente depois de up() completar.
4. Verifique a estrutura no cliente MySQL, por exemplo SHOW CREATE TABLE order_items;, e confira índices/FKs no schema do banco. Esse comando é SQL para o cliente do banco, não um subcomando MVC.
5. Para validar o rollback em ambiente descartável, use php mvc migrate:rollback e depois reaplique com php mvc migrate. --step=N indica quantos batches desfazer, não quantos arquivos. Faça isso apenas quando o impacto nos dados for aceitável.

O framework não fornece nesta classe um validador estático/preview de DDL, dry-run do Blueprint ou método de teste de migration isolada. Pode inspecionar a string internamente com Blueprint::toCreateSql() / toAlterSql(), mas esses métodos são auxiliares públicos voltados ao Schema e não substituem execução em MySQL compatível. Erros de PDO são lançados; identifique a primeira instrução que falhou e confirme o schema real antes de repetir.

11. O que evitar: erros comuns e correção

12. Referência técnica resumida e limites reais

Schema

Métodos auxiliares públicos de Blueprint

Métodos públicos de Column usados internamente

Para a API de Models e a ausência de relações ORM, consulte Models; para transações e statements parametrizados, Database e PDO; para queries/join, Query Builder; para criar/executar migrations, CLI. O ponto de partida das implementações é framework/Database/Schema.php, Blueprint.php, Column.php, Migration.php, Database.php e cli/Migrator.php.

Chaves estrangeiras e SQL gerado

foreignId($name) cria coluna e a marca para geração de FK; encadeie constrained($table) para informar a tabela referenciada antes de executar a migration. Sem constrained(), o gerador chega a SQL com tabela referenciada ausente, portanto não use foreignId isoladamente.

$table->foreignId('user_id')
      ->constrained('users')
      ->onDelete('cascade');

Schema executa DDL imediatamente no MySQL. Os nomes de tabela/coluna e expressões raw são interpolados no SQL gerado; mantenha-os como literais do código. default($value, raw: true) e rawExtra() aceitam SQL literal e não devem receber input externo. Os valores de enum também são interpolados sem escaping automático.

A referência inclui Database/PDO e a classe Migration base. O Migrator executa migrations PHP em ordem de nome; migrations SQL não são carregadas pelo comando atual.

migrate --fresh recria o database inteiro

php mvc migrate --fresh não limpa apenas as tabelas de migrations: o Migrator executa DROP e CREATE do database configurado. O comando pede que você digite o nome do database para confirmar; --yes suprime essa pergunta. Em produção, também é necessário --force. Faça e verifique um backup antes de qualquer execução; --force apenas autoriza o comando e não protege os dados.

# Interativo; leia a confirmação e digite o nome do database
php mvc migrate --fresh

# Não interativo (continua destrutivo)
php mvc migrate --fresh --yes