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)を使用します。
挿入、更新、削除#
// 1 行または行の配列を挿入し、それらを取得します。
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()
// アップサート
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でその理由を示します。
間違いを防ぐ 2 つのルール:
- バッチ挿入では、すべての行に同じキーが必要です。 異なるキーを持つ行は、
400とAll object keys must matchを返します。不足しているキーをnullで埋めます。 - フィルターのない
update()およびdelete()は、リクエストが送信される前に、クライアント によってエラー コードUNFILTERED_MUTATIONで拒否されます。すべての行を意図的に変更するには、サーバーから SQL を実行します。
1 行、複数行、カウント#
// 1 行のみ: 行がないか、複数行ある場合はエラー
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 フィルタが 0 行または複数の行に一致した場合
// 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になります。meta.totalも取得するには、count: 'exact'を要求します。 - キーセットのページネーションを使用して大きなテーブルをページングします。100 万ページ目でも同じコストがかかります:
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 数値として返され、それ以外の場合は正確な 10 進数文字列 (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()を使用します。