Saltar al contenido
Logotipo de Aurabase
aurabase

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.

Guía práctica9 min leerNivel intermedioRevisado el 12 oct 2026

Esta página fue traducida automáticamente. La versión en inglés es autorizada.

Leer filas#

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') 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#

write.tstypescript
// 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 400 con All object keys must match. Complete las claves que faltan con null.
  • update() y delete() sin filtro son rechazados por el cliente con el código de error UNFILTERED_MUTATION, antes de enviar cualquier solicitud. Para cambiar cada fila a propósito, ejecute SQL desde un servidor.

Una fila, muchas filas, cuentan#

count.tstypescript
// 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#

RLS está habilitado de forma predeterminada a través de Aurabase, agregue políticas para otorgar acceso

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:

SQLsql
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():

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
  • Se requiere grant_execute_to para llamarlo. Sin él, nadie puede ejecutar la función. Un rol que no aparece en la lista obtiene 403 permission denied for function. Se aceptan tanto authenticated como aura_authenticated. Esto también se aplica a las funciones que crea con db.sql() o una migración en proyectos creados después de este cambio (el privilegio predeterminado EXECUTE de PUBLIC está revocado): agregue grant 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() devuelve 404 Could not find the function.
  • Funciones vía SQL (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION está permitido en el modo SECURITY INVOKER (predeterminado); SECURITY DEFINER se rechaza en /raw y debe crearse a través de createFunction (POST /v1/db/{project_id}/functions) o CLI/migraciones con grant_execute_to explícito.

Ejecutar SQL desde un 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() 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() o range() que solicite. meta.has_more es true cuando coinciden más filas; Solicite count: 'exact' para obtener también meta.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; offset se vuelve más lento cuanto más profundizas.
  • Números más allá del 2^53 de JavaScript. Un bigint superior 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. Un numeric se devuelve como un número JSON cuando es exactamente representable y, en caso contrario, como una cadena decimal exacta (valores largos como 12345678901234567890.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). Utilice count: 'exact' cuando el número importe.
  • Una columna vector regresa como una cadena como "[0.1,0.2,0.3]": analícela con JSON.parse para obtener un number[].
  • 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. Escriba with (security_invoker = false) explícitamente solo si realmente desea que la vista omita RLS.
  • db.sql() reintenta un 429 después del retraso Retry-After (una solicitud rechazada nunca se ejecutó). /raw está limitado por proyecto; para cargas masivas use el insert() escrito con una matriz.