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

Быстрый старт

От нуля до запрашиваемого API: выделенная база данных Postgres, безопасность на уровне строк, генерация типов в реальном времени и TypeScript — кредитная карта не требуется.

Обучающее руководство5 мин читатьУровень новичокПересмотрено 21 окт. 2026 г.

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

Промпт для вашего агента-программиста

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-адрес вашего проекта.

bash
pnpm add @aurabase/aurabase-js

2. Создайте клиента#

Создайте клиент, используя URL-адрес вашего проекта и ключ анонима, в Studio › Settings › Connection. Сохраните ключ роли службы на сервере.

typescript
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.

typescript
// `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.

terminalbash
# Рекомендуется
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 остается строго на стороне сервера.

.env.localbash
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 и ключи.

terminalbash
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 для посетителей).

todos.sqlsql
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):

terminalbash
npx @aurabase/gen --out lib/aurabase.types.ts

Первый звонок#

Создайте многоразовый клиент Aurabase, прочитав ключи из переменных среды, а затем запросите свою первую таблицу. Указанные ниже пути указаны относительно корня вашего приложения: если ваш проект использует каталог src/, поместите в него lib/, components/ и app/, чтобы разрешился псевдоним импорта @/.

lib/aurabase.tstypescript
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!,
)

Затем в обработчике маршрута или серверном компоненте:

app/api/todos/route.tstypescript
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():

scripts/first-row.tstypescript
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:

terminalbash
pnpm add -D tsx
pnpm approve-builds   # pnpm 10+: разрешите сценарий установки esbuild, затем запустите:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
npm 11 блокирует сценарий установки esbuild

В 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:

terminalbash
aura db table realtime todos on

или с помощью HTTP API с сервера (значения из .env.local):

terminalbash
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 с указанием причины.

components/LiveTodos.tsxtypescript
'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-соединению. Открывайте столько, сколько вам нужно — никаких дополнительных затрат на сеть.

Чтобы пойти дальше#