Быстрый старт
От нуля до запрашиваемого API: выделенная база данных Postgres, безопасность на уровне строк, генерация типов в реальном времени и TypeScript — кредитная карта не требуется.
Промпт для вашего агента-программиста
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.Быстрый старт#
Установите SDK, создайте клиент и прочитайте свои первые строки.
1. Установите SDK#
Добавьте SDK в свой проект. Вкладка Rust устанавливает крейт aurabase; вкладка cURL проверяет, отвечает ли URL-адрес вашего проекта.
pnpm add @aurabase/aurabase-js
2. Создайте клиента#
Создайте клиент, используя URL-адрес вашего проекта и ключ анонима, в Studio › Settings › Connection. Сохраните ключ роли службы на сервере.
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. Запросить базу данных#
Прочитайте до 10 строк из todos. Таблица создается в разделе «Создать таблицу» ниже; пока он не существует, устанавливается error.
// `todos` создается в разделе «Создание таблицы» ниже.
const { data, error } = await aura
.from('todos')
.select('id, title, done')
.limit(10)
console.log(data, error)
Предварительные условия#
Мы предполагаем, что Node.js ≥ 20 установлен и терминал POSIX находится в пределах досягаемости. Локальная база данных не требуется: Aurabase выделяет специальную базу данных Postgres для каждого проекта.
Вы из Supabase или Firebase? Большинство понятий переносимы. См. руководство по миграции.
Установка SDK#
Официальный SDK предоставляет типизированный клиент для CRUD, аутентификации, реального времени и хранилища. Это работает одинаково в Next.js, React, Node, Bun или Deno.
# Рекомендуется
pnpm add @aurabase/aurabase-js
Имя пакета включает область действия @aurabase/. Пакет aurabase-js без области действия не поддерживается Aurabase: не устанавливайте его.
SDK напрямую включает экспорт @aurabase/aurabase-js/ssr (createServerClient) для Next.js (маршрутизатор приложений, действия сервера, промежуточное ПО), Remix, Nuxt и SvelteKit с автоматическим управлением файлами cookie сеанса и фрагментацией для предотвращения усечения.
Создать проект#
Создать проект из Студии. Когда он становится активным, Студия отображает панель Copy yourkeys now с готовым к использованию .env.local (скопируйте или загрузите его): ключ service_role появляется там один раз, после этого сохраняется только его хэш. Настройки › Соединение позже покажет URL-адрес проекта и открытый ключ анонима; если вы потеряли ключ service_role, создайте его заново (предыдущий аннулируется). NEXT_PUBLIC_AURABASE_URL и NEXT_PUBLIC_AURABASE_ANON_KEY можно публиковать на стороне клиента; AURABASE_SERVICE_ROLE_KEY остается строго на стороне сервера.
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
| Схема | Доступ | Содержит |
|---|---|---|
project_{uuid} | Ты | Таблицы ваших приложений |
project_{uuid}_auth | Система | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | Система | buckets, objects, rls_policies |
project_{uuid}_platform | Система | functions, jobs, cron_jobs, api_keys |
Весь путь также работает из CLI (см. CLI для установки): aura projects create ждет, пока проект будет готов, и один раз печатает URL и ключи.
aura login
aura projects create todos-app --json > project.json # ждет, пока проект станет активным
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> # посмотреть, что видит этот пользователь
Никогда не включайте AURABASE_SERVICE_ROLE_KEY в клиентский пакет. Обходит все политики RLS, и API отклоняет его от браузера (401 SECRET_KEY_IN_BROWSER). Зарезервируйте его для вызовов сервера (обработчики маршрутов, действия сервера, задания).
Создать таблицу#
Откройте Базу данных в Студии, нажмите Редактор SQL (ссылка внизу панели таблиц) и запустите этот скрипт. Безопасность на уровне строк включена для каждой таблицы: первые две политики позволяют каждому вошедшему пользователю читать и создавать свои собственные строки, третья представляет собой пример , который позволяет посетителям читать таблицу, чтобы вы могли видеть свои первые строки без входа в систему. Политики нацелены на роль aura_authenticated (aura_anon для посетителей).
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);
-- Только пример: любой посетитель может прочитать все задачи. Отбросьте его перед производством:
-- удалить политику «todos_public_read» в todos;
create policy "todos_public_read" on todos for select to aura_anon using (true);
Затем сгенерируйте типы TypeScript вашей схемы (команда читается как .env.local):
npx @aurabase/gen --out lib/aurabase.types.ts
Первый звонок#
Создайте многоразовый клиент Aurabase, прочитав ключи из переменных среды, а затем запросите свою первую таблицу. Указанные ниже пути указаны относительно корня вашего приложения: если ваш проект использует каталог src/, поместите в него lib/, components/ и app/, чтобы разрешился псевдоним импорта @/.
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!,
)
Затем в обработчике маршрута или серверном компоненте:
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)
}
Это возвращает строки таблицы, в том числе без вошедшего в систему пользователя, благодаря примеру политики todos_public_read. Без него (как только вы его удалили, как и должно быть перед производством) посетитель получает []: другие политики открывают только строки для aura_authenticated, поэтому сначала войдите в систему с помощью aura.auth.signInWithPassword({ email, password }) (см. Готовые страницы входа для Next.js). Повторно сгенерируйте типы Database с помощью npx @aurabase/gen после каждого изменения схемы.
Чтобы вставить первую строку, зарегистрируйте пользователя и затем вставьте его. Столбец user_id по умолчанию имеет значение auth.uid():
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)
})
Запустите его с помощью tsx, который разрешает импорт без расширений и читает .env.local:
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: разрешите сценарий установки esbuild, затем запустите:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
В npm 11 или более поздней версии npx tsx завершается с ошибкой «Вы установили esbuild для другой платформы», поскольку сценарий установки esbuild заблокирован по умолчанию. Используйте pnpm, как указано выше, или пропустите tsx и запустите сценарий со встроенным разделением типов Node (Node 22.6+) после записи двух импортов с их расширением ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.
Для пользователей вашего проекта signUp, за которым следует signInWithPassword, работает сразу: подтверждение по электронной почте отключено, пока вы не включите его в Studio › Аутентификация › Конфигурация (для этого нужен почтовый сервер). Тогда любой сможет зарегистрироваться с любым адресом, поэтому включите его перед началом работы.
Ключ service_role не имеет вошедшего в систему пользователя, поэтому auth.uid() — это NULL, а вставка, основанная на значении по умолчанию, завершается с ошибкой NOT_NULL_VIOLATION. С сервера передайте user_id явно.
Подключайтесь в режиме реального времени#
Три транспорта с автоматическим согласованием: WebSocket, SSE, NATS. Клиент выбирает лучший вариант в зависимости от сети — настройка не требуется.
Включите режим реального времени для таблицы один раз с помощью CLI:
aura db table realtime todos on
или с помощью HTTP API с сервера (значения из .env.local):
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}'
Тогда подписывайтесь на изменения. Вошедший в систему пользователь получает строки, которые его политики RLS позволяют ему читать, в том числе, когда канал был открыт до входа в систему (он автоматически проходит повторную аутентификацию); об отказе в подписке сообщается CHANNEL_ERROR с указанием причины.
'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) => {
// В разработке React StrictMode монтирует, размонтирует и повторно монтирует компонент:
// первое ЗАКРЫТО происходит в результате этой очистки и ожидается.
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
Подписки мультиплексируются по одному TCP-соединению. Открывайте столько, сколько вам нужно — никаких дополнительных затрат на сеть.