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.
Ler linhas#
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#
// 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
400comAll object keys must match. Preencha as chaves que faltam comnull. update()edelete()sem filtro são recusados pelo cliente com o código de erroUNFILTERED_MUTATION, antes de qualquer solicitação ser enviada. Para alterar cada linha propositalmente, execute o SQL em um servidor.
Uma linha, muitas linhas, conta#
// 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#
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:
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():
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'],
})
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ém403 permission denied for function. Ambosauthenticatedeaura_authenticatedsão aceitos. Isso também vale para funções que você cria comdb.sql()ou uma migração em projetos criados após essa alteração (o privilégio padrãoEXECUTEdePUBLICé revogado): adicionegrant 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()retorna404 Could not find the function. - Funções via SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONé permitido no modoSECURITY INVOKER(padrão);SECURITY DEFINERé rejeitado em/rawe deve ser criado por meio decreateFunction(POST /v1/db/{project_id}/functions) ou CLI/migrações comgrant_execute_toexplícito.
Execute SQL de um servidor#
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()ourange()que você solicitar.meta.has_moreétruequando mais linhas correspondem; peçacount: 'exact'para obter tambémmeta.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;offsetfica mais lento quanto mais fundo você vai. - Números além de 2 ^ 53 do JavaScript. Um
bigintacima 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. Umnumericé retornado como um número JSON quando é exatamente representável e, caso contrário, como uma string decimal exata (valores longos como12345678901234567890.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). Usecount: 'exact'quando o número for importante.- Uma coluna
vectorretorna como uma string como"[0.1,0.2,0.3]": analise-a comJSON.parsepara obter umnumber[]. - 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. Escrevawith (security_invoker = false)explicitamente apenas se você realmente deseja que a visualização ignore RLS. db.sql()tenta novamente um429após o atrasoRetry-After(uma solicitação recusada nunca foi executada)./rawé limitado por projeto; para cargas em massa, use oinsert()digitado com uma matriz.