コンテンツへスキップ
オーラベースのロゴ
オーラベース

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
// 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 行、複数行、カウント#

count.tstypescript
// 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' は、非常に大きなテーブルでは高速であり、おおよその速度です。

テーブルを保護する#

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 になります。 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() を使用します。