Inicio rápido
De cero a una API consultable: base de datos Postgres dedicada, seguridad a nivel de fila, tiempo real y generación de tipo TypeScript incluida; no se requiere tarjeta de crédito.
Prompt para tu agente de código
Set up Aurabase in this app by following this page: https://aurabase.cloud/en/docs/getting-started.md
Documentation: read https://aurabase.cloud/llms.txt first. Every docs page is also available as Markdown: add .md to its URL, for example (the same works for every page): https://aurabase.cloud/en/docs/getting-started.md
Client: install @aurabase/aurabase-js and create the client with createClient(NEXT_PUBLIC_AURABASE_URL, NEXT_PUBLIC_AURABASE_ANON_KEY). Keep AURABASE_SERVICE_ROLE_KEY on the server: never put it in client code.
Project access: to read the schema and run SQL, start the Aurabase MCP server over stdio (82 tools with a project key):
npx -y -p @aurabase/mcp-server aurabase-mcp --url https://<slug>.aurabase.cloud --project-id <project-id> --service-role-key aura_sk_…
The project id is in Studio › Settings › General. The service role key is shown once when the project is created; regenerate it in Studio › Settings › Connection if you lost it.Inicio rápido#
Instale el SDK, cree el cliente y lea sus primeras filas.
1. Instale el SDK#
Agregue el SDK a su proyecto. La pestaña Rust instala la caja aurabase; la pestaña cURL verifica que la URL de su proyecto responda.
pnpm add @aurabase/aurabase-js
2. Crea el cliente#
Cree el cliente con la URL de su proyecto y la clave anónima, ambas en Studio › Configuración › Conexión. Mantenga la clave de función de servicio en el servidor.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Consultar la base de datos.#
Lea hasta 10 filas de todos. La tabla se crea en la sección "Crear una tabla" a continuación; hasta que exista, se establece error.
// `todos` se crea en "Crear una tabla" a continuación
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Requisitos previos#
Suponemos que Node.js ≥ 20 está instalado y que hay un terminal POSIX dentro del alcance. No se requiere ninguna base de datos local: Aurabase proporciona una base de datos Postgres dedicada para cada proyecto.
¿Vienes de Supabase o Firebase? La mayoría de los conceptos son transponibles. Ver el guía de migración.
Instalación del SDK#
El SDK oficial expone un cliente escrito para CRUD, autenticación, tiempo real y almacenamiento. Funciona de la misma manera en Next.js, React, Node, Bun o Deno.
# Recomendado
pnpm add @aurabase/aurabase-js
El nombre del paquete incluye el alcance @aurabase/. El paquete aurabase-js sin alcance no lo mantiene Aurabase: no lo instale.
El SDK incluye directamente la exportación @aurabase/aurabase-js/ssr (createServerClient) para Next.js (App Router, Server Actions, Middleware), Remix, Nuxt y SvelteKit con administración automática de cookies de sesión y fragmentación antitruncamiento.
Crear un proyecto#
Crea un proyecto desde el Estudio. Cuando se activa, Studio muestra un panel Copie sus claves ahora con un .env.local listo para usar (cópielo o descárguelo): la clave service_role aparece allí una vez, solo se conserva su hash después. Configuración › Conexión luego muestra la URL del proyecto y la clave pública anónima; si perdiste la clave service_role, regénala allí (la anterior queda revocada). NEXT_PUBLIC_AURABASE_URL y NEXT_PUBLIC_AURABASE_ANON_KEY se pueden publicar en el lado del cliente; AURABASE_SERVICE_ROLE_KEY permanece estrictamente en el lado del servidor.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| esquema | Acceso | Contiene |
|---|---|---|
project_{uuid} | tu | Tus tablas de aplicaciones |
project_{uuid}_auth | Sistema | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | Sistema | buckets, objects, rls_policies |
project_{uuid}_platform | Sistema | functions, jobs, cron_jobs, api_keys |
Toda la ruta también funciona desde la CLI (consulte CLI para la instalación): aura projects create espera hasta que el proyecto esté listo e imprime la URL y las claves una vez.
aura login
aura projects create todos-app --json > project.json # espera hasta que el proyecto esté activo
aura link --project-id "$(jq -r .id project.json)"
export NEXT_PUBLIC_AURABASE_URL="$(jq -r .url project.json)"
export AURABASE_SERVICE_ROLE_KEY="$(jq -r .service_role_key project.json)"
aura db raw "create table todos (id bigint generated always as identity primary key, title text not null, done boolean not null default false, user_id uuid not null default auth.uid(), created_at timestamptz not null default now())"
aura db raw "create policy todos_own_read on todos for select to aura_authenticated using (auth.uid() = user_id)"
aura db raw "create policy todos_own_insert on todos for insert to aura_authenticated with check (auth.uid() = user_id)"
aura db table realtime todos on
aura db raw "select count(*) from todos" --as authenticated --user <a user id> # ver lo que ve ese usuario
Nunca incluya AURABASE_SERVICE_ROLE_KEY en un paquete de cliente. Omite todas las políticas RLS y la API las rechaza desde un navegador (401 SECRET_KEY_IN_BROWSER). Resérvelo para llamadas al servidor (controladores de ruta, acciones del servidor, trabajos).
Crear una tabla#
Abierto Base de datos en Studio, haga clic en Editor SQL (el enlace en la parte inferior del panel de tablas) y ejecute este script. La seguridad a nivel de fila está habilitada en todas las tablas: las dos primeras políticas permiten que cada usuario que haya iniciado sesión lea y cree sus propias filas, la tercera es una ejemplo que permite a los visitantes leer la tabla para que pueda ver las primeras filas sin iniciar sesión. Las políticas se dirigen a aura_authenticated role (aura_anon para visitantes).
create table todos (
id bigint generated always as identity primary key,
title text not null,
done boolean not null default false,
user_id uuid not null default auth.uid(),
created_at timestamptz not null default now()
);
create policy "todos_own_read" on todos for select to aura_authenticated using (auth.uid() = user_id);
create policy "todos_own_insert" on todos for insert to aura_authenticated with check (auth.uid() = user_id);
-- Solo ejemplo: cualquier visitante puede leer cada tarea. Déjalo antes de la producción:
-- eliminar la política "todos_public_read" en todos;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Luego genere los tipos TypeScript de su esquema (el comando dice .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Primera llamada#
Cree un cliente Aurabase reutilizable leyendo claves de variables de entorno y luego consulte su primera tabla. Las rutas a continuación son relativas a la raíz de su aplicación: si su proyecto usa un directorio src/, coloque lib/, components/ y app/ dentro de él, para que se resuelva el alias de importación @/.
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'
export const aura = createClient<Database>(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
Luego, en un controlador de ruta o un componente del servidor:
import { aura } from '@/lib/aurabase'
export async function GET() {
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.order('created_at', { ascending: false })
.limit(10)
if (error) throw error
return Response.json(data)
}
Esto devuelve las filas de la tabla, incluso sin un usuario que haya iniciado sesión, gracias a la política de ejemplo todos_public_read. Sin él (una vez que lo eliminó, como debería hacerlo antes de la producción), un visitante obtiene []: las otras políticas solo abren filas en aura_authenticated, así que primero inicie sesión como usuario con aura.auth.signInWithPassword({ email, password }) (consulte Páginas de inicio de sesión listas para usar para Next.js). Regenere los tipos Database con npx @aurabase/gen después de cada cambio de esquema.
Para insertar una primera fila, registre a un usuario y luego insértelo. La columna user_id por defecto es auth.uid():
import { aura } from '../lib/aurabase'
async function main() {
const email = 'you@example.com'
const password = 'a-strong-password'
await aura.auth.signUp({ email, password })
await aura.auth.signInWithPassword({ email, password })
const { data, error } = await aura.from('todos').insert({ title: 'First todo' }).select()
console.log(data, error)
}
main().catch((err) => {
console.error(err)
process.exit(1)
})
Ejecútelo con tsx, lo que resuelve la importación sin extensión y lee .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: permita el script de instalación de esbuild, luego ejecute:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
Con npm 11 o posterior, npx tsx falla con "Instalaste esbuild para otra plataforma" porque el script de instalación de esbuild está bloqueado de forma predeterminada. Use pnpm como se indicó anteriormente, u omita tsx y ejecute el script con la eliminación de tipos incorporada de Node (Node 22.6+) después de escribir las dos importaciones con su extensión ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Para los usuarios de su proyecto, signUp seguido de signInWithPassword funciona inmediatamente: la confirmación por correo electrónico está desactivada hasta que la active en Studio › Autenticación › Configuración (necesita un servidor de correo). Cualquiera puede registrarse con cualquier dirección, así que actívela antes de la producción.
La clave service_role no tiene ningún usuario que haya iniciado sesión, por lo que auth.uid() es NULL y una inserción que se basa en el valor predeterminado falla con NOT_NULL_VIOLATION. Desde un servidor, pase user_id explícitamente.
Conéctate en tiempo real#
Tres transportes negociados automáticamente: WebSocket, SSE, NATS. El cliente elige el mejor según la red, sin necesidad de configuración.
Habilite el tiempo real en la mesa una vez, con la CLI:
aura db table realtime todos on
o con la API HTTP, desde un servidor (valores de .env.local):
curl -X PUT "$NEXT_PUBLIC_AURABASE_URL/v1/db/schema/tables/todos/realtime" \
-H "apikey: $AURABASE_SERVICE_ROLE_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
Entonces suscríbete a los cambios. Un usuario que ha iniciado sesión recibe las filas que sus políticas RLS le permiten leer, incluido cuándo se abrió el canal antes de iniciar sesión (se vuelve a autenticar automáticamente); una suscripción rechazada informa CHANNEL_ERROR con el motivo.
'use client'
import { aura } from '@/lib/aurabase'
import { useEffect } from 'react'
export function LiveTodos() {
useEffect(() => {
const channel = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (change) =>
console.log(change.eventType, change.new),
)
.subscribe((status, err) => {
// En desarrollo, React StrictMode monta, desmonta y vuelve a montar el componente:
// el primer CERRADO proviene de esa limpieza y se espera.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Las suscripciones se multiplexan a través de una única conexión TCP. Abra tantos como necesite: cero costos de red adicionales.