Запрос к базе данных с помощью JavaScript SDK
Ежедневные потоки aura.db, правила, запрещающие небезопасные вызовы, и способы защиты таблицы с помощью безопасности на уровне строк.
Чтение строк#
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.eq('done', false)
.order('created_at', { ascending: false })
.limit(20)
aura.from('todos') — это форма, используемая в этой документации (это сокращение для aura.db.from('todos'), тот же звонок). Каждый звонок возвращается { data, error } и никогда не бросает, см. параметры и ошибки клиента.
Цепочка фильтров: eq, neq, gt, gte, lt, lte, like, ilike, in, is и другие, перечисленные в справочнике по базе данных .. Для страницы строк используйте range(from, to).
Вставка, обновление и удаление#
// Вставьте одну строку или массив строк и верните их обратно.
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()
// Upsert
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()
// Для обновления и удаления нужен фильтр
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)
Запись ничего не возвращает (data — это null), если вы не свяжете .select(): вставка 10 000 строк не отправит 10 000 строк обратно. При использовании .select() строки возвращаются, а PATCH или POST, не совпавшие ни с одной строкой, говорят, почему в meta.hint.
Два правила защитят вас от ошибок:
- Для пакетной вставки нужны одни и те же ключи в каждой строке. Строки с разными ключами возвращают
400сAll object keys must match. Заполните недостающие ключиnull. update()иdelete()без фильтра отклоняются клиентом с кодом ошибкиUNFILTERED_MUTATIONдо отправки любого запроса. Чтобы намеренно изменить каждую строку, запустите SQL с сервера.
Одна строка, много строк, считается#
// Ровно одна строка: ошибка, если их нет или несколько
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406, когда фильтр соответствует нулю или нескольким строкам
// Ноль или одна строка: данные равны нулю, если ничего не соответствует
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()
// Строки и их сумма
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count — это сумма, независимо от диапазона
// Только итог, без строк
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })
count: 'exact' подсчитывает каждую совпадающую строку. 'planned' и 'estimated' работают быстрее на очень больших таблицах и приблизительны.
Защитить стол#
Таблицы, созданные с помощью Aurabase (db.sql(), миграции, Studio или API таблиц), автоматически получают ENABLE и FORCE ROW LEVEL SECURITY (если вы явно не включите DISABLE ROW LEVEL SECURITY в пакет DDL). Пока политики отсутствуют, вызывающие anon и authenticated видят []. Таблицы, созданные через прямое соединение Postgres, явно требуют enable row level security. Добавьте необходимые вам политики:
create policy todos_own_read on todos
for select to aura_authenticated
using (auth.uid() = owner);
Каноническими ролями базы данных являются aura_anon, aura_authenticated и aura_service_role (псевдонимы групп anon, authenticated, service_role также сопоставляются с ними в управляемых кластерах). auth.uid() — это NULL для открытого ключа и идентификатора для вошедшего в систему пользователя. См. Безопасность на уровне строк.
Ключ service_role намеренно обходит RLS: сохраните его на своем сервере.
Функции SQL и RPC#
Создайте функцию на сервере, а затем вызовите ее из любого места с помощью 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
- Для его вызова требуется Grant_execute_to. Без него никто не сможет выполнить функцию. Роль, которой нет в списке, получает
403 permission denied for function. Обаauthenticatedиaura_authenticatedпринимаются. Это также справедливо для функций, которые вы создаете с помощьюdb.sql()или миграция проектов, созданных после этого изменения (по умолчаниюEXECUTEпривилегияPUBLICаннулировано): добавитьgrant execute on function hello(text) to aura_authenticated;сам. - Новая функция может быть вызвана через несколько секунд. Пока API не перезагрузит свою схему,
rpc()возвращает404 Could not find the function. - Функции через SQL (
db.sql()):CREATE FUNCTION/CREATE OR REPLACE FUNCTIONразрешено в режимеSECURITY INVOKER(по умолчанию);SECURITY DEFINERотклонен на/rawи должен быть создан с помощьюcreateFunction(POST /v1/db/{project_id}/functions) или CLI/миграции с явнымgrant_execute_to.
Запуск SQL с сервера#
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() нужен ключ service_role. Он отклоняет DELETE без WHERE и не читает системные каталоги, такие как pg_class или pg_roles. Чтобы перечислить ваши таблицы, используйте admin.db.schema().
Нумерация страниц, ограничение строк и точные цифры
- При чтении возвращается не более 1000 строк. — значение по умолчанию и жесткий потолок, независимо от того, какие
limit()илиrange()вы запросите.meta.has_moreравенtrue, если совпадает больше строк; попроситеcount: 'exact', чтобы также получитьmeta.total. - Пролистываем большую таблицу с нумерацией страниц, которая на миллионной странице стоит столько же:
aura.from('events').select('id,label').limit(1000).after('id', lastId)(это.order('id').gt('id', lastId))..cursor()предназначен только для MongoDB;offsetстановится медленнее, чем глубже вы погружаетесь. - Числа за пределами JavaScript 2^53.
bigintвыше 9 007 199 254 740 991 теряет свои последние цифры при анализе как номера JS: создайте клиент с{ parseBigIntAsString: true }для получения этих значений в виде строк.numericвозвращается как число JSON, если оно точно представимо, и как точная десятичная строка в противном случае (длинные значения, такие как12345678901234567890.123456789). count: 'planned'и'estimated'являются приблизительными. Они берутся из статистики PostgreSQL, которая пуста в только что загруженной таблице (таблица из 60 строк может сообщить 430). Используйтеcount: 'exact', когда число имеет значение.- Столбец
vectorвозвращается в виде строки, например"[0.1,0.2,0.3]": проанализируйте ее с помощьюJSON.parse, чтобы получитьnumber[]. - Представление читается с вашими привилегиями. Создаваемые вами представления (SQL, миграция) получают
security_invoker = true, поэтому политики базовых таблиц применяются к считывателю. Пишитеwith (security_invoker = false)явно, только если вы действительно хотите, чтобы представление обходило RLS. db.sql()повторяет429после задержкиRetry-After(отклоненный запрос никогда не выполнялся)./rawограничен для каждого проекта; для массовой загрузки используйте типизированныйinsert()с массивом.