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!

Install the DuckDB plugin

The DuckDB plugin requires a ProxySQL 4.0 build. In 4.0.12 it is available through source installation and is not included in the downloadable packages. Build the core and plugin together, using the same release and build mode.

The system-installation steps below are for a fresh Linux host with systemd. For an existing ProxySQL deployment, use your normal upgrade procedure and keep its configuration and data; see upgrades.

Prepare the build tools

You need Git, a C++17 compiler, GNU Make, CMake, Autoconf/Automake, Libtool, Python 3, Perl, and the development libraries used by ProxySQL.

For Ubuntu 24.04, install the build tools and libraries:

sudo apt-get update
sudo apt-get install -y \
  build-essential git cmake autoconf automake libtool pkg-config \
  bison flex python3 perl wget curl unzip zstd \
  libssl-dev libgnutls28-dev libmysqlclient-dev libunwind-dev \
  uuid-dev libncurses-dev libicu-dev libevent-dev libtirpc-dev zlib1g-dev

Other distributions need their corresponding development packages. DuckDB 1.4.5 is included in the ProxySQL source tree.

Build ProxySQL and the plugin

Get the 4.0.12 source:

git clone --branch v4.0.12 --single-branch https://github.com/sysown/proxysql.git proxysql-duckdb
cd proxysql-duckdb

Check the included DuckDB archive, then build:

deps/duckdb/verify-source.bash
make PROXYSQL40=1

Keep PROXYSQL40=1 on the build and install commands. If reusing a checkout built for a different tier or debug mode, run make cleanall before rebuilding.

The resulting files are:

  • src/proxysql
  • plugins/duckdb/ProxySQL_DuckDB_Plugin.so

Install on a new host

This command installs the binary, sample configuration, built plugins, and service files. It replaces /etc/proxysql.cnf, so use it for a fresh installation, not as an unattended upgrade of a configured server.

sudo make PROXYSQL40=1 install

The DuckDB library is installed at:

/usr/lib/proxysql/plugins/ProxySQL_DuckDB_Plugin.so

The supplied systemd service runs as proxysql. Make its data directory writable by that account and allow it to read the configuration:

sudo install -d -o proxysql -g proxysql -m 0750 /var/lib/proxysql
sudo chown root:proxysql /etc/proxysql.cnf
sudo chmod 0640 /etc/proxysql.cnf

Configure startup

Edit /etc/proxysql.cnf. In its existing admin_variables section, set a strong Admin password and bind Admin to the local interface. Replace the password placeholder before starting the service:

admin_credentials="admin:REPLACE_WITH_A_STRONG_ADMIN_PASSWORD"
mysql_ifaces="127.0.0.1:6032"

Add the plugin path to the top-level plugins array. If an array already exists, add an entry to it:

plugins = (
    "/usr/lib/proxysql/plugins/ProxySQL_DuckDB_Plugin.so"
)

Both DuckDB listeners initially bind to all interfaces, on ports 6031 and 6034. Keep them within a trusted network or behind host network controls during initial setup. The quickstart shows how to save loopback-only bindings before creating the example users.

Start the service:

sudo systemctl daemon-reload
sudo systemctl start proxysql

If startup fails, inspect the service and ProxySQL logs:

sudo journalctl -u proxysql -n 50 --no-pager
sudo tail -n 50 /var/lib/proxysql/proxysql.log

See troubleshooting for library, engine, and listener errors. Continue with the quickstart to configure the database, create users, and run queries.

Plugin changes require a ProxySQL restart. There is no runtime LOAD PLUGIN command. If using a custom installation path, put that library’s absolute path in the plugins array.

Upgrade an existing installation

Before replacing an installed core or plugin:

  1. Stop new application work and let active queries and transactions finish.
  2. Stop ProxySQL cleanly.
  3. Back up its configuration database, configuration file, and any file-backed DuckDB database using the backup procedure.
  4. Install the matching core and every plugin that the configuration loads, preserving the deployment’s configuration and service settings.
  5. Start ProxySQL, inspect logs, and reconnect clients to check the data.

Do not use the fresh-install command above to preserve an existing configuration; it installs the sample configuration over it. Do not replace only a loaded library and expect the running process to adopt the new file.