Admin Cluster Variables

ProxySQL Cluster is managed through a set of specialized variables within the Admin module. Because they belong to the Admin module, any changes to these variables must be activated using the standard Admin module commands.

ℹInfo

Critical Note: Cluster variables are part of the Admin variables group. Moving them between layers (Memory, Disk, and Runtime) is performed using the LOAD ADMIN VARIABLES TO RUNTIME and SAVE ADMIN VARIABLES TO DISK commands.

inter-node Credentials

In order for ProxySQL Cluster to work, instances need to connect to each other to perform health checks and pull configuration updates.

Variable Name	Default Value	Description
admin-cluster_username	(empty)	Username for inter-node communication.
admin-cluster_password	(empty)	Password for inter-node communication.

`admin-cluster_username`

`admin-cluster_password`

These credentials are used by the current node to authenticate against other ProxySQL nodes in the cluster. Requirement: These same credentials must be present in the admin-admin_credentials list of every node in the cluster.

Checks & Intervals

Variable Name	Default Value	Description
admin-cluster_check_interval_ms	1000	Interval between checksum comparisons.
admin-cluster_check_status_frequency	10	Frequency of detailed status checks.

`admin-cluster_check_interval_ms`

Defines how often (in milliseconds) the cluster module compares configuration checksums with its peers.

`admin-cluster_check_status_frequency`

Defines after how many checksum checks a detailed status check (SHOW MYSQL STATUS) is performed on peers.

Synchronization Thresholds

These variables define the “grace period” before a local node decides to synchronize a module from a peer.

Variable	Default	Module Affected
`admin-cluster_mysql_servers_diffs_before_sync`	3	MySQL Servers & Hostgroups
`admin-cluster_mysql_users_diffs_before_sync`	3	MySQL Users
`admin-cluster_mysql_query_rules_diffs_before_sync`	3	MySQL Query Rules
`admin-cluster_mysql_variables_diffs_before_sync`	3	MySQL Global Variables
`admin-cluster_admin_variables_diffs_before_sync`	3	Admin Variables
`admin-cluster_proxysql_servers_diffs_before_sync`	3	ProxySQL Cluster Nodes
`admin-cluster_pgsql_servers_diffs_before_sync`	3	PostgreSQL Servers
`admin-cluster_pgsql_users_diffs_before_sync`	3	PostgreSQL Users
`admin-cluster_pgsql_query_rules_diffs_before_sync`	3	PostgreSQL Query Rules
`admin-cluster_pgsql_variables_diffs_before_sync`	3	PostgreSQL Global Variables

The matching PostgreSQL checksum gates are admin-checksum_pgsql_servers, admin-checksum_pgsql_users, admin-checksum_pgsql_query_rules, and admin-checksum_pgsql_variables. Disabling a checksum gate also forces that module’s runtime diff threshold to 0. A nonzero threshold counts consecutive checksum mismatches before ProxySQL pulls the module from a peer.

Configuration Persistence

Variable	Default	Description
`admin-cluster_<module>_save_to_disk`	true	Automatically persist synced data to local DISK.
`admin-cluster_pgsql_servers_save_to_disk`	true	Persist peer-pulled PostgreSQL servers.
`admin-cluster_pgsql_users_save_to_disk`	true	Persist peer-pulled PostgreSQL users.
`admin-cluster_pgsql_query_rules_save_to_disk`	true	Persist peer-pulled PostgreSQL query rules.
`admin-cluster_pgsql_variables_save_to_disk`	true	Persist peer-pulled PostgreSQL variables.

If enabled, ProxySQL will automatically execute a SAVE <MODULE> TO DISK after successfully fetching and loading a new configuration from a peer.

For PostgreSQL modules, a peer pull updates the corresponding runtime tables and in-memory module. With the module’s save flag enabled, the cluster path then performs the equivalent persistence step to the local disk database. With it disabled, the pulled state is runtime-only and can be lost at restart. Explicit operator commands remain unchanged: use LOAD PGSQL SERVERS|USERS|QUERY RULES|VARIABLES TO RUNTIME to promote local configuration and SAVE PGSQL SERVERS|USERS|QUERY RULES|VARIABLES TO DISK to persist runtime state.

MySQL Server Synchronization Algorithm

admin-cluster_mysql_servers_sync_algorithm defaults to 1: synchronize both runtime server state and mysql_servers_v2. Value 2 synchronizes only mysql_servers_v2; value 3 auto-selects 2 when ProxySQL starts with -M, otherwise 1. Changing the algorithm resets cluster checksums so the selected source is evaluated immediately.

Apply your changes: Remember to use the appropriate Admin Commands to activate and persist your cluster configuration.