クイックスタート
ゼロからクエリ可能な 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. クライアントを作成する#
Studio › 設定 › 接続 で、プロジェクト URL と anon キーを使用してクライアントを作成します。サービスロールキーをサーバー上に保持します。
import { createClient } from '@aurabase/aurabase-js'
const aura = createClient(
process.env.NEXT_PUBLIC_AURABASE_URL!,
process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)
3. データベースにクエリを実行する#
todosから最大 10 行を読み取ります。テーブルは、以下の「テーブルの作成」セクションで作成されます。存在するまで、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 には、自動セッション Cookie 管理と切り捨て防止チャンキングを備えた Next.js (App Router、Server Actions、Middleware)、Remix、Nuxt、および SvelteKit 用の @aurabase/aurabase-js/ssr (createServerClient) エクスポートが直接含まれています。
プロジェクトを作成する#
Studioからプロジェクトを作成します。アクティブになると、Studio にはすぐに使用できる .env.local (コピーまたはダウンロード) を含む [今すぐキーをコピー] パネルが表示されます。 service_role キーはそこに一度表示され、その後はそのハッシュのみが保持されます。設定 › 後で接続すると、プロジェクト URL と公開 anon キーが表示されます。 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 とキーを 1 回出力します。
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)。サーバー呼び出し (ルート ハンドラー、サーバー アクション、ジョブ) 用に予約します。
テーブルを作成する#
Studio で データベース を開き、SQL エディター (テーブル パネルの下部にあるリンク) をクリックして、このスクリプトを実行します。すべてのテーブルで行レベルのセキュリティが有効になっています。最初の 2 つのポリシーでは、サインインしている各ユーザーが独自の行の読み取りと作成を許可します。3 番目のポリシーは、訪問者がテーブルを読み取れるようにする の例 で、サインインせずに最初の行を表示できます。ポリシーは 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);
-- 例のみ: すべての訪問者はすべての Todo を読むことができます。実稼働前にドロップします。
-- todos にポリシー「todos_public_read」を削除します。
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 用の既製のサインイン ページを参照)。スキーマを変更するたびに、npx @aurabase/gen を使用して Database 型を再生成します。
最初の行を挿入するには、ユーザーをサインアップしてログインしてから挿入します。 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 以降では、esbuild のインストール スクリプトがデフォルトでブロックされているため、npx tsx は「別のプラットフォーム用に esbuild をインストールしました」というエラーで失敗します。上記のように pnpm を使用するか、 tsx をスキップして、拡張子 ('../lib/aurabase.ts'、 './aurabase.types.ts') : node --env-file=.env.local --experimental-strip-types scripts/first-row.tsを使用して 2 つのインポートを記述した後、Node の組み込みタイプ ストリッピング (Node 22.6 以降) を使用してスクリプトを実行します。
プロジェクトのユーザーの場合、signUp に続いて signInWithPassword を実行すると、すぐに機能します。Studio › Authentication › Configuration (メール サーバーが必要です) で有効にするまで、電子メール確認は オフ になります。誰でも任意のアドレスでサインアップできるため、運用前に有効にしてください。
service_role キーにはサインインしているユーザーがいないため、 auth.uid() は NULL となり、デフォルトに依存する挿入は NOT_NULL_VIOLATIONで失敗します。サーバーから、明示的に user_id を渡します。
リアルタイム接続#
3 つの自動ネゴシエーショントランスポート: 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 はコンポーネントをマウント、アンマウント、再マウントします。
// 最初の CLOSED はクリーンアップからのものであり、予期されています。
if (status === 'SUBSCRIBED') console.log('realtime connected')
if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
})
return () => {
void channel.unsubscribe()
}
}, [])
return null
}
サブスクリプションは単一の TCP 接続上で多重化されます。必要なだけ開くことができ、追加のネットワークコストはかかりません。