MOTOKO BASE

Documentação

Migrations

Quando usar pnpm db:generate, pnpm db:migrate e pnpm db:studio no Motoko Base.

Abrir emChatGPT (abre em uma nova aba)Claude (abre em uma nova aba)Cursor (abre em uma nova aba)Quando usar pnpm db:generate, pnpm db:migrate e pnpm db:studio no Motoko Base.

O Motoko Base usa Drizzle Kit para gerenciar migrations do banco. O schema é definido em TypeScript (src/lib/db/schema/); o Drizzle gera arquivos SQL de migration e os aplica ao seu banco Postgres.

Os três comandos estão definidos em package.json:

"db:generate": "drizzle-kit generate",
"db:migrate": "drizzle-kit migrate",
"db:studio": "drizzle-kit studio"

A configuração fica em drizzle.config.ts:

export default defineConfig({
  schema: "./src/lib/db/schema/schema.ts",
  out: "./drizzle/migrations",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

DATABASE_URL deve estar definida em .env antes de rodar qualquer comando. No Supabase, use a conexão direta (porta 5432) se as migrations falharem pelo transaction pooler.

pnpm db:generate

Gera um novo arquivo de migration a partir das diferenças entre seu schema TypeScript e o último snapshot de migration.

When to use

  • Após adicionar ou editar uma tabela em src/lib/db/schema/
  • Após adicionar colunas, índices, foreign keys ou constraints
  • Após exportar um novo arquivo de schema de schema.ts

When not to use

  • Para aplicar migrations — use db:migrate em vez disso
  • Para explorar dados — use db:studio em vez disso
  • Em um clone fresco sem mudanças de schema — não há nada novo para gerar

What it does

  1. Lê src/lib/db/schema/schema.ts e todas as tabelas exportadas
  2. Compara com o snapshot mais recente em drizzle/migrations/
  3. Cria uma nova pasta em drizzle/migrations/ com:
    • migration.sql — o SQL a executar
    • snapshot.json — estado do schema para o próximo diff

Example

Você adicionou uma tabela notes ao schema:

pnpm db:generate

Saída (exemplo):

drizzle/migrations/20260824120000_some_name/migration.sql

Revise o SQL gerado antes de migrar. O Drizzle Kit é preciso na maioria das mudanças, mas sempre confira operações destrutivas (drops, renames).

pnpm db:migrate

Aplica migrations pendentes ao banco conectado via DATABASE_URL.

When to use

  • Após pnpm db:generate — para aplicar sua nova migration
  • Após fazer pull do git quando um colega (ou upstream) adicionou migrations
  • Em um banco fresco — para criar todas as tabelas do zero
  • Durante o setup local — logo após clonar (veja Installation)

When not to use

  • Quando você alterou o schema mas ainda não rodou db:generate — gere primeiro
  • Para inspecionar dados — use db:studio

What it does

  1. Conecta ao Postgres usando DATABASE_URL
  2. Executa qualquer SQL de migration ainda não registrado no journal de migrations do banco
  3. Atualiza o journal para que a mesma migration não seja aplicada duas vezes

Example

pnpm db:migrate

Rode isso após cada fluxo de mudança de schema:

pnpm db:generate && pnpm db:migrate

Em CI ou deploy de produção, rode pnpm db:migrate como parte do passo de release (depois que as env vars estiverem disponíveis).

Troubleshooting

ProblemFix
DDL fails via poolerAponte DATABASE_URL para a conexão direct do Supabase (porta 5432), migre e volte
DATABASE_URL not setAdicione em .env; o Drizzle Kit carrega via dotenv/config
Migration already appliedNormal ao rodar de novo — o Drizzle pula migrations concluídas
Generated SQL looks wrongEdite o schema, delete a pasta de migration ruim e rode db:generate de novo (só antes de aplicar)

pnpm db:studio

Abre o Drizzle Studio — uma UI web local para explorar tabelas, ver linhas e rodar queries ad-hoc.

When to use

  • Inspecionar dados durante o desenvolvimento (users, links, files, sessions)
  • Depurar se uma migration criou as colunas esperadas
  • Verificar se sign-ups de teste gravaram as linhas corretas
  • Explorar tabelas desconhecidas após puxar migrations novas

When not to use

  • Para alterar o schema — edite os arquivos TypeScript do schema e rode db:generate + db:migrate
  • Em produção como ferramenta de admin principal — use o Supabase Dashboard ou um admin dedicado para dados de produção
  • Como substituto de scripts de seed adequados — o Studio é para inspeção, não para setup repetível

What it does

Inicia um servidor local (o Drizzle Kit imprime a URL, tipicamente https://local.drizzle.studio). Conecta usando DATABASE_URL de .env.

Example

pnpm db:studio

Mantenha o terminal aberto enquanto usa o Studio. Pare com Ctrl+C quando terminar.

Typical workflows

First-time local setup

cp .env.example .env
# fill in DATABASE_URL
pnpm db:migrate
pnpm dev

Não é preciso db:generate — as migrations já vêm no repositório.

You changed the schema

# 1. Edit src/lib/db/schema/*.ts and export from schema.ts
pnpm db:generate
pnpm db:migrate
pnpm db:studio   # optional — verify the new table

You pulled new migrations from git

pnpm db:migrate

You want to inspect data without changing anything

pnpm db:studio

Migration files in the repo

Migrations aplicadas ficam em drizzle/migrations/. Cada pasta contém:

  • migration.sql — SQL executado por db:migrate
  • snapshot.json — snapshot interno do schema para o próximo diff de db:generate

Faça commit dos arquivos de migration no git. Colegas e deploys de produção dependem do mesmo histórico SQL ordenado.

Não edite à mão migrations já aplicadas em produção. Se precisar corrigir um erro antes de alguém migrar, delete a pasta de migration não aplicada e regenere. Se já foi aplicada, crie uma migration corretiva nova.

Next steps

Adding a New Table — Tutorial completo: schema → export → generate → migrate → queries.

Database — Visão geral da arquitetura, convenções de schema e padrões de query.