Banco de dados
PostgreSQL 18, um banco de dados dedicado por projeto no cluster da sua organização, esquemas isolados, tipos TypeScript gerados automaticamente, RLS nativo. Sem bifurcações, sem reescrever proxies — suas extensões, gatilhos e PL/pgSQL funcionam como estão.
Postgres 18, sem abstração#
O serviço aura-db expõe um CRUD genérico sobre um PostgreSQL 18: cada projeto tem seu próprio banco de dados, hospedado no cluster PostgreSQL da sua organização (um cluster inteiramente dedicado a um único projeto na oferta corporativa). Cada chamada do SDK é traduzida em SQL nativo por meio de uma camada fina que respeita o RLS policies injetado na sessão.
Você também pode ignorar o SDK e apontar psql, Prisma, Drizzle, Kysely, Metabase ou pg_dump em seu banco de dados: protocolo de conexão padrão PostgreSQL, TLS, uma função que só pode alcançar o banco de dados do seu projeto. Consulte Conectar diretamente abaixo. (Uma implantação que não publica a porta PostgreSQL diz isso em Studio › Configurações › Conexão: use o SDK, a API REST, o editor SQL ou a CLI, aura db raw.)
Um pg_dump fornece seu banco de dados completo (esquema, dados, extensões, políticas). Sem aprisionamentos, migração de saída trivial.
O SDK chama PostgREST, que chama Postgres#
Nos bastidores, o SDK serializa suas chamadas .from().select()… em uma solicitação HTTP para aura-db que delega para um arquivo secundário PostgREST. PostgREST traduz para SQL e abre uma conexão em pool via PgBouncer com o search_path do projeto injetado.
SDK → HTTPS GET /v1/db/sensors?select=id,name
Gateway → aura-db Session verification & routing
aura-db → PgBouncer → PostgreSQL 18
# Conexão com o projeto search_path
SET LOCAL search_path = project_a7f3_, public;
SET LOCAL request.jwt.claims = '{ "sub": "u_9k2", "tenant": "t_4c" }';
SELECT id, name, temperature FROM sensors WHERE active = true LIMIT 50;
As políticas RLS têm acesso a auth.uid(), auth.role(), auth.tenant(). Esses auxiliares leem request.jwt.claims injetado pelo gateway – impossível de ser adulterado no lado do cliente.
Seis habilidades nativas#
- Esquema por projeto. Particionamento aplicado por PostgreSQL: nenhuma coluna tenant_id, uma função de conexão por projeto, direitos nunca abertos para PUBLIC.
- Migrações versionadas. SQL versionado, reversão atômica, tempo de inatividade zero. Os tipos TypeScript são regenerados a cada migração.
- Gerador de código TypeScript e Rust. Geração automática de tipos para tabelas, visualizações, enums e funções RPC a partir de seu esquema ativo.
- Nativo RLS. Políticas declarativas testáveis. O SDK injeta o locatário da declaração em cada conexão.
- Extensões permitidas. 14 extensões instaladas pela plataforma quando um projeto é criado:
pgvector,pgcrypto,uuid-ossp,pg_trgm,pg_graphql,pg_stat_statements,citext,hstore,ltree,unaccent,btree_gin,btree_gist,fuzzystrmatch,intarray. - Ramos do banco de dados.
aura branch createcopia um projeto (esquema, políticas, funções, gatilhos, visualizações e linhas) em um novo projeto com seu próprio URL e chaves, excluído automaticamente após seu tempo de vida. Uma cópia feita no momento da criação, não uma réplica ativa.
CRUD completo, digitado#
As quatro operações básicas compartilham a mesma superfície .from(table). Os tipos retornados são inferidos do seu esquema – abra seu IDE, o preenchimento automático funciona em colunas, junções e retornos.
// Liste os últimos 50 sensores ativos
const { data, error } = await aura
.from('sensors')
.select('id, name, temperature, location!inner(city)')
.eq('active', true)
.order('captured_at', { ascending: false })
.limit(50)
Precisa de SQL mais complexo? Crie uma função Postgres e chame-a via aura.rpc('function_name', args). As funções se beneficiam das mesmas políticas RLS das tabelas.
14 extensões permitidas prontas#
14 extensões permitidas, prontas para cada novo projeto
A plataforma os instala quando o projeto é criado (uma função de projeto não pode executar CREATE EXTENSION sozinha, portanto não há nenhuma etapa de ativação a ser esquecida). Liste o que está instalado com aura db extensions list ou Studio › Banco de dados › Extensões; aura db extensions enable <name> e POST /v1/db/{project_id}/schema/extensions reaplicam um permitido.
- pgvector (
vector) - pg_graphql (instalado quando você ativa GraphQL)
- pg_stat_statements
- pgcrypto
- uuid-ossp
- pg_trgm
- citexto
- hstore
- árvore
- sem sotaque
- btree_gin
- btree_gist
- fuzzystrmatch
- intarray
postgis, pg_cron, timescaledb, pgmq e pg_partman não estão incluídos na imagem gerenciada padrão. Para cargas de trabalho agendadas, acione uma função Edge em um agendamento cron em Cron. Um projeto criado antes desta mudança possui apenas as cinco extensões históricas (vector, pgcrypto, uuid-ossp, pg_trgm, pg_graphql) até que a plataforma execute sua próxima atualização de esquema; você não pode adicionar os outros sozinho, porque somente o operador do banco de dados pode instalá-los.
Conecte-se diretamente: psql, Prisma, Drizzle, pg_dump#
Cada projeto tem sua própria função de login PostgreSQL (proj_xxxxxxxx) e um host no formato <project-slug>.db.<your-domain> na porta 5432. A senha é emitida sob demanda e mostrada uma vez: a plataforma não a mantém clara, então uma senha perdida é substituída, nunca recuperada.
# Host, porta, banco de dados e função do projeto vinculado (sem senha)
aura db connection
# Emita uma senha e imprima a string de conexão completa (revoga a senha anterior)
aura db connection --new-password
# Abra o psql nele (o psql pede a senha)
aura connect
aura db connection --new-password imprime uma string que você pode colar em qualquer lugar:
postgresql://proj_ef13db60:<password>@my-app-ab12cd34.db.example.com:5432/project_694efb7f_...?sslmode=require
O mesmo cartão existe em Studio › Configurações › Conexão › Banco de dados (Gerar senha / Redefinir senha).
- TLS é obrigatório. O endpoint recusa conexões de texto simples (
sslmode=require). Em uma pilha k3d local, o certificado é autoassinado (*.db.localhost), entãosslmode=verify-fullfalha por design; a produção usa um certificado emitido para*.db.<your-domain>. - Confinado ao seu projeto. O roteador escolhe seu banco de dados a partir do nome da função e o força: pedir outro nome de banco de dados ainda chega ao seu e apresentar sua função no host de outro projeto é recusado. Sua função não é de superusuário e não ignora RLS; para executar uma migração como proprietário da tabela, use
BEGIN; SET LOCAL ROLE tenant_<project-uuid>_admin; …; COMMIT;. - As tabelas que você cria aqui são privadas da plataforma. A segurança em nível de linha não pode ser ativada automaticamente para uma tabela criada por meio desta conexão (que precisa de um superusuário PostgreSQL, que um projeto gerenciado nunca expõe), portanto, as chaves públicas não têm privilégio sobre ela: a API REST responde
permission deniedpara a chave anônima e para usuários conectados, enquanto oservice_rolekey, Studio e sua própria função lêem e escrevem. Para expô-lo ao SDK, habilite RLS, conceda e adicione uma política (consulte Segurança em nível de linha):ALTER TABLE posts ENABLE ROW LEVEL SECURITY; GRANT SELECT ON posts TO aura_anon; CREATE POLICY …. PostgREST aprende sobre a nova tabela quando você executaNOTIFY pgrst, 'reload schema'. As tabelas criadas nesta conexão antes da existência desta regra serão fechadas na próxima vez que você emitir uma senha (aura db connection --new-password), a menos que já tenham RLS ativado. - Pool de transações. As conexões passam por PgBouncer no modo de transação. O estado da sessão não é transferido de uma transação para a próxima: use
SET LOCALdentro de uma transação e espere que instruções preparadas nomeadas,LISTENe bloqueios de aconselhamento em nível de sessão não sejam confiáveis (Prisma: adicionepgbouncer=trueà URL). - Versão do cliente.
pg_dumprecusa um servidor mais novo que ele: use um cliente PostgreSQL 18 (pg_dump --version).
O acesso direto depende da implantação que publica a porta PostgreSQL. Está ativado para a pilha k3d local e para implantações cujos valores do Helm o habilitam (ingress.tcp.enabled atrás de ingress-nginx ou pgproxy.nodePort); o Studio e aura db connection informam quando não está.
Para ir mais longe#
- Segurança em nível de linha
Políticas nativas, testes, padrões multilocatários.
- Convenções
Nomeando esquemas, colunas, políticas, auxiliares RLS.
- Ramos de banco de dados
Uma cópia de um projeto para cada solicitação pull, excluída por seu TTL.
- Arquitetura
Como o aura-db se encaixa nos 8 serviços.
- API REST
Superfície HTTP bruta para banco de dados, autenticação, armazenamento.
- Supabase Migração
pg_dump + RLS remapeamento, 1 hora para um projeto médio.