Router
The SPQR Router configuration can be specified in JSON, TOML, or YAML format. The configuration file passing as a parameter to run command:
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 |
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/router.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. On object with usr and password fields | An AuthBackendCfg object |
pool_default | Indicates if the connection should use the default pool settings. | true or false |
connection_limit | The maximum number of connections allowed to the backend. | Any integer value |
connection_retries | The number of retries for a failed connection attempt. | Any integer value |
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 |
query_routing.default_route_behaviour | Whether to explicitly block multishard queries. | BLOCK, ALLOW |
with_jaeger | Whether to integrate with Jaeger for tracing. | true, false |
world_shard_fallback | Whether to enable fallback to world shard. | 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 |
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 |
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 |
Router
The SPQR Router configuration can be specified in JSON, TOML, or YAML format. The configuration file passing as a parameter to run command:
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 |
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/router.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. On object with usr and password fields | An AuthBackendCfg object |
pool_default | Indicates if the connection should use the default pool settings. | true or false |
connection_limit | The maximum number of connections allowed to the backend. | Any integer value |
connection_retries | The number of retries for a failed connection attempt. | Any integer value |
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 |
query_routing.default_route_behaviour | Whether to explicitly block multishard queries. | BLOCK, ALLOW |
with_jaeger | Whether to integrate with Jaeger for tracing. | true, false |
world_shard_fallback | Whether to enable fallback to world shard. | 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 |
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 |
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 |