본문으로 건너뛰기
아우라베이스 로고
아우라베이스

빠른 시작

0에서 쿼리 가능한 API까지: 전용 Postgres 데이터베이스, 행 수준 보안, 실시간 및 TypeScript 유형 생성이 포함되어 있으며 신용 카드가 필요하지 않습니다.

튜토리얼5분 읽기레벨 초보자2026. 10. 21.에 개정됨

이 페이지는 자동으로 번역되었습니다. 영어 버전은 권위가 있습니다.

코딩 에이전트용 프롬프트

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. 클라이언트 생성#

Studio › 설정 › 연결에서 프로젝트 URL과 익명 키를 사용하여 클라이언트를 생성합니다. 서버에 서비스 역할 키를 유지하십시오.

typescript
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가 설정됩니다.

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에는 자동 세션 쿠키 관리 및 잘림 방지 청킹 기능이 있는 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는 엄격하게 서버 측에 유지됩니다.

.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)에서 이를 거부합니다. 서버 호출(라우트 핸들러, 서버 작업, 작업)용으로 예약하세요.

테이블 만들기#

Studio에서 데이터베이스를 열고 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에 "todos_public_read" 정책을 삭제합니다.
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)
}
팁

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()입니다.

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)
})

확장 없는 가져오기를 해결하고 .env.local를 읽는 tsx로 실행합니다.

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 이상에서는 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를 사용하여 테이블에서 실시간을 한 번 활성화합니다.

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는 구성 요소를 마운트, 마운트 해제 및 다시 마운트합니다.
        // 첫 번째 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 연결을 통해 다중화됩니다. 필요한 만큼 열 수 있으며 추가 네트워크 비용이 없습니다.

더 나아가려면#