本文介绍一种安全、可扩展的 go 多租户数据库连接管理方案：通过中心化租户元数据（主库）识别租户，并在请求生命周期内按需动态初始化并复用对应租户的 postgresql 连接池。

在 Go 构建的多租户应用中，为每个租户分配独立 PostgreSQL 数据库是常见且推荐的隔离策略。但关键挑战在于：如何在不牺牲性能与安全的前提下，实现请求级的数据库连接动态路由？ 直接维护 map[string]*sql.DB 虽简单，却存在连接泄漏、并发竞争、缺乏健康检查及冷启动延迟等风险。更优实践是采用“主库驱动 + 连接池缓存 + 请求上下文绑定”的分层设计。

核心架构设计

1. 主数据库（Master DB）：单一、长期存活的 *sql.DB，仅用于查询租户元数据（如 tenants 表），字段建议包含 id, subdomain, db_host, db_port, db_name, db_user, db_password（密钥应加密存储或通过 Vault 注入）。
2. 租户连接池缓存（Tenant DB Cache）：使用线程安全的 sync.Map 缓存已初始化的 *sql.DB 实例，键为租户标识（如 subdomain），值为配置好连接池参数（SetMaxOpenConns, SetMaxIdleConns, SetConnMaxLifetime）的租户专属连接池。
3. 中间件路由（Tenant Router Middleware）：在 HTTP 请求处理链早期（如 Gin/Gorilla Mux 中间件），从 Host 或 Header 提取租户标识 → 查询主库验证租户有效性 → 从缓存获取或新建租户连接池 → 将 *sql.DB 注入 context.Context，供后续 Handler 使用。

示例代码实现（基于 database/sql + pgx/v5）

// 主库初始化（全局单例）
var masterDB *sql.DB

func initMasterDB() error {
    db, err := sql.Open("pgx", "host=localhost port=5432 dbname=master user=app password=secret")
    if err != nil {
        return err
    }
    db.SetMaxOpenConns(20)
    db.SetMaxIdleConns(10)
    masterDB = db
    return nil
}

// 租户连接池缓存
var tenantDBs sync.Map // map[string]*sql.DB

// 获取租户 DB（线程安全）
func getTenantDB(subdomain string) (*sql.DB, error) {
    if cached, ok := tenantDBs.Load(subdomain); ok {
        return cached.(*sql.DB), nil
    }

    // 查询主库获取租户 DB 配置
    var config struct {
        Host, Port, Name, User, Password string
    }
    err := masterDB.QueryRow(
        `SELECT db_host, db_port, db_name, db_user, db_password FROM tenants WHERE subdomain = $1`,
        subdomain,
    ).Scan(&config.Host, &config.Port, &config.Name, &config.User, &config.Password)
    if err != nil {
        return nil, fmt.Errorf("tenant not found or db config error: %w", err)
    }

    // 构建租户 DSN（生产环境请使用 pgxpool 并启用 TLS）
    dsn := fmt.Sprintf("host=%s port=%s dbname=%s user=%s password=%s",
        config.Host, config.Port, config.Name, config.User, config.Password)

    // 初始化租户连接池
    db, err := sql.Open("pgx", dsn)
    if err != nil {
        return nil, fmt.Errorf("failed to open tenant DB: %w", err)
    }
    db.SetMaxOpenConns(50)
    db.SetMaxIdleConns(20)
    db.SetConnMaxLifetime(1 * time.Hour)

    // 验证连接
    if err := db.Ping(); err != nil {
        return nil, fmt.Errorf("tenant DB ping failed: %w", err)
    }

    // 缓存并返回
    tenantDBs.Store(subdomain, db)
    return db, nil
}

// Gin 中间件示例
func TenantRouter() gin.HandlerFunc {
    return func(c *gin.Context) {
        host := c.Request.Host // 或解析 subdomain: strings.Split(host, ".")[0]
        subdomain := strings.Split(host, ".")[0]

        db, err := getTenantDB(subdomain)
        if err != nil {
            c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "invalid tenant"})
            return
        }

        // 注入 Context，供 Handler 使用
        c.Set("tenant_db", db)
        c.Next()
    }
}

// 在 Handler 中使用
func UserListHandler(c *gin.Context) {
    db, _ := c.Get("tenant_db")
    rows, err := db.(*sql.DB).Query("SELECT id, name FROM users LIMIT 10")
    // ... 处理逻辑
}

关键注意事项与最佳实践

• ✅ 连接池复用而非连接复用：每个租户应拥有独立的 *sql.DB（即连接池），而非每次请求新建连接。sync.Map 缓存的是连接池，不是单个连接。
• ✅ 连接池参数调优：租户连接池的 MaxOpenConns 应根据租户负载预估，避免耗尽数据库连接数；主库连接池应保持较小（如 10–20），因其只承担元数据查询。
• ⚠️ 租户标识安全性：切勿直接信任用户输入的 subdomain/tenant ID。务必在查询主库前进行白名单校验或正则过滤（如 ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$）。
• ⚠️ 连接泄漏防护：sync.Map 不自动清理失效连接池。建议添加后台 goroutine 定期调用 db.Ping() 检测健康状态，并对失败池执行 db.Close() 后从缓存删除。
• ? 凭证安全：租户数据库密码绝不可明文存于主库。应使用 HashiCorp Vault、AWS Secrets Manager 或加密字段（如 pgp_sym_encrypt）存储。
• ? 扩展性考量：当租户规模超千级时，可引入 LRU 缓存（如 lru.Cache）替代 sync.Map，并设置 TTL 防止内存无限增长；或采用连接池分片（sharding）机制。

该方案兼顾开发简洁性与生产可靠性，已在多个高并发 SaaS 服务中验证。核心思想是：将租户发现（主库）、连接池生命周期管理（缓存）、请求上下文绑定（中间件）解耦，各司其职，避免全局状态污染与资源争用。