Hi! 👋 We are doing a big documentation refresh. Help us improve — what's missing or could be better? Let us know! Simply send an email or start a conversation in Google Groups!

Operate the DuckDB plugin

Startup

At startup, ProxySQL restores its saved configuration and the plugin opens one shared DuckDB database, then binds its MySQL and PostgreSQL listeners. If a saved setting is invalid, the database cannot open, or a listener cannot bind, the plugin does not start. Inspect the ProxySQL log for the affected setting, path, or address.

Runtime configuration workflow

Run these commands through ProxySQL Admin:

UPDATE global_variables
SET variable_value='200'
WHERE variable_name='duckdb-max_connections';

LOAD DUCKDB VARIABLES TO RUNTIME;

SELECT variable_name, variable_value FROM runtime_global_variables
WHERE variable_name LIKE 'duckdb-%' ORDER BY variable_name;

SAVE DUCKDB VARIABLES TO DISK;

Check that LOAD succeeded and Runtime contains the intended effective values before saving. duckdb-memory_limit, duckdb-threads, and duckdb-max_connections apply live. Disabling external access also applies live.

LOAD fails if Main contains an invalid value or a change requiring restart; it does not apply the other live edits in that request. For restart changes, edit Main and save directly to Disk, then use the restart procedure. See the Admin reference for comparisons and ways to restore saved or running values to Main.

Health checks

Use protocol-level checks from the same network path as clients. Replace CHECK_USER with a frontend user configured for the endpoint:

mysql -h 127.0.0.1 -P 6031 -u CHECK_USER -p -e 'SELECT 42'
psql -h 127.0.0.1 -p 6034 -U CHECK_USER -d main -c 'SELECT 42'

Use your deployment’s TLS options where required. A TCP connect alone proves only that a socket is listening. A useful check authenticates and completes a query.

Capacity planning

Plan these settings together:

  • duckdb-memory_limit limits DuckDB’s buffer manager. It is not a process memory limit; query results and other allocations can exceed it.
  • duckdb-threads controls DuckDB query parallelism.
  • duckdb-max_connections caps connections across both DuckDB listeners.

DuckDB runs in the ProxySQL process. Leave memory for ProxySQL, client buffers, other plugins, the operating system, and workload spikes. Monitor total process memory under representative concurrent queries.

The plugin creates one thread per accepted connection, in addition to DuckDB’s query workers. A high connection cap therefore consumes thread stacks and scheduling capacity even when sessions are idle.

Connection-limit behavior

At duckdb-max_connections, the plugin closes new sockets before protocol setup. Existing connections remain active. Reducing the limit below the current count does not disconnect them; new connections are admitted after the count drops below the cap.

Clients may report a connection reset or unexpected EOF instead of a structured MySQL or PostgreSQL error. Reduce application connection-pool sizes or raise the cap only after checking memory and thread capacity.

A connection occupies a slot before authentication. The MySQL listener uses mysql-connect_timeout_client and the PostgreSQL listener uses pgsql-connect_timeout_client to disconnect clients that do not finish authenticating in time. These are core ProxySQL variables, in milliseconds; a value of zero disables that timeout. The value is read when each connection is created, so changes affect subsequent handshakes. Timed-out connections release their slots and produce a Closing not established DuckDB client connection warning in the ProxySQL log.

Backup and restore

With :memory:, there is no database file that survives restart. Export needed data before stopping ProxySQL, subject to the external-access policy.

For a file-backed database:

  1. Stop new application traffic to the DuckDB listeners.
  2. Allow active queries and transactions to finish.
  3. Stop ProxySQL cleanly.
  4. Copy or snapshot the database file and its containing storage.
  5. Restart ProxySQL and verify the expected data; test writes if the database is intended to be writable.

Keep ProxySQL stopped during the copy or snapshot. Do not assume copying a live database file while writes continue produces a usable backup. If you need an online export instead, choose a DuckDB-supported method compatible with the bundled DuckDB version and your external-access policy, and verify restoration before relying on it.

Back up ProxySQL’s configuration database and startup configuration separately. The DuckDB data file does not contain the plugin settings or frontend user configuration.

To restore, stop ProxySQL, preserve the current file, and place the restored database at duckdb-database_path with ownership and permissions suitable for the ProxySQL account. Start ProxySQL and verify the expected data through a DuckDB listener.

Restart changes

Restart to apply changes to duckdb-database_path, duckdb-read_only, duckdb-mysql_ifaces, or duckdb-pgsql_ifaces, or to enable duckdb-enable_external_access:

  1. Review Main and record the current Runtime values.
  2. Save the intended configuration with SAVE DUCKDB VARIABLES TO DISK.
  3. Drain application traffic and allow queries and transactions to finish.
  4. Restart ProxySQL using your normal service procedure.
  5. Inspect the log, query Runtime through Admin, and reconnect through the configured DuckDB listeners.
  6. Verify the expected database and data, including write behavior if relevant.

There is no need to attempt LOAD first for these changes. Restarting ProxySQL also affects its normal proxy traffic, so include those clients in the maintenance plan. An in-memory DuckDB database loses its contents on restart.

A database path change does not move existing data. If you intend to move a file-backed database, stop ProxySQL and copy or move the database to the new path before restarting, preserving ownership and permissions. Opening a new empty path can otherwise look like data loss.

Shutdown

Prefer normal service shutdown so the plugin can stop accepting connections, interrupt active queries, close sessions, and close the database. Drain clients first when their work needs to complete; shutdown does not wait for every application transaction to finish successfully.

Upgrade checks

Back up data and configuration before upgrading. Build and install the core and plugin as a matching pair; see Installation. After upgrading:

  • Check logs for plugin load or database-open errors.
  • Verify the expected database file and data are available.
  • Compare duckdb-* Runtime values with the saved Disk values.
  • Run queries through each enabled protocol and test a transaction.
  • Confirm memory and connection limits remain suitable for the workload.

If upgrading from the former dedicated DuckDB variable tables, update Admin scripts as described in the Admin reference.