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

JavaScript SDK로 데이터베이스 쿼리

aura.db의 일상적인 흐름, 안전하지 않은 호출을 거부하는 규칙, 행 수준 보안으로 테이블을 보호하는 방법.

방법 가이드9분 읽기레벨 중급2026. 10. 12.에 개정됨

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

행 읽기#

read.tstypescript
const { data, error } = await aura
  .from('todos')
  .select('id, title, done')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .limit(20)

aura.from('todos')는 이 문서 전체에서 사용되는 형식입니다(동일한 호출인 aura.db.from('todos')의 단축형입니다). 모든 호출은 { data, error }를 반환하고 결코 발생하지 않습니다. 클라이언트 옵션 및 오류를 참조하세요.

필터 체인: eq, neq, gt, gte, lt, lte, like, ilike, in, is및 기타 항목에 나열된 항목 데이터베이스 참조. 행 페이지의 경우 range(from, to)을 사용하세요.

삽입, 업데이트 및 삭제#

write.tstypescript
// 하나의 행 또는 행 배열을 삽입하고 다시 가져옵니다.
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// Upsert
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// 업데이트 및 삭제에는 필터가 필요합니다.
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

.select()를 연결하지 않는 한 쓰기는 아무것도 반환하지 않습니다(data는 null입니다). 10,000개의 행을 삽입해도 10,000개의 행이 다시 전송되지 않습니다. .select()를 사용하면 행이 다시 나타나고 행과 일치하지 않는 PATCH 또는 POST는 meta.hint에서 이유를 알려줍니다.

실수로부터 여러분을 보호하는 두 가지 규칙은 다음과 같습니다.

  • 일괄 삽입에는 모든 행에 동일한 키가 필요합니다. 키가 다른 행은 All object keys must match와 함께 400를 반환합니다. 누락된 키를 null로 채웁니다.
  • 필터가 없는 update() 및 delete()는 요청이 전송되기 전에 오류 코드 UNFILTERED_MUTATION와 함께 클라이언트에 의해 거부됩니다. 의도적으로 모든 행을 변경하려면 서버에서 SQL을 실행하십시오.

한 행, 여러 행, 개수#

count.tstypescript
// 정확히 하나의 행: 행이 없거나 여러 개인 경우 오류
const one = await aura.from('todos').select('*').eq('id', id).single()
// → 필터가 0개 또는 여러 행과 일치하는 경우 error.status 406

// 0개 또는 1개 행: 일치하는 항목이 없으면 데이터가 null입니다.
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// 행 및 합계
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count는 범위에 관계없이 총계입니다.

// 합계만 있고 행은 없습니다.
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact'는 일치하는 모든 행을 계산합니다. 'planned' 및 'estimated'는 매우 큰 테이블과 근사치에서 더 빠릅니다.

테이블 보호#

RLS은(는) Aurabase을(를) 통해 기본적으로 활성화됩니다. 액세스 권한을 부여하는 정책을 추가하세요.

Aurabase(db.sql(), 마이그레이션, Studio 또는 테이블 API)를 통해 생성된 테이블은 자동으로 ENABLE 및 FORCE ROW LEVEL SECURITY를 가져옵니다(DDL 배치에 DISABLE ROW LEVEL SECURITY를 명시적으로 포함하지 않는 한). 아직 정책이 없으면 anon 및 authenticated 호출자는 []을 참조합니다. 직접 Postgres 연결을 통해 생성된 테이블에는 명시적으로 enable row level security이 필요합니다. 필요한 정책을 추가하세요.

SQLsql
create policy todos_own_read on todos
  for select to aura_authenticated
  using (auth.uid() = owner);

정식 데이터베이스 역할은 aura_anon, aura_authenticated 및 aura_service_role(그룹 별칭 anon, authenticated, service_role 도 관리형 클러스터에 매핑됨)입니다. auth.uid()는 공개 키의 경우 NULL이고 로그인한 사용자의 사용자 ID입니다. 행 수준 보안을 참조하세요.

service_role 키는 설계상 RLS를 우회합니다. 서버에 보관하세요.

SQL 함수 및 rpc#

서버에서 함수를 만든 다음 rpc()를 사용하여 어디서나 호출하세요.

server/setup.tstypescript
await admin.db.createFunction({
  name: 'add',
  args: [
    { name: 'a', data_type: 'int', mode: 'IN' },
    { name: 'b', data_type: 'int', mode: 'IN' },
  ],
  returns: 'int',
  language: 'sql',
  body: 'SELECT a + b',
  grant_execute_to: ['anon', 'authenticated'],
})
client.tstypescript
const { data } = await aura.rpc('add', { a: 1, b: 2 }) // → 3
  • 호출하려면 grant_execute_to이 필요합니다. 이것이 없으면 누구도 해당 기능을 실행할 수 없습니다. 나열되지 않은 역할은 403 permission denied for function를 얻습니다. authenticated 및 aura_authenticated가 모두 허용됩니다. 이는 db.sql()로 생성한 기능이나 이 변경 이후 생성된 프로젝트의 마이그레이션에도 적용됩니다(PUBLIC의 기본 EXECUTE 권한은 취소됨). grant execute on function hello(text) to aura_authenticated;를 직접 추가하세요.
  • 몇 초 후에 새 함수를 호출할 수 있습니다. API가 해당 스키마를 다시 로드할 때까지 rpc()는 404 Could not find the function를 반환합니다.
  • SQL을 통한 함수(db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION는 SECURITY INVOKER 모드에서 허용됩니다(기본값). SECURITY DEFINER은(는) /raw에서 거부되며 createFunction(POST /v1/db/{project_id}/functions) 또는 명시적 grant_execute_to을 사용한 CLI/마이그레이션을 통해 생성되어야 합니다.

서버에서 SQL 실행#

server/migrate.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

await admin.db.sql(`
  create table if not exists todos (
    id uuid primary key default gen_random_uuid(),
    title text not null,
    done boolean not null default false,
    owner uuid,
    created_at timestamptz not null default now()
  )
`)

db.sql()에는 service_role 키가 필요합니다. WHERE없이 DELETE을 거부하고 pg_class 또는 pg_roles와 같은 시스템 카탈로그를 읽지 않습니다. 테이블을 나열하려면 admin.db.schema()를 사용하세요.

페이지 매김, 행 캡 및 정확한 숫자

  • 읽기는 최대 1,000개의 행을 반환합니다. — 요청한 limit() 또는 range()에 관계없이 기본값과 하드 한도입니다. 더 많은 행이 일치하면 meta.has_more는 true입니다. count: 'exact'을 요청하면 meta.total도 얻을 수 있습니다.
  • 백만 번째 페이지인 aura.from('events').select('id,label').limit(1000).after('id', lastId) (즉 .order('id').gt('id', lastId))에 동일한 비용이 드는 키 세트 페이지 매김을 사용하여 큰 테이블을 페이지로 이동합니다. .cursor()는 MongoDB 전용입니다. offset는 깊이 들어갈수록 속도가 느려집니다.
  • JavaScript의 2^53을 넘는 숫자. 9,007,199,254,740,991 이상의 bigint는 JS 번호로 구문 분석할 때 마지막 숫자를 잃습니다. 해당 값을 문자열로 받으려면 { parseBigIntAsString: true }를 사용하여 클라이언트를 생성하세요. numeric는 정확하게 표현할 수 있으면 JSON 숫자로 반환되고, 그렇지 않으면 정확한 십진수 문자열로 반환됩니다(12345678901234567890.123456789와 같은 긴 값).
  • count: 'planned' 및 'estimated'는 추정치일 뿐입니다. 이는 방금 로드된 테이블에서 비어 있는 PostgreSQL의 통계에서 가져옵니다(60행 테이블은 430을 보고할 수 있음). 숫자가 중요한 경우 count: 'exact'를 사용하세요.
  • vector 열은 "[0.1,0.2,0.3]"와 같은 문자열로 반환됩니다. JSON.parse로 구문 분석하여 number[]를 얻습니다.
  • 사용자의 권한으로 뷰를 읽습니다. 생성한 뷰(SQL, 마이그레이션)는 security_invoker = true를 가져오므로 기본 테이블의 정책이 판독기에 적용됩니다. 뷰가 실제로 RLS를 우회하기를 원하는 경우에만 with (security_invoker = false)을 명시적으로 작성하세요.
  • db.sql()는 Retry-After 지연 후에 429을 재시도합니다(거부된 요청은 실행되지 않음). /raw는 프로젝트별로 제한됩니다. 대량 로드의 경우 배열과 함께 형식화된 insert()를 사용합니다.