InsForge 常見問題：資料庫、Edge Function 與 SDK

讀寫資料庫算 Edge Function 嗎？資料庫、Edge Function、Custom Compute 有什麼差別？

不算。你平常對資料表做增刪改查的時候，其實沒有執行任何函式，當然也就不是 Edge Function。在 InsForge 裡，你的程式碼有三種方式跟後端打交道，很容易搞混：

	怎麼觸發	會不會一直執行	用來做什麼
讀寫資料庫（自動產生的 REST API）	用戶端發一個 SDK 或 REST 請求	不用你管，後端託管	增刪改查資料表
Edge Function	HTTP 請求、定時（cron），或資料庫觸發器	跑一次就結束	自訂 API、webhook、觸發邏輯、呼叫外部服務
Custom Compute	你自己啟動一個常駐行程	一直開著	佇列 worker、AI 推論迴圈、websocket、需要一直保持狀態的工作

讀寫資料庫。 你建好一張表，InsForge 自動就給你一套 REST 介面（例如 GET /api/database/records/{table}）和一個帶型別的 SDK。你呼叫 select、insert 這些，就是直接在讀寫資料庫，不用部署也不用跑任何東西。日常的增刪改查用這個就夠了，參見資料庫。Edge Function。 當自動介面滿足不了、你想寫自己的伺服器端邏輯時才用它，例如接付款回呼（webhook）、登入掛鉤、在某列資料發生 INSERT/UPDATE/DELETE 時觸發一段程式碼，或者定時任務。它的特點是跑完一次請求就結束，不會一直待著。參見 Edge Functions。Custom Compute。 當你需要一個一直開著的行程時才用它，例如佇列 worker 或者 AI 推論迴圈。這種工作 Edge Function 做不到，因為它不常駐。參見 Custom Compute。一句話判斷：只是讀寫資料，就走資料庫（自動 REST）；要寫一段跑完就結束的邏輯，用 Edge Function；要一直執行，用 Custom Compute。

怎麼查詢 public 以外 schema 裡的表？

預設你所有的表都在 public 裡。只有當你自己用 CREATE SCHEMA 建過別的 schema，才會有非 public 的 schema（InsForge 自己的內部 schema，例如 auth、storage，不對資料 API 開放，.schema() 和 ?schema= 查不到；但身為 project admin，你仍可以用原始 SQL 讀它們，例如 insforge db query 或 dashboard 的 SQL 編輯器）。一旦有了，dashboard、REST API、CLI、SDK 都能讀寫它。下面的例子用一個你自己建立、名叫 my_schema 的 schema。Dashboard。 打開 Database，用側邊欄頂部的 schema 選擇器。你建的任何 schema 都會和 public 並列出現，選中它就能瀏覽該 schema 下的表。REST API。 records 介面既接受 query 參數，也接受 PostgREST 的 profile header。讀用 Accept-Profile，寫和 RPC 用 Content-Profile：

# 讀：?schema= 參數，或 Accept-Profile header
curl "$PROJECT_URL/api/database/records/mytable?schema=my_schema" \
  -H "Authorization: Bearer $TOKEN"

# 寫：帶上 Content-Profile
curl -X POST "$PROJECT_URL/api/database/records/mytable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Profile: my_schema" \
  -H "Content-Type: application/json" \
  -d '{"name": "hello"}'

CLI。 CLI 用 db query 就能讀寫任意 schema，把表名加上 schema 前綴即可：

insforge db query "SELECT * FROM my_schema.mytable"

SDK。 在查詢建構器前鏈式呼叫 .schema()（@insforge/sdk 支援）。它底層對應到同樣的 Accept-Profile / Content-Profile header，讀、寫、RPC 都會路由到你指定的 schema：

// 讀
const { data } = await client.database
  .schema('my_schema')
  .from('mytable')
  .select('*')

// 寫
await client.database
  .schema('my_schema')
  .from('mytable')
  .insert([{ name: 'hello' }])

// RPC
await client.database.schema('my_schema').rpc('my_function', { day: '2026-01-01' })

不管走哪條路，存取 API 都還有一步：自建 schema 只是「可路由」，不等於「可讀」。在你顯式授權之前，anon 和 authenticated 角色對它沒有任何權限，跟表的 owner 是誰無關，所以授權前呼叫只會回傳空結果或權限不足。給你要開放的每個角色授權，再加 RLS：

GRANT USAGE ON SCHEMA my_schema TO anon, authenticated;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA my_schema TO anon, authenticated;

之後列級可見性照常由 RLS 控制。project_admin 擁有表，只是讓它能管理並直接查詢這些表（例如在 dashboard 的 SQL 編輯器裡），並不會給 API 角色存取權限。

怎麼幫一張表開啟或關閉列級安全性（RLS）？

新建的表預設開啟 RLS。建立表時（在 dashboard、POST /api/database/tables，或用 SDK），除非你明確傳 rlsEnabled: false，否則都會啟用 RLS。update-table-schema 端點（PATCH /api/database/tables/{table}/schema）沒有切換 RLS 的欄位——它只處理欄、外鍵和重新命名。要改已存在表的 RLS，執行一條 SQL 即可：

-- 關閉 RLS
ALTER TABLE public.mytable DISABLE ROW LEVEL SECURITY;

-- 重新開啟 RLS
ALTER TABLE public.mytable ENABLE ROW LEVEL SECURITY;

用任何你執行管理員 SQL 的方式都可以執行它，這些方式都需要 project owner / admin 權限：

# 一次性執行，透過 CLI
insforge db query "ALTER TABLE public.mytable DISABLE ROW LEVEL SECURITY"

# 或者作為 migration 追蹤
npx @insforge/cli db migrations new disable-rls-on-mytable
# 把 ALTER TABLE 語句寫進產生的 .sql 檔案裡，然後：
npx @insforge/cli db migrations up --all

也可以在 dashboard 的 SQL 編輯器、MCP 的 run-raw-sql 工具，或原始 SQL 的 REST 端點（POST /api/database/advance/rawsql/unrestricted）裡執行。

關閉 RLS 會移除所有列級過濾：任何擁有表權限的角色（例如 authenticated，以及被授權的 anon）都能透過資料 API 讀寫每一列。相比關閉 RLS，更推薦撰寫 RLS 原則。用 API Key（ik_...）發起的管理員請求本來就會繞過 RLS。給一張沒有任何原則的表開啟 RLS 會觸發 PostgreSQL 的預設拒絕：在你至少加一條原則之前，anon 和 authenticated 透過資料 API 對它的所有存取都會被拒絕（每個 SELECT/INSERT/UPDATE/DELETE 都被擋下）。請在開啟 RLS 之前，或緊接著，補上需要的原則。

InsForge 有 `service_role` key / `INSFORGE_SERVICE_ROLE_KEY` 嗎？

沒有叫這個名字的。InsForge 裡的等價物是你專案的 API Key（以 ik_ 開頭），也就是全權限的管理員 key。每個專案有兩個 key：

Anon Key：公開的，給瀏覽器用。請求以 anon 角色執行，受 RLS 管，permission denied for schema storage 就是它撞出來的。
API Key：全權限管理員 key，只在伺服器端用，繞過 RLS。

在 dashboard 的 Project Settings → General 裡找 API Key（標著 API Key 的那一行，寫明「對專案有完全控制權限，不要暴露在前端」），或者執行 npx @insforge/cli secrets get API_KEY。在可信的伺服器端程式碼裡透過 createAdminClient 使用，絕不要放到瀏覽器：

import { createAdminClient } from '@insforge/sdk'

const admin = createAdminClient({
  baseUrl: process.env.INSFORGE_URL,
  apiKey: process.env.INSFORGE_API_KEY, // ik_... 管理員 key，繞過 RLS
})

const { data, error } = await admin.storage
  .from('post-images')
  .upload('posts/post-123/cover.jpg', fileObject)

把它放在只有伺服器端能讀的環境變數裡，絕不要用會暴露給瀏覽器的變數（不要帶 NEXT_PUBLIC_、VITE_ 或 PUBLIC_ 前綴）。

怎麼把專案分享給另一個管理員，或者邀請隊友？

存取權限是按 organization（組織） 共享的，不是按單個 project。你是把人邀請進擁有這些 project 的組織，他就能存取組織下的所有 project，沒有「只分享某一個 project」的入口。邀請步驟：

在 dashboard 裡，用左上角的組織切換器打開擁有該 project 的組織。
點左側欄的 Members。
點 Invite Member，填對方信箱，選一個角色：
- Administrator（管理員）：完全控制，既能管理 project，也能邀請、移除成員、修改成員角色。
- Developer（開發者）：能正常存取組織的 project，但不能管理成員。
對方會收到一封邀請郵件（7 天內有效）。他用「收到邀請的那個信箱」登入 InsForge 並接受後，就以你選的角色加入組織。

想專門加一個管理員，邀請時選 Administrator 即可，之後也能在 Members 列表裡改角色。只有 Administrator 能邀請和管理成員。把整個組織「移交給新 Owner」是另一個獨立操作，跟邀請成員不是一回事。要移交的話，打開 Organization Settings，用裡面的 Transfer Ownership（只有目前的 Owner 能發起，且對方必須是已驗證的 InsForge 使用者並接受郵件裡的請求）。

為什麼我的專案被暫停了？要怎麼避免被暫停？

只有 Free 方案會出現暫停，原因有兩種：

閒置：free 專案連續 7 天沒有任何請求後會被暫停。我們會先寄信提醒，任何一次請求都會重置這 7 天的計時。
超出用量：如果你的 organization 超過 Free 的用量額度，底下的專案會一直保持暫停，直到你升級。

無論哪種情況，你的資料都完好無損。想徹底不再被暫停，把 organization 升級到 Pro。參見 Pricing。

我的專案被暫停了，要怎麼重新啟動？

在 dashboard 裡打開這個專案，點 Restore Project，幾分鐘後就會帶著完整資料恢復。有幾種情況要注意：

free 專案在暫停後的 30 天內都可以在 dashboard 直接恢復。超過之後專案會被封存，你只能下載資料庫備份和 Storage 檔案（資料仍然不會遺失）。
如果是因為 organization 超出用量而暫停，需要 Upgrade to Pro 才能恢復。

還是卡住？到我們的 Discord 提問，回應最快。

不打開瀏覽器，怎麼幫 CLI 登入驗證？

npx @insforge/cli login 會打開瀏覽器登入。在無介面機器、遠端伺服器或 CI 上，改用 user API key，不需要瀏覽器。最快的方式是用 dashboard 裡的 setup prompt，它會幫你登入並關聯好專案：

打開 Install 頁

在 dashboard 裡打開你的專案，進入 Install 頁。

選擇你的 coding agent

在 Install in Agent 下點你在用的 agent，然後切到 CLI 分頁。

複製 prompt

複製 setup prompt 貼給你的 agent，它會一步搞定登入和專案關聯。

這個 prompt 會填好一條限定到你帳號的登入命令，後面跟著關聯命令：

npx @insforge/cli login --user-api-key <your-user-api-key>
npx @insforge/cli link --project-id <your-project-id>

如果你只需要那把 key（例如在 CI 裡跑 CLI），打開帳號選單，進入 Profile → API Keys，建立一把 key（設個有效期，或選 Never）。把它存成 CI secret，再用它跑 login --user-api-key。加上 --json 可以得到機器可讀的輸出。這把 key 擁有你帳號的完整權限，所以要保密，一旦外洩就輪換掉。

FLY_API_TOKEN 是什麼？

只有當你自行託管 InsForge 並且想使用 Custom Compute 時才需要設定這個環境變數。Custom Compute 把你的長駐容器跑在 Fly.io 上，所以自行託管的實例需要你自己的 Fly 帳號：在 .env 裡設定 FLY_API_TOKEN（用 fly tokens create org 產生的 Fly API token）和 FLY_ORG（用 fly orgs list 查到的 Fly org slug），然後重新啟動。兩者都必填，在設定之前 compute 端點會回傳 503 COMPUTE_NOT_CONFIGURED。在 InsForge Cloud 上你完全不用碰這個。Compute 由平台代管，平台其餘部分（資料庫、認證、Storage、Edge Functions）都不需要任何 Fly token。

這個助手能幫我解決我自己專案裡的具體問題嗎？

基本上不行。這個助手是根據 InsForge 的公開文件來回答的，看不到你的專案：既沒辦法除錯，也讀不到你的資料，更查不了你的設定。凡是跟你自己專案相關的，交給你的編碼 agent 來處理。你的 agent 透過 CLI 或 MCP 連著 InsForge，能讀到你的即時後端、結構、資料和日誌，直接幫你除錯，用白話描述問題就行。想自己拿一份後端健康和報錯報告，跑 npx @insforge/cli diagnose。參見 Diagnostics & advisor。

怎麼拿到資料庫的 Postgres 連線字串（connection string）？

每個 cloud 專案都有一個直連的 Postgres connection string，方便用 psql、資料庫 GUI、ORM（Prisma、Drizzle），或者像 Better Auth 這類需要自帶 Postgres 的外部服務。用 CLI 印出來：

npx @insforge/cli db connection-string

你也可以在 dashboard 裡拿到：進入 Project Settings → Connect → Connection String（僅限 cloud 專案）。它回傳的 URL 形如：

postgresql://postgres:<password>@<appkey>.<region>.database.insforge.app:5432/insforge?sslmode=require

加上 --json 會得到 { "connectionURL": "..." }，方便腳本使用。這個命令只對 cloud 專案有效——自行託管的實例其 Postgres 由你的 docker-compose 直接暴露，所以請改用本地 Postgres 憑證（.env 裡的 DATABASE_URL / POSTGRES_*）。這個字串以擁有完整權限的 postgres 角色連線，因此不受行級安全（RLS）限制，而且字串裡嵌了該角色的密碼。請把它當成機密：只在伺服端使用，絕不要發到瀏覽器。

怎麼把既有的 Postgres 資料庫匯入（load）到 InsForge？

用專案的 Postgres connection string（就是上一個問題裡的那個 URL）把既有資料庫還原（restore）過去即可。標準的 PostgreSQL 用戶端工具——pg_dump、pg_restore 和 psql——都能直接連它，所以匯入就是一次「先 dump、再 restore」。不需要專門的 InsForge 命令。

dump 你本地（或其他）的資料庫：

# 自訂格式（推薦——體積更小，且支援平行 restore）
pg_dump -Fc your_local_db > local.dump

# ……或者純 SQL 檔
pg_dump your_local_db > local.sql

拿到 InsForge 的 connection string（僅限 cloud 專案）：

npx @insforge/cli db connection-string

restore 到 InsForge：

# 自訂格式的 dump
pg_restore --no-owner --single-transaction -d "postgresql://postgres:<password>@<appkey>.<region>.database.insforge.app:5432/insforge?sslmode=require" local.dump

# ……或者純 SQL 檔
psql --single-transaction "postgresql://postgres:<password>@<appkey>.<region>.database.insforge.app:5432/insforge?sslmode=require" < local.sql

有幾點需要注意：

加上 --no-owner，讓還原出來的物件歸 postgres 角色所有，而不是只存在於來源庫裡的那些角色。
這個 connection string 以擁有完整權限的 postgres 角色連線（會繞過行級安全 RLS），請把它當成機密，只在伺服端執行這些命令。
這只對 cloud 專案有效。自行託管的實例請改用本地 Postgres 憑證（.env 裡的 DATABASE_URL / POSTGRES_*）來 restore。
restore 會寫入你正在使用的資料庫，並可能覆蓋既有物件。請先手動做一次備份——參見資料庫備份與還原。
--single-transaction 讓整個還原在單一交易裡執行：任何一句失敗（物件已存在、擴充功能或角色缺失、約束衝突），整個匯入都會回滾，而不會把資料庫留在匯入了一半的狀態。
匯入的表不會自動獲得 InsForge 託管的存取設定。raw 還原會跳過 InsForge 為表設定的 anon / authenticated 授權和列級安全（RLS），因此在你為每張表授予存取權限並加入 RLS 政策之前，這些表無法透過 REST API 或 SDK 存取，來源庫裡的存取規則也不帶 InsForge 的 RLS 保護（參見資料庫）。如果你更想把 schema 變更納入 git 版本管理，參見資料庫遷移。

怎麼下線或刪除已部署的站點（site）？

目前沒有自助下線已部署 Site 的方式——既沒有 deployments delete 命令，dashboard 裡也沒有對應操作。已部署的站點託管在外部，所以即使刪除專案（npx @insforge/cli projects delete --project <id>）也只會清掉後端資源——資料庫、Storage 和後端分支——而不會移除已託管的站點。實際上這基本不影響使用。如果你確實需要下線某個已部署的站點，請到 Discord 聯繫 InsForge 團隊。有兩個相關操作，和「下線一個已上線站點」並不是一回事：

取消還在跑的建置： npx @insforge/cli deployments cancel <id> 會終止一個進行中的部署；它不會下線一個已經上線的站點。
替換目前上線的內容： 用 npx @insforge/cli deployments deploy ./frontend 在同一個站點上重新部署——最新一次 ready 的部署會接管這個 URL。

快速開始

Products

Agent-Native Initiatives

Partnership

Self-Hosting

Resources

常見問題

InsForge 常見問題：資料庫、Edge Function 與 SDK