在自托管 Xata Postgres 平台时用：通过…

适用场景：需要在 Kubernetes 上自托管或本地部署 Xata 开源 Postgres 平台，并用 CoW 分支、scale-to-zero、CLI/REST API 管理项目与分支。

适用场景

解决思路

1. 准备本地环境：安装 Docker、Kind、Tilt、kubectl。
2. 创建 Kind 集群：运行 `kind create cluster --wait 10m`。
3. 用 Tilt 部署 Xata：运行 `tilt up`，等待所有资源就绪；首次运行会下载镜像且较慢，后续运行很快。
4. 安装 Xata CLI：运行 `curl -fsSL https://xata.io/install.sh | bash`。
5. 认证到本地 Xata 实例：默认凭据 email=dev@xata.tech、password=Xata1234!，运行 `xata auth login --profile local --env local --force`，再运行 `xata auth switch local`。
6. 创建项目：运行 `xata project create --name my-project`；项目创建时会自动创建 main 分支。
7. 创建子分支（父分支的 CoW 拷贝）：运行 `xata branch create`。
8. 登录 Xata Cloud：运行 `xata auth login`。
9. 切换 profile：运行 `xata auth switch local` 或 `xata auth switch default`；列出 profile：运行 `xata auth list`。
10. 管理项目：`xata project create --name my-project`、`xata project list`、`xata project get <project-id>`、`xata project delete <project-id>`。
11. 管理分支：`xata branch create`（CoW 快照，即使 TB 数据也可在数秒内完成）、`xata branch create --name feature-xyz --from main`、`xata branch list`、`xata branch get <branch-id>`、`xata branch delete <branch-id>`。
12. 连接分支：用 `xata branch connection-string <branch-id>` 获取连接串，再用 `psql "$(xata branch connection-string <branch-id>)"` 连接。
13. 配置环境变量：`export XATA_API_URL=http://localhost:8080`、`export XATA_API_KEY=your_api_key_here`、`export XATA_PROJECT_ID=your_project_id`。
14. 管理 RBAC API key：`xata apikey create --name ci-key --role branch:read,branch:write`、`xata apikey list`、`xata apikey delete <key-id>`。
15. 使用 Serverless SQL Driver over HTTP/WebSockets：向 `{XATA_API_URL}/branches/{branchID}/sql` 发 POST，JSON body 含 `query` 和可选 `params`，headers 设 `Authorization: Bearer <XATA_API_KEY>` 与 `Content-Type: application/json`，解析响应中的 `records`/`error`；适合边缘函数和无持久 TCP 连接环境。
16. 用 Go 通过 HTTP 查询：定义 `SQLRequest{Query, Params}` 与 `SQLResponse{Records, Error}`，从 `XATA_API_URL`、`XATA_API_KEY`、`XATA_BRANCH_ID` 读取配置，`http.NewRequest("POST", url, bytes.NewReader(data))`，设置 Bearer header，`json.NewDecoder(resp.Body).Decode(&sqlResp)`。
17. 用 Go 直连 Postgres：使用 `github.com/jackc/pgx/v5`，从 `XATA_DATABASE_URL` 读取连接串（如 `postgresql://user:pass@sql-gateway-host:5432/dbname`），`pgx.Connect(context.Background(), connStr)`，执行 `SELECT ...` 并用 `rows.Scan` 读取。
18. Preview 环境 CI/CD 创建脚本 `create-preview.sh`：`PR_NUMBER="${1:?PR number required}"`、`BRANCH_NAME="pr-${PR_NUMBER}"`、`BRANCH_ID=$(xata branch create --name "$BRANCH_NAME" --from main --output json | jq -r '.id')`、`CONN_STR=$(xata branch connection-string "$BRANCH_ID")`，输出 database_url 和 branch_id。
19. Preview 环境清理脚本 `cleanup-preview.sh`：`BRANCH_ID="${1:?Branch ID required}"`，运行 `xata branch delete "$BRANCH_ID"`。
20. GitHub Actions 集成：在 `pull_request` 的 `opened`/`synchronize` 时触发；checkout 后用 `curl -fsSL https://xata.io/install.sh | bash` 安装 CLI；用 secret `XATA_API_KEY` 执行 `xata auth login --api-key "$XATA_API_KEY"`；创建分支 `xata branch create --name "pr-${{ github.event.number }}" --from main --output json | jq -r '.id'`；把 branch_id 与 connection string 写入 `$GITHUB_OUTPUT`；用 `DATABASE_URL` 运行 `go test ./...`；cleanup job 设置 `if: always()` 并运行 `xata branch delete "${{ needs.create-preview.outputs.branch_id }}"`。
21. 用 Go 程序化管理分支：定义 `XataClient{BaseURL, APIKey, Project, http}`，从 `XATA_API_URL`、`XATA_API_KEY`、`XATA_PROJECT_ID` 读取；CreateBranch 向 `%s/projects/%s/branches` POST JSON（含 `name`、`parentId`），header 设 Bearer，解析 `Branch{ID, Name, ParentID, State, ConnectionURL}`；DeleteBranch 向 `%s/projects/%s/branches/%s` 发 DELETE，header 设 Bearer。
22. Scale-to-zero：分支不活动会自动休眠，下次连接自动唤醒；SQL Gateway 透明处理唤醒，首次连接后可能延迟约数秒。
23. 手动控制 scale-to-zero/休眠唤醒：`xata branch hibernate <branch-id>`、`xata branch wake <branch-id>`、`xata branch get <branch-id> --output json | jq '.state'`。
24. 排查 Tilt/Kind 问题：`kubectl get pods -A`、`kubectl get pods -n xata`；查看日志 `kubectl logs -n xata -l app=sql-gateway --tail=100`、`kubectl logs -n xata -l app=branch-operator --tail=100`、`kubectl logs -n xata -l app=clusters --tail=100`；资源卡住时 `tilt down && tilt up`。
25. 排查分支卡在 provisioning：`kubectl logs -n xata -l app=branch-operator -f`、`kubectl get clusters -A`、`kubectl describe cluster <cluster-name> -n <namespace>`、`kubectl get pvc -A`、`kubectl describe pvc <pvc-name> -n <namespace>`。
26. 排查 SQL Gateway connection refused：`kubectl get svc -n xata sql-gateway`、`kubectl port-forward -n xata svc/sql-gateway 5432:5432`、`psql "postgresql://$DB_USER:$DB_PASS@localhost:5432/$DB_NAME"`。
27. 排查 CLI 认证失败：`xata auth login --profile local --env local --force`、`xata auth whoami`、`xata apikey list`。
28. 检查 scale-to-zero 插件：`kubectl get plugins -A | grep scale-to-zero`、`kubectl get cluster <name> -n <namespace> -o jsonpath='{.metadata.annotations}'`。
29. 按组件理解职责：SQL Gateway 负责连接路由、scale-to-zero 唤醒、HTTP/WS serverless driver；Branch Operator 负责每分支的 Kubernetes 资源生命周期；clusters service 提供集群管理 REST API；projects service 提供项目管理 REST API；Auth service 基于 Keycloak 做认证和 RBAC API keys；CloudNativePG 提供 HA Postgres、failover、backups、connection pooling；OpenEBS 提供 local NVMe 或 Mayastor replicated 存储。
30. 按用例决策：内部 Postgres-as-a-Service 用 Xata OSS；预览/测试/开发环境的 CoW 用 Xata OSS；单个 Postgres 实例改用 plain Postgres 或托管服务；面向终端客户的公共 PGaaS 需联系 Xata 获取 BYOC 方案。

适用边界 · 注意事项

• 只需要单个 Postgres 实例时，不要用 Xata OSS；使用 plain Postgres 或托管服务。
• 想直接面向终端客户提供公共 PGaaS 时，不要直接套用；需联系 Xata 获取 BYOC 方案。
• 没有 Docker、Kind、Tilt、kubectl 和 Xata CLI 等依赖，或不想在 Kubernetes 上自托管时，不适用。