Przejdź do treści
Logo Aurabase
aurabaza

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.

Samouczek5 min przeczytanePoziom początkującyZmieniono 21 paź 2026

Ta strona została przetłumaczona automatycznie. Wersja angielska jest miarodajna.

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.

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

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

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

Informacje

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.

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

Wskazówka

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.

.env.localbash
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
SchematDostępZawiera
project_{uuid}TyTwoje tabele zastosowań
project_{uuid}_authSystemusers, sessions, oauth_accounts, mfa
project_{uuid}_storageSystembuckets, objects, rls_policies
project_{uuid}_platformSystemfunctions, jobs, cron_jobs, api_keys
Wolisz terminal?

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.

terminalbash
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
Klucz roli usługi

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

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

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

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!,
)

Następnie w procedurze obsługi tras lub komponencie serwera:

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)
}
Wskazówka

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

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

Uruchom go za pomocą tsx, który rozwiąże import bez rozszerzenia i odczyta .env.local:

terminalbash
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
npm 11 blokuje skrypt instalacyjny esbuild

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.

Potwierdzenie e-mailem jest domyślnie wyłączone

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.

Uwaga

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:

terminalbash
aura db table realtime todos on

lub za pomocą API HTTP z serwera (wartości z .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}'

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.

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) => {
        // 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
}
Wskazówka

Subskrypcje są multipleksowane w ramach jednego połączenia TCP. Otwórz tyle, ile potrzebujesz — zero dodatkowych kosztów sieciowych.

Aby pójść dalej#