Geração de Esquema

Visão Geral

A Rebase usa um pipeline de esquema-como-código onde suas definições de coleções em TypeScript são a única fonte de verdade. A CLI as transforma através de um pipeline determinístico:

Collections (TypeScript) → Drizzle Schema → SQL Migrations → PostgreSQL

Esta página cobre todos os comandos da CLI envolvidos nesse pipeline.

O Pipeline

1. Coleções → Esquema Drizzle

Suas definições de coleções em config/collections/ descrevem tabelas, colunas, tipos, relações e enums. O comando schema generate as lê e produz um arquivo de esquema Drizzle ORM.

2. Esquema Drizzle → Migrações

A partir do esquema Drizzle gerado, db generate compara com o estado atual do banco de dados e produz arquivos de migração SQL com carimbo de data/hora.

3. Migrações → PostgreSQL

O comando db migrate aplica as migrações pendentes ao seu banco de dados PostgreSQL.

Comandos

rebase schema generate

Gere um arquivo de esquema Drizzle ORM a partir das suas definições de coleções:

rebase schema generate

O que ele faz:

• Lê todas as coleções de config/collections/
• Gera backend/src/schema.generated.ts com as definições de tabelas, enums e relações do Drizzle

Opções:

Flag	Descrição
--collections, -c	Caminho para o diretório de coleções (padrão: config/collections/)
--output, -o	Caminho de saída para o arquivo de esquema gerado
--watch, -w	Observar mudanças e regenerar automaticamente

O modo watch é útil durante o desenvolvimento — edite um arquivo de coleção e o esquema é regenerado instantaneamente:

rebase schema generate --watch

rebase schema introspect

Faça engenharia reversa das definições de coleções a partir de um banco de dados PostgreSQL existente:

rebase schema introspect

O que ele faz:

• Conecta-se ao seu banco de dados (usando a string de conexão do seu .env)
• Inspeciona todas as tabelas, colunas, tipos e chaves estrangeiras
• Gera arquivos de definição de coleções

Opções:

Flag	Descrição
--output, -o	Diretório de saída para os arquivos de coleção gerados

Isso é útil ao adotar a Rebase em um banco de dados existente — faça a introspecção primeiro, depois personalize as coleções geradas.

rebase db push

Envie as mudanças de esquema diretamente para o banco de dados sem arquivos de migração:

rebase db push

O que ele faz:

• Lê o esquema Drizzle gerado
• Aplica as mudanças diretamente ao banco de dados (CREATE, ALTER, DROP)
• Não cria arquivos de migração

Cuidado

db push modifica o banco de dados diretamente. Use-o apenas em desenvolvimento. Para produção, use db generate + db migrate para criar arquivos de migração revisáveis.

rebase db generate

Gere arquivos de migração SQL a partir das mudanças de esquema:

rebase db generate

O que ele faz:

• Compara o esquema Drizzle com o estado atual do banco de dados
• Produz arquivos de migração SQL com carimbo de data/hora no diretório drizzle/
• Os arquivos podem ser revisados, editados e commitados no controle de versão

As migrações geradas são arquivos SQL simples — você pode inspecioná-las e modificá-las antes de aplicá-las.

rebase db migrate

Execute todas as migrações pendentes:

rebase db migrate

O que ele faz:

• Lê o diretório drizzle/ em busca de migrações não aplicadas
• Aplica-as em ordem ao banco de dados
• Rastreia quais migrações foram aplicadas

Definir uma baseline num banco de dados que o Rebase já arrancou

Cada arranque do Rebase assegura o esquema, e rebase db push aplica-o diretamente. Um banco de dados em que qualquer um dos dois já tenha corrido já tem as tabelas e os tipos que a primeira migração criaria, e rebase db migrate para em pq: type "posts_status" already exists (42710).

Não há nada de errado com a migração: o banco de dados foi provisionado por outra via. Registe onde ele já está e migre normalmente:

rebase db migrate --baseline 20260906101530
rebase db migrate

A versão é o prefixo numérico do ficheiro de migração que descreve o que está no banco de dados agora. Essa migração e todas as anteriores ficam registadas como aplicadas; tudo o que vem depois é executado. Num banco de dados que nunca arrancou não é precisa baseline — migre diretamente.

rebase db branch

Ramificação de banco de dados para desenvolvimento paralelo:

rebase db branch create feature_auth
rebase db branch list
rebase db branch delete feature_auth

rebase doctor

Detecte a divergência de três vias entre suas definições de coleções, o esquema Drizzle gerado e o banco de dados PostgreSQL ativo:

rebase doctor

O que ele verifica:

• Coleções ↔ Esquema gerado — estão sincronizados?
• Esquema gerado ↔ Banco de dados — há mudanças não aplicadas?
• Coleções ↔ Banco de dados — há alguma divergência inesperada?

Execute doctor sempre que algo parecer fora de sincronia. Ele aponta exatamente onde está a incompatibilidade.

rebase generate-sdk

Gere um SDK cliente tipado a partir das suas definições de coleções:

rebase generate-sdk

O que ele faz:

• Lê as coleções de config/collections/ (suporta exports de barril index.ts ou arquivos individuais)
• Gera tipos TypeScript para todas as entidades em generated/sdk/
• Produz um arquivo database.types.ts para uso com createRebaseClient<Database>()

Opções:

Flag	Descrição
-c, --collections-dir	Caminho para o diretório de coleções (padrão: config/collections/)
-o, --output	Diretório de saída para o SDK (padrão: generated/sdk/)
--from <link|url>	Lê o esquema de um projeto em execução em vez do código local. link usa o projeto vinculado a este checkout.
--token	Token Bearer para o endpoint de contrato (padrão: $REBASE_SERVICE_KEY)

--from é o que permite que um repositório sem coleções — um frontend separado, uma segunda aplicação web, uma aplicação móvel — gere um cliente tipado a partir do projeto com que fala. REBASE_SERVICE_KEY só é enviado ao projeto vinculado a este checkout; para qualquer outro host, passe --token explicitamente.

Uso após a geração:

import { createRebaseClient } from "@rebasepro/client";
import { collectionsDictionary, type Database } from "./generated/sdk/database.types";

const client = createRebaseClient<Database>({
    baseUrl: import.meta.env.VITE_API_URL,
    collections: collectionsDictionary,
});

// Full type safety and autocomplete
const { data } = await client.data.products.find();

Os nomes dos campos nos tipos gerados são os que a API serve, inalterados: uma coluna createdAt é row.createdAt. Apenas o accessor da coleção é convertido num nome de propriedade (my-notes → client.data.myNotes), que é o que collectionsDictionary mapeia de volta para o slug.

Fluxo de Trabalho de Desenvolvimento

O fluxo de trabalho de iteração rápida para desenvolvimento:

# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Push directly to dev database
rebase db push

Fluxo de Trabalho de Produção

O fluxo de trabalho seguro e revisável para produção:

# 1. Edit your collection in config/collections/
# 2. Generate the Drizzle schema
rebase schema generate

# 3. Generate SQL migration files
rebase db generate

# 4. Review the generated SQL in drizzle/
# 5. Commit the migration to version control
git add drizzle/

# 6. Apply in production
#    A database Rebase has already booted needs a baseline the first time —
#    see the baselining section above.
rebase db migrate

Solução de Problemas

Sintoma	Solução
Could not detect an active database plugin	Instale @rebasepro/server-postgres em backend/package.json
O arquivo de esquema não atualiza	Verifique se o caminho --collections aponta para o diretório correto
A migração mostra mudanças inesperadas	Execute rebase doctor para identificar a divergência
db push falha em produção	Use db generate + db migrate em vez disso
db migrate falha com already exists (42710)	O arranque ou db push já provisionaram o esquema — registe-o com rebase db migrate --baseline <version>

Próximos Passos

• Coleções — Defina seu modelo de dados
• Referência da CLI — Todos os comandos da CLI
• SDK Cliente — Use o SDK gerado