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.
Przeczytaj wiersze#
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ń#
// 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ą
400zAll object keys must match. Wypełnij brakujące klucze za pomocąnull. update()idelete()bez filtra są odrzucane przez klienta z kodem błęduUNFILTERED_MUTATIONprzed wysłaniem jakiegokolwiek żądania. Aby celowo zmienić każdy wiersz, uruchom SQL z serwera.
Liczy się jeden rząd, wiele rzędów#
// 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ół#
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:
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():
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'],
})
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, otrzymuje403 permission denied for function. Akceptowane są zarównoauthenticated, jak iaura_authenticated. Dotyczy to również funkcji utworzonych za pomocądb.sql()lub migracji projektów utworzonych po tej zmianie (domyślne uprawnienieEXECUTEPUBLICzostało cofnięte): dodajgrant 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()zwraca404 Could not find the function. - Funkcje poprzez SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONjest dozwolone w trybieSECURITY INVOKER(domyślnie);SECURITY DEFINERjest odrzucany w dniu/rawi musi zostać utworzony za pomocącreateFunction(POST /v1/db/{project_id}/functions) lub CLI/migracji z jawnymgrant_execute_to.
Uruchom SQL z serwera#
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()lubrange()poprosisz.meta.has_moretotrue, gdy pasuje więcej wierszy; poproś ocount: '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;offsetstaje się wolniejszy, im głębiej schodzisz. - Liczby przekraczające 2^53 JavaScriptu.
bigintpowyż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śćnumericjest 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 jak12345678901234567890.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żyjcount: 'exact', gdy liczba ma znaczenie.- Kolumna
vectorzwracana 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. Napiszwith (security_invoker = false)jawnie tylko wtedy, gdy naprawdę chcesz, aby widok ominął RLS. db.sql()ponawia próbę429po opóźnieniuRetry-After(odrzucone żądanie nigdy nie zostało zrealizowane). Wartość/rawjest ograniczona w zależności od projektu; w przypadku ładunków masowych użyj wpisanegoinsert()z tablicą.