빠른 시작
0에서 쿼리 가능한 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과 익명 키를 사용하여 클라이언트를 생성합니다. 서버에 서비스 역할 키를 유지하십시오.
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에는 자동 세션 쿠키 관리 및 잘림 방지 청킹 기능이 있는 Next.js(앱 라우터, 서버 작업, 미들웨어), Remix, Nuxt 및 SvelteKit에 대한 @aurabase/aurabase-js/ssr(createServerClient) 내보내기가 직접 포함되어 있습니다.
프로젝트 만들기#
Studio에서 프로젝트를 생성합니다. 활성화되면 Studio에는 바로 사용할 수 있는 .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)에서 이를 거부합니다. 서버 호출(라우트 핸들러, 서버 작업, 작업)용으로 예약하세요.
테이블 만들기#
Studio에서 데이터베이스를 열고 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에 "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)
}
This returns the rows of the table, including without a signed-in user, thanks to the example policy todos_public_read. Without it (once you dropped it, as you should before production) a visitor gets []: the other policies only open rows to aura_authenticated, so sign a user in first with aura.auth.signInWithPassword({ email, password }) (see Ready-made sign-in pages for Next.js). Regenerate the Database types with npx @aurabase/gen after each schema change.
첫 번째 행을 삽입하려면 사용자를 등록한 다음 삽입하세요. 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)
})
확장 없는 가져오기를 해결하고 .env.local를 읽는 tsx로 실행합니다.
pnpm add -D tsx
pnpm approve-builds # pnpm 10+: esbuild의 설치 스크립트를 허용한 후 다음을 실행합니다.
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
npm 11 이상에서는 esbuild의 설치 스크립트가 기본적으로 차단되어 있기 때문에 "다른 플랫폼에 대해 esbuild를 설치했습니다"라는 메시지와 함께 npx tsx가 실패합니다. 위와 같이 pnpm을 사용하거나 tsx를 건너뛰고 확장자('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts를 사용하여 두 가져오기를 작성한 후 Node의 내장 유형 제거(Node 22.6+)로 스크립트를 실행합니다.
프로젝트 사용자의 경우 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는 구성 요소를 마운트, 마운트 해제 및 다시 마운트합니다.
// 첫 번째 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 연결을 통해 다중화됩니다. 필요한 만큼 열 수 있으며 추가 네트워크 비용이 없습니다.