Przejdź do treści
Logo Aurabase
aurabaza

Zapytaj swoją bazę danych za pomocą pakietu JavaScript SDK

Codzienne przepływy aura.db, reguły odrzucające niebezpieczne wywołania i sposoby ochrony tabeli za pomocą zabezpieczeń na poziomie wiersza.

Przewodnik krok po kroku9 min przeczytanePoziom mediatorZmieniono 12 paź 2026

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

Przeczytaj wiersze#

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') to formularz używany w całej dokumentacji (jest to skrót od aura.db.from('todos'), to samo wywołanie). Każde połączenie powraca { data, error } i nigdy nie rzuca, rozumiesz opcje klienta i błędy.

Łańcuch filtrów: eq, neq, gt, gte, lt, lte, like, ilike, in, isoraz inne wymienione w pkt odniesienie do bazy danych. W przypadku strony wierszy użyj range(from, to).

Wstaw, zaktualizuj i usuń#

write.tstypescript
// Wstaw jeden wiersz lub tablicę wierszy i odzyskaj je
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// Wstaw
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// Aktualizowanie i usuwanie wymaga filtra
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

Zapis nic nie zwraca (data to null), chyba że połączysz łańcuchowo .select(): wstawienie 10 000 wierszy nie powoduje przesłania 10 000 wierszy z powrotem. W przypadku .select() wiersze wracają, a PATCH lub POST, które nie pasują do żadnego wiersza, mówią dlaczego w meta.hint.

Przed błędami chronią Cię dwie zasady:

  • Wstawianie wsadowe wymaga tych samych kluczy w każdym wierszu. Wiersze z różnymi kluczami zwracają 400 z All object keys must match. Wypełnij brakujące klucze za pomocą null.
  • update() i delete() bez filtra są odrzucane przez klienta z kodem błędu UNFILTERED_MUTATION przed wysłaniem jakiegokolwiek żądania. Aby celowo zmienić każdy wiersz, uruchom SQL z serwera.

Liczy się jeden rząd, wiele rzędów#

count.tstypescript
// Dokładnie jeden wiersz: błąd, jeśli nie ma ich wcale lub jest ich kilka
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406, gdy filtr pasuje do zera lub kilku wierszy

// Zero lub jeden wiersz: dane mają wartość null, gdy nic nie pasuje
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// Wiersze i ich suma
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count to suma, niezależnie od zakresu

// Tylko suma, bez wierszy
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact' zlicza każdy pasujący wiersz. 'planned' i 'estimated' są szybsze w przypadku bardzo dużych tabel i są przybliżone.

Chroń stół#

RLS jest domyślnie włączone przez Aurabase, dodaj zasady, aby przyznać dostęp

Tabele utworzone za pomocą Aurabase (db.sql(), migracje, Studio lub interfejs API tabel) automatycznie otrzymują ENABLE i FORCE ROW LEVEL SECURITY (chyba że jawnie dołączysz DISABLE ROW LEVEL SECURITY do swojej partii DDL). Jeśli nie ma jeszcze żadnych zasad, dzwoniący anon i authenticated zobaczą []. Tabele utworzone poprzez bezpośrednie połączenie Postgres wymagają jawnego enable row level security. Dodaj potrzebne zasady:

SQLsql
create policy todos_own_read on todos
  for select to aura_authenticated
  using (auth.uid() = owner);

Kanoniczne role bazy danych to aura_anon, aura_authenticated i aura_service_role (aliasy grup anon, authenticated, service_role są również mapowane na nie w zarządzanych klastrach). auth.uid() to NULL dla klucza publicznego i identyfikatora użytkownika zalogowanego. Zobacz Zabezpieczenia na poziomie wiersza.

Klucz service_role omija RLS zgodnie z projektem: przechowuj go na swoim serwerze.

Funkcje SQL i RPC#

Utwórz funkcję na serwerze, a następnie wywołaj ją z dowolnego miejsca za pomocą 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
  • Do wywołania wymagane jest grant_execute_to. Bez tego nikt nie może wykonać tej funkcji. Rola, która nie jest wymieniona, otrzymuje 403 permission denied for function. Akceptowane są zarówno authenticated, jak i aura_authenticated. Dotyczy to również funkcji utworzonych za pomocą db.sql() lub migracji projektów utworzonych po tej zmianie (domyślne uprawnienie EXECUTE PUBLIC zostało cofnięte): dodaj grant execute on function hello(text) to aura_authenticated; samodzielnie.
  • Po kilku sekundach można wywołać nową funkcję. Dopóki interfejs API nie przeładuje swojego schematu, rpc() zwraca 404 Could not find the function.
  • Funkcje poprzez SQL (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION jest dozwolone w trybie SECURITY INVOKER (domyślnie); SECURITY DEFINER jest odrzucany w dniu /raw i musi zostać utworzony za pomocą createFunction (POST /v1/db/{project_id}/functions) lub CLI/migracji z jawnym grant_execute_to.

Uruchom SQL z serwera#

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() potrzebuje klucza service_role. Odrzuca DELETE bez WHERE i nie czyta katalogów systemowych, takich jak pg_class lub pg_roles. Aby wyświetlić listę tabel, użyj admin.db.schema().

Paginacja, tytuł wiersza i dokładne liczby

  • Odczyt zwraca maksymalnie 1000 wierszy — wartość domyślna i sztywny limit, niezależnie od tego, o co limit() lub range() poprosisz. meta.has_more to true, gdy pasuje więcej wierszy; poproś o count: 'exact', aby otrzymać również meta.total.
  • Przeglądaj dużą tabelę z paginacją zestawu kluczy, która kosztuje tyle samo na milionowej stronie: aura.from('events').select('id,label').limit(1000).after('id', lastId) (jest to .order('id').gt('id', lastId)). .cursor() to tylko MongoDB; offset staje się wolniejszy, im głębiej schodzisz.
  • Liczby przekraczające 2^53 JavaScriptu. bigint powyżej 9 007 199 254 740 991 traci swoje ostatnie cyfry, gdy jest analizowany jako numer JS: utwórz klienta za pomocą { parseBigIntAsString: true }, aby otrzymywać te wartości jako ciągi znaków. Wartość numeric jest zwracana jako liczba JSON, jeśli można ją dokładnie przedstawić, lub jako dokładny ciąg dziesiętny w przeciwnym razie (długie wartości, takie jak 12345678901234567890.123456789).
  • count: 'planned' i 'estimated' mają charakter wyłącznie szacunkowy. Pochodzą ze statystyk PostgreSQL, które są puste w właśnie załadowanej tabeli (tabela 60-wierszowa może zgłosić 430). Użyj count: 'exact', gdy liczba ma znaczenie.
  • Kolumna vector zwracana jest jako ciąg znaków, na przykład "[0.1,0.2,0.3]": przeanalizuj ją za pomocą JSON.parse, aby uzyskać number[].
  • Widok czyta z Twoimi uprawnieniami. Utworzone widoki (SQL, migracja) otrzymują security_invoker = true, więc zasady tabel bazowych mają zastosowanie do czytnika. Napisz with (security_invoker = false) jawnie tylko wtedy, gdy naprawdę chcesz, aby widok ominął RLS.
  • db.sql() ponawia próbę 429 po opóźnieniu Retry-After (odrzucone żądanie nigdy nie zostało zrealizowane). Wartość /raw jest ograniczona w zależności od projektu; w przypadku ładunków masowych użyj wpisanego insert() z tablicą.