insforge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InsForge SDK Skill

InsForge SDK 技能

This skill covers client-side SDK integration using

@insforge/sdk

. For backend infrastructure operations (creating tables, inspecting schema, deploying functions, secrets, managing storage buckets, website deployments, cron job and schedules, logs, etc.), use the insforge-cli skill.

本技能涵盖使用

@insforge/sdk

进行的客户端SDK集成。对于后端基础设施操作（创建表、查看 schema、部署函数、管理密钥、存储桶、网站部署、定时任务和计划、日志等），请使用insforge-cli技能。

Quick Setup

快速设置

bash

npm install @insforge/sdk@latest

javascript

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: 'https://your-project.region.insforge.app',
  anonKey: 'your-anon-key'
})

bash

npm install @insforge/sdk@latest

javascript

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: 'https://your-project.region.insforge.app',
  anonKey: 'your-anon-key'
})

Module Reference

模块参考

Module	SDK Integration
Database	database/sdk-integration.md
Auth	auth/sdk-integration.md
Storage	storage/sdk-integration.md
Functions	functions/sdk-integration.md
AI	ai/sdk-integration.md
Real-time	realtime/sdk-integration.md

模块	SDK集成
数据库	database/sdk-integration.md
身份验证	auth/sdk-integration.md
存储	storage/sdk-integration.md
函数	functions/sdk-integration.md
AI	ai/sdk-integration.md
实时消息	realtime/sdk-integration.md

What Each Module Covers

各模块涵盖内容

Module	Content
Database	CRUD operations, filters, pagination, RPC calls
Auth	Sign up/in, OAuth, sessions, profiles, password reset
Storage	Upload, download, delete files
Functions	Invoke edge functions
AI	Chat completions, image generation, embeddings
Real-time	Connect, subscribe, publish events

模块	内容
数据库	CRUD操作、过滤、分页、RPC调用
身份验证	注册/登录、OAuth、会话、用户信息、密码重置
存储	文件上传、下载、删除
函数	调用边缘函数
AI	聊天补全、图像生成、嵌入向量
实时消息	连接、订阅、发布事件

Guides

指南

Guide	When to Use
database/postgres-rls.md	Writing or reviewing RLS policies — covers infinite recursion prevention, `SECURITY DEFINER` patterns, performance tips, and common InsForge RLS patterns

指南	使用场景
database/postgres-rls.md	编写或审核RLS策略——涵盖无限递归预防、 `SECURITY DEFINER` 模式、性能技巧和常见InsForge RLS模式

Real-time Configuration

实时配置

For real-time channels and database triggers, use

insforge db query

with SQL to create triggers that publish to channels. The real-time SDK is for frontend event handling and messaging, not backend configuration.

对于实时通道和数据库触发器，请使用

insforge db query

结合SQL创建用于发布消息到通道的触发器。实时SDK用于前端事件处理和消息传递，而非后端配置。

Create Database Triggers

创建数据库触发器

Automatically publish events when database records change.

sql

-- Create trigger function
CREATE OR REPLACE FUNCTION notify_order_changes()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.publish(
    'order:' || NEW.id::text,    -- channel
    TG_OP || '_order',           -- event: INSERT_order, UPDATE_order
    jsonb_build_object(
      'id', NEW.id,
      'status', NEW.status,
      'total', NEW.total
    )
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- Attach to table
CREATE TRIGGER order_realtime
  AFTER INSERT OR UPDATE ON orders
  FOR EACH ROW
  EXECUTE FUNCTION notify_order_changes();

当数据库记录发生变化时自动发布事件。

sql

-- Create trigger function
CREATE OR REPLACE FUNCTION notify_order_changes()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.publish(
    'order:' || NEW.id::text,    -- channel
    TG_OP || '_order',           -- event: INSERT_order, UPDATE_order
    jsonb_build_object(
      'id', NEW.id,
      'status', NEW.status,
      'total', NEW.total
    )
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

-- Attach to table
CREATE TRIGGER order_realtime
  AFTER INSERT OR UPDATE ON orders
  FOR EACH ROW
  EXECUTE FUNCTION notify_order_changes();

Conditional Trigger (Status Changes Only)

条件触发器（仅当状态变化时触发）

sql

CREATE OR REPLACE FUNCTION notify_order_status()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.publish(
    'order:' || NEW.id::text,
    'status_changed',
    jsonb_build_object('id', NEW.id, 'status', NEW.status)
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER order_status_trigger
  AFTER UPDATE ON orders
  FOR EACH ROW
  WHEN (OLD.status IS DISTINCT FROM NEW.status)
  EXECUTE FUNCTION notify_order_status();

sql

CREATE OR REPLACE FUNCTION notify_order_status()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM realtime.publish(
    'order:' || NEW.id::text,
    'status_changed',
    jsonb_build_object('id', NEW.id, 'status', NEW.status)
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER order_status_trigger
  AFTER UPDATE ON orders
  FOR EACH ROW
  WHEN (OLD.status IS DISTINCT FROM NEW.status)
  EXECUTE FUNCTION notify_order_status();

Access Control (RLS)

访问控制（RLS）

RLS is disabled by default. To restrict channel access:

Enable RLS

sql

ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY;
ALTER TABLE realtime.messages ENABLE ROW LEVEL SECURITY;

Restrict Subscribe (SELECT on channels)

sql

CREATE POLICY "users_subscribe_own_orders"
ON realtime.channels FOR SELECT
TO authenticated
USING (
  pattern = 'order:%'
  AND EXISTS (
    SELECT 1 FROM orders
    WHERE id = NULLIF(split_part(realtime.channel_name(), ':', 2), '')::uuid
      AND user_id = auth.uid()
  )
);

Restrict Publish (INSERT on messages)

sql

CREATE POLICY "members_publish_chat"
ON realtime.messages FOR INSERT
TO authenticated
WITH CHECK (
  channel_name LIKE 'chat:%'
  AND EXISTS (
    SELECT 1 FROM chat_members
    WHERE room_id = NULLIF(split_part(channel_name, ':', 2), '')::uuid
      AND user_id = auth.uid()
  )
);

Quick Reference

Task	SQL
Create channel	`INSERT INTO realtime.channels (pattern, description, enabled) VALUES (...)`
Create trigger	`CREATE TRIGGER ... EXECUTE FUNCTION ...`
Publish from SQL	`PERFORM realtime.publish(channel, event, payload)`
Enable RLS	`ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY`

RLS默认是禁用的。要限制通道访问：

启用RLS

sql

ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY;
ALTER TABLE realtime.messages ENABLE ROW LEVEL SECURITY;

限制订阅（对channels表执行SELECT）

sql

CREATE POLICY "users_subscribe_own_orders"
ON realtime.channels FOR SELECT
TO authenticated
USING (
  pattern = 'order:%'
  AND EXISTS (
    SELECT 1 FROM orders
    WHERE id = NULLIF(split_part(realtime.channel_name(), ':', 2), '')::uuid
      AND user_id = auth.uid()
  )
);

限制发布（对messages表执行INSERT）

sql

CREATE POLICY "members_publish_chat"
ON realtime.messages FOR INSERT
TO authenticated
WITH CHECK (
  channel_name LIKE 'chat:%'
  AND EXISTS (
    SELECT 1 FROM chat_members
    WHERE room_id = NULLIF(split_part(channel_name, ':', 2), '')::uuid
      AND user_id = auth.uid()
  )
);

快速参考

任务	SQL
创建通道	`INSERT INTO realtime.channels (pattern, description, enabled) VALUES (...)`
创建触发器	`CREATE TRIGGER ... EXECUTE FUNCTION ...`
从SQL发布消息	`PERFORM realtime.publish(channel, event, payload)`
启用RLS	`ALTER TABLE realtime.channels ENABLE ROW LEVEL SECURITY`

Best Practices

最佳实践

Create channel patterns first before subscribing from frontend
- Insert channel patterns into
```
realtime.channels
```
  table
- Ensure
```
enabled
```
  is set to
```
true
```
Use specific channel patterns
- Use wildcard
```
%
```
  patterns for dynamic channels (e.g.,
```
order:%
```
  for
```
order:123
```
  )
- Use exact patterns for global channels (e.g.,
```
notifications
```
  )

先创建通道模式，再从前端订阅
- 向
```
realtime.channels
```
  表插入通道模式
- 确保
```
enabled
```
  设置为
```
true
```
使用特定的通道模式
- 对动态通道使用通配符
```
%
```
  模式（例如
```
order:%
```
  对应
```
order:123
```
  ）
- 对全局通道使用精确模式（例如
```
notifications
```
  ）

Common Mistakes

常见错误

Mistake	Solution
Subscribing to undefined channel pattern	Create channel pattern in `realtime.channels` first
Channel not receiving messages	Ensure channel `enabled` is `true`
Publishing without trigger	Create database trigger to auto-publish on changes

错误	解决方案
订阅未定义的通道模式	先在 `realtime.channels` 中创建通道模式
通道未接收消息	确保通道 `enabled` 为 `true`
未通过触发器发布消息	创建数据库触发器以在数据变化时自动发布

Recommended Workflow

Backend Configuration (Not Yet in CLI)

后端配置（暂未支持CLI）

These modules still require HTTP API calls because the CLI does not yet support them:

Module	Backend Configuration
Auth	auth/backend-configuration.md
AI	ai/backend-configuration.md

这些模块仍需通过HTTP API调用，因为CLI尚未支持：

模块	后端配置
身份验证	auth/backend-configuration.md
AI	ai/backend-configuration.md

SDK Quick Reference

SDK快速参考

All SDK methods return

{ data, error }

Module	Methods
`insforge.database`	`.from().select()` , `.insert()` , `.update()` , `.delete()` , `.rpc()`
`insforge.auth`	`.signUp()` , `.signInWithPassword()` , `.signInWithOAuth()` , `.signOut()` , `.getCurrentSession()`
`insforge.storage`	`.from().upload()` , `.uploadAuto()` , `.download()` , `.remove()`
`insforge.functions`	`.invoke()`
`insforge.ai`	`.chat.completions.create()` , `.images.generate()` , `.embeddings.create()`
`insforge.realtime`	`.connect()` , `.subscribe()` , `.publish()` , `.on()` , `.disconnect()`

所有SDK方法均返回

{ data, error }

。

模块	方法
`insforge.database`	`.from().select()` , `.insert()` , `.update()` , `.delete()` , `.rpc()`
`insforge.auth`	`.signUp()` , `.signInWithPassword()` , `.signInWithOAuth()` , `.signOut()` , `.getCurrentSession()`
`insforge.storage`	`.from().upload()` , `.uploadAuto()` , `.download()` , `.remove()`
`insforge.functions`	`.invoke()`
`insforge.ai`	`.chat.completions.create()` , `.images.generate()` , `.embeddings.create()`
`insforge.realtime`	`.connect()` , `.subscribe()` , `.publish()` , `.on()` , `.disconnect()`

Important Notes

重要注意事项

Database inserts require array format:
```
insert([{...}])
```
not
```
insert({...})
```
Storage: Save both
```
url
```
AND
```
key
```
to database for download/delete operations
Functions invoke URL:
```
/functions/{slug}
```
(without
```
/api
```
prefix)
Use Tailwind CSS v3.4 (do not upgrade to v4)
Always local build before deploy: Prevents wasted build resources and faster debugging

数据库插入需要数组格式：使用
```
insert([{...}])
```
而非
```
insert({...})
```
存储：请同时保存
```
url
```
和
```
key
```
到数据库，以便后续下载/删除操作
函数调用URL：
```
/functions/{slug}
```
（无需
```
/api
```
前缀）
使用Tailwind CSS v3.4（请勿升级到v4）
部署前务必本地构建：避免浪费构建资源，加快调试速度