文档›指南›Query your database (SDK) 使用 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()
// 更新插入
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)
有两条规则可以保护您免受错误的影响：
- 批量插入需要每行具有相同的键。 具有不同键的行返回
400 和 All object keys must match。用 null填充缺失的键。
- 在发送任何请求之前，客户端会拒绝不带过滤器的
update() 和 delete() ，并返回错误代码 unfiltered_mutation。要有意更改每一行，请从服务器运行 SQL。
count.tstypescript
// 恰好一行：如果没有或有几行，则会出错
const one = await aura.from('todos').select('*').eq('id', id).single()
// → 当过滤器匹配零行或几行时，error.status 406
// 零行或一行：当没有匹配项时数据为空
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' 在非常大的表和近似值上更快。
在 SQL 中创建的表将处于打开状态，直到您启用 RLS
在新表上，行级安全性是 关闭 。有了公钥，任何人都可以读写它。启用它，然后添加您需要的策略：
SQLsql
alter table todos 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。 auth.uid() 是 NULL 的公钥和登录用户的用户 ID。请参阅 行级安全性。
service_role 密钥在设计上会绕过 RLS：将其保留在您的服务器上。
从服务器创建一个函数，然后使用 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 均被接受。
- 几秒钟后即可调用新函数。 在 API 重新加载其架构之前，
rpc() 返回 404 Could not find the function。
- 使用原始 SQL (
CREATE FUNCTION) 创建函数被拒绝：使用 createFunction。
server/migrate.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'
const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_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()。
