Database Plugin

Lynx does not expose one generic lynx.db config block or runtime plugin. SQL is enabled through the concrete plugins lynx-mysql, lynx-pgsql, and lynx-mssql, while shared pool, reconnect, health-check, and provider behavior comes from lynx-sql-sdk.

Runtime Matrix

Database	Config prefix	Runtime plugin	Template coverage in this repo	Notes
MySQL	lynx.mysql	mysql.client	No lynx-mysql/conf/example_config.yml	Use the MySQL plugin README / proto plus the runnable lynx-layout bootstrap example. This page does not invent missing MySQL keys.
PostgreSQL	lynx.pgsql	pgsql.client	lynx-pgsql/conf/example_config.yml	Shares SQL SDK pool and reconnect behavior.
MSSQL	lynx.mssql	mssql.client	lynx-mssql/conf/example_config.yml	Adds a server_config block for structured DSN generation.

lynx-sql-sdk itself does not own a lynx.sql subtree. YAML always belongs to a concrete database plugin.

PostgreSQL Template Field Guide

The field notes below are scoped to lynx-pgsql/conf/example_config.yml.

Field	What it controls	Enable when	Default / interaction	Common misconfig
driver	PostgreSQL driver name.	Always.	Default is pgx.	Using postgres from older examples is wrong for this plugin.
source	Full PostgreSQL DSN.	Always.	Required. DSN options such as sslmode, connect_timeout, and statement_timeout live inside this string, not as sibling YAML keys.	Splitting DSN options into fake top-level YAML keys.
min_conn	Startup warmup target and initial idle-cap source.	When you want prewarmed idle connections.	Default 0. When > 0, the plugin enables warmup and initially sets idle cap to this value.	Setting it higher than max_conn; the implementation clips warmup and idle cap down to max_conn.
max_conn	Maximum open database/sql connections.	Always.	Default 25. This is the real SQL SDK pool ceiling.	Sizing it above the database's max_connections budget across all service replicas.
max_idle_conn	Explicit idle connection cap.	When idle capacity should differ from min_conn.	Default 0. If set, it overrides the idle cap derived from min_conn. If min_conn was omitted, it also becomes the warmup target.	Assuming it adds to min_conn; it replaces the idle cap instead.
max_idle_time	Maximum idle lifetime for pooled connections.	Usually always.	Default 300s. Shorter values recycle idle connections faster.	Setting it below normal request gaps and causing avoidable reconnect churn.
max_life_time	Maximum total lifetime for pooled connections.	Usually always.	Default 3600s. Useful for periodic pool recycling and failover hygiene.	Forgetting it in long-lived services and then blaming the driver for stale pools.
ensure_alive_before_handout	SQL SDK liveness check before GetDB() / GetDBWithContext() hands out the pool.	Only when you intentionally want to skip the pre-handoff ping/reconnect guard.	Default true when omitted. This key is accepted at the same lynx.pgsql prefix even though it is not part of pgsql.proto.	Setting false and then caching a broken pool in business code.
prometheus	Turns on plugin-local Prometheus metrics.	When you will merge pgsql.GetMetricsGatherer() into your /metrics endpoint.	Disabled when the block is absent.	Expecting metrics to appear without adding the block or without exposing the gatherer.
prometheus.namespace	Metric namespace prefix.	Only when prometheus exists.	Default empty.	Changing it without updating dashboard queries.
prometheus.subsystem	Metric subsystem name.	Only when prometheus exists.	Default empty.	Copying a subsystem from another plugin and mixing metrics families.
prometheus.labels	Extra labels attached to every exported metric.	Only when prometheus exists.	Default empty map.	Adding high-cardinality labels such as request IDs or user IDs.

Important interaction: if both min_conn and max_idle_conn are set, max_idle_conn wins for idle-cap sizing, while min_conn still remains the warmup target unless it also had to be clipped down to max_conn.

MSSQL Template Field Guide

The field notes below are scoped to lynx-mssql/conf/example_config.yml.

Root fields

Field	What it controls	Enable when	Default / interaction	Common misconfig
driver	SQL Server driver name.	Always.	Default mssql.	Swapping in a different driver name and expecting the plugin to adapt automatically.
source	Full SQL Server DSN.	When you want full control over authentication and DSN flags.	Default empty. In the current implementation, source is only authoritative when server_config is omitted.	Keeping a populated server_config block next to source and assuming source still wins; the base runtime DSN is still built from server_config when that block exists.
min_conn	Documented minimum connection count.	Only as an intent / metric value today.	Default 5. The current MSSQL conversion does not use it to warm the SQL SDK pool or size idle connections.	Assuming it prewarms or hard-enforces a minimum pool size.
max_conn	Maximum open database/sql connections.	Always.	Default 20. This is the real SQL SDK pool ceiling.	Tuning only server_config.max_pool_size and forgetting that max_conn still owns the Go pool.
max_idle_conn	Explicit idle connection cap.	When you want a specific idle cap.	Default 0. If omitted, runtime conversion derives an idle cap from max_conn / 5 with a minimum of 1.	Leaving it unset and then expecting idle capacity to match min_conn.
max_idle_time	Maximum idle lifetime for pooled connections.	Usually always.	Default 300s.	Setting it too low and forcing needless churn under bursty traffic.
max_life_time	Maximum total lifetime for pooled connections.	Usually always.	Default 3600s.	Forgetting it in long-lived services that sit behind failover or load-balancing changes.
server_config	Structured SQL Server DSN builder.	When you do not want to handwrite source.	Defaults come from the block below. It does not create a second runtime plugin.	Treating it as additive to source instead of an alternative source of DSN fields.

server_config fields

Field	What it controls	Enable when	Default / interaction	Common misconfig
server_config.instance_name	SQL Server host or instance listener.	When auto-building DSN from structured fields.	Default "localhost".	Leaving a local default in production and accidentally connecting to the wrong server.
server_config.port	SQL Server TCP port.	When auto-building DSN.	Default 1433.	Forgetting non-default ports on named or managed instances.
server_config.database	Default database name inside the generated DSN.	When auto-building DSN.	Default "master".	Pointing business code at master because the template value was never changed.
server_config.username	Intended SQL authentication username.	Only if you rely on SQL auth and also choose a fully explicit DSN strategy.	Default empty. The current buildDSN implementation does not append this field to the generated DSN.	Setting it here and assuming auto-built DSN will include credentials.
server_config.password	Intended SQL authentication password.	Only if you rely on SQL auth and also choose a fully explicit DSN strategy.	Default empty. Like username, it is not appended by the current DSN builder.	Leaving source empty and expecting this password to be used.
server_config.encrypt	Adds encrypt=true/false to the generated DSN.	Always when auto-building DSN.	Default false.	Leaving it false for Azure / managed SQL endpoints that require TLS.
server_config.trust_server_certificate	Adds trustservercertificate=true to the generated DSN.	Only when you intentionally skip strict cert validation.	Default false. In practice it matters only when encryption is on.	Enabling it in production as a substitute for real certificate trust setup.
server_config.connection_timeout	Generated DSN connection timeout in seconds.	When auto-building DSN.	Default 30.	Confusing it with query timeout or with SQL SDK pool lifetimes.
server_config.command_timeout	Generated DSN command timeout in seconds.	When auto-building DSN.	Default 30.	Expecting it to resize the Go connection pool.
server_config.application_name	Generated DSN application identifier.	When auto-building DSN.	Default "Lynx-MSSQL-Plugin".	Forgetting to set a service-specific name and then losing observability value in SQL Server diagnostics.
server_config.workstation_id	Intended workstation identifier.	Only if future DSN generation starts honoring it.	Default empty. The current DSN builder does not append it.	Expecting this field to appear in SQL Server connection metadata today.
server_config.connection_pooling	Whether MSSQL-specific pool hints are added to the generated DSN.	Only when auto-building DSN.	Default true. This does not disable the outer database/sql pool managed by SQL SDK.	Setting it false and expecting Lynx to run without a Go connection pool.
server_config.max_pool_size	MSSQL-specific DSN pool hint.	Only when connection_pooling: true and auto-building DSN.	Default 20. The actual Go pool ceiling still comes from root max_conn.	Tuning only this field and ignoring root max_conn.
server_config.min_pool_size	MSSQL-specific DSN pool hint.	Only when connection_pooling: true and auto-building DSN.	Default 5. It does not replace root min_conn, and current root min_conn is not used for warmup anyway.	Assuming it guarantees a warmed SQL SDK pool.
server_config.pool_blocking_timeout	MSSQL-specific DSN pool-blocking hint.	Only when connection_pooling: true and auto-building DSN.	Default 30.	Expecting it to change SQL SDK retry or reconnect behavior.
server_config.pool_lifetime_timeout	MSSQL-specific DSN pool lifetime hint.	Only when connection_pooling: true and auto-building DSN.	Default 3600. Root max_life_time still governs the Go database/sql pool.	Forgetting which lifetime belongs to which layer.

PostgreSQL Complete YAML Example

This example expands every field that appears in lynx-pgsql/conf/example_config.yml, plus the optional SQL SDK / Prometheus keys that the template comments point to.

lynx:
  pgsql:
    driver: "pgx" # PostgreSQL driver used by this plugin.
    source: "postgres://app_user:app_password@127.0.0.1:5432/orders?sslmode=disable&connect_timeout=10" # Full DSN, including SSL and timeout flags.
    min_conn: 10 # Warm this many idle connections on startup when possible.
    max_conn: 50 # Hard cap for open database/sql connections.
    max_idle_conn: 12 # Explicit idle cap; overrides the idle cap derived from min_conn.
    max_idle_time: "30s" # Close idle connections that stay unused longer than this.
    max_life_time: "300s" # Recycle long-lived connections after this total lifetime.
    ensure_alive_before_handout: true # Ping/reconnect before handing the pool to callers.
    prometheus:
      namespace: "lynx" # Metric namespace prefix.
      subsystem: "pgsql" # Metric subsystem prefix.
      labels:
        environment: "dev" # Extra static labels for all exported metrics.
        service: "orders-api" # Keep labels low-cardinality.

PostgreSQL Minimum Viable YAML Example

For PostgreSQL, the only truly required YAML key is the DSN. driver falls back to the plugin default pgx.

lynx:
  pgsql:
    source: "postgres://app_user:app_password@127.0.0.1:5432/orders?sslmode=disable" # Required DSN for the PostgreSQL runtime plugin.

MSSQL Complete YAML Example

This example expands every field that appears in lynx-mssql/conf/example_config.yml.

lynx:
  mssql:
    driver: "mssql" # SQL Server driver used by this plugin.
    source: "" # Leave empty when you want the runtime to build the DSN from server_config.
    min_conn: 5 # Documented minimum; current runtime does not warm the Go pool from this value.
    max_conn: 20 # Hard cap for open database/sql connections.
    max_idle_conn: 10 # Explicit idle connection cap for the Go pool.
    max_idle_time: "300s" # Close idle connections after five minutes.
    max_life_time: "3600s" # Recycle long-lived connections after one hour.
    server_config:
      instance_name: "sqlserver.internal" # Host or instance listener used for DSN generation.
      port: 1433 # SQL Server TCP port.
      database: "orders" # Default database name.
      username: "sa" # Documented credential field; current buildDSN does not append it automatically.
      password: "change_me" # Same caveat as username.
      encrypt: true # Enable TLS in the generated DSN for managed / Azure-style deployments.
      trust_server_certificate: false # Keep strict certificate validation in production.
      connection_timeout: 30 # Connection timeout in seconds.
      command_timeout: 30 # Command timeout in seconds.
      application_name: "orders-api" # Application name visible in SQL Server diagnostics.
      workstation_id: "orders-api-01" # Documented workstation identifier; current buildDSN does not append it automatically.
      connection_pooling: true # Add SQL Server pooling hints to the generated DSN.
      max_pool_size: 20 # SQL Server DSN pool hint; Go pool ceiling still comes from max_conn.
      min_pool_size: 5 # SQL Server DSN pool hint; it does not warm the outer Go pool.
      pool_blocking_timeout: 30 # Pool-blocking timeout hint in seconds.
      pool_lifetime_timeout: 3600 # Pool lifetime hint in seconds.

MSSQL Minimum Viable YAML Example

For MSSQL, the shortest explicit path is a single source DSN. The runtime default already seeds driver: "mssql".

lynx:
  mssql:
    source: "sqlserver://sa:change_me@127.0.0.1:1433?database=orders&encrypt=disable" # Minimal DSN path when you are not using server_config.

MySQL Status In This Repo

• lynx-mysql is a real concrete plugin with config prefix lynx.mysql.
• This repo currently does not ship lynx-mysql/conf/example_config.yml.
• Because there is no official MySQL template file to mirror here, this page does not invent a MySQL field matrix.
• For a runnable MySQL example, use the lynx-layout bootstrap config. For authoritative schema details, use lynx-mysql/conf/mysql.proto or the MySQL plugin README.

Related Pages

• SQL SDK
• Layout
• Plugin Usage Guide