Pular para o conteúdo

Upgrading

Atualizando de 0.30 para 0.31

Desde 0.31

O 0.31 torna o backend Postgres-first. As tabelas que você declara com defineTable em backend/schema/ são a única coisa que o backend sabe sobre seus dados; o que o painel de administração exibe sobre elas fica no frontend. Quase todas as entradas abaixo são uma consequência dessa divisão, e quase tudo é feito para você por um único comando.

  1. Atualize todos os pacotes @rebasepro primeiro, em cada pacote do workspace, para que os tipos lidos pelo codemod sejam os do 0.31: pnpm -r up "@rebasepro/*@0.31.0", e depois pnpm install. Um projeto em uma versão anterior à 0.30 deve aplicar as alterações de código dos guias intermediários primeiro (Upgrading) e atender aos requisitos mínimos da toolchain do 0.31 — Node 22.22, TypeScript 6, React 19.2.7, React Router 8, Vite 8 (a lista): o codemod carrega um config/ do 0.20–0.29 e sua verificação SQL passa, mas essa verificação compara o compilador do 0.31 consigo mesmo — apenas a etapa 7, contra o seu banco de dados, comprova que o DDL gerado é o que o seu banco de dados possui.

  2. Faça commit, depois execute o codemod como uma simulação (dry run): rebase migrate collections-to-tables --dry-run. Ele exibe os arquivos que escreveria, o que ele recusa (com arquivo e linha), as notas e as etapas manuais, e não escreve nada. Corrija o que ele recusar em config/ primeiro.

  3. Execute para valer: rebase migrate collections-to-tables. Ele grava backend/schema/, frontend/src/cms/ (com ui-config.json), os módulos de backend/ e os arquivos do projeto, adiciona rebaseBackendGuard() ao vite.config.ts do scaffold, reescreve suas chamadas de SDK, move as importações de nomes que o 0.31 moveu para outro pacote (seção 135), e comprova que o SQL gerado é byte a byte idêntico — ou restaura todos os arquivos. Consulte a seção 108.

  4. Leia a última seção de sua saída, “Review before deploying: these rules change meaning”, e decida cada regra listada (abaixo).

  5. Execute as etapas manuais impressas, em ordem. Cada uma indica o arquivo correspondente, e a maioria inclui o trecho de código a ser inserido: a montagem do <RebaseCMS> com tableCustomizations e uiConfig quando seu App.tsx não for o do scaffold (ou o painel estiver montado em outro módulo, informado pela etapa), rebaseBackendGuard() quando seu vite.config.ts não for o do scaffold e em todos os outros apps estáticos do rebase.json (seção 130), hooks globais, uma importação de um nome que o 0.31 removeu (seção 135), e rebase skills install quando o projeto contiver agent skills (seção 128). Execute pnpm install quando a saída listar “Dependencies added”. Em seguida, leia duas listas na parte de SDK da saída:

    • “Rewritten by name — review”: chamadas .collection( em um receptor sem tipo (any), reescritas porque o receptor se chama dataAsAdmin, ou é .data com um nome de tabela literal; o membro collection de um tipo que um slot data / dataAsAdmin contém; e dublês de teste (test doubles). Verifique se cada um pertence ao SDK.
    • “Left unchanged — check each”: chamadas .collection( que o codemod não comprovou serem do SDK, como uma chamada por meio de um tipo que o próprio projeto declara. Uma chamada deixada aqui que seja do SDK falhará em tempo de execução no 0.31: renomeie-a para .table( manualmente. O código que testa se collection existe (typeof data.collection === "function") é uma etapa manual: no 0.31, ele seguirá silenciosamente o outro caminho.

    Um arquivo commitado como saída de build (um .js empacotado ou minificado) nunca é editado: ele é listado, portanto recompile-o após a migração e substitua qualquer cópia vendored do cliente pela compilação do 0.31. Etapas repetidas de um mesmo tipo são impressas apenas uma vez, listando todos os arquivos e linhas aos quais se referem; --json mantém cada etapa separadamente. Em seguida, leia O que os projetos alteraram manualmente: as alterações que projetos reais ainda precisaram fazer após essas etapas.

  6. Execute a linha git rm que o codemod imprimiu assim que o diff for revisado e rebase migrate collections-to-tables --check passar: git rm -r config/collections … e as configurações/ligações movidas para backend/, ou git rm -r config quando nada próprio seu restar lá (seção 109). As próximas três etapas exigem isso: generate-sdk, db push, doctor e verify recusam um projeto que ainda tenha config/collections.

  7. rebase generate-sdk — os nomes do módulo gerado mudaram (seção 115).

  8. Contra o seu banco de dados, execute rebase db push --dry-run e aguarde “No changes: the database already matches these tables.”, depois rebase doctor --policies e certifique-se de que não haja divergência de políticas (policy drift). A verificação SQL do codemod comprova a fidelidade da conversão; essas duas comprovam contra o banco de dados real, e qualquer diferença de política listada por qualquer uma delas representa uma alteração em quem pode acessar o quê.

  9. rebase verify — agora ele também lê frontend/src/cms: uma customização que nomeia uma tabela ou campo inexistente, uma coluna obrigatória deixada fora do formulário, a ausência de rebaseBackendGuard(), ou um ui-config.json não passado para o <RebaseCMS>.

  10. Recompile e faça o deploy. Um bundle gerado antes do 0.31 não inicializa em um runtime 0.31 (seção 112). A primeira inicialização atualiza a versão do schema no banco de dados uma única vez (seção 113).

Execute rebase migrate collections-to-tables --check no CI até que config/ seja removido: ele verifica se as tabelas migradas ainda geram o mesmo SQL que as coleções de origem e sai com código 1 enquanto uma regra listada em “Review before deploying” não for confirmada — passe --accept-rule-changes depois de tê-las revisado.

Revise antes de fazer o deploy: estas regras mudam de significado

Seção intitulada “Revise antes de fazer o deploy: estas regras mudam de significado”

O codemod mantém todas as regras de segurança como foram escritas, e cada uma preserva o nome de sua política. No entanto, o compilador do 0.30 lia apenas a primeira entre condition, using, access: "public" e ownerField, e não reconhecia nenhum outro valor de access, de modo que quatro formatos de regras agora concedem acessos diferentes. Dois deles ampliam o acesso:

A regra 0.30 concedia 0.31 concede
um access: "authenticated" simples (sem roles) nada qualquer chamador autenticado, incluindo convidados (guests) amplia
access + check, sem condition, em select / update / delete / all nenhuma linha existente todas as linhas existentes, para os chamadores em access amplia
access: "authenticated" + condition qualquer um que atenda a condition apenas chamadores autenticados que atendam à condição restringe
access: "authenticated" + check, em insert qualquer um inserindo uma linha correspondente apenas chamadores autenticados restringe

O mais comum é o primeiro caso. Escreva access: "registered" para admitir apenas chamadores com uma conta (não convidados anônimos), ou remova a regra para continuar não concedendo nada. access com roles e um condition de objeto simples continuam significando o mesmo que antes e não são listados.

O codemod também recusa qualquer regra que o compilador do 0.31 recusa: regras que combinem cláusulas excluídas pelo tipo SecurityRule (access junto a ownerField, using ou withCheck; ownerField junto a using, withCheck, condition ou check; condition ou check junto a using ou withCheck), e regras com um valor inválido de access, mode, operation(s) ou roles — um "restrictive" digitado incorretamente costumava compilar como permissivo. Consulte Security rules.

  • O que o GET /api/schema/tables informa. Administradores e detentores de schema:read recebem todas as tabelas. Qualquer outro usuário autenticado, incluindo convidados, recebe apenas as tabelas que suas roles podem acessar, apenas com as regras aplicáveis a eles; relações com outras tabelas são omitidas e flags de hooks são ocultadas. Um frontend que lia a descrição de outra tabela como usuário comum recebe menos dados; schemaTables: { persons: "all" } nas opções do backend restaura a descrição completa. Consulte Endpoints.
  • Os nomes de relações são exatos e chaves estrangeiras do tipo big-integer são números (seção 131).
  • O histórico é servido mascarado (seção 132).
  • Os nomes das ferramentas MCP e o payload da view mudam juntos para o conector hospedado e os runtimes que ele acessa (seção 122).
  • Restrições intencionais. Carimbos de auditoria (colunas .onCreateNow() / .onUpdateNow()) ficam ocultos das colunas de listagem do painel por padrão: uma lista migrada que exibia created_at perde essa coluna até que você defina fields: { created_at: { hidden: false } } em seu customizeTable. O codemod recusa, informando o motivo: arrays JSON de tuplas, um vector / binary / reference dentro de um mapa, databaseId em uma coleção Postgres, isId: "cuid", uma relação isolada com isId e disableDefaultPolicies: true sem regras. Uma relação de coluna única para uma tabela com chave composta é recusada (escreva-a com rel.via()). As tags da OpenAPI passam a ser derivadas do slug, não do nome de exibição. O rebase schema introspect omite tabelas sem chave primária e explica o motivo (um servidor inspecionando o banco de dados ainda a disponibiliza). Uma view simples declarando roles gera erro de compilação; o codemod a descarta com uma observação.
  • O que projetos reais ainda alteraram manualmente — versões mínimas da toolchain, ({ entity }) no código de administração, includes de relações renomeadas, objetos de coleção alterados em tempo de execução, chamadas de SDK em receptores sem tipo: O que os projetos alteraram manualmente.
  • Restauração para outro cluster. O carimbo das políticas de admin padrão gera um hash dos OIDs das roles; assim, após um dump ou restauração pontual (point-in-time restore) em um cluster diferente, o primeiro db push ou inicialização recria essas políticas uma única vez, com os mesmos nomes e o mesmo SQL.
Antes Agora Onde “collection” permanece
uma coleção em config/collections/ uma tabela em backend/schema/ (defineTable) —
properties columns (col.*) e relations (rel.*) —
securityRules, defaultSecurityRules rls (obrigatório), defaultRls —
callbacks, Property.callbacks hooks, o .transform() de uma coluna —
o bloco admin customizeTable em frontend/src/cms/ —
data.collection(slug) data.table(slug) —
o que o painel de administração renderiza uma coleção: uma tabela da forma como o painel a exibe, ou uma coleção do Firestore o CMS: CollectionPanel, o Collection Editor, externalCollections

108. Tabelas em backend/schema substituem config/collections — execute o codemod primeiro

Seção intitulada “108. Tabelas em backend/schema substituem config/collections — execute o codemod primeiro”

Quem é afetado: qualquer projeto com um diretório config/collections/.

O que mudou: o backend lê apenas backend/schema/index.ts e os resultados de defineTable, defineAuthTable e defineView exportados por ele. Arquivos com defineCollection não são lidos por nada: o runtime, todos os comandos da CLI e a validação do rebase.json recusam projetos que ainda contenham config/collections, indicando o comando abaixo. rls é obrigatório em todas as tabelas — uma lista de regras, "admin-only", ou "inherit" para o defaultRls que o índice exporta — e disableDefaultPolicies passa a ser defaultPolicies: false.

O que fazer:

rebase migrate collections-to-tables # or --dry-run first

Ele escreve uma tabela por coleção, com todas as colunas físicas explícitas em suas posições originais (portanto, a coluna de chave de um belongsTo é declarada explicitamente), o índice com defaultRls vindo de defaultSecurityRules, um customizeTable para cada coleção cuja apresentação não era a padrão, e arquivos defineFirestoreCollection para coleções do Firestore. Os callbacks de uma coleção se tornam os hooks da sua tabela e os .transform() das suas colunas; os callbacks globais que config/index.ts exportava são tratados em uma etapa manual (seção 109). Em seguida, ele relê o resultado por meio do novo pipeline: DDL, políticas, busca, vector, triggers, views e o schema do Drizzle devem ser byte a byte idênticos ao que as coleções geravam, caso contrário todos os arquivos são restaurados e a execução é encerrada com código 1 exibindo o diff.

Ele também realiza automaticamente o que antes exigia trabalho manual:

  • Callbacks gerados por uma função auxiliar (callbacks: softDeleteCallbacks(...), ou um objeto de callbacks importado) se tornam hooks: com a mesma expressão, e as funções da função auxiliar são convertidas em propriedades de hook de tabela onde são declaradas (o codemod segue importações relativas, consts, leituras de propriedades e um único return). Quando não for possível seguir a função auxiliar, uma etapa indicará os hooks que devem ser verificados.
  • Uma função storagePath é migrada dividida em duas partes: a função se torna o storage.path da customização, permitindo que o painel continue definindo para onde o upload vai, e o template de path da coluna adota o formato das chaves que ela retorna — o texto estático do template literal com cada ${…} substituído por {path} (`${owner}/cv` → {path}/cv). O servidor passa a aplicar o maxBytes e o accept da coluna a cada upload cuja chave corresponda a esse template, e não apenas àqueles que nomeiam a coluna explicitamente, tornando os limites mais rígidos do que na versão 0.30. Uma função cujo resultado não contenha texto estático é recusada: forneça um texto estático a ela primeiro.
  • Um policy.existsIn({ collection }) do 0.30 mantém sua tabela, e auth: { collection: usersCollection } em um arquivo de entrada de backend customizado é descartado (a tabela defineAuthTable passa a ser a tabela de autenticação). Uma opção de inicialização collections torna-se schemaDir.
  • Um gerador de dynamicProps retorna uma customização de campo com chaves simplificadas no 0.31 ({ readOnly: true }, e não { admin: { readOnly: true } }). O codemod reescreve funções que retornam objetos literais, seja de forma inline ou em módulos compartilhados, e lista quaisquer outras.
  • Apresentação aplicada via spread a partir de um objeto compartilhado é transportada para a customização (….dynamicProps); uma apresentação calculada por uma função wrapper é listada como uma etapa para verificação, e não como uma recusa do projeto. O caminho de um componente é resolvido em relação ao módulo que o declarou, e um valor calculado quando o config/ é carregado (new Date(), Date.now(), uma leitura de variável de ambiente) é mantido como sua expressão original, nunca fixado com o valor da execução.
  • Coleções do Firestore geradas por funções (como um getAllFirestoreCollections() que o app espalha no painel via spread) são convertidas para defineFirestoreCollection uma a uma onde o arquivo da coleção mantém seu literal; uma etapa por builder lista as restantes e a estrutura a ser escrita, e outra etapa lista qualquer referência escrita fora de um literal convertido, que ainda conteria path.
  • Importações de config/ por meio de um alias de caminho (uma entrada em paths no tsconfig, um resolve.alias no Vite) são reescritas ou listadas como importações relativas, e um storageAuthorize reexportado por config/index.ts é transferido para backend/storage.ts.
  • Uma relação renomeada para <key>Relation mantém seu rótulo, coluna de listagem e título: a customização passa a referenciar a nova chave. Código que a inclua não acompanha a alteração automaticamente (o que alterar).

O que não puder ser migrado com exatidão é recusado informando o arquivo e a linha, e nada é escrito: uma coleção construída chamando uma função, um spread ou accessor que não possa ser analisado, um banco de dados diferente de Postgres ou Firestore, ou um arquivo de saída existente com outro conteúdo (mova-o para outro local ou use --force). Uma árvore git com alterações não commitadas ou um projeto fora do git também são recusados, garantindo que a migração gere um único diff revisável. --json exibe o relatório completo para uso por scripts ou agentes. Consulte rebase migrate e Tables.

As tabelas geradas declaram suas colunas da mesma forma que o pg-core do Drizzle — col.varchar({ length: 160 }), col.timestamp({ withTimezone: true }), col.text().array(), pgEnum(...), .default(sql`…`), .generatedByDefaultAsIdentity() — portanto, sua saída não requer alterações adicionais; consulte Columns. Uma tabela escrita manualmente com base em uma versão de pré-lançamento do 0.31 com as sintaxes antigas (col.timestamptz(), col.varchar(160), col.array(col.text()), col.enum(values, { name }), .defaultSql(), .identity(), .column("…")) não compilará mais: o script tooling/scripts/drizzle-sweep.mts no repositório Rebase faz essa conversão, reescrevendo apenas o encadeamento de métodos dos builders e, com a flag --verify, comprova que todas as tabelas convertidas compilam para o mesmo descritor (npx tsx drizzle-sweep.mts --verify backend/schema).

A etapa de sdk-calls que é executada em seguida também reescreve fontes de regras: existsIn({ collection }) e membership: { collection } passam a ser table (seção 123); --skip-sdk-calls também pula essa reescrita. O que restar para você fazer manualmente é exibido em etapas numeradas e, caso o projeto possua agent skills instaladas, a última etapa será a linha rebase skills install para atualizá-las (seção 128). Executar apenas rebase migrate exibe o menu de ajuda para ambos os subcomandos.

Quem é afetado: todos os projetos — config/ era um workspace próprio.

O 0.31 deixa de ler config/collections; ele não proíbe a existência de config/. O codemod remove o que o Rebase lia — os arquivos de coleções e a infraestrutura que agora fica em backend/ (resources.ts, storage.ts, generated/register.ts e as reexportações correspondentes em config/index.ts) — e mantém os seus próprios módulos em config/ intactos, importáveis como antes: config/ continua como um pacote do workspace, e o backend continua compilando ../config/**/*. Apenas as importações dos arquivos removidos são reescritas: um arquivo de coleção importado pelo código do backend passa a apontar para o módulo da tabela (uma etapa lista os usos que o liam como um objeto); se importado pelo código do frontend, passa a ser uma importação de tipos da tabela onde era usado apenas como tipo, ou gera uma etapa indicando a customização correspondente; uma função utilitária dentro de config/collections é copiada para junto do código que precisa dela.

O que mudou: o que ficava junto às coleções foi movido para backend/:

Antes Agora
config/resources.ts backend/resources.ts
config/storage.ts, storageAuthorize de config/index.ts backend/storage.ts
callbacks exportados de config/index.ts hooks exportados de backend/hooks.ts (TableHooks: table em vez de collection, values em vez de row)
config/generated/register.ts backend/generated/register.ts
rebase.json config, usersCollection tables (padrão backend/schema); a tabela de auth é aquela declarada com defineAuthTable

O runtime lê storageAuthorize e hooks, e nada mais desses módulos; qualquer outra exportação é reportada durante a inicialização. O frontend deve importar backend/** apenas como tipos — pnpm check:frontend-backend-imports recusa importações de valores, o que enviaria código do servidor para o navegador.

O que fazer: o codemod move resources.ts, storage.ts e o registro, além de reescrever rebase.json, package.json, pnpm-workspace.yaml e backend/tsconfig.json. Os callbacks globais são informados como uma etapa manual: mova-os para backend/hooks.ts manualmente e adicione hooks.ts ao include do backend/tsconfig.json para que o tsc os verifique. Em seguida, execute a linha de git rm impressa: git rm -r config/collections …, ou git rm -r config caso não reste mais nada próprio seu lá.

Quem é afetado: backends inicializados manualmente (initializeRebaseBackend, createRebaseBackend), e código que anexa hooks após a inicialização.

O que mudou:

Antes Agora
collections, collectionsDir tables, defaultRls, schemaDir
callbacks hooks
auth.collection removido: use defineAuthTable em tables
backend.setCollectionCallbacks(slug, cb) backend.setTableHooks(slug, hooks)
propriedades de hook collection, row table (o descritor), values
composeCallbacks composeTableHooks de @rebasepro/common
openRebase({ collections, callbacks }) openRebase({ tables, hooks }), com tables originado de compileSchema([...])
OpenedRebase.collections; a variável collections do rebase console .tables; tables
await initializeRebaseBackend({ app, server, collectionsDir: "./config/collections", callbacks });
await initializeRebaseBackend({ app, server, schemaDir: path.resolve(__dirname, "../schema"), hooks });

Hooks associados a um objeto de coleção passado no local da chamada não são mais executados: o driver executa os hooks das tabelas que ele gerencia, portanto anexe-os usando setTableHooks.

O que fazer: rebase migrate sdk-calls reescreve setCollectionCallbacks, adapta as propriedades dos hooks e lista cada objeto de opções do backend que precisa ser atualizado manualmente. Scripts que abrem os dados devem compilar suas tabelas:

const rebase = await openRebase({ databaseUrl, collections, callbacks });
const rebase = await openRebase({ databaseUrl, tables: compileSchema([products, orders]), hooks });

Consulte Scripts. Consulte Backend overview e Global hooks.

111. O painel de administração renderiza as tabelas que o servidor disponibiliza

Seção intitulada “111. O painel de administração renderiza as tabelas que o servidor disponibiliza”

Quem é afetado: qualquer frontend que monte <RebaseCMS>.

O que mudou: a propriedade collections de <RebaseCMS collections> foi removida. O painel passa a exibir todas as tabelas que o backend disponibiliza em GET /api/schema/tables, sem a necessidade de um arquivo por tabela, além de externalCollections (Firestore). tableCustomizations recebe os objetos de customizeTable provenientes de frontend/src/cms/. O plugin de coleções do Vite e o módulo virtual:rebase-collections foram removidos. O CollectionsProvider aceita essas mesmas três entradas (tableCustomizations, externalCollections, tables).

import { collections } from "virtual:rebase-collections";
<RebaseCMS collections={collections}/>
import { postsCms } from "./cms/posts";
<RebaseCMS tableCustomizations={[postsCms]}/>

O que fazer: o codemod gera frontend/src/cms/index.ts, que exporta tableCustomizations (e externalCollections), e o monta no App.tsx padrão do scaffold; um App.tsx não reconhecido, o plugin em vite.config.ts e a declaração do módulo virtual serão listados como etapas manuais na saída. Consulte Customizing a table.

112. Formato de bundle 3; bundles no formato 2 são recusados

Seção intitulada “112. Formato de bundle 3; bundles no formato 2 são recusados”

Quem é afetado: qualquer deploy de um bundle compilado — hospedado por conta própria com a imagem de runtime ou na Rebase Cloud.

O que mudou: o schema de um bundle é composto por entry.tables, ao lado de entry.resources, entry.storage e entry.hooks; o bundleFormat passa a ser 3 e o contrato de runtime passa a ser 2. Bundles nos formatos 1 ou 2 carregam config/collections, que o runtime 0.31 não é capaz de ler; portanto, a inicialização falha informando o comando do codemod na mensagem de erro, em vez de inspecionar o banco de dados e expor uma API diferente.

O que fazer: migre o código-fonte, execute rebase build e faça o deploy. Na Rebase Cloud, fazer o deploy do repositório migrado aciona uma nova compilação. Consulte Runtime and bundles.

Na Rebase Cloud, um projeto ainda no 0.30 continua rodando, mas não pode receber deploys. A plataforma continuará servindo o bundle atual e as atualizações de runtime serão pausadas (o console exibirá esse aviso), mas ela aceitará apenas o formato 3: uma tentativa de deploy a partir de uma CLI na versão 0.30 fará o upload de todo o bundle e, em seguida, será recusada com BUNDLE_FORMAT_TOO_OLD. A solução para qualquer projeto consiste nos mesmos três comandos:

pnpm exec rebase upgrade --to latest
rebase migrate collections-to-tables
rebase cloud deploy

Uma versão da CLI superior à 0.32.0 recusa a operação antecipadamente, antes de compilar ou fazer o upload: rebase build e rebase cloud deploy em um projeto cujas tabelas ainda estejam em config/collections serão interrompidos informando o nome do codemod; um --bundle-dir contendo um bundle no formato 2 é recusado com a mensagem “Nothing was uploaded”; e rebase upgrade aponta o codemod como próxima etapa em vez de rebase build. (O comando rebase upgrade nativo da versão 0.30 ainda encerra informando “Run rebase build”; esse é o build que será interrompido.)

113. A versão do schema é calculada a partir das tabelas (v2:)

Seção intitulada “113. A versão do schema é calculada a partir das tabelas (v2:)”

Quem é afetado: todos os bancos de dados provisionados por um runtime anterior ao 0.31 e todos os SDKs gerados.

O que mudou: a versão do schema gera um hash dos descritores compilados das tabelas e passa a ter o prefixo v2:. Um banco de dados registrado com v1: reportará a alteração no modelo uma única vez — o log de inicialização e o rebase doctor informarão isso, junto das instruções de atualização — e todos os SDKs gerados serão reportados como desatualizados uma vez.

O que fazer: provisione uma vez usando o novo runtime: inicialize o processo responsável pelo schema ou execute rebase db push. Com REBASE_REQUIRE_SCHEMA_MATCH=true, atualize o schema antes de reiniciar os demais processos. Gere o SDK novamente.

Quem é afetado: código que realiza condicionais baseando-se no code do erro.

O que mudou:

Antes Agora
NO_COLLECTIONS (404) NO_TABLES
COLLECTION_READ_ONLY (405) TABLE_READ_ONLY
UNKNOWN_COLLECTION (SDK) UNKNOWN_TABLE
INVALID_COLLECTION_PATH (SDK) INVALID_TABLE_PATH

O que fazer: rebase migrate sdk-calls reescreve essas strings literais. Consulte Errors.

Quem é afetado: qualquer cliente, função, cron, hook ou script que referencie uma tabela pelo slug ou que receba o dicionário gerado.

O que mudou:

Antes Agora
data.collection(slug) data.table(slug)
createRebaseClient({ collections: collectionsDictionary }) createRebaseClient({ tables: tablesDictionary })
os tipos gerados CollectionName, CollectionsDictionary TableName, TablesDictionary
lote { op, collection } (SDK e POST /api/data/_batch) { op, table }
CollectionClient, SDKCollectionClient, CollectionAccessor, CollectionTrashAccessor TableClient, SDKTableClient, TableAccessor, TableTrashAccessor
offline: maxCachedRowsPerCollection, maxCachedQueriesPerCollection …PerTable
acessor reservado <name>Collection; collectionCollection <name>Table; a tabela collection agora é collection
const { data } = await client.data.collection("posts").find();
const { data } = await client.data.table("posts").find();

Acessores tipados (client.data.posts) não sofreram alterações.

O que fazer: o codemod executa rebase migrate sdk-calls sobre seu código — execute-o de forma independente em um projeto já migrado — e depois execute rebase generate-sdk. Chamadas a .collection( cujo receptor não seja o SDK são mantidas inalteradas e devidamente listadas. Consulte Typed SDK.

116. Flags da CLI: --schema-dir, não --collections

Seção intitulada “116. Flags da CLI: --schema-dir, não --collections”

Quem é afetado: scripts e etapas de CI que chamam a CLI informando o caminho do schema.

O que mudou: --collections / -c são recusadas em todos os comandos que realizam a leitura do schema, indicando o codemod na mensagem (o generate-sdk ignora um --collections-dir avulso); --schema-dir especifica um diretório de schema diferente de backend/schema. O comando rebase schema introspect escreve arquivos defineTable em backend/schema/ — a flag --output foi removida. REBASE_STRICT_COLLECTION_CONFIG não é mais lida: um schema que não compilar sempre impedirá a inicialização.

O que fazer: substitua as flags. Consulte CLI e Schema generation.

117. O editor de schema edita backend/schema com TablePatch

Seção intitulada “117. O editor de schema edita backend/schema com TablePatch”

Quem é afetado: código que consome as rotas do editor de schema ou de live-schema, além de deploys que definem variáveis de edição em tempo real.

O que mudou: as rotas /api/admin/schema-editor/collection/save, collection/delete, property/save e property/delete foram removidas. O editor passa a atender a GET /tables, POST /preview e POST /apply, e as rotas /plan e /apply de edição de schema em tempo real passam a receber { patches: TablePatch[] } em vez de uma coleção ou seu patch correspondente. REBASE_LIVE_SCHEMA_COLLECTIONS_PATH é recusada na inicialização: use REBASE_LIVE_SCHEMA_PATH (padrão backend/schema), e liveSchema.repository.collectionsPath passa a ser schemaPath. Apresentação visual nunca constitui uma edição de schema: ela é armazenada como preferências de UI (/api/admin/ui-config). Uma edição cujo arquivo no disco tenha sido modificado após o preparo da alteração (um salvamento na IDE, outro processo) retorna o código 409 SCHEMA_EDIT_STALE_FILE e nada é gravado; anteriormente, isso retornava 400 SCHEMA_EDIT_REFUSED.

O que fazer: renomeie a variável; reescreva os consumidores dessas rotas para enviar patches do tipo TablePatch e faça o reload ao receber SCHEMA_EDIT_STALE_FILE. Consulte Live schema editing.

Quem é afetado: customizações que referenciavam um componente React por meio de um caminho em formato de string ou via thunk lazy () => import(…).

O que mudou: as propriedades Field / Preview / Filter de um campo, bem como Actions de coleção, entityViews[].Builder, collectionViews[].Builder, formView.Builder e sobrescritas de componentes agora devem receber o próprio componente diretamente. ComponentRef, ComponentLike, LazyComponentRef e isLazyComponentRef (@rebasepro/types), asComponentRef e asReactComponent (@rebasepro/cms-types), além de resolveComponentRef / useResolvedComponent (@rebasepro/app), foram removidos. O customizeTable recusa uma string ou thunk com a mensagem “imported by value”.

O que fazer: importe o componente diretamente no arquivo frontend/src/cms/ e passe-o por referência. Consulte Custom fields.

O codemod realiza isso para todos os caminhos em formato de string e registra cada um deles, pois um componente importado passa a ter seus tipos verificados em relação ao slot onde uma string antes não era validada. Um Preview que declara customProps?: MyProps falhará na checagem do tsc do seu frontend: o slot fornece customProps como unknown, já que não há vínculo estático entre as customProps de um campo e os componentes que as consomem. Declare customProps?: unknown e faça o narrowing de tipo dentro do próprio componente.

119. Preferências do painel são preferências de UI

Seção intitulada “119. Preferências do painel são preferências de UI”

Quem é afetado: código que implementa UserConfigurationPersistence.

O que mudou: a forma como um usuário redimensionou ou reordenou uma tabela agora é uma alteração do tipo UiTablePreferences: getTablePreferences / saveTablePreferences substituem getCollectionConfig / onCollectionModified, e o tipo de configuração parcial de coleção que eles recebiam foi removido. O armazenamento local do navegador as mantém sob a chave table_preferences::<slug>, ignorando os dados gravados por painéis antigos; dessa forma, a largura das colunas e os modos de visualização de cada usuário serão resetados uma única vez. A propriedade userSelect em campos foi removida: utilize uma coluna .userId() como seletor de usuário.

A integração do Studio acompanha essas mudanças: StudioSchemaEditing.updateCollection passa a ser applyTablePatches(slug, patches), e o editor de coleções envia { patches } para o editor de schema.

O que fazer: migre a persistência customizada para os novos dois métodos e atualize implementações personalizadas de StudioSchemaEditing para utilizar applyTablePatches.

Quem é afetado: projetos que utilizam @rebasepro/server-mongo ou declaram database(…, { engine: "mongodb" }).

O que mudou: o pacote foi removido, assim como os tipos de coleções do Mongo e todo o restante do modelo associado a ele. O Postgres é o único mecanismo suportado no servidor: uma fonte com outro mecanismo impede a inicialização do runtime, indicando o erro explicitamente.

O que fazer: migre seus dados para o Postgres. Não há um caminho de migração automatizado interno no Rebase.

Quem é afetado: projetos híbridos que contenham coleções com engine: "firestore".

O que mudou: uma coleção do Firestore é uma fonte para o CMS lida diretamente pelo navegador: use defineFirestoreCollection de @rebasepro/firebase, dentro de frontend/src/cms/, repassado para <RebaseCMS externalCollections>. Uma referência entre o Firestore e uma tabela Postgres é armazenada como o ID do registro de destino, e uma referência Firestore cujo path coincida com o slug de uma tabela Postgres passará a apontar para a referida tabela Postgres.

O que fazer: o codemod escreve os arquivos defineFirestoreCollection. Aponte referências para uma coleção do Firestore utilizando o slug da respectiva coleção. Consulte Firebase.

122. Ferramentas MCP são nomeadas com base em tabelas

Seção intitulada “122. Ferramentas MCP são nomeadas com base em tabelas”

Quem é afetado: prompts, scripts e allow-lists que referenciem nomes de ferramentas MCP.

O que mudou: no endpoint remoto /mcp: list_collections, describe_collection, query_collection, show_collection, count_documents, aggregate_documents, get_document, create_document, update_document, delete_document → list_tables, describe_table, query_table, show_table, count_rows, aggregate_rows, get_row, create_row, update_row, delete_row; o argumento collection passa a ser table, e show_app / save_app agora recebem tables. No servidor local: list_documents → query_table, get_document → get_row, create_document → create_row, update_document → update_row, delete_document → delete_row; rebase_schema_plan passa a receber patches; os recursos passam a usar o padrão rebase://tables/{name}. O payload das views em MCP Apps passa para a versão 3: descritores de tabelas redigidos com base no chamador, permissões por tabela e as preferências de UI do chamador organizadas em preferences (file, workspace, user; uma chave de API não possui a camada user), com blocos e seeds referenciando table. A view collection-table foi removida. list_tables não possui mais title; describe_table inclui primaryKey, relations, o rls do chamador, title e presentation.

O que fazer: renomeie as chamadas. A view e o servidor precisam operar na mesma versão de payload: conectores hospedados e os runtimes com os quais se comunicam devem ser atualizados conjuntamente, e qualquer view de MCP gerada pelo projeto deve ser recompilada com os pacotes da versão 0.31. Consulte MCP tool reference e Remote MCP.

Quem é afetado: regras que usem policy.existsIn ou tenant por associação (membership tenant), além de regras que combinem access com outras cláusulas.

O que mudou: policy.existsIn({ collection, where }) passa a ser existsIn({ table, where }), e tenant.from.membership.collection passa a ser membership.table; os nomes das políticas não se alteram. Quatro formatos de regras agora concedem permissões diferentes, sendo dois deles mais permissivos (consulte a tabela acima): um { access: "authenticated" } isolado, que antes não concedia acesso, agora admite qualquer chamador autenticado, e as tabelas de junção associadas recebem suas políticas de gravação em arestas. Regras combinando cláusulas incompatíveis com o tipo SecurityRule, ou com valores inválidos de access, mode, operation ou roles, serão recusadas.

O que fazer: o codemod renomeia as chaves, recusa regras inválidas informando o arquivo e linha, e lista as regras com mudança de comportamento na seção “Review before deploying”. Para cada uma, decida se deve mantê-la, alterá-la para access: "registered" (usuários autenticados com conta cadastrada) ou removê-la. Em seguida, avalie os resultados de rebase db push --dry-run e rebase doctor --policies no seu banco de dados.

Quem é afetado: instâncias do Studio apontadas para um backend anterior à versão 0.31 e scripts do console JS do Studio.

O que mudou: todas as ferramentas cientes do schema passam a ler GET /api/schema/tables; ao se conectarem a um runtime sem esse endpoint, elas exibirão um aviso de atualização. A seção de regras declaradas no editor de RLS reflete o que foi compilado pelo servidor. Scripts no console JS passam a receber context.tables (antes context.collections).

O que fazer: atualize o runtime em conjunto com o painel. Consulte Studio.

Quem é afetado: ferramentas que consomem a saída de rls-check --format agent.

O que mudou: remediation.rebase.securityRules passa a ser remediation.rebase.rls, o trecho gerado é um defineTable(…, { rls }), e a versão do formato do documento passa para 2. --json permanece inalterado. Consulte rls-check.

O que fazer: altere o consumo para a nova chave.

Quem é afetado: projetos utilizando o plugin de revisão (review plugin).

O que mudou: reviewSecurityRules(slug, review) passa a ser reviewRls(slug, review), aplicado via spread no rls da tabela; findReviewConfigProblems e assertReviewConfig agora recebem descritores de tabela.

O que fazer: renomeie a chamada e passe services.tables() ou compileTables(…).

Quem é afetado: código que consome o gerador diretamente.

O que mudou: generateTypedefs(tables) e generateSDK(tables, options) passam a receber TableDescriptor[] — o retorno de compileTables e o conteúdo servido em GET /api/schema/tables — em vez de coleções.

O que fazer: compile suas definições antes de chamar o método, ou utilize o comando rebase generate-sdk.

128. A agent skill rebase-collections passa a ser rebase-tables

Seção intitulada “128. A agent skill rebase-collections passa a ser rebase-tables”

Quem é afetado: projetos com as agent skills instaladas, e prompts ou instruções que façam menção a essa skill.

O que mudou: a skill que ensina o modelo de dados agora é rebase-tables: cobrindo a criação de tabelas, colunas, relações, rls, hooks e a camada do CMS associada. O comando rebase skills install remove a cópia antiga de rebase-collections, incluindo instalações anteriores à criação do manifesto de skills, mantendo qualquer diretório com esse mesmo nome criado manualmente por você.

O que fazer: execute rebase skills install após concluir a atualização. As instruções exibidas pelo rebase migrate collections-to-tables também reforçam essa necessidade. Renomeie as referências à skill em arquivos de instruções que a utilizem. Consulte Agent Skills.

129. useJsonCollectionsConfigController foi removido

Seção intitulada “129. useJsonCollectionsConfigController foi removido”

Quem é afetado: projetos que armazenavam definições de coleções em JSON usando @rebasepro/cms.

O que mudou: o hook useJsonCollectionsConfigController foi descontinuado, assim como seu tipo de opções e a classe de armazenamento JSON subjacente. O schema de uma tabela reside em backend/schema, e as configurações de visualização no painel residem nas preferências de UI: frontend/src/cms/ui-config.json em ambiente de desenvolvimento, e na tabela rebase.ui_preferences em produção.

O que fazer: declare as tabelas usando defineTable (rebase migrate collections-to-tables gera essas declarações a partir das definições das coleções antigas) e passe o uiConfig do scaffold para o componente <RebaseCMS>. Consulte Customizing a table.

130. rebase build recusa frontends sem rebaseBackendGuard()

Seção intitulada “130. rebase build recusa frontends sem rebaseBackendGuard()”

Quem é afetado: qualquer projeto que possua um frontend.

O que mudou: o frontend só pode importar elementos de backend/ como tipos (type). Uma importação de valor incluiria código do servidor — como hooks e eventuais secrets acessados por eles — dentro do bundle enviado ao navegador. O plugin rebaseBackendGuard(), disponibilizado em @rebasepro/app/vitePlugin, interrompe os comandos vite build e vite dev caso qualquer módulo do frontend resolva dependências em backend/, indicando o importador, a instrução de import e o arquivo envolvido após processar aliases, paths do tsconfig, resoluções de pacotes ou absolutas, globs, ?raw, reexportações e dynamic imports. O comando rebase build, assim como a compilação do frontend executada pelo rebase cloud deploy, abortam o processo se o arquivo de configuração do Vite não incluir o plugin; rebase dev emitirá um aviso; e rebase verify acusará cms-backend-guard-missing.

O que fazer: o codemod insere o plugin automaticamente no arquivo frontend/vite.config.ts padrão do scaffold, e imprime as linhas necessárias para qualquer outra configuração customizada:

import { rebaseBackendGuard } from "@rebasepro/app/vitePlugin";
export default defineConfig({
plugins: [react()],
plugins: [react(), rebaseBackendGuard()],
});

Depois, certifique-se de converter qualquer importação de valor proveniente de backend/ para import type.

131. Linhas trafegadas na rede seguem suas colunas

Seção intitulada “131. Linhas trafegadas na rede seguem suas colunas”

Quem é afetado: clientes que leem chaves estrangeiras ou nomeiam relações, e operações de escrita que enviam colunas geradas ou objetos JSON incompletos.

O que mudou: os valores são processados pelo codec de sua coluna durante a saída e submetidos às regras da coluna durante a entrada.

  • Colunas de chave estrangeira do tipo bigint ou numeric geradas por relações, que o Postgres retorna como texto, são trafegadas como número no REST, no SDK e no painel de administração. Colunas numéricas explicitamente declaradas já seguiam esse comportamento.

  • Os elementos de arrays nativos são trafegados conforme o tipo de seu escalar correspondente, no REST, SDK, socket e driver:

    Coluna 0.30 retornava 0.31 retorna
    timestamptz[] ["2026-01-02 11:00:00+01"] ["2026-01-02T10:00:00.000Z"]
    numeric[] (driver aberto sem a configuração de numéricos na inicialização: testes, scripts) ["1.50", "2.25"] [1.5, 2.25]
    bigint[] com elemento nulo [1, 0, 3] [1, null, 3]
    date[], timestamptz[] ou array de enum com elemento nulo ["2026-01-02", "NULL"] ["2026-01-02", null]

    Tipos como date[], time[], text[], uuid[], boolean[], integer[] e double precision[] continuam sendo retornados como antes. A forma como os dados são gravados não se altera: ler uma linha e gravá-la novamente persiste exatamente o mesmo array.

  • Qualquer relação indicada em include, filtros ou ordenação deve utilizar seu nome exato. As tentativas automáticas de resolução usando o slug ou variações em snake_case foram descontinuadas.

  • Colunas geradas são rejeitadas em operações de escrita e suprimidas do schema de entrada da OpenAPI.

  • A presença de campos obrigatórios no interior de objetos JSON passa a ser estritamente validada; $inc e itens de arrays em colunas de inteiros devem ser números inteiros.

O que fazer: trate chaves estrangeiras como números onde antes fazia comparações com strings, faça o parse de elementos de timestamptz[] no formato RFC 3339 e trate valores nulos de arrays como null, e certifique-se de referenciar relações exatamente como declaradas na tabela (as chaves em relations). Remova o envio de colunas geradas nas mutações.

Quem é afetado: sistemas ou leitores de snapshots de histórico, e implementações customizadas de DataDriver.

O que mudou: registros de histórico passam a ser processados da mesma forma que operações de leitura: checagem de acesso aos campos primeiro, seguida por afterRead (global, tabela, coluna). Uma coluna mascarada via hook ou .transform({ afterRead }) permanece mascarada em todos os snapshots; colunas cujo chamador não possua permissão de leitura são omitidas e excluídas de changed_fields; chaves de colunas deletadas são suprimidas; e uma ação de restauração (revert) nunca grava em colunas que o chamador não tenha permissão para ler. Um hook que lance uma exceção em um snapshot antigo fará a requisição falhar. Na versão 0.30, os valores eram servidos em formato bruto, portanto projetos com histórico e regras de mascaramento devem ser atualizados.

Um registro de histórico reflete o conteúdo da linha exatamente como retornado por GET /api/data/<table>/<id> sem a cláusula include: valores simples, e relações belongsTo representadas por sua chave estrangeira. Snapshots legados gerados pelo modelo de visão do painel de administração antigo são entregues, e restaurados, refletindo esse mesmo formato: o envelope { "__type": "date", "value" } é convertido para o seu valor direto, uma referência { "__type": "relation" } de uma relação proprietária se torna a chave estrangeira sob o próprio nome da chave, e outras referências passam a ser a chave da linha relacionada. A versão 0.30 fornecia essas referências de forma literal.

Drivers fornecem acesso ao histórico através do método DataDriver.serveStoredRows(path, rows), executado dentro da transação de leitura do chamador; rotas de histórico respondem com código 501 se o driver não implementar o método, prevenindo a entrega de dados não mascarados.

O que fazer: nada para o driver Postgres padrão. Implementações personalizadas de driver devem incluir o método serveStoredRows. Consulte History.

133. Exportações de @rebasepro/server nomeiam tabelas

Seção intitulada “133. Exportações de @rebasepro/server nomeiam tabelas”

Quem é afetado: qualquer servidor montado manualmente utilizando os módulos internos de @rebasepro/server em vez de initializeRebaseBackend / createRebaseBackend.

O que mudou:

Antes Agora
new RestApiGenerator(collections, …) new RestApiGenerator(tables, …) (RestTables)
mountOpenApiDocs({ collections }), createHistoryRoutes({ collections }) mountOpenApiDocs({ serverTables }), createHistoryRoutes({ tables })
versionProperty, buildCollection*Schema versionColumn, buildTable*Schema; validadores e utilitários de conflito e ETag recebem um TableDescriptor
auth-collection-writes auth-table-writes: createUserThroughAuthTable, isAuthTable, prepareAuthTableUpdates, deletingAuthTableUsers
opção do auth adapter collectionAuthConfig authTableHooks (CompiledAuthHooks)
McpRoutesConfig.getCollections getTables()
assertUploadWithinPropertyLimits, readUploadPropertyContext assertUploadWithinColumnLimits, readUploadColumnContext (retorna { table, column }); detalhes de recusa reportam column
provisionCollectionTables, provisionCollectionPolicies, collectionsStoredBy provisionTableSchema, provisionTablePolicies, tablesStoredBy
handGlobalCallbacksTo, warnOnAuthCollectionDataCallbacks handGlobalHooksTo, warnOnAuthTableDataHooks
SchemaEditingAdmin.planSchemaChange(collections, …) planSchemaChange(tables, …) usando CompiledTable[]; EditedSchema.tables
buildCollectionFromTableMetadata, IntrospectedCollection, IntrospectedRelation removidos: tabelas inspecionadas são representadas por TableDescriptor
createUserThroughAuthCollection; NestedWriteHop.parentCollection / .targetCollection; ContractRoutesConfig.collectionRegistry createUserThroughAuthTable; .parent / .target (descritores); removido
o carregador de coleções: CollectionConfigError, ConfigProblem, applyCollectionDefaults, CollectionDefaults e as opções de validação, accessModelFromCollections, loadBundleConfigExports, BundleConfigExports, unknownKeyPolicyFromEnv, UnknownKeyPolicy removidos: compileSchema / loadBackendSchema carregam e validam backend/schema, com exceções informando cada erro via SchemaDefinitionError

O que fazer: atualize as nomenclaturas. O comando rebase migrate sdk-calls renomeia assertUploadWithinPropertyLimits e as constantes de campos de upload (UPLOAD_COLLECTION_FIELD / UPLOAD_PROPERTY_FIELD → UPLOAD_TABLE_FIELD / UPLOAD_COLUMN_FIELD, com os mesmos valores), e gera etapas manuais numeradas para as demais importações e opções listadas nesta tabela.

134. Exportações de @rebasepro/server-postgres nomeiam tabelas

Seção intitulada “134. Exportações de @rebasepro/server-postgres nomeiam tabelas”

Quem é afetado: código que instancia o driver Postgres diretamente, envolve o adapter em camadas customizadas ou consome o planejador de schema.

O que mudou:

Antes Agora
a classe PostgresCollectionRegistry, getTable(name), registerTable PostgresTableRegistry, getPgTable, registerPgTable
openPostgresDriver(config, { collections }) openPostgresDriver(config, { tables }), onde tables vem de compileSchema; chamadas de driver não possuem a propriedade collection (seção 137)
adapter / bootstrapper: ensureCollectionSchema, ensureCollectionPolicies, readCollectionsSchemaVersion, stampCollectionsSchemaVersion ensureTableSchema, ensureTablePolicies, readTablesSchemaVersion, stampTablesSchemaVersion, recebendo CompiledTable[]
serializePropertyToServer, parsePropertyFromServer serializeColumnToServer(value, column); parsePropertyFromServer foi removido — leituras pelo driver retornam a linha REST (seção 136)
ensureCollectionTables, planCollectionSchemaEnsure, planCollectionPolicies, CollectionPolicyPlan, lockCollectionTables ensureTables, planTableSchemaEnsure, planTablePolicies, TablePolicyPlan, lockTables
CollectionIndexSpec, CollectionIndexConfigError, collectionIndexStatements TableIndexSpec, TableIndexConfigError, tableIndexStatements
checkCollectionsVsDatabase / …VsSchema / …VsSdk, columnKeysFromCollections, buildDrizzleRelationsFromCollections, schemaOfCollection, getTableIncludesFromCollections checkTablesVs…, columnKeysFromTables, buildDrizzleRelationsFromTables, schemaOfTable, getTableIncludesFromTables
SchemaDifference.collection, .property (e os campos de log de aviso de drift no boot) .slug, .key
createStampKeys, sharedRelationName, isAuthCollection, lowerCompiledTables, buildCollectionIndexPlan removidos

O formato JSON retornado pelo planejador mantém suas chaves: SchemaReconcileColumn.collection e os tipos de SchemaChange continuam os mesmos.

O que fazer: atualize as nomenclaturas. Wrappers que adaptam o driver para um BackendBootstrapper devem repassar ensureTableSchema e ensureTablePolicies. Consulte Embedding the Postgres driver.

135. @rebasepro/types e @rebasepro/common removem o modelo de coleções de suas raízes

Seção intitulada “135. @rebasepro/types e @rebasepro/common removem o modelo de coleções de suas raízes”

Quem é afetado: código que importa tipos de coleções ou propriedades, helpers do painel de administração ou funções utilitárias de migração a partir de @rebasepro/types ou @rebasepro/common — campos e views customizadas, plugins, testes com fixtures de coleções — além de drivers customizados que implementem o registro de dados.

O que mudou: os pacotes base passam a descrever apenas tabelas. A modelagem descritiva de uma coleção usada pela interface do painel agora reside em @rebasepro/cms-types:

  • Tipos migrados de @rebasepro/types: CollectionConfig, PostgresCollectionConfig, FirebaseCollectionConfig, AnyCollectionConfig, todas as variações de …Property (StringProperty, NumberProperty, ArrayProperty, …) e Properties, CollectionCallbacks e suas propriedades de hook, as categorias de relações do 0.30 e suas formas Resolved…, CollectionIndex, o esquema de cores para chips (ColorScheme, ColorKey, …), FieldAccess, EnumValues.
  • Helpers migrados de @rebasepro/common: os utilitários de políticas baseados em coleções (policyToPostgres, compileRulePolicies, getEffectiveSecurityRules, getGeneratedPolicyNames, …), CollectionRegistry, resolveCollectionRelations, resolveRelation, getTableName, findRelation, rowToViewModel, resolvePrimaryKeys, a verificação de acesso em nível de campo de propriedades (effectiveAccess, canReadField, canWriteField), evaluateCondition, canEditEntity, resolveProperty, getDefaultValuesFor, getSubcollections, getCopyValues, enumToObjectEntries. Regras geradas de expressões puras passam a usar compilePolicyExpression(expr) de @rebasepro/common.
  • composeCallbacks agrega os callbacks de uma coleção para o painel e foi movido para @rebasepro/cms-types; @rebasepro/server não o reexporta mais. O código do backend deve agregar hooks de tabela usando composeTableHooks de @rebasepro/common, e o codemod apontará importações no backend de composeCallbacks como uma etapa manual informando essa necessidade.
  • defineCollection foi removido de @rebasepro/common e @rebasepro/cms-types: declare a tabela via defineTable em backend/schema e aplique customizações via customizeTable em frontend/src/cms; para o Firestore, use defineFirestoreCollection de @rebasepro/firebase.
  • Acessores e tipos de dados do painel: Entity, EntityValues, TableAccessor, TableTrashAccessor, FindResponse, QueryBuilderInterface, RebaseData e AuthState saíram de @rebasepro/types; buildRebaseData, wrapAsEntityData, buildRoutedRebaseData, EntityDataOptions, QueryBuilder, RelationRef e createRelationRef saíram de @rebasepro/common. Todos agora são importados de @rebasepro/cms-types. A camada de dados nativa do SDK — buildSdkData, createDriverTableRows, buildRoutedSdkData, presentes em @rebasepro/common — trafega linhas diretamente e preserva seus retornos anteriores.
  • EntityDataOptions.resolveCollection foi substituído por primaryKeysOf, viewModelOf, storedValuesOf e viewModelSourceOf; a função collectionEntityDataOptions(resolveCollection, { resolveDataPath, resolveAccessor }) de @rebasepro/cms-types os constrói.
  • Utilitários de migração (collectionsToTableDefs, collectionToTableDef, LiftNote, LiftResult, LiftOptions) foram transferidos para @rebasepro/common/migrate, acompanhados de uma réplica imutável do modelo de coleções da versão 0.30 (tipos Legacy…) e de defineLegacyCollection.
  • Outras remoções na raiz dos pacotes, listadas pelo codemod como etapas manuais: a API de patches de coleções de @rebasepro/types (CollectionPatch, CollectionPatchOp, applyCollectionPatch, collectionPatchProblems, isCollectionPatch, nestCollectionPatchPaths → use TablePatch), seus helpers de JSON para coleções (diffCollections, diffJsonValues, toCollectionJson, RUNTIME_ONLY_COLLECTION_KEYS, runtimeOnlyKeyIn), as capacidades legadas do Mongo DocumentAdmin, isDocumentAdmin e supportsDocumentAdmin, e as propriedades RebaseProjectContract.collectionSlugs / .collections / .generatedAt (/api/meta/contract passa a servir tables); em @rebasepro/common, buildTenantSecurityRule → tenantSecurityRule, defaultPoliciesDisabled → tableDefaultPoliciesDisabled, restoresSoftDeletedRow → isSoftDeleteRestore, softDeleteFieldOf → softDeleteColumn, getJunctionConfigForRelation → resolveTableJunctions, e isRelationRequired, relationDeclaringProperty, requireCallbackCollection sem substitutos diretos (consulte o TableDescriptor).
  • O registro de um driver passa a ser TableRegistryInterface (antes CollectionRegistryInterface): setGlobalHooks? e setTableHooks? substituem getGlobalCallbacks / setGlobalCallbacks?. globalHooksAsCallbacks, resolveDriftCheckName e PENDING_TABLE_FEATURES foram removidos.

O que fazer: rebase migrate sdk-calls (executado junto com collections-to-tables) redireciona as importações listadas abaixo para seus novos pacotes — mesclando-as com importações pré-existentes e mantendo import type, type inline e apelidos as — adicionando as novas dependências aos arquivos package.json correspondentes; execute pnpm install ao final. Importações de identificadores extintos, usos com namespace (import * as), export *, import() dinâmicos ou require() que utilizem os nomes afetados serão sinalizados em etapas manuais numeradas. Testes que utilizem coleções literais como fixtures devem tipá-las com os tipos Legacy… e processá-las via @rebasepro/common/migrate.

Todos os identificadores que a versão 0.31 transferiu de pacote ou descontinuou estão documentados em Importações que mudaram no 0.31, acompanhados de orientações de substituição para os removidos. Esse catálogo é derivado diretamente do mapeamento utilizado pelo codemod, refletindo rigorosamente o que o comando rebase migrate sdk-calls reescreve.

136. O driver Postgres e as leituras one-shot do socket retornam a linha do REST

Seção intitulada “136. O driver Postgres e as leituras one-shot do socket retornam a linha do REST”

Quem é afetado: funções ou plugins que realizem leituras via requireDriver(c) / getDriver(c), implementações que consumam os frames FETCH_COLLECTION / FETCH_ONE do socket, e código que extraia objetos baseados no discriminador { __type } das respostas.

O que mudou: o retorno das leituras foi unificado em uma única estrutura. Os métodos fetchCollection e fetchOne do driver Postgres — utilizados internamente por requireDriver(c), plugins, frames one-shot de sockets, MCP e pelo simulador de RLS — passam a devolver o mesmo conteúdo retornado por GET /api/data/<table>:

Valor Leitura pelo driver no 0.30 0.31
um timestamp { "__type": "date", "value": … } uma string RFC 3339
um belongsTo { "__type": "relation", "id", "path" } associado ao nome da relação a chave estrangeira atribuída à sua própria chave (authorId)
uma linha relacionada todas as relações carregadas via fetchOne apenas relações explicitadas via include, contendo a respectiva linha de destino
um vetor, um bytea { "__type": "Vector" }, uma data URL no formato padrão servido via REST

FetchOneProps aceita o parâmetro include (ListenOneTarget foi descontinuado: use FetchOneProps). As chamadas via rebase.data, context.data e via SDK já retornavam essa estrutura e continuam inalteradas.

O pacote @rebasepro/client processa payloads do REST e frames de sockets como JSON tradicional: valores com a propriedade __type deixam de ser automaticamente convertidos para instâncias de Date, EntityReference, EntityRelation, GeoPoint ou Vector, e documentos JSON que contenham a chave __type serão retornados conforme armazenados.

O que fazer: consuma a linha diretamente em formato plano: converta datas a partir das strings retornadas, leia referências de chaves estrangeiras diretamente por suas respectivas chaves e forneça include para carregar as relações necessárias:

const article = await requireDriver(c).fetchOne({ path: "articles", id });
const authorId = article?.author.id; // a { __type: "relation" } ref
const article = await requireDriver(c).fetchOne({ path: "articles", id, include: ["author"] });
const authorId = article?.authorId;

137. Interfaces de driver e backend utilizam tabelas, não coleções

Seção intitulada “137. Interfaces de driver e backend utilizam tabelas, não coleções”

Quem é afetado: implementações personalizadas de DataDriver, adaptadores de bancos de dados ou servidores customizados compostos pelos módulos isolados de @rebasepro/server.

O que mudou:

Antes Agora
o argumento collection em operações de DataDriver (fetch, save, delete, count, search, listen) removido: o driver determina a tabela gerenciada através de path
checkUniqueField(path, name, value, id, collection) checkUniqueField(path, name, value, id?)
scanStoredRows({ path, collection, pageSize }) scanStoredRows({ path, pageSize })
DataDriver.initTextSearch removido
DatabaseAdapterInitConfig.collections, .collectionRegistry removidos: o adaptador recebe instâncias de CompiledTable[]
BackendServices.collections() services.tables()
serializeCollections, deserializeCollections, isSerializedCollectionRef, SerializedCollectionRef removidos: descritores passam a ser disponibilizados via GET /api/schema/tables
AuthAdapter.prepareUserCreation(values, collectionAuth, options?), describeUserCreationContract(collectionAuth) prepareUserCreation(values, options?), describeUserCreationContract()
initializeDriver retornando { driver, collectionRegistry, … }; BackendInstance.collectionRegistry { driver, tableRegistry, … }; BackendInstance.tableRegistry
PolicyEvalContext.entity (uma instância de Entity) PolicyEvalContext.row (valores brutos da linha)
wrapAsSdkData(…) buildSdkData(driver); para múltiplas origens de dados: buildRoutedSdkData
FindResponse de @rebasepro/client FindResult
ListenCollectionRequest, ListenEntityRequest de @rebasepro/server ListenCollectionProps, ListenOneProps

O que fazer: descarte os argumentos removidos e faça o mapeamento de tabelas via path. O codemod identificará usos de implements DataDriver indicando-os como uma etapa manual. Consulte Embedding the Postgres driver.

138. O backend aceita apenas os valores documentados pela API REST

Seção intitulada “138. O backend aceita apenas os valores documentados pela API REST”

Quem é afetado: clientes que gravam relações to-one como objetos ou vetores no formato { value }, consultas que filtram relações usando objetos, código que importa classes de valores do painel e aplicações offline com mutações enfileiradas pelo 0.30.

O que mudou: as mutações exigem o mesmo formato gerado nas consultas de leitura — estabelecendo paridade de escrita entre REST, sockets, MCP e no SDK local:

Valor Aceito Agora recusado
uma relação to-one (belongsTo, hasOne, um via to-one) a chave da linha relacionada, ou null ("" é tratado como null), sob o nome da relação ou da chave estrangeira um objeto como { "id": 5 }: retorna 400 VALIDATION_INVALID_VALUE, “‘posts.author’ links one ‘authors’ row: write that row’s key (a string or a number), or null to unlink — not an object.”
uma relação to-many (hasMany, manyToMany, um via gravável to-many) uma lista de chaves, ou uma lista de { id, _pivot? } — (propriedades adicionais no objeto são ignoradas, como antes)
um vetor uma lista de números um Vector, ou { "value": [...] }: retorna 400, “‘embedding’ expects a vector as a list of numbers”
uma data, um horário texto em formato ISO (Date em execuções no processo) —
um geopoint { latitude, longitude } —
um bytea uma URL data:application/octet-stream;base64, (Buffer / Uint8Array no processo) —
filtro em relações a chave correspondente o desempacotamento de objetos foi descontinuado: o objeto é comparado integralmente

A versão 0.30 tolerava a escrita de relações to-one enviadas como objetos, extraindo silenciosamente seu atributo id; esse formato nunca fez parte da documentação oficial e pertencia ao modelo interno da interface administrativa. Agora, o painel de administração realiza a conversão desse modelo em valores de payload diretamente no navegador antes de disparar gravações e filtros.

As classes de valores do painel foram realocadas com o restante de seu modelo de dados: EntityReference, EntityRelation, GeoPoint, Vector e EntityReferenceProps devem ser importados de @rebasepro/cms-types (removidos de @rebasepro/types), e normalizeToEntityRelation também (removido de @rebasepro/common); o utilitário withRelationReferencesOnly foi extinto. O histórico grava a linha no formato puro da leitura; snapshots antigos são servidos e restaurados também com base nesses valores primitivos (seção 132).

A fila de sincronização offline do @rebasepro/client armazena valores conforme trafegados na rede. Mutações offline pendentes enfileiradas pelo SDK 0.30 são convertidas assim que lidas para repetição: nenhuma operação gravada antes do upgrade é perdida.

O que fazer: passe a enviar diretamente a chave: use { "author": 5 } em vez de { "author": { "id": 5 } }; envie vetores como listas de números e filtre relacionamentos informando a chave. O script rebase migrate sdk-calls transfere as importações dessas classes de valores (consulte a listagem). Consulte Writes.

139. /api/docs é disponibilizado para o mesmo público do endpoint de schema

Seção intitulada “139. /api/docs é disponibilizado para o mesmo público do endpoint de schema”

Quem é afetado: qualquer pessoa ou ferramenta que leia /api/docs ou acesse /api/swagger — como Swagger UI, ferramentas de geração de clientes e pipelines de CI.

O que mudou: se enableSwagger não for declarado (variável de ambiente REBASE_ENABLE_SWAGGER ausente), em qualquer ambiente, a documentação OpenAPI passa a ser servida apenas aos chamadores com autorização para consumir tabelas via GET /api/schema/tables, seguindo as mesmas restrições — código 401 para não autenticados salvo se configurado schemaTables.public, e código 403 para tokens sem escopo apropriado para o schema ou dados — exibindo para cada usuário estritamente as tabelas, colunas e relacionamentos acessíveis a ele (administradores mantêm visão completa). A interface Swagger UI foi desativada por padrão. Servidores operando sem autenticação responderão com 404 DOCS_UNAVAILABLE. A versão 0.30 expunha o schema integral publicamente para usuários anônimos em desenvolvimento, reservando-o exclusivamente para administradores em produção.

enableSwagger / REBASE_ENABLE_SWAGGER /api/docs /api/swagger
não definido (padrão) para cada chamador autorizado a consultar o schema: apenas suas tabelas não servido
true o documento completo, aberto a todos servido fora do ambiente de produção
false o documento completo, restrito à autenticação de admin não servido

O que fazer: envie credenciais autenticadas ao requisitar /api/docs. Se desejar expor a documentação integralmente a todos como ocorria no ambiente de desenvolvimento do 0.30, declare REBASE_ENABLE_SWAGGER=true (ou configure enableSwagger: true). Consulte Endpoints.

140. Uma coluna de pivot many-to-many não pode declarar .transform()

Seção intitulada “140. Uma coluna de pivot many-to-many não pode declarar .transform()”

Quem é afetado: definições rel.manyToMany(…, { pivot: { … } }) cujas colunas da tabela intermediária usem .transform().

O que mudou: o compilador recusa essa construção com um erro (“the pivot column “x” declares .transform() …“). O transform em colunas da tabela pivot nunca era executado, permitindo que valores destinados a mascaramento fossem expostos no formato bruto do banco.

O que fazer: remova a declaração .transform() e aplique o mascaramento do atributo _pivot via hooks.afterRead na tabela de destino. Consulte Relations.

Seção intitulada “141. Um link tem exatamente as mesmas permissões de leitura e escrita que sua coluna de chave”

Quem é afetado: clientes que realizem mutações em belongsTo usando o nome da relação, leiam ou filtrem relações com colunas de chave protegidas, ou dependam do comportamento de strictWrites: false.

O que mudou: qualquer restrição sobre a coluna de chave passa a valer para qualquer método de acesso que a leia ou modifique.

  • Atribuir um link usando o nome da relação ({ "reviewer": 7 }) passa a aplicar todas as regras de validação da coluna de chave vinculada — .readOnly(), .private(), access.write, carimbos temporais de criação, coluna de tenant e imutabilidade de chave — via REST, bulk, _batch, sockets e MCP. Informar valores conflitantes enviando ambas as propriedades simultaneamente ({ "reviewer": 7, "reviewerId": 8 }) acarreta em erro 400 VALIDATION_INVALID_VALUE. Tentar transferir uma linha para outro tenant manipulando a relação responde com o erro 400 TENANT_IMMUTABLE (anteriormente 500).
  • Relações só podem ser lidas se o usuário tiver acesso de leitura a todas as colunas envolvidas nas junções de chave, em todas as tabelas percorridas: a chave do belongsTo, a chave estrangeira de destino no caso de hasMany / hasOne, e quaisquer colunas que sirvam de ponte em etapas de um via. Relações inacessíveis são descartadas de include e _count, enquanto o uso em filtros, ordenação ou navegação aninhada retornará FIELD_NOT_READABLE (ou relação inexistente caso a coluna seja .private()). Mutações to-one usando via que exigissem a leitura prévia de colunas protegidas do usuário falham com FIELD_NOT_READABLE. Esses cenários reversos e com via já eram bloqueados a partir do 0.30.x.
  • Acessos a links cujas colunas de chave não possam ser lidas são omitidos de include, e qualquer tentativa de filtrar, ordenar, selecionar em fields ou navegar por eles responde com FIELD_NOT_READABLE; caso a coluna seja .private(), a relação é tratada como inexistente. GET /api/schema/tables, OpenAPI e a ferramenta MCP describe_table documentam links e suas respectivas chaves de forma unificada; portanto, chaves cujos links associados estejam bloqueados também são suprimidas dessas definições.
  • strictWrites: false determina apenas um comportamento: campos não modelados são repassados ao driver subjacente (sendo gravados caso existam na tabela do banco, ou retornando 400 VALIDATION_UNKNOWN_FIELDS). Ele nunca flexibiliza o acesso a colunas declaradas, carimbos do sistema, dados de tenant, chaves de registro, alvos de relacionamentos ou validações de _pivot.

O que fazer: realize mutações de um link optando por uma única propriedade, ou informando o mesmo valor em ambas se enviadas juntas; garanta que chamadas que leiam links restritos utilizem roles com permissão de leitura sobre suas chaves. Consulte Field access.