Aura Logo
aurabasedocumentos
documentos›Guias›Query your database (SDK)

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.

9 min lido·Nível intermediário·Revisado em 12 de out. de 2026
Este texto em inglês foi gerado automaticamente a partir do original em francês e ainda não foi revisado.
Esta página foi traduzida automaticamente. A versão em inglês é oficial.
#
Leia

1. Leia as 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') é um atalho para aura.db.from('todos'). 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, is, e os outros listados na referência do banco de dados . Para uma página de linhas, use range(from, to).

#
Escreva

2. 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)

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.
#
Resultados

3. 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.

#
Segurança

4. Proteja uma mesa

Uma tabela criada em SQL fica aberta até você habilitar RLS

A segurança em nível de linha está desativada em uma nova tabela. Com a chave pública, qualquer pessoa pode ler e escrever. Ative-o e adicione as políticas necessárias:

SQLsql
alter table todos enable row level security;

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

As funções de banco de dados são aura_anon, aura_authenticated e aura_service_role. 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

5. 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.
  • 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.
  • A criação de funções com SQL bruto (CREATE FUNCTION) é recusada: use createFunction.
#
Servidor

6. Execute SQL de um servidor

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

const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_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().

Última atualização · 12 de out. de 2026