DuckDB Admin reference

Run these commands through ProxySQL Admin, normally MySQL protocol on port 6032. Do not send them to the DuckDB listeners.

Inspect configuration

DuckDB has eight duckdb-* variables in the standard ProxySQL variable tables:

-- Main: editable configuration
SELECT variable_name, variable_value FROM global_variables
WHERE variable_name LIKE 'duckdb-%' ORDER BY variable_name;

-- Runtime: settings currently in effect
SELECT variable_name, variable_value FROM runtime_global_variables
WHERE variable_name LIKE 'duckdb-%' ORDER BY variable_name;

-- Disk: saved configuration used at restart
SELECT variable_name, variable_value FROM disk.global_variables
WHERE variable_name LIKE 'duckdb-%' ORDER BY variable_name;

A fresh installation supplies defaults in Main. Edit Main to request a change; query Runtime to check what is running. Do not update Runtime directly.

Commands

These commands copy only duckdb-* rows. Other modules’ variables are unaffected.

SAVE DUCKDB VARIABLES TO MEMORY overwrites pending DuckDB edits in Main. Use it when you want to discard those edits or start from the current running configuration. LOAD DUCKDB VARIABLES FROM DISK also replaces pending edits.

Saving to Disk does not apply or validate the saved values. Review them before restarting, because an invalid saved configuration can prevent the plugin from starting.

Apply live changes

These settings can change while ProxySQL runs:

• duckdb-memory_limit
• duckdb-threads
• duckdb-max_connections
• duckdb-enable_external_access, when changing from true to false

For example:

UPDATE global_variables SET variable_value='4'
WHERE variable_name='duckdb-threads';
LOAD DUCKDB VARIABLES TO RUNTIME;

SELECT variable_name, variable_value FROM runtime_global_variables
WHERE variable_name='duckdb-threads';

SAVE DUCKDB VARIABLES TO DISK;

LOAD checks the whole proposed configuration. An unknown variable, invalid value, or change requiring restart makes LOAD fail, including when the same request contains otherwise valid live edits. Correct the offending Main values before retrying. If a row is absent from Main, LOAD keeps its effective value; deleting a row does not reset that setting to its default.

Save changes for restart

The following changes require restarting ProxySQL:

• duckdb-database_path
• duckdb-read_only
• duckdb-mysql_ifaces
• duckdb-pgsql_ifaces
• duckdb-enable_external_access, when changing from false to true

Edit Main and save it directly to Disk. For example, to move a listener to a local address:

UPDATE global_variables SET variable_value='127.0.0.1:6031'
WHERE variable_name='duckdb-mysql_ifaces';
SAVE DUCKDB VARIABLES TO DISK;

Then follow the restart procedure. LOAD does not rebind listeners or reopen the database. A database path change does not move or copy existing data.

Compare pending and running values

SELECT m.variable_name, m.variable_value AS main_value,
       r.variable_value AS runtime_value
FROM global_variables AS m
LEFT JOIN runtime_global_variables AS r USING (variable_name)
WHERE m.variable_name LIKE 'duckdb-%'
ORDER BY m.variable_name;

Memory limits may use different units in the two tables: Runtime reports DuckDB’s formatted value, so equivalent limits need not be identical strings.

If LOAD returns an error indicating that settings were applied but could not be reported, or that a previous setting could not be restored, query Runtime and check the ProxySQL log before making further changes. Main retains the values you edited even when LOAD fails.

Upgrade from dedicated DuckDB tables

At the first startup after upgrading, recognized values from the former duckdb_variables tables are imported into global_variables with the duckdb- prefix. Existing prefixed values take precedence. Values saved only in the old Disk table are available on that startup too.

The old duckdb_variables and runtime_duckdb_variables tables are removed. Update scripts to use the standard tables shown above, compare Runtime with your intended configuration, and check the log for unsupported legacy variable names that were not migrated.