JavaScript SDK로 데이터베이스 쿼리
aura.db의 일상적인 흐름, 안전하지 않은 호출을 거부하는 규칙, 행 수준 보안으로 테이블을 보호하는 방법.
행 읽기#
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)을 사용하세요.
삽입, 업데이트 및 삭제#
// 하나의 행 또는 행 배열을 삽입하고 다시 가져옵니다.
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을 실행하십시오.
한 행, 여러 행, 개수#
// 정확히 하나의 행: 행이 없거나 여러 개인 경우 오류
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'는 매우 큰 테이블과 근사치에서 더 빠릅니다.
테이블 보호#
Aurabase(db.sql(), 마이그레이션, Studio 또는 테이블 API)를 통해 생성된 테이블은 자동으로 ENABLE 및 FORCE ROW LEVEL SECURITY를 가져옵니다(DDL 배치에 DISABLE ROW LEVEL SECURITY를 명시적으로 포함하지 않는 한). 아직 정책이 없으면 anon 및 authenticated 호출자는 []을 참조합니다. 직접 Postgres 연결을 통해 생성된 테이블에는 명시적으로 enable row level security이 필요합니다. 필요한 정책을 추가하세요.
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()를 사용하여 어디서나 호출하세요.
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'],
})
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 실행#
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()를 사용합니다.