Início rápido
De zero a uma API consultável: banco de dados Postgres dedicado, segurança em nível de linha, geração em tempo real e tipo TypeScript incluída – sem necessidade de cartão de crédito.
Prompt para o seu agente de código
Set up Aurabase in this app by following this page: https://aurabase.cloud/en/docs/getting-started.md
Documentation: read https://aurabase.cloud/llms.txt first. Every docs page is also available as Markdown: add .md to its URL, for example (the same works for every page): https://aurabase.cloud/en/docs/getting-started.md
Client: install @aurabase/aurabase-js and create the client with createClient(NEXT_PUBLIC_AURABASE_URL, NEXT_PUBLIC_AURABASE_ANON_KEY). Keep AURABASE_SERVICE_ROLE_KEY on the server: never put it in client code.
Project access: to read the schema and run SQL, start the Aurabase MCP server over stdio (82 tools with a project key):
npx -y -p @aurabase/mcp-server aurabase-mcp --url https://<slug>.aurabase.cloud --project-id <project-id> --service-role-key aura_sk_…
The project id is in Studio › Settings › General. The service role key is shown once when the project is created; regenerate it in Studio › Settings › Connection if you lost it.Início rápido#
Instale o SDK, crie o cliente e leia suas primeiras linhas.
1. Instale o SDK#
Adicione o SDK ao seu projeto. A guia Rust instala a caixa aurabase; a guia cURL verifica se o URL do seu projeto responde.
pnpm add @aurabase/aurabase-js
2. Crie o cliente#
Crie o cliente com a URL do seu projeto e a chave anon, ambos em Studio › Configurações › Conexão. Mantenha a chave da função de serviço no servidor.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Consulte o banco de dados#
Leia até 10 linhas de todos. A tabela é criada na seção “Criar uma tabela” abaixo; até existir, error está definido.
// `todos` é criado em "Criar uma tabela" abaixo
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Pré-requisitos#
Assumimos que Node.js ≥ 20 está instalado e um terminal POSIX está dentro do alcance. Nenhum banco de dados local é necessário: Aurabase provisiona um banco de dados Postgres dedicado para cada projeto.
Você está vindo de Supabase ou Firebase? A maioria dos conceitos são transponíveis. Veja o guia de migração.
Instalando o SDK#
O SDK oficial expõe um cliente digitado para CRUD, autenticação, tempo real e armazenamento. Funciona da mesma maneira em Next.js, React, Node, Bun ou Deno.
# Recomendado
pnpm add @aurabase/aurabase-js
O nome do pacote inclui o escopo @aurabase/. O pacote aurabase-js sem escopo não é mantido por Aurabase: não o instale.
O SDK inclui diretamente a exportação de @aurabase/aurabase-js/ssr (createServerClient) para Next.js (App Router, Server Actions, Middleware), Remix, Nuxt e SvelteKit com gerenciamento automático de cookies de sessão e fragmentação anti-truncamento.
Crie um projeto#
Crie um projeto no Studio. Quando fica ativo, o Studio mostra um painel Copie suas chaves agora com um .env.local pronto para usar (copie ou baixe): a chave service_role aparece lá uma vez, apenas seu hash é mantido depois. Configurações › Conexão posteriormente mostra a URL do projeto e a chave pública anônima; se você perdeu a chave service_role, regenere-a lá (a anterior é revogada). NEXT_PUBLIC_AURABASE_URL e NEXT_PUBLIC_AURABASE_ANON_KEY podem ser publicados no lado do cliente; AURABASE_SERVICE_ROLE_KEY permanece estritamente no lado do servidor.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Esquema | Acesso | Contém |
|---|---|---|
project_{uuid} | Você | Suas tabelas de aplicativos |
project_{uuid}_auth | Sistema | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | Sistema | buckets, objects, rls_policies |
project_{uuid}_platform | Sistema | functions, jobs, cron_jobs, api_keys |
Todo o caminho também funciona a partir da CLI (veja CLI para a instalação): aura projects create espera até que o projeto esteja pronto e imprime a URL e as chaves uma vez.
aura login
aura projects create todos-app --json > project.json # espera até que o projeto esteja ativo
aura link --project-id "$(jq -r .id project.json)"
export NEXT_PUBLIC_AURABASE_URL="$(jq -r .url project.json)"
export AURABASE_SERVICE_ROLE_KEY="$(jq -r .service_role_key project.json)"
aura db raw "create table todos (id bigint generated always as identity primary key, title text not null, done boolean not null default false, user_id uuid not null default auth.uid(), created_at timestamptz not null default now())"
aura db raw "create policy todos_own_read on todos for select to aura_authenticated using (auth.uid() = user_id)"
aura db raw "create policy todos_own_insert on todos for insert to aura_authenticated with check (auth.uid() = user_id)"
aura db table realtime todos on
aura db raw "select count(*) from todos" --as authenticated --user <a user id> # veja o que esse usuário vê
Nunca inclua AURABASE_SERVICE_ROLE_KEY em um pacote configurável do cliente. Ele ignora todas as políticas RLS e a API o recusa em um navegador (401 SECRET_KEY_IN_BROWSER). Reserve-o para chamadas de servidor (manipuladores de rotas, ações de servidor, trabalhos).
Crie uma tabela#
Abra o Banco de Dados no Studio, clique em Editor SQL (o link na parte inferior do painel de tabelas) e execute este script. A segurança em nível de linha está habilitada em todas as tabelas: as duas primeiras políticas permitem que cada usuário conectado leia e crie suas próprias linhas, a terceira é um exemplo que permite que os visitantes leiam a tabela para que você possa ver suas primeiras linhas sem fazer login. As políticas têm como alvo a função aura_authenticated (aura_anon para visitantes).
create table todos (
id bigint generated always as identity primary key,
title text not null,
done boolean not null default false,
user_id uuid not null default auth.uid(),
created_at timestamptz not null default now()
);
create policy "todos_own_read" on todos for select to aura_authenticated using (auth.uid() = user_id);
create policy "todos_own_insert" on todos for insert to aura_authenticated with check (auth.uid() = user_id);
-- Apenas exemplo: qualquer visitante pode ler todas as tarefas. Solte-o antes da produção:
-- descartar a política "todos_public_read" em todos;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Em seguida, gere os tipos TypeScript do seu esquema (o comando é .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Primeira chamada#
Crie um cliente Aurabase reutilizável lendo chaves de variáveis de ambiente e, em seguida, consulte sua primeira tabela. Os caminhos abaixo são relativos à raiz do seu aplicativo: se o seu projeto usa um diretório src/, coloque lib/, components/ e app/ dentro dele, para que o alias de importação @/ seja resolvido.
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'
export const aura = createClient<Database>(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
Então, em um manipulador de rota ou componente de servidor:
import { aura } from '@/lib/aurabase'
export async function GET() {
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.order('created_at', { ascending: false })
.limit(10)
if (error) throw error
return Response.json(data)
}
Isso retorna as linhas da tabela, inclusive sem um usuário conectado, graças ao exemplo de política todos_public_read. Sem ele (depois que você o descarta, como deveria antes da produção), um visitante recebe []: as outras políticas apenas abrem linhas para aura_authenticated, portanto, conecte um usuário primeiro com aura.auth.signInWithPassword({ email, password }) (consulte Páginas de login prontas para Next.js). Gere novamente os tipos Database com npx @aurabase/gen após cada alteração de esquema.
Para inserir uma primeira linha, inscreva um usuário e insira-o. O padrão da coluna user_id é auth.uid():
import { aura } from '../lib/aurabase'
async function main() {
const email = 'you@example.com'
const password = 'a-strong-password'
await aura.auth.signUp({ email, password })
await aura.auth.signInWithPassword({ email, password })
const { data, error } = await aura.from('todos').insert({ title: 'First todo' }).select()
console.log(data, error)
}
main().catch((err) => {
console.error(err)
process.exit(1)
})
Execute-o com tsx, que resolve a importação sem extensão e lê .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: permita o script de instalação do esbuild e execute:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
Com o npm 11 ou posterior, npx tsx falha com « Você instalou o esbuild para outra plataforma » porque o script de instalação do esbuild está bloqueado por padrão. Use pnpm como acima ou pule tsx e execute o script com a remoção de tipo integrada do Node (Node 22.6+) depois de escrever as duas importações com suas extensões ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Para os usuários do seu projeto, signUp seguido de signInWithPassword funciona imediatamente: a confirmação por e-mail está desativada até que você a ligue em Studio › Autenticação › Configuração (precisa de um servidor de e-mail). Qualquer pessoa pode se inscrever com qualquer endereço, então ative-o antes da produção.
A chave service_role não tem usuário conectado, então auth.uid() é NULL e uma inserção que depende do padrão falha com NOT_NULL_VIOLATION. De um servidor, passe user_id explicitamente.
Conecte-se em tempo real#
Três transportes negociados automaticamente: WebSocket, SSE, NATS. O cliente escolhe o melhor com base na rede – sem necessidade de configuração.
Habilite o tempo real na tabela uma vez, com a CLI:
aura db table realtime todos on
ou com a API HTTP, de um servidor (valores de .env.local):
curl -X PUT "$NEXT_PUBLIC_AURABASE_URL/v1/db/schema/tables/todos/realtime" \
-H "apikey: $AURABASE_SERVICE_ROLE_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
Em seguida, assine as alterações. Um usuário conectado recebe as linhas que suas políticas RLS permitem ler, inclusive quando o canal foi aberto antes do login (ele é autenticado novamente automaticamente); uma assinatura recusada informa CHANNEL_ERROR o motivo.
'use client'
import { aura } from '@/lib/aurabase'
import { useEffect } from 'react'
export function LiveTodos() {
useEffect(() => {
const channel = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (change) =>
console.log(change.eventType, change.new),
)
.subscribe((status, err) => {
// No desenvolvimento, o React StrictMode monta, desmonta e remonta o componente:
// o primeiro FECHADO vem dessa limpeza e é esperado.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
As assinaturas são multiplexadas em uma única conexão TCP. Abra quantos você precisar — sem custos adicionais de rede.