Gerador de migration Knex a partir de tabela

Knex.js migrations: schema versionado para Node.js

O Knex.js é o query builder SQL para Node.js criado por Tim Griesser em 2013. Além das cadeias fluentes de SELECT/INSERT/UPDATE, ele traz um sistema de migrations de primeira classe: uma pasta de arquivos JavaScript com timestamp descrevendo cada mudança de schema como código, versionada junto com a aplicação. O runner registra as versões aplicadas na tabela knex_migrations, garantindo que a mesma série produza schemas idênticos em dev, CI, staging e produção.

O Knex é agnóstico de banco e suporta PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, Oracle e Amazon Redshift. Ele não é um ORM completo — não há modelos, validações ou hooks de ciclo de vida. Para recursos completos de ORM, combine com o Objection.js, que fica em cima do Knex.

Criando e executando migrations

O CLI do Knex gera, executa e reverte migrations:

• npx knex migrate:make create_users_table — gera um template com timestamp em ./migrations.
• npx knex migrate:latest — aplica todas as migrations pendentes em ordem.
• npx knex migrate:rollback — reverte o último batch aplicado.
• npx knex migrate:status — lista aplicadas vs pendentes.
• npx knex seed:run — popula tabelas de lookup (separado das migrations).

Anatomia de um arquivo de migration

Cada arquivo exporta uma função up (aplicar) e down (reverter). O schema builder oferece API fluente para tipos e constraints:

exports.up = (knex) => knex.schema.createTable('users', (t) => {
  t.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
  t.string('email').notNullable().unique();
  t.string('name', 100);
  t.boolean('active').notNullable().defaultTo(true);
  t.timestamps(true, true); // created_at + updated_at
  t.index(['email']);
});

exports.down = (knex) => knex.schema.dropTable('users');

Helpers comuns: t.string, t.integer, t.bigInteger, t.boolean, t.date, t.timestamp, t.json, t.jsonb (PostgreSQL), t.uuid, t.text, t.decimal. Chaves estrangeiras: t.foreign('user_id').references('users.id').onDelete('CASCADE'). Índices compostos: t.index(['col1', 'col2']); únicos: t.unique(['email', 'tenant_id']).

Boas práticas e anti-padrões

• Sempre escreva o down — mesmo que nunca rode em produção, ele documenta a intenção e permite que colaboradores reiniciem localmente.
• Nunca edite uma migration já commitada — rodá-la de novo em um banco zerado precisa produzir o mesmo estado. Adicione uma nova migration em vez disso.
• Use knex.transaction em migrations que misturam DDL com backfill de dados, mas lembre que o MySQL faz commit implícito de DDL.
• Em suites de teste, aponte o Knex para um SQLite em memória (:memory:) para startup sub-segundo.
• Em NestJS ou apps grandes, exponha o Knex via custom provider para que a mesma instância seja compartilhada entre módulos.

FAQ

O Knex é um ORM? Não — é um query builder. Não há modelos nem relações. Combine com Objection.js se quiser um ORM por cima.

Posso usar Knex junto com Prisma? Tecnicamente sim, mas as filosofias divergem: o Prisma é dono do schema via schema.prisma e roda as próprias migrations. Escolha um dos dois para gerenciar schema.

Migrations suportam transações? Sim. Por padrão cada migration roda em uma transação (onde o engine suporta). Desabilite por arquivo com config.transaction = false em engines como o MySQL.

Como o Knex se compara a Drizzle ou Kysely? Drizzle e Kysely são builders mais novos, TypeScript-first, com inferência de tipos mais forte. O Knex continua sendo a opção mais testada em produção e funciona em JavaScript puro, sem build step.

Onde ficam as credenciais? No knexfile.js da raiz do projeto, normalmente lendo de process.env. Use um bloco por ambiente (development, test, production).