Szybki start
Od zera do API z możliwością zapytań: dedykowana baza danych Postgres, zabezpieczenia na poziomie wiersza, wliczone w cenę generowanie typu TypeScript w czasie rzeczywistym i TypeScript — nie jest wymagana karta kredytowa.
Prompt dla Twojego agenta kodującego
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.Szybki start#
Zainstaluj pakiet SDK, utwórz klienta i przeczytaj pierwsze wiersze.
1. Zainstaluj pakiet SDK#
Dodaj SDK do swojego projektu. Zakładka Rust instaluje skrzynkę aurabase; karta cURL sprawdza, czy adres URL projektu odpowiada.
pnpm add @aurabase/aurabase-js
2. Utwórz klienta#
Utwórz klienta z adresem URL projektu i kluczem anon, oba w Studio > Ustawienia > Połączenie. Zachowaj klucz roli usługi na serwerze.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Zapytaj bazę danych#
Przeczytaj do 10 wierszy z todos. Tabela jest tworzona w sekcji „Utwórz tabelę” poniżej; dopóki nie istnieje, ustawiany jest error.
// `todos` jest tworzone w sekcji „Utwórz tabelę” poniżej
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Warunki wstępne#
Zakładamy, że Node.js ≥ 20 jest zainstalowany i terminal POSIX jest w zasięgu. Nie jest wymagana żadna lokalna baza danych: Aurabase udostępnia dedykowaną bazę danych Postgres dla każdego projektu.
Przyjeżdżasz z Supabase lub Firebase? Większość koncepcji można transponować. Zobacz przewodnik po migracji.
Instalowanie pakietu SDK#
Oficjalny zestaw SDK udostępnia klienta typowego dla CRUD, uwierzytelniania, czasu rzeczywistego i przechowywania. Działa to w ten sam sposób w Next.js, React, Node, Bun lub Deno.
# Zalecony
pnpm add @aurabase/aurabase-js
Nazwa pakietu zawiera zakres @aurabase/. Pakiet aurabase-js bez zakresu nie jest obsługiwany przez Aurabase: nie instaluj go.
SDK bezpośrednio obejmuje eksport @aurabase/aurabase-js/ssr (createServerClient) dla Next.js (router aplikacji, akcje serwera, oprogramowanie pośrednie), Remix, Nuxt i SvelteKit z automatycznym zarządzaniem plikami cookie sesji i fragmentacją zapobiegającą obcinaniu.
Utwórz projekt#
Utwórz projekt w Studio. Kiedy stanie się aktywny, Studio wyświetli Skopiuj teraz swoje klucze panel z gotowym do użycia .env.local (skopiuj go lub pobierz): klucz service_role pojawia się tam raz, później zachowywany jest tylko jego skrót. Ustawienia › Połączenie później pokazuje adres URL projektu i publiczny klucz anonimowy; jeśli zgubiłeś klucz service_role, zregeneruj go tam (poprzedni zostanie unieważniony). NEXT_PUBLIC_AURABASE_URL i NEXT_PUBLIC_AURABASE_ANON_KEY można opublikować po stronie klienta; AURABASE_SERVICE_ROLE_KEY pozostaje wyłącznie po stronie serwera.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Schemat | Dostęp | Zawiera |
|---|---|---|
project_{uuid} | Ty | Twoje tabele zastosowań |
project_{uuid}_auth | System | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | System | buckets, objects, rls_policies |
project_{uuid}_platform | System | functions, jobs, cron_jobs, api_keys |
Cała ścieżka działa również z CLI (patrz CLI dla instalacji): aura projects create czeka, aż projekt będzie gotowy i drukuje raz adres URL i klucze.
aura login
aura projects create todos-app --json > project.json # czeka, aż projekt będzie aktywny
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> # zobaczyć, co widzi ten użytkownik
Nigdy nie dołączaj AURABASE_SERVICE_ROLE_KEY do pakietu klienta. Omija wszystkie zasady RLS, a API odrzuca je z przeglądarki (401 SECRET_KEY_IN_BROWSER). Zarezerwuj go na wywołania serwera (obsługa tras, akcje serwera, zadania).
Utwórz tabelę#
Otwórz Baza danych w Studio, kliknij Edytor SQL (link na dole panelu tabel) i uruchom ten skrypt. W każdej tabeli włączone są zabezpieczenia na poziomie wierszy: pierwsze dwie zasady pozwalają każdemu zalogowanemu użytkownikowi czytać i tworzyć własne wiersze, trzecia to przykład, który pozwala odwiedzającym czytać tabelę, dzięki czemu można zobaczyć pierwsze wiersze bez konieczności logowania się. Zasady są ukierunkowane na rolę aura_authenticated (aura_anon dla odwiedzających).
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);
-- Tylko przykład: każdy odwiedzający może przeczytać każde zadanie. Upuść to przed produkcją:
-- porzuć politykę „todos_public_read” na todos;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Następnie wygeneruj typy TypeScript swojego schematu (polecenie brzmi .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Pierwsze połączenie#
Utwórz klienta Aurabase wielokrotnego użytku, odczytując klucze ze zmiennych środowiskowych, a następnie wykonaj zapytanie do pierwszej tabeli. Poniższe ścieżki odnoszą się do katalogu głównego Twojej aplikacji: jeśli Twój projekt korzysta z katalogu src/, umieść w nim lib/, components/ i app/, aby alias importu @/ został rozwiązany.
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!,
)
Następnie w procedurze obsługi tras lub komponencie serwera:
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)
}
Zwraca to wiersze tabeli, także bez zalogowanego użytkownika, dzięki przykładowej polityce todos_public_read. Bez tego (gdy go upuścisz, tak jak powinieneś przed produkcją) odwiedzający otrzyma []: inne zasady otwierają tylko wiersze do aura_authenticated, więc najpierw zaloguj użytkownika za pomocą aura.auth.signInWithPassword({ email, password }) (zobacz Gotowe strony logowania dla Next.js). Wygeneruj ponownie typy Database za pomocą npx @aurabase/gen po każdej zmianie schematu.
Aby wstawić pierwszy wiersz, zarejestruj użytkownika i zaloguj się, a następnie wstaw. Kolumna user_id ma domyślnie wartość 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)
})
Uruchom go za pomocą tsx, który rozwiąże import bez rozszerzenia i odczyta .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: zezwól na skrypt instalacyjny esbuild, a następnie uruchom:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
W wersji npm 11 lub nowszej npx tsx kończy się niepowodzeniem z komunikatem „Zainstalowałeś esbuild na inną platformę”, ponieważ skrypt instalacyjny esbuild jest domyślnie zablokowany. Użyj pnpm jak powyżej lub pomiń tsx i uruchom skrypt z wbudowanym usuwaniem typów węzła (Node 22.6+) po zapisaniu dwóch importów z ich rozszerzeniem ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Dla użytkowników Twojego projektu signUp, po którym następuje signInWithPassword, działa natychmiast: potwierdzenie e-mailem jest wyłączone, dopóki nie włączysz go w Studio > Uwierzytelnianie > Konfiguracja (wymaga serwera pocztowego). Każdy może wtedy zarejestrować się przy użyciu dowolnego adresu, więc włącz go przed rozpoczęciem produkcji.
Klucz service_role nie ma zalogowanego użytkownika, więc auth.uid() to NULL, a wstawienie oparte na wartości domyślnej kończy się niepowodzeniem z NOT_NULL_VIOLATION. Z serwera przekaż jawnie user_id.
Połącz się w czasie rzeczywistym#
Trzy automatycznie negocjowane transporty: WebSocket, SSE, NATS. Klient wybiera najlepszy w oparciu o sieć — nie jest wymagana żadna konfiguracja.
Włącz raz czas rzeczywisty na stole za pomocą interfejsu CLI:
aura db table realtime todos on
lub za pomocą API HTTP z serwera (wartości z .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}'
Następnie zasubskrybuj zmiany. Zalogowany użytkownik otrzymuje wiersze, które pozwalają mu na odczytanie zasady RLS, łącznie z informacją o otwarciu kanału przed zalogowaniem (jest on automatycznie ponownie uwierzytelniany); odmowa subskrypcji zgłasza CHANNEL_ERROR z powodem.
'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) => {
// W fazie rozwoju React StrictMode montuje, odmontowuje i ponownie montuje komponent:
// pierwsze ZAMKNIĘTE pochodzi z tego czyszczenia i jest oczekiwane.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Subskrypcje są multipleksowane w ramach jednego połączenia TCP. Otwórz tyle, ile potrzebujesz — zero dodatkowych kosztów sieciowych.