Files
NianAIGC/.project-docs/30-worklog/tasks/20260812-rds-postgres-adapter-7f2c1a.md
T

4.9 KiB

Task: Add direct PostgreSQL support for Alibaba Cloud RDS

Identity

  • Task ID: 20260812-rds-postgres-adapter-7f2c1a
  • Mode: Feature
  • Branch: codex/rds-postgres-adapter-7f2c1a
  • Worktree: D:\Datas\OthersProjects\NianAIGC-rds-postgres-7f2c1a
  • Base commit: 0bcb149fad8e4131fdf960cc61106ac5912cf34f
  • Owner: codex
  • Status: Ready for Integration

Scope

  • Replace the Supabase/PostgREST persistence path in data-store, account-store, and billing-store with a shared server-only PostgreSQL adapter backed by pg.
  • Migrate the bootstrap/import scripts to the same PostgreSQL configuration contract while preserving their existing public behavior.
  • Add a versioned PostgreSQL migration runner and an RDS-compatible baseline schema that preserves atomic job claiming and wallet posting.
  • Add fail-closed production backend selection, database readiness, Docker runtime support, and ACK deployment manifests for Web, Worker, migration Job, Service, Ingress, ConfigMap, and Secret templates.
  • Update environment and deployment documentation for Alibaba Cloud ACK + RDS PostgreSQL.
  • Preserve the local JSON backend for development and existing unit tests.

Intent And Constraints

  • ZHINIAN_DATA_BACKEND=postgres must never silently fall back to container-local JSON when database configuration or connectivity is missing.
  • Keep store exports and route/component callers stable; isolate pooling, TLS, timeouts, transactions, and SQL execution behind one deep server-only module.
  • Keep the Worker as an HTTP poller; only the Web workload connects directly to PostgreSQL in the current architecture.
  • Retain the PostgreSQL functions that provide FOR UPDATE SKIP LOCKED job claiming and atomic wallet ledger posting.
  • Use parameterized SQL and explicit transactions where an operation crosses multiple statements.
  • Inject credentials through Kubernetes Secrets; do not place RDS passwords or application secrets in images or ConfigMaps.
  • Use TLS verification for RDS when SSL is enabled; do not introduce rejectUnauthorized: false as a production shortcut.
  • Do not modify canonical .project-docs files in feature mode; record promotion candidates here for later integration.
  • No live RDS credentials or ACK cluster access are available, so actual external connectivity and rollout remain explicitly unverified.

Outcome

  • Replaced the Supabase/PostgREST runtime path with a shared server-only pg adapter across data, account, and billing persistence while preserving explicit local JSON mode for development and tests.
  • Added fail-closed production backend selection, verified-CA TLS configuration, pooled queries/transactions, full schema-and-privilege readiness, versioned/checksummed/advisory-locked migrations, and constrained application-role grants.
  • Migrated bootstrap/import tooling, preserved database-side atomic job claim and wallet posting, and hardened authentication/password and wallet idempotency concurrency paths.
  • Added Docker migration assets and eight ACK manifests covering namespace, configuration, secret templates, migration Job, Web, Worker, Service isolation, and Ingress, with updated Chinese/English deployment guidance.
  • Final independent Sol review returned PASS with no blocking findings.

Verification

  • npm ci --ignore-scripts — passed.
  • pnpm install --lockfile-only --frozen-lockfile — passed; npm/pnpm Next and React resolutions remain aligned.
  • npm test -- --run — passed, 31 files / 119 tests.
  • npx tsc --noEmit --pretty false --incremental false — passed.
  • npm run build — passed with /api/ready in the production route output.
  • npm run deploy:check — passed static assertions for all 8 ACK manifests.
  • PostgreSQL/account/worker script node --check commands — passed.
  • git diff --check and project documentation drift checks — passed.
  • Not externally verified: no live RDS credentials, ACK kubeconfig, psql, or available Docker daemon were present, so real migration execution, database concurrency, image startup, and cluster rollout remain deployment checks.

Follow-ups

  • Before production cutover, back up the target database, provision separate migration/application roles, mount the Alibaba Cloud RDS CA, verify the VPC/internal endpoint and whitelist, and run the one-shot migration Job before Web rollout.
  • Keep Web at one replica until generated assets are externalized to OSS/shared object storage; PostgreSQL alone does not make container-local files multi-replica safe.
  • Move the image to a non-root runtime user in a later hardening change after writable runtime paths and ownership are explicitly defined.

Promotion Candidates

  • Promote the explicit ZHINIAN_DATA_BACKEND fail-closed contract, shared server-only PostgreSQL boundary, and versioned migration ownership model into canonical architecture/deployment memory after this feature is integrated.
  • Record that the Worker remains an HTTP-only poller and does not require RDS credentials in the current architecture.