Router

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.

Many of these settings can be overridden at runtime using routing hints.

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

Setting	Description	Possible Values	Overridable by Hint
query_routing.default_route_behaviour	Whether to explicitly block multishard queries. Can be overridden by the __spqr__default_route_behaviour hint.	BLOCK, ALLOW	Yes
query_routing.default_target_session_attrs	Default target_session_attrs for connections. Can be overridden by the __spqr__target_session_attrs hint.	read-write, smart-read-write, read-only, prefer-standby, any	Yes
query_routing.enhanced_multishard_processing	Whether to enable enhanced processing for multishard queries. Can be overridden by the __spqr__engine_v2 hint.	true, false	Yes
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	No
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	No

Transaction Settings

Setting	Description	Possible Values	Overridable by Hint
default_commit_strategy	Default commit strategy for distributed transactions. Can be overridden per session with the __spqr__commit_strategy hint. See Distributed Transactions for details.	best-effort, 1pc, 2pc	Yes

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	Overridable by Hint
show_notice_messages	Whether to show notice messages. Can be overridden by the __spqr__reply_notice hint.	true, false	Yes
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	No
pid_file_name	The file name to store the process ID.	Any valid filepath	No
log_file_name	The file name for logging output.	Any valid filepath	No
pgproto_debug	PostgreSQL protocol debug flag.	true, false	No

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