rxdb-adapter-supabase

RxDB Supabase 适配器 — 基于 PostgreSQL 的远程同步实现。

作为 RxDB 的 remote 适配器使用：本地用 SQLite（wa-sqlite / PGlite）离线读写，远程用 Supabase 做多端同步、实时推送与云端备份。

特性

✅ 完整 CRUD — 通过 SupabaseRepository 封装 PostgREST
✅ 批量操作 — saveMany / removeMany（非事务）、mutations（RPC 事务）
✅ 事务支持 — 基于 PostgreSQL RPC rxdb_mutations 的原子写入
✅ 实时订阅 — 监听 rxdb_change 表的 INSERT，自动派发远程事件（带指数退避重连）
✅ 双向同步 — pullChanges / mergeChanges / pullChangesBatch 配合 RxDB VersionManager
✅ 树形结构 — SupabaseTreeRepository（递归 CTE，缺函数时降级到内存遍历）
✅ RLS 自检 — 连接时校验目标表是否开启行级安全（可配 warn / throw）
✅ 瞬时错误重试 — 写入/事务路径对网关超时等瞬时错误自动重试

何时使用

需要多端数据同步（Web / 移动端 / 桌面端）
需要实时协作
需要云端备份与恢复
需要 PostgreSQL 高级特性（JSONB、全文搜索、RLS）
已有 Supabase 基础设施

与其他适配器对比

特性	Supabase	PGlite	wa-sqlite
部署模式	云端/自托管	本地	本地
多端同步	✅	❌	❌
实时订阅	✅	❌	❌
离线优先	✅（混合）	✅	✅
数据库	PostgreSQL	PostgreSQL	SQLite
认证集成	✅	❌	❌

安装

pnpm add @aiao/rxdb @aiao/rxdb-adapter-supabase @supabase/supabase-js
# 本地适配器（二选一或按需）
pnpm add @aiao/rxdb-adapter-wa-sqlite

peerDependencies：@aiao/rxdb、@supabase/supabase-js ^2.88、rxjs ^7.8。

导出

RxDBAdapterSupabase — 远程适配器主类
SupabaseRepository — 表级 CRUD / 查询 Repository
SupabaseTreeRepository — 树形（邻接表）Repository
SupabaseAdapterOptions — 配置类型
SupabaseSyncError / SupabaseConfigError / SupabaseNetworkError / SupabaseDataError — 错误类型
ADAPTER_NAME — 常量 'supabase'

⚠️ 不存在 createSupabaseAdapter() / createRxdb() 这类工厂函数，请用下方的类 + rxdb.adapter() 注册方式。

快速开始

1. 配置 RxDB（本地 wa-sqlite + 远程 supabase）

import { RxDB, SyncType } from '@aiao/rxdb';
import { RxDBAdapterSupabase } from '@aiao/rxdb-adapter-supabase';
import { RxDBAdapterWaSqlite } from '@aiao/rxdb-adapter-wa-sqlite';
import { Todo } from './entities/Todo';

const rxdb = new RxDB({
  dbName: 'my-app',
  context: { userId: 'current-user-id' },
  entities: [Todo],
  sync: {
    local: { adapter: 'wa-sqlite' },
    remote: { adapter: 'supabase' },
    type: SyncType.Full
  }
});

// 注册本地适配器
rxdb.adapter('wa-sqlite', db => new RxDBAdapterWaSqlite(db, { vfs: 'IDBBatchAtomicVFS', async: true }));

// 注册远程适配器
rxdb.adapter(
  'supabase',
  async db =>
    new RxDBAdapterSupabase(db, {
      supabaseUrl: 'https://your-project.supabase.co',
      supabaseKey: 'your-anon-key'
      // 或复用已有客户端：client: existingSupabaseClient
    })
);

// 连接本地（自动建表）
await rxdb.connect('wa-sqlite');

// 连接远程（启动 Realtime 订阅 + RLS 自检）
const supabase = await rxdb.getAdapter('supabase');
await supabase.connect();

2. 数据操作（active-record 风格）

// 创建
const todo = new Todo();
todo.title = 'Learn RxDB';
todo.completed = false;
await todo.save();

// 查询（本地 SQLite，响应式）
const todos = await rxdb.repository(Todo).find({
  where: `{ combinator: 'and', rules: [{ field: 'completed', operator: '=', value: false }] }`
});

3. 同步

await rxdb.versionManager.push(); // 推送本地变更到远程
await rxdb.versionManager.pull(); // 拉取远程变更到本地
await rxdb.versionManager.sync(); // 双向（pull + push）

// 也可按实体粒度同步
await rxdb.versionManager.pushRepository('public', 'Todo');
await rxdb.versionManager.pullRepository('public', 'Todo', { limit: 200 });
await rxdb.versionManager.syncRepository('public', 'Todo');

配置项（`SupabaseAdapterOptions`）

supabaseUrl?: string — 项目 URL（与 supabaseKey 配合）
supabaseKey?: string — API Key（与 supabaseUrl 配合）
client?: SupabaseClient — 复用已有客户端，优先级高于 URL+Key
rlsCheck?: boolean | SupabaseRlsCheckOptions — 连接时 RLS 自检；false 关闭，对象可配 rpcName / failureMode / tables

rlsCheck 默认行为：调用 RPC rxdb_check_rls 检查实体表是否启用 RLS，未启用时 告警但不阻断（failureMode: 'warn'）。设为 'throw' 可在生产环境强制阻断未开启 RLS 的连接。

const adapter = new RxDBAdapterSupabase(rxdb, {
  client,
  rlsCheck: `{ failureMode: 'throw' }`
});

严格模式下，目标表不存在、RLS 未启用、RPC 响应遗漏目标表、检查 RPC 缺失或检查请求失败都会拒绝 connect()，且不会启动 Realtime；后续重试会重新执行检查。该检查只确认目标表已启用 RLS，不验证 policy 内容、认证 claims、tenant ownership 或 RPC grants，这些仍需在服务端独立审计。

数据库 Schema

适配器依赖两张系统表（snake_case 表名，camelCase 列名加引号），完整脚本见 docker/sql/。

`rxdb_change`（变更记录）

CREATE TABLE public.rxdb_change (
  id            serial PRIMARY KEY,
  namespace     varchar NOT NULL DEFAULT 'public',
  entity        varchar NOT NULL,
  "entityId"    varchar NOT NULL,
  "branchId"    varchar DEFAULT 'main',
  type          varchar NOT NULL CHECK (type IN ('INSERT','UPDATE','DELETE')),
  patch         jsonb,
  "inversePatch" jsonb,
  "transactionId" uuid,
  "localId"     integer,
  "clientId"    varchar,
  "createdAt"   timestamptz(3) NOT NULL DEFAULT now(),
  "updatedAt"   timestamptz(3) NOT NULL DEFAULT now()
);

`rxdb_branch`（分支元数据）

CREATE TABLE public.rxdb_branch (
  id            varchar PRIMARY KEY,
  activated     boolean DEFAULT false,
  "fromChangeId" integer,
  "lastPushedChangeId" integer,
  "lastPushedAt" timestamptz(3),
  "lastPulledAt" timestamptz(3),
  "parentId"    varchar,
  "createdAt"   timestamptz(3) NOT NULL DEFAULT now(),
  "updatedAt"   timestamptz(3) NOT NULL DEFAULT now()
);

Realtime 需把 rxdb_change 加入 supabase_realtime publication；系统表初始化脚本已处理。同步事务依赖 RPC：rxdb_mutations、rxdb_check_rls、rxdb_enable_sync_for_branch，树查询依赖 get_descendants / get_root_descendants / get_ancestors（缺失时自动降级为内存遍历）。

API