Router - SPQR

The SPQR Router configuration can be specified in JSON, TOML, or YAML format. The configuration file passing as a parameter to run command:

spqr-router run --config ./examples/router.yaml

Refer to the pkg/config/router.go file for the most up-to-date configuration options.

General Settings

Setting	Description	Possible Values
`log_level`	The level of logging output.	`debug`, `info`, `warning`, `error`, `fatal`
`pretty_logging`	Whether to write logs in an colorized, human-friendly format.	`true`, `false`
`daemonize`	Whether to run the router as a daemon.	`true`, `false`
`reuse_port`	Whether to create a socket with SO_REUSEPORT and SO_REUSEADDR options.	`true`, `false`
`use_systemd_notifier`	Whether to use systemd notifier.	`true`, `false`
`systemd_notifier_debug`	Whether to run systemd notifier in debug mode.	`true`, `false`
`with_coordinator`	Whether to run the router in a special coordinator mode.	`true`, `false`
`enable_role_system`	Whether to enable the role-based access control system.	`true`, `false`
`roles_file`	The file path to the roles configuration.	Any valid file path
`identity_range_size`	Size of range identifiers of sequence which router gets from coordinator.	int > 1

Network Settings

Setting	Description	Possible Values
`host`	The host address the router listens on.	Any valid hostname
`router_port`	The port number for the router.	Any valid port number
`router_ro_port`	The port number for the read-only queries router.	Any valid port number
`admin_console_port`	The port number for the admin console.	Any valid port number
`grpc_api_port`	The port number for the gRPC API.	Any valid port number

Frontend Rules

Frontend rule is a specification of how clients connect to the router. Refer to the FrontendRule struct in the pkg/config/rules.go file for the most up-to-date configuration options.

Setting	Description	Possible Values
`db`	The database name to which the rule applies	Any valid database name
`usr`	The user name for which the rule is applicable	Any valid username
`search_path`	The search path used for the database connection	Any valid search path
`auth_rule`	See General Auth Settings	Object of `AuthCfg`
`pool_mode`	The mode of connection pooling used	`SESSION`, `TRANSACTION`
`pool_discard`	Determines if `DISCARD ALL` will be issued after transaction end	`true`, `false`
`pool_rollback`	Specifies whether to execute a rollback on connections returned to the pool	`true`, `false`
`pool_prepared_statement`	Indicates if prepared statements should be pooled	`true`, `false`
`pool_default`	If set to true, uses the default pool settings defined elsewhere	`true`, `false`

Backend Rules

Backend Rule is a global setting that determines how the router connects to every shard. Refer to the BackendRule struct in the pkg/config/rules.go and pkg/config/auth_backend.go file for the most up-to-date configuration options.

Setting	Description	Possible Values
`db`	The database name to connect to.	Any valid database name
`usr`	The username for database authentication.	Any valid username
`auth_rules`	A map of authentication rules for backend connections.	Map of string keys to `AuthBackendCfg` objects
`auth_rule`	The default auth rule. An object with `usr` and `password` fields	An `AuthBackendCfg` object
`pool_default`	Indicates if the connection should use the default pool settings.	`true`, `false`
`connection_limit`	The maximum number of connections allowed to the backend (host shard).	Any integer value
`connection_retries`	The number of retries for a failed connection attempt.	Any integer value
`connection_timeout`	The timeout duration for establishing connections to the backend.	Any valid duration (e.g., `30s`, `1m`)
`keep_alive`	The duration for keeping connections alive.	Any valid duration (e.g., `30s`, `1m`)
`tcp_user_timeout`	The TCP user timeout for backend connections.	Any valid duration (e.g., `30s`, `1m`)

Shards

Map of string to Shard objects. Refer to the Shard struct in the pkg/config/router.go file for the most up-to-date configuration options.

Setting	Description	Possible Values
`hosts`	A list of host addresses for the shard.	Array of host addresses
`type`	Use `DATA` always	`DATA`, `WORLD`
`tls`	See auth.mdx	Object of `TLSConfig`

Statistics Settings

Setting	Description	Possible Values
`time_quantiles`	The list of time quantiles to show query time statistics. When empty, no statistics is collected	Array of floats. For example, `[0.8]`

Feature Flags

Setting	Description	Possible Values
`maintain_params`	Whether to maintain parameters flag.	`true`, `false`
`with_jaeger`	Whether to integrate with Jaeger for tracing.	`true`, `false`
`world_shard_fallback`	Whether to enable fallback to world shard.	`true`, `false`

Query Routing Settings

Query routing settings are nested under the query_routing configuration key and control how queries are routed across shards. Refer to the QRouter struct in the pkg/config/router.go file for the most up-to-date configuration options.

Setting	Description	Possible Values
`query_routing.default_route_behaviour`	Whether to explicitly block multishard queries.	`BLOCK`, `ALLOW`
`query_routing.default_target_session_attrs`	Default target_session_attrs for connections.	`read-write`, `smart-read-write`, `read-only`, `prefer-standby`, `any`
`query_routing.enhanced_multishard_processing`	Whether to enable enhanced processing for multishard queries.	`true`, `false`
`query_routing.always_check_rules`	Whether to always check the routing rules for every query. This only makes sense in a single-shard deployment.	`true`, `false`
`query_routing.auto_route_ro_on_standby`	Whether to automatically route read-only queries to standby servers. Currently only supported for single-shard topology.	`true`, `false`

Mode Settings

Setting	Description	Possible Values
`pool_mode`	Defines the pool modes.	`SESSION`, `TRANSACTION`
`shard_type`	Defines the shard types.	`DATA`, `WORLD`
`router_mode`	TL;DR Use `PROXY` always. Defines the router modes. Local mode acts like a connection pooler, Proxy mode acts like a query router in sharded installation.	`LOCAL`, `PROXY`

Debug Settings

Setting	Description	Possible Values
`show_notice_messages`	Whether to show notice messages.	`true`, `false`
`notice_message_format`	Format template for notice messages. Supported placeholders: `{shard}`, `{host}`, `{hostname}`, `{port}`, `{user}`, `{db}`, `{pid}`, `{az}`, `{id}`, `{tx_status}`, `{tx_served}`. Default: `"{shard}@{host}"`. Examples: `"{shard}"`, `"{host}"`, `"{shard}@{hostname}:{port}"`, `"{shard}@{host} (user={user}, db={db})"`	Any valid template string
`pid_file_name`	The file name to store the process ID.	Any valid filepath
`log_file_name`	The file name for logging output.	Any valid filepath
`pgproto_debug`	PostgreSQL protocol debug flag.	`true`, `false`

DBpool Settings

Setting	Description	Possible Values
`dbpool_cache_ttl`	Time-to-live for database pool cache entries	Any valid duration (e.g., `30s`, `1m`)
`dbpool_check_interval`	Interval for checking database pool health and cleanup	Any valid duration (e.g., `30s`, `1m`)
`dbpool_dead_check_interval`	Background health check interval for dead hosts (enables faster recovery)	Any valid duration (e.g., `15s`, `30s`) or `0` to disable

QDB Settings

Setting	Description	Possible Values
`use_init_sql`	Whether to execute commands from Init SQL file	`true`, `false`
`use_coordinator_init`	Whether to execute commands from Init SQL file on Router	`true`, `false`
`init_sql`	Path to SQL file that router will execute before the start	Any valid file path
`exit_on_init_sql`	Whether to exit if the parsing of the SQL file fails	`true`, `false`
`memqdb_backup_path`	MemQDB backup state path. MemQDB’s state restored if a file backup exists during the router startup. If there is no file, init.sql will be used	Any valid file path

Documentation

​General Settings

​Network Settings

​Frontend Rules

​Backend Rules

​Shards

​Statistics Settings

​Feature Flags

​Query Routing Settings

​Mode Settings

​Debug Settings

​DBpool Settings

​QDB Settings