DuckDB configuration reference

Edit these eight settings in ProxySQL Admin’s global_variables table. Query runtime_global_variables for the effective values. The Admin reference explains how to apply and save changes.

Boolean values are case-insensitive. Runtime reports them as true or false. Main can retain the spelling you entered. An empty database path selects :memory:.

Listener variables

Separate multiple addresses with ; and bracket IPv6 literals:

127.0.0.1:6031;10.0.0.10:6031
[::1]:6031

Ports must be between 1 and 65535. An empty value disables that protocol’s listener at the next restart. Use a dedicated port for each listener; do not reuse the Admin or normal proxy ports. The defaults bind on all IPv4 interfaces; choose local or private addresses and appropriate network access controls for your deployment.

Save listener edits to Disk and restart ProxySQL. If Main contains a changed listener value, LOAD rejects the request, including unrelated live edits in that request.

duckdb-database_path

:memory: keeps data only for the lifetime of the running process. Any other value names a database file accessible to the ProxySQL operating-system account. Use an absolute path to avoid dependence on the service’s working directory. For a new database, its parent directory must exist and be writable by that account.

Changing the path does not copy or migrate data. After saving and restarting, verify that the expected database opened; a new writable path can create an empty database. Runtime continues to show the old path until restart.

duckdb-memory_limit

Examples are 512MB, 1GB, and 8GB. DuckDB validates the value when LOAD applies the proposed configuration. Invalid syntax makes LOAD fail before other live edits are applied. Runtime may express the limit in different units from the value you entered.

This limits DuckDB’s buffer manager, not the total memory used by the ProxySQL process. Query results, connection buffers, and other allocations can consume additional memory. Leave room for ProxySQL, the operating system, and workload spikes; monitor process memory as well as this setting.

duckdb-threads

Controls DuckDB query parallelism. A live change is global and is visible to existing connections. It does not cap the listener’s connection threads: the plugin also creates one thread per accepted connection.

Clients cannot change threads or its alias worker_threads with SQL. Change duckdb-threads through Admin instead.

duckdb-max_connections

Limits concurrent client connections across both DuckDB listeners together. Unauthenticated connections also occupy slots. Lowering the limit preserves existing sessions and rejects new ones until the count falls below the limit. At the cap, clients may receive a connection reset or EOF instead of a protocol error. See connection-limit behavior.

duckdb-read_only

Opens the main database read-only. This requires an existing file-backed database; true with :memory: or an empty database path is invalid. Save the change and restart ProxySQL to apply it.

Read-only mode does not replace the external-access policy. See the Security guide.

duckdb-enable_external_access

External access is disabled by default. Enabling it grants DuckDB clients access to external resources available to the ProxySQL process, including filesystem operations permitted by the operating system. Review the Security guide before enabling it.

Changing from true to false works live. Changing from false to true requires saving the edit to Disk and restarting ProxySQL.

Clients cannot change this setting with SET or RESET. Engine-wide settings are managed through Admin; supported client settings are limited to the client’s own session.