Ir para o conteúdo
Aura Logo
aurabase

Consulte seu banco de dados com o JavaScript SDK

Os fluxos diários de aura.db, as regras que recusam chamadas inseguras e como proteger uma tabela com segurança em nível de linha.

Guia prático9 min lidoNível intermediárioRevisado em 12 de out. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

Ler linhas#

read.tstypescript
const { data, error } = await aura
  .from('todos')
  .select('id, title, done')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .limit(20)

aura.from('todos') é o formato usado em toda esta documentação (é um atalho para aura.db.from('todos'), a mesma chamada). Cada chamada retorna { data, error } e nunca é lançada, consulte opções do cliente e erros.

Cadeia de filtros: eq, neq, gt, gte, lt, lte, like, ilike, in, ise os demais listados no referência de banco de dados. Para uma página de linhas, use range(from, to).

Inserir, atualizar e excluir#

write.tstypescript
// Insira uma linha ou uma matriz de linhas e recupere-as
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// Upsert
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// Atualizar e excluir precisam de um filtro
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

Uma gravação não retorna nada (data é null) a menos que você encadeie .select(): inserir 10.000 linhas não envia 10.000 linhas de volta. Com .select() as linhas voltam, e um PATCH ou POST que não corresponde a nenhuma linha diz o porquê em meta.hint.

Duas regras protegem você de erros:

  • Uma inserção em lote precisa das mesmas chaves em todas as linhas. Linhas com chaves diferentes retornam 400 com All object keys must match. Preencha as chaves que faltam com null.
  • update() e delete() sem filtro são recusados pelo cliente com o código de erro UNFILTERED_MUTATION, antes de qualquer solicitação ser enviada. Para alterar cada linha propositalmente, execute o SQL em um servidor.

Uma linha, muitas linhas, conta#

count.tstypescript
// Exatamente uma linha: um erro se não houver nenhuma ou várias
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 quando o filtro corresponde a zero ou várias linhas

// Zero ou uma linha: os dados são nulos quando nada corresponde
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// Linhas e seu total
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count é o total, qualquer que seja o intervalo

// Somente o total, sem linhas
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact' conta todas as linhas correspondentes. 'planned' e 'estimated' são mais rápidos em tabelas muito grandes e aproximadas.

Proteja uma mesa#

RLS é habilitado por padrão por meio de Aurabase, adicione políticas para conceder acesso

Tabelas criadas por meio de Aurabase (db.sql(), migrações, Studio ou API de tabela) obtêm automaticamente ENABLE e FORCE ROW LEVEL SECURITY (a menos que você inclua explicitamente DISABLE ROW LEVEL SECURITY em seu lote DDL). Ainda sem políticas, os chamadores de anon e authenticated veem []. Tabelas criadas por meio de uma conexão direta Postgres precisam de enable row level security explicitamente. Adicione as políticas necessárias:

SQLsql
create policy todos_own_read on todos
  for select to aura_authenticated
  using (auth.uid() = owner);

As funções canônicas do banco de dados são aura_anon, aura_authenticated e aura_service_role (os aliases de grupo anon, authenticated, service_role também são mapeados para elas em clusters gerenciados). auth.uid() é NULL para a chave pública e um ID de usuário para um usuário conectado. Consulte Segurança em nível de linha.

Uma chave service_role ignora RLS por design: mantenha-a em seu servidor.

Funções SQL e RPC#

Crie uma função a partir de um servidor e chame-a de qualquer lugar com rpc():

server/setup.tstypescript
await admin.db.createFunction({
  name: 'add',
  args: [
    { name: 'a', data_type: 'int', mode: 'IN' },
    { name: 'b', data_type: 'int', mode: 'IN' },
  ],
  returns: 'int',
  language: 'sql',
  body: 'SELECT a + b',
  grant_execute_to: ['anon', 'authenticated'],
})
client.tstypescript
const { data } = await aura.rpc('add', { a: 1, b: 2 }) // → 3
  • grant_execute_to é necessário para chamá-lo. Sem ele, ninguém pode executar a função. Uma função que não está listada obtém 403 permission denied for function. Ambos authenticated e aura_authenticated são aceitos. Isso também vale para funções que você cria com db.sql() ou uma migração em projetos criados após essa alteração (o privilégio padrão EXECUTE de PUBLIC é revogado): adicione grant execute on function hello(text) to aura_authenticated; você mesmo.
  • Uma nova função pode ser chamada após alguns segundos. Até que a API recarregue seu esquema, rpc() retorna 404 Could not find the function.
  • Funções via SQL (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION é permitido no modo SECURITY INVOKER (padrão); SECURITY DEFINER é rejeitado em /raw e deve ser criado por meio de createFunction (POST /v1/db/{project_id}/functions) ou CLI/migrações com grant_execute_to explícito.

Execute SQL de um servidor#

server/migrate.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

await admin.db.sql(`
  create table if not exists todos (
    id uuid primary key default gen_random_uuid(),
    title text not null,
    done boolean not null default false,
    owner uuid,
    created_at timestamptz not null default now()
  )
`)

db.sql() precisa de uma chave service_role. Ele recusa DELETE sem WHERE e não lê catálogos de sistema como pg_class ou pg_roles. Para listar suas tabelas, use admin.db.schema().

Paginação, limite de linha e números exatos

  • Uma leitura retorna no máximo 1.000 linhas — o padrão e o teto rígido, qualquer que seja limit() ou range() que você solicitar. meta.has_more é true quando mais linhas correspondem; peça count: 'exact' para obter também meta.total.
  • Percorra uma grande tabela com paginação de conjunto de chaves, que custa o mesmo na milionésima página: aura.from('events').select('id,label').limit(1000).after('id', lastId) (é .order('id').gt('id', lastId)). .cursor() é apenas MongoDB; offset fica mais lento quanto mais fundo você vai.
  • Números além de 2 ^ 53 do JavaScript. Um bigint acima de 9.007.199.254.740.991 perde seus últimos dígitos quando analisado como um número JS: crie o cliente com { parseBigIntAsString: true } para receber esses valores como strings. Um numeric é retornado como um número JSON quando é exatamente representável e, caso contrário, como uma string decimal exata (valores longos como 12345678901234567890.123456789).
  • count: 'planned' e 'estimated' são apenas estimativas. Eles vêm das estatísticas de PostgreSQL, que estão vazias em uma tabela que acabou de ser carregada (uma tabela de 60 linhas pode reportar 430). Use count: 'exact' quando o número for importante.
  • Uma coluna vector retorna como uma string como "[0.1,0.2,0.3]": analise-a com JSON.parse para obter um number[].
  • Uma visualização é lida com seus privilégios. As visualizações que você cria (SQL, migração) obtêm security_invoker = true, portanto, as políticas das tabelas subjacentes se aplicam ao leitor. Escreva with (security_invoker = false) explicitamente apenas se você realmente deseja que a visualização ignore RLS.
  • db.sql() tenta novamente um 429 após o atraso Retry-After (uma solicitação recusada nunca foi executada). /raw é limitado por projeto; para cargas em massa, use o insert() digitado com uma matriz.