跳转到主要内容

数据库插件

Lynx 并没有一个通用的 lynx.db 配置块或 runtime 插件。SQL 能力始终通过具体插件 lynx-mysql、lynx-pgsql、lynx-mssql 启用，而连接池、重连、健康检查、provider 这类共享行为来自 lynx-sql-sdk。

Runtime Matrix（运行时矩阵）​

数据库配置前缀Runtime 插件本仓库模板覆盖说明
MySQLlynx.mysqlmysql.client没有 lynx-mysql/conf/example_config.yml请以 MySQL 插件的 README / proto 和可运行的 lynx-layout bootstrap 示例为准，本页不会虚构缺失的 MySQL 字段。
PostgreSQLlynx.pgsqlpgsql.clientlynx-pgsql/conf/example_config.yml共享 SQL SDK 的连接池与重连行为。
MSSQLlynx.mssqlmssql.clientlynx-mssql/conf/example_config.yml额外提供结构化的 server_config DSN 构造块。

lynx-sql-sdk 自身并不拥有 lynx.sql 这类配置树。YAML 永远归属于具体数据库插件。

PostgreSQL Template Field Guide（PostgreSQL 模板字段说明）​

以下说明严格对应 lynx-pgsql/conf/example_config.yml。

字段作用什么时候启用默认值 / 交互关系常见误配
driverPostgreSQL 驱动名。始终需要。默认是 pgx。继续沿用旧示例里的 postgres。这个插件不是这么配的。
source完整 PostgreSQL DSN。始终需要。必填。sslmode、connect_timeout、statement_timeout 这类选项应放在 DSN 里，而不是拆成同级 YAML 键。把 DSN 参数拆成插件并不识别的顶级 YAML 字段。
min_conn启动预热目标和初始空闲连接上限来源。需要预热空闲连接时。默认 0。当它大于 0 时，插件会开启预热，并先把 idle cap 设为这个值。把它设得大于 max_conn；实现里会把预热数和 idle cap 都裁剪到 max_conn。
max_conndatabase/sql 最大打开连接数。始终需要。默认 25。这是 SQL SDK 连接池的真实上限。多副本服务里只盯单实例值，结果总连接数冲爆数据库 max_connections。
max_idle_conn显式空闲连接上限。需要让空闲容量不同于 min_conn 时。默认 0。一旦设置，它会覆盖由 min_conn 推导出的 idle cap；如果 min_conn 没配，它也会成为预热目标。误以为它是在 min_conn 基础上再追加。实际是替换 idle cap。
max_idle_time连接在池中允许保持空闲的最长时间。一般都应配置。默认 300s。更短会更快回收空闲连接。设得低于正常请求间隔，导致无意义的重建连接。
max_life_time单条连接的最大总生命周期。一般都应配置。默认 3600s。适合做周期性连接轮换和故障切换卫生。长生命周期服务里完全不设，随后把陈旧连接问题怪到驱动上。
ensure_alive_before_handoutSQL SDK 在 GetDB() / GetDBWithContext() 返回连接池前先做一次存活检查。只有你明确想跳过这个 ping/reconnect 护栏时才改。省略时默认 true。它虽然不在 pgsql.proto 里，但能在同一个 lynx.pgsql 前缀下被 SQL SDK 接收。设成 false 后又在业务里长期缓存坏掉的连接池。
prometheus开启插件本地 Prometheus 指标。你会把 pgsql.GetMetricsGatherer() 合并进 /metrics 时。不写这个块就不开启。没配块或没暴露 gatherer，却期待指标自动出现。
prometheus.namespace指标命名空间前缀。只有 prometheus 存在时。默认空。改了命名空间，却忘了同步更新仪表盘查询。
prometheus.subsystem指标子系统名。只有 prometheus 存在时。默认空。复制别的插件 subsystem，结果把指标族混在一起。
prometheus.labels给所有导出指标附加额外标签。只有 prometheus 存在时。默认空 map。塞进请求 ID、用户 ID 这类高基数字段。

关键交互：如果 min_conn 和 max_idle_conn 同时配置，max_idle_conn 会接管 idle cap，而 min_conn 仍然保留为预热目标，除非它本身又被 max_conn 裁剪掉。

MSSQL Template Field Guide（MSSQL 模板字段说明）​

以下说明严格对应 lynx-mssql/conf/example_config.yml。

Root fields（根字段）​

字段作用什么时候启用默认值 / 交互关系常见误配
driverSQL Server 驱动名。始终需要。默认 mssql。随意替换驱动名，期待插件自动适配。
source完整 SQL Server DSN。需要完全掌控认证和 DSN 参数时。默认空。在当前实现里，只有省略 server_config 时，source 才能真正成为权威 DSN。同时保留 server_config 和 source，却以为 source 一定优先；当前 base runtime 依然会从 server_config 构造 DSN。
min_conn模板里声明的最小连接数。目前只能当作意图或指标值。默认 5。当前 MSSQL 转换逻辑不会用它去预热 SQL SDK 连接池，也不会据此设置空闲连接数。误以为它会预热连接池或强制维持最小连接数。
max_conndatabase/sql 最大打开连接数。始终需要。默认 20。这是 SQL SDK 连接池的真实上限。只调 server_config.max_pool_size，却忘了真正控制 Go 连接池的是 max_conn。
max_idle_conn显式空闲连接上限。需要指定具体 idle cap 时。默认 0。省略时，运行时会按 max_conn / 5 推导一个 idle cap，最小为 1。留空后又期待空闲连接数自动等于 min_conn。
max_idle_time连接在池中允许保持空闲的最长时间。一般都应配置。默认 300s。设得过低，在突发流量场景里制造无意义的连接抖动。
max_life_time单条连接的最大总生命周期。一般都应配置。默认 3600s。长生命周期服务背后有 failover / 负载均衡变化，却完全不设轮换。
server_config结构化 SQL Server DSN 构造块。不想手写 source 时。默认值见下表。它不会创建第二个 runtime 插件。把它当成 source 的补充，而不是另一种 DSN 来源。

server_config fields（server_config 字段）​

字段作用什么时候启用默认值 / 交互关系常见误配
server_config.instance_nameSQL Server 主机名或实例监听地址。用结构化字段自动构造 DSN 时。默认 "localhost"。生产环境忘了改模板默认值，结果连到了错误服务器。
server_config.portSQL Server TCP 端口。自动构造 DSN 时。默认 1433。命名实例或托管实例用了非默认端口，却仍然保留模板值。
server_config.database自动生成 DSN 中的默认数据库名。自动构造 DSN 时。默认 "master"。业务一直打到 master，只是因为模板没改。
server_config.username期望使用的 SQL 认证用户名。只有你准备走 SQL Auth 且愿意显式掌控 DSN 时。默认空。当前 buildDSN 实现并不会把它拼进自动生成的 DSN。只在这里填用户名，却以为自动构造出的 DSN 已经带上了凭据。
server_config.password期望使用的 SQL 认证密码。只有你准备走 SQL Auth 且愿意显式掌控 DSN 时。默认空。和 username 一样，当前自动 DSN 构造不会拼接它。留空 source，却以为这个密码已经生效。
server_config.encrypt在自动生成的 DSN 中写入 encrypt=true/false。自动构造 DSN 时始终生效。默认 false。Azure / 托管 SQL 环境明明要求 TLS，却还保留 false。
server_config.trust_server_certificate在自动生成的 DSN 中写入 trustservercertificate=true。只有你明确要跳过严格证书校验时。默认 false。实际通常只有在开启加密时才有意义。在生产环境把它当成正式证书信任方案。
server_config.connection_timeout自动生成 DSN 中的连接超时，单位秒。自动构造 DSN 时。默认 30。把它和查询超时、SQL SDK 生命周期混为一谈。
server_config.command_timeout自动生成 DSN 中的命令超时，单位秒。自动构造 DSN 时。默认 30。误以为它会改变 Go 连接池大小。
server_config.application_name自动生成 DSN 中的应用标识。自动构造 DSN 时。默认 "Lynx-MSSQL-Plugin"。没改成服务专属名字，导致 SQL Server 侧排障价值很低。
server_config.workstation_id期望的工作站标识。只有未来 DSN 构造开始实际使用它时。默认空。当前 DSN 构造器不会拼接这个字段。以为它现在就会出现在 SQL Server 连接元数据里。
server_config.connection_pooling是否把 MSSQL 自带的连接池提示写入自动生成的 DSN。自动构造 DSN 时。默认 true。它不会关闭 SQL SDK 管理的外层 database/sql 连接池。设成 false 后，以为 Lynx 就不再使用 Go 连接池。
server_config.max_pool_sizeMSSQL DSN 级别的连接池上限提示。只有 connection_pooling: true 且自动构造 DSN 时。默认 20。真正的 Go 连接池上限仍由根级 max_conn 控制。只调这个字段，不调根级 max_conn。
server_config.min_pool_sizeMSSQL DSN 级别的连接池下限提示。只有 connection_pooling: true 且自动构造 DSN 时。默认 5。它不会替代根级 min_conn，而且当前根级 min_conn 也不会触发预热。误以为它能保证 SQL SDK 连接池被预热。
server_config.pool_blocking_timeoutMSSQL DSN 级别的池阻塞超时提示。只有 connection_pooling: true 且自动构造 DSN 时。默认 30。误以为它会改变 SQL SDK 的重试或重连逻辑。
server_config.pool_lifetime_timeoutMSSQL DSN 级别的池生命周期提示。只有 connection_pooling: true 且自动构造 DSN 时。默认 3600。根级 max_life_time 依然控制 Go database/sql 连接池。没分清哪个 lifetime 属于哪一层。

PostgreSQL Complete YAML Example（PostgreSQL 完整 YAML 示例）​

下面这个示例展开了 lynx-pgsql/conf/example_config.yml 中出现的全部字段，以及模板注释里顺带指向的可选 SQL SDK / Prometheus 键。

lynx:
  pgsql:
    driver: "pgx" # 这个插件使用的 PostgreSQL 驱动名。
    source: "postgres://app_user:app_password@127.0.0.1:5432/orders?sslmode=disable&connect_timeout=10" # 完整 DSN，包含 SSL 和超时参数。
    min_conn: 10 # 尽可能在启动时预热这么多空闲连接。
    max_conn: 50 # database/sql 最大打开连接数上限。
    max_idle_conn: 12 # 显式空闲连接上限；会覆盖由 min_conn 推导出的 idle cap。
    max_idle_time: "30s" # 空闲超过这个时间的连接会被关闭。
    max_life_time: "300s" # 连接总生命周期超过这个时间后会被轮换。
    ensure_alive_before_handout: true # 在把连接池交给调用方前先做 ping/reconnect。
    prometheus:
      namespace: "lynx" # 指标命名空间前缀。
      subsystem: "pgsql" # 指标子系统前缀。
      labels:
        environment: "dev" # 附加到所有导出指标上的静态标签。
        service: "orders-api" # 标签要保持低基数。

PostgreSQL Minimum Viable YAML Example（PostgreSQL 最小可用 YAML 示例）​

对 PostgreSQL 来说，真正必填的 YAML 键只有 DSN。driver 会回落到插件默认值 pgx。

lynx:
  pgsql:
    source: "postgres://app_user:app_password@127.0.0.1:5432/orders?sslmode=disable" # PostgreSQL runtime 插件必需的 DSN。

MSSQL Complete YAML Example（MSSQL 完整 YAML 示例）​

下面这个示例展开了 lynx-mssql/conf/example_config.yml 中出现的全部字段。

lynx:
  mssql:
    driver: "mssql" # 这个插件使用的 SQL Server 驱动名。
    source: "" # 如果你希望 runtime 从 server_config 构造 DSN，就保持为空。
    min_conn: 5 # 模板里的最小连接数；当前 runtime 不会据此预热 Go 连接池。
    max_conn: 20 # database/sql 最大打开连接数上限。
    max_idle_conn: 10 # Go 连接池的显式空闲连接上限。
    max_idle_time: "300s" # 空闲五分钟后关闭连接。
    max_life_time: "3600s" # 连接总生命周期一小时后轮换。
    server_config:
      instance_name: "sqlserver.internal" # 用于构造 DSN 的主机名或实例监听地址。
      port: 1433 # SQL Server TCP 端口。
      database: "orders" # 默认数据库名。
      username: "sa" # 文档里存在的凭据字段；当前 buildDSN 并不会自动拼进去。
      password: "change_me" # 和 username 一样有这个 caveat。
      encrypt: true # 托管 / Azure 风格部署通常需要在生成的 DSN 中开启 TLS。
      trust_server_certificate: false # 生产环境应保持严格证书校验。
      connection_timeout: 30 # 连接超时，单位秒。
      command_timeout: 30 # 命令超时，单位秒。
      application_name: "orders-api" # 会出现在 SQL Server 诊断信息里的应用名。
      workstation_id: "orders-api-01" # 文档里的工作站标识；当前 buildDSN 不会自动拼进去。
      connection_pooling: true # 在生成的 DSN 里附加 SQL Server 连接池提示。
      max_pool_size: 20 # SQL Server DSN 级连接池提示；Go 连接池上限仍由 max_conn 控制。
      min_pool_size: 5 # SQL Server DSN 级连接池提示；不会预热外层 Go 连接池。
      pool_blocking_timeout: 30 # 池阻塞超时提示，单位秒。
      pool_lifetime_timeout: 3600 # 池生命周期提示，单位秒。

MSSQL Minimum Viable YAML Example（MSSQL 最小可用 YAML 示例）​

对 MSSQL 来说，最短且显式的路径是一条 source DSN。runtime 默认值里已经预置了 driver: "mssql"。

lynx:
  mssql:
    source: "sqlserver://sa:change_me@127.0.0.1:1433?database=orders&encrypt=disable" # 不使用 server_config 时的最小 DSN 路径。

MySQL Status In This Repo（MySQL 在本仓库中的状态）​

  • lynx-mysql 是真实存在的具体插件，配置前缀是 lynx.mysql。
  • 但本仓库当前 没有 lynx-mysql/conf/example_config.yml。
  • 因为没有官方 MySQL 模板文件可镜像，本页不会虚构一张 MySQL 字段表。
  • 如果要看可运行示例，请用 lynx-layout 的 bootstrap 配置；如果要看权威字段定义，请看 lynx-mysql/conf/mysql.proto 或 MySQL 插件 README。