Saltar al contenido
Logotipo de Aurabase
aurabase

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.

Tutorial5 min leerNivel principianteRevisado el 21 oct 2026

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

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.

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

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

typescript
// `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.

Información

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

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

Consejo

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.

.env.localbash
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
esquemaAccesoContiene
project_{uuid}tuTus tablas de aplicaciones
project_{uuid}_authSistemausers, sessions, oauth_accounts, mfa
project_{uuid}_storageSistemabuckets, objects, rls_policies
project_{uuid}_platformSistemafunctions, jobs, cron_jobs, api_keys
¿Prefieres la terminal?

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.

terminalbash
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
Clave de rol de servicio

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

todos.sqlsql
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):

terminalbash
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 @/.

lib/aurabase.tstypescript
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:

app/api/todos/route.tstypescript
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)
}
Consejo

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

scripts/first-row.tstypescript
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:

terminalbash
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
npm 11 bloquea el script de instalación de esbuild

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.

La confirmación por correo electrónico está desactivada de forma predeterminada

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.

Atenció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:

terminalbash
aura db table realtime todos on

o con la API HTTP, desde un servidor (valores de .env.local):

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

components/LiveTodos.tsxtypescript
'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
}
Consejo

Las suscripciones se multiplexan a través de una única conexión TCP. Abra tantos como necesite: cero costos de red adicionales.

para ir más lejos#