postgres

Postgres 技能

配置 DigitalOcean Managed Postgres 数据库，采用适当的安全隔离和适用于生产环境的默认设置。

快速决策

Need multiple isolated schemas in one database?
├── YES → Path B (Schema Isolation)
└── NO  → Path A (Bindable Variables) ✅ RECOMMENDED

---

路径 A：可绑定变量（推荐）

适用场景：每个数据库对应一个应用、标准 CRUD 应用。

快速开始

# 1. Create cluster + user via doctl (DO stores password internally)
doctl databases create my-app-db --engine pg --region nyc3 --size db-s-1vcpu-2gb
CLUSTER_ID=$(doctl databases list --format ID,Name --no-header | grep my-app-db | awk '{print $1}')
doctl databases db create $CLUSTER_ID myappdb
doctl databases user create $CLUSTER_ID myappuser

# 2. Grant permissions (REQUIRED - users have no access by default!)
# Run: scripts/grant_permissions.sql as doadmin

# 3. Reference in app spec

# .do/app.yaml
databases:
  - name: db
    engine: PG
    production: true
    cluster_name: my-app-db
    db_name: myappdb
    db_user: myappuser

services:
  - name: api
    envs:
      - key: DATABASE_URL
        scope: RUN_TIME
        value: ${db.DATABASE_URL}

完整指南：参阅 path-a-bindable-vars.md

---

路径 B：架构隔离

适用场景：多租户 SaaS、多个应用共享一个集群、需要架构级隔离。

快速开始

# Hands-free setup (requires gh CLI)
./scripts/secure_setup.sh \
  --admin-url "$ADMIN_URL" \
  --app-name myapp \
  --schema myapp \
  --repo owner/repo

密码会直接传递到 GitHub Secrets，绝不会显示。

完整指南：参阅 path-b-schema-isolation.md

---

可用的可绑定变量

变量	示例
${db.DATABASE_URL}	postgresql://user:pass@host:25060/db?sslmode=require
${db.HOSTNAME}	my-db-do-user-123.db.ondigitalocean.com
${db.PORT}	25060
${db.USERNAME}	myappuser
${db.PASSWORD}	（自动填充）
${db.DATABASE}	myappdb
${db.CA_CERT}	（证书内容）

---

脚本

脚本	用途
scripts/secure_setup.sh	通过 GitHub Secrets 免手动操作完成路径 B 设置
scripts/create_schema_user.py	创建隔离的架构和用户
scripts/list_schemas_users.py	审核现有架构/用户
scripts/generate_connection_string.py	构建连接字符串

---

参考文件

• path-a-bindable-vars.md — 完整的路径 A 工作流、连接池、多应用设置
• path-b-schema-isolation.md — 完整的路径 B 工作流、多租户模式
• orm-configurations.md — Prisma、SQLAlchemy、Drizzle、TypeORM 配置
• database-migrations.md — Alembic、Prisma Migrate、Drizzle Migrate
• doctl-reference.md — 所有 doctl databases 命令
• troubleshooting.md — 常见错误及修复方法
• bundled-scripts.md — 脚本使用文档

---

常见问题（快速修复）

错误	修复方法
"permission denied for schema"	使用 doadmin 运行权限 SQL
"relation does not exist"	检查 search_path，或使用带架构限定的名称
"too many connections"	通过 doctl 创建连接池
"SSL connection required"	在连接字符串中添加 ?sslmode=require
未填充可绑定变量	确认 production: true，且名称完全匹配

完整故障排除指南：参阅 troubleshooting.md

---

与其他技能集成

• → designer：将数据库块添加到应用规范中
• → deployment：使用 DATABASE_URL 密钥的 GitHub Actions 工作流
• → devcontainers：与生产环境保持一致的本地 Postgres
• → troubleshooting：用于连接测试的调试容器