Consulta tu base de datos con el SDK de JavaScript
Los flujos cotidianos de aura.db, las reglas que rechazan llamadas no seguras y cómo proteger una tabla con seguridad a nivel de fila.
Leer filas#
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.eq('done', false)
.order('created_at', { ascending: false })
.limit(20)
aura.from('todos') es el formulario utilizado a lo largo de esta documentación (es un atajo para aura.db.from('todos'), la misma llamada). Cada llamada regresa { data, error } y nunca tira, mira opciones y errores del cliente.
Cadena de filtros: eq, neq, gt, gte, lt, lte, like, ilike, in, isy los demás enumerados en el referencia de base de datos. Para una página de filas, utilice range(from, to).
Insertar, actualizar y eliminar#
// Inserte una fila o una serie de filas y recupérelas
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()
// insertar
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()
// Actualizar y eliminar necesitan un filtro
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)
Una escritura no devuelve nada (data es null) a menos que encadene .select(): insertar 10,000 filas no devuelve 10,000 filas. Con .select() las filas regresan, y un PATCH o POST que no coincidió con ninguna fila dice por qué en meta.hint.
Dos reglas te protegen de errores:
- Una inserción por lotes necesita las mismas claves en cada fila. Las filas con claves diferentes devuelven
400conAll object keys must match. Complete las claves que faltan connull. update()ydelete()sin filtro son rechazados por el cliente con el código de errorUNFILTERED_MUTATION, antes de enviar cualquier solicitud. Para cambiar cada fila a propósito, ejecute SQL desde un servidor.
Una fila, muchas filas, cuentan#
// Exactamente una fila: error si no hay ninguna o varias
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 cuando el filtro coincide con cero o varias filas
// Cero o una fila: los datos son nulos cuando nada coincide
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()
// Filas y su total.
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count es el total, sea cual sea el rango
// Solo el total, sin filas
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })
count: 'exact' cuenta cada fila coincidente. 'planned' y 'estimated' son más rápidos en tablas muy grandes y aproximados.
Proteger una mesa#
Las tablas creadas a través de Aurabase (db.sql(), migraciones, Studio o la API de tablas) obtienen automáticamente ENABLE y FORCE ROW LEVEL SECURITY (a menos que incluya explícitamente DISABLE ROW LEVEL SECURITY en su lote DDL). Sin políticas todavía, las personas que llaman anon y authenticated ven []. Las tablas creadas a través de una conexión directa Postgres necesitan enable row level security explícitamente. Añade las políticas que necesites:
create policy todos_own_read on todos
for select to aura_authenticated
using (auth.uid() = owner);
Las funciones de base de datos canónicas son aura_anon, aura_authenticated y aura_service_role (los alias de grupo anon, authenticated, service_role también se asignan a ellos en clústeres administrados). auth.uid() es NULL para la clave pública y una identificación de usuario para un usuario que ha iniciado sesión. Consulte Seguridad a nivel de fila.
Una clave service_role omite RLS por diseño: manténgala en su servidor.
Funciones SQL y rpc#
Cree una función desde un servidor, luego llámela desde cualquier lugar con 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
- Se requiere
grant_execute_topara llamarlo. Sin él, nadie puede ejecutar la función. Un rol que no aparece en la lista obtiene403 permission denied for function. Se aceptan tantoauthenticatedcomoaura_authenticated. Esto también se aplica a las funciones que crea condb.sql()o una migración en proyectos creados después de este cambio (el privilegio predeterminadoEXECUTEdePUBLICestá revocado): agreguegrant execute on function hello(text) to aura_authenticated;usted mismo. - Se puede llamar a una nueva función después de unos segundos. Hasta que la API recargue su esquema,
rpc()devuelve404 Could not find the function. - Funciones vía SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONestá permitido en el modoSECURITY INVOKER(predeterminado);SECURITY DEFINERse rechaza en/rawy debe crearse a través decreateFunction(POST /v1/db/{project_id}/functions) o CLI/migraciones congrant_execute_toexplícito.
Ejecutar SQL desde un 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() necesita una clave service_role. Rechaza un DELETE sin un WHERE y no lee catálogos del sistema como pg_class o pg_roles. Para enumerar sus tablas, use admin.db.schema().
Paginación, límite de fila y números exactos.
- Una lectura devuelve como máximo 1000 filas: el valor predeterminado y el límite máximo, lo que sea
limit()orange()que solicite.meta.has_moreestruecuando coinciden más filas; Solicitecount: 'exact'para obtener tambiénmeta.total. - Hojee una tabla grande con paginación de conjunto de claves, que cuesta lo mismo en la millonésima página:
aura.from('events').select('id,label').limit(1000).after('id', lastId)(es.order('id').gt('id', lastId))..cursor()es solo para MongoDB;offsetse vuelve más lento cuanto más profundizas. - Números más allá del 2^53 de JavaScript. Un
bigintsuperior a 9,007,199,254,740,991 pierde sus últimos dígitos cuando se analiza como un número JS: cree el cliente con{ parseBigIntAsString: true }para recibir esos valores como cadenas. Unnumericse devuelve como un número JSON cuando es exactamente representable y, en caso contrario, como una cadena decimal exacta (valores largos como12345678901234567890.123456789). count: 'planned'y'estimated'son solo estimaciones. Provienen de las estadísticas de PostgreSQL, que están vacías en una tabla que se acaba de cargar (una tabla de 60 filas puede informar 430). Utilicecount: 'exact'cuando el número importe.- Una columna
vectorregresa como una cadena como"[0.1,0.2,0.3]": analícela conJSON.parsepara obtener unnumber[]. - Una vista lee con tus privilegios. Las vistas que crea (SQL, migración) obtienen
security_invoker = true, por lo que las políticas de las tablas subyacentes se aplican al lector. Escribawith (security_invoker = false)explícitamente solo si realmente desea que la vista omita RLS. db.sql()reintenta un429después del retrasoRetry-After(una solicitud rechazada nunca se ejecutó)./rawestá limitado por proyecto; para cargas masivas use elinsert()escrito con una matriz.