Перейти к содержимому
Логотип Аурабаза
аурабаза

Запрос к базе данных с помощью JavaScript SDK

Ежедневные потоки aura.db, правила, запрещающие небезопасные вызовы, и способы защиты таблицы с помощью безопасности на уровне строк.

Практическое руководство9 мин читатьУровень среднийПересмотрено 12 окт. 2026 г.

Эта страница была переведена автоматически. Английская версия является авторитетной.

Чтение строк#

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') — это форма, используемая в этой документации (это сокращение для aura.db.from('todos'), тот же звонок). Каждый звонок возвращается { data, error } и никогда не бросает, см. параметры и ошибки клиента.

Цепочка фильтров: eq, neq, gt, gte, lt, lte, like, ilike, in, is и другие, перечисленные в справочнике по базе данных .. Для страницы строк используйте range(from, to).

Вставка, обновление и удаление#

write.tstypescript
// Вставьте одну строку или массив строк и верните их обратно.
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 с сервера.

Одна строка, много строк, считается#

count.tstypescript
// Ровно одна строка: ошибка, если их нет или несколько
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' работают быстрее на очень больших таблицах и приблизительны.

Защитить стол#

RLS включен по умолчанию через Aurabase, добавьте политики для предоставления доступа.

Таблицы, созданные с помощью Aurabase (db.sql(), миграции, Studio или API таблиц), автоматически получают ENABLE и FORCE ROW LEVEL SECURITY (если вы явно не включите DISABLE ROW LEVEL SECURITY в пакет DDL). Пока политики отсутствуют, вызывающие anon и authenticated видят []. Таблицы, созданные через прямое соединение Postgres, явно требуют enable row level security. Добавьте необходимые вам политики:

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

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
  • Для его вызова требуется 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 с сервера#

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() нужен ключ 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() с массивом.