feat(database): support custom PostgreSQL schema via DATABASE_SCHEMA

Allows multiple projects to share a single PostgreSQL database (e.g. Supabase)
by isolating tables in a configurable schema. When DATABASE_SCHEMA is set,
startup creates the schema if missing and pins search_path on every pool
connection via libpq options. Empty value preserves existing behavior.

Closes #119

Author: james-6-23

.env.example

@@ -61,6 +61,10 @@ DATABASE_PORT=5432
 DATABASE_USER=codex2api
 DATABASE_PASSWORD=codex2api
 DATABASE_NAME=codex2api
+# 可选：自定义 schema（适用于 Supabase 等多项目共享 database 的场景）
+# 启动时会自动 CREATE SCHEMA IF NOT EXISTS，并在所有连接上 SET search_path 到该 schema
+# 仅允许字母/数字/下划线，长度 ≤63；留空时使用数据库默认 search_path（通常是 public）
+# DATABASE_SCHEMA=codex2api
 
 # ---- Redis ----
 CACHE_DRIVER=redis

config/config.go

@@ -3,12 +3,24 @@ package config
 import (
 	"fmt"
 	"os"
+	"regexp"
 	"strconv"
 	"strings"
 
 	"github.com/joho/godotenv"
 )
 
+// schemaNameRegex 限定 PostgreSQL schema 名为 ASCII 标识符，避免 DSN/DDL 注入。
+var schemaNameRegex = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+// IsValidSchemaName 校验 PostgreSQL schema 名（首字母为字母或下划线，余下为字母/数字/下划线，长度 ≤63）。
+func IsValidSchemaName(name string) bool {
+	if name == "" || len(name) > 63 {
+		return false
+	}
+	return schemaNameRegex.MatchString(name)
+}
+
 // DatabaseConfig 数据库核心配置。
 type DatabaseConfig struct {
 	Driver   string
@@ -18,6 +30,7 @@ type DatabaseConfig struct {
 	User     string
 	Password string
 	DBName   string
+	Schema   string // PostgreSQL schema（search_path）；空值保持数据库默认行为
 	SSLMode  string
 }
 
@@ -30,8 +43,14 @@ func (d *DatabaseConfig) DSN() string {
 	if sslMode == "" {
 		sslMode = "disable"
 	}
-	return fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
+	dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=%s",
 		d.Host, d.Port, d.User, d.Password, d.DBName, sslMode)
+	if d.Schema != "" {
+		// 通过 libpq options 在连接启动时设置 search_path，覆盖连接池中的所有连接。
+		// schema 已在 Load() 阶段做白名单校验，此处可安全拼接。
+		dsn += fmt.Sprintf(" options='-c search_path=%s,public'", d.Schema)
+	}
+	return dsn
 }
 
 // Label 返回用于展示的数据库标签。
@@ -139,6 +158,12 @@ func Load(envPath string) (*Config, error) {
 	cfg.Database.User = os.Getenv("DATABASE_USER")
 	cfg.Database.Password = os.Getenv("DATABASE_PASSWORD")
 	cfg.Database.DBName = os.Getenv("DATABASE_NAME")
+	if v := strings.TrimSpace(os.Getenv("DATABASE_SCHEMA")); v != "" {
+		if !IsValidSchemaName(v) {
+			return nil, fmt.Errorf("非法的 DATABASE_SCHEMA: %q（仅允许字母、数字、下划线，且不能以数字开头，长度不超过 63）", v)
+		}
+		cfg.Database.Schema = v
+	}
 	if v := os.Getenv("DATABASE_SSLMODE"); v != "" {
 		cfg.Database.SSLMode = v
 	}

config/config_test.go

@@ -1,6 +1,9 @@
 package config
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestLoadDefaultsToPostgresAndRedis(t *testing.T) {
 	keys := []string{
@@ -301,3 +304,63 @@ func TestLoadReadsRedisTLSSettings(t *testing.T) {
 		t.Fatal("Redis.InsecureSkipVerify = false, want true")
 	}
 }
+
+func TestLoadAcceptsValidDatabaseSchema(t *testing.T) {
+	t.Setenv("DATABASE_DRIVER", "")
+	t.Setenv("DATABASE_HOST", "postgres")
+	t.Setenv("DATABASE_NAME", "postgres")
+	t.Setenv("DATABASE_SCHEMA", "codex2api")
+	t.Setenv("CACHE_DRIVER", "")
+	t.Setenv("REDIS_ADDR", "redis:6379")
+
+	cfg, err := Load("__not_exists__.env")
+	if err != nil {
+		t.Fatalf("Load() 返回错误: %v", err)
+	}
+	if got := cfg.Database.Schema; got != "codex2api" {
+		t.Fatalf("Database.Schema = %q, want codex2api", got)
+	}
+	dsn := cfg.Database.DSN()
+	if !strings.Contains(dsn, "options='-c search_path=codex2api,public'") {
+		t.Fatalf("DSN 未包含 search_path 选项: %s", dsn)
+	}
+}
+
+func TestLoadRejectsInvalidDatabaseSchema(t *testing.T) {
+	cases := []string{
+		"public; DROP TABLE users",
+		"with space",
+		"1leading-digit",
+		"with-dash",
+		"中文",
+		strings.Repeat("a", 64),
+	}
+	for _, name := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Setenv("DATABASE_DRIVER", "")
+			t.Setenv("DATABASE_HOST", "postgres")
+			t.Setenv("DATABASE_SCHEMA", name)
+			t.Setenv("CACHE_DRIVER", "")
+			t.Setenv("REDIS_ADDR", "redis:6379")
+
+			if _, err := Load("__not_exists__.env"); err == nil {
+				t.Fatalf("非法 schema %q 应当被拒绝，但 Load() 通过了", name)
+			}
+		})
+	}
+}
+
+func TestDSNOmitsSchemaWhenEmpty(t *testing.T) {
+	d := DatabaseConfig{
+		Driver:   "postgres",
+		Host:     "h",
+		Port:     5432,
+		User:     "u",
+		Password: "p",
+		DBName:   "db",
+		SSLMode:  "disable",
+	}
+	if got := d.DSN(); strings.Contains(got, "search_path") {
+		t.Fatalf("空 schema 时 DSN 不应包含 search_path: %s", got)
+	}
+}

database/postgres.go

@@ -11,7 +11,7 @@ import (
 	"sync/atomic"
 	"time"
 
-	_ "github.com/lib/pq"
+	"github.com/lib/pq"
 	_ "modernc.org/sqlite"
 )
 
@@ -181,13 +181,19 @@ type usageLogEntry struct {
 }
 
 // New 创建数据库连接并自动建表。
-func New(driver string, dsn string) (*DB, error) {
+// schema 仅对 PostgreSQL 生效；为空时保持数据库默认 search_path。
+func New(driver string, dsn string, schema ...string) (*DB, error) {
 	driver = normalizeDriver(driver)
 	driverName := driver
 	if driver == "sqlite" {
 		driverName = "sqlite"
 	}
 
+	pgSchema := ""
+	if len(schema) > 0 {
+		pgSchema = strings.TrimSpace(schema[0])
+	}
+
 	conn, err := sql.Open(driverName, dsn)
 	if err != nil {
 		return nil, fmt.Errorf("连接数据库失败: %w", err)
@@ -228,6 +234,18 @@ func New(driver string, dsn string) (*DB, error) {
 		if _, err := conn.ExecContext(ctx, "SET timezone = 'UTC'"); err != nil {
 			return nil, fmt.Errorf("设置数据库时区失败: %w", err)
 		}
+		// 自定义 schema：确保 schema 存在并确认当前会话 search_path 已生效。
+		// search_path 已通过 DSN 的 options=-c search_path=... 在所有连接启动时设置；
+		// 这里仅做一次幂等的 CREATE SCHEMA + SET 兜底，便于首次部署时自动建好 schema。
+		if pgSchema != "" {
+			quoted := pq.QuoteIdentifier(pgSchema)
+			if _, err := conn.ExecContext(ctx, "CREATE SCHEMA IF NOT EXISTS "+quoted); err != nil {
+				return nil, fmt.Errorf("创建数据库 schema 失败: %w", err)
+			}
+			if _, err := conn.ExecContext(ctx, "SET search_path TO "+quoted+", public"); err != nil {
+				return nil, fmt.Errorf("设置 search_path 失败: %w", err)
+			}
+		}
 	}
 	if err := db.migrate(ctx); err != nil {
 		return nil, fmt.Errorf("数据库迁移失败: %w", err)

docs/CONFIGURATION.md

@@ -69,6 +69,7 @@ Codex2API 采用三层配置架构：
 | `DATABASE_USER` | 是 | - | PostgreSQL 用户名 |
 | `DATABASE_PASSWORD` | 是 | - | PostgreSQL 密码 |
 | `DATABASE_NAME` | 是 | - | PostgreSQL 数据库名 |
+| `DATABASE_SCHEMA` | 否 | - | PostgreSQL schema；适合 Supabase 等多项目共享 database 的场景。配置后启动时自动 `CREATE SCHEMA IF NOT EXISTS` 并将所有连接的 `search_path` 指向该 schema。仅允许字母/数字/下划线，长度 ≤63；留空保持默认（通常是 `public`）。|
 | `DATABASE_SSLMODE` | 否 | disable | SSL 模式: disable/require/verify-full |
 
 ### 生图工作台

main.go

@@ -41,7 +41,7 @@ func main() {
 	log.Printf("物理层配置加载成功: port=%d, database=%s, cache=%s", cfg.Port, cfg.Database.Label(), cfg.Cache.Label())
 
 	// 2. 初始化数据库
-	db, err := database.New(cfg.Database.Driver, cfg.Database.DSN())
+	db, err := database.New(cfg.Database.Driver, cfg.Database.DSN(), cfg.Database.Schema)
 	if err != nil {
 		log.Fatalf("数据库初始化失败: %v", err)
 	}
@@ -50,7 +50,11 @@ func main() {
 	case "sqlite":
 		log.Printf("%s 连接成功: %s", cfg.Database.Label(), cfg.Database.Path)
 	default:
-		log.Printf("%s 连接成功: %s:%d/%s", cfg.Database.Label(), cfg.Database.Host, cfg.Database.Port, cfg.Database.DBName)
+		if cfg.Database.Schema != "" {
+			log.Printf("%s 连接成功: %s:%d/%s (schema=%s)", cfg.Database.Label(), cfg.Database.Host, cfg.Database.Port, cfg.Database.DBName, cfg.Database.Schema)
+		} else {
+			log.Printf("%s 连接成功: %s:%d/%s", cfg.Database.Label(), cfg.Database.Host, cfg.Database.Port, cfg.Database.DBName)
+		}
 	}
 
 	// 3. 读取运行时的系统逻辑设置（需在缓存初始化之前，以获取连接池大小）