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!

DuckDB user guide

Connecting

Use an active frontend user from mysql_users for the MySQL endpoint or pgsql_users for the PostgreSQL endpoint. Load the users to runtime before connecting. The quickstart shows account creation and connection checks.

MySQL protocol, default port 6031:

mysql -h 127.0.0.1 -P 6031 -u USERNAME -p

PostgreSQL protocol, default port 6034:

psql -h 127.0.0.1 -p 6034 -U USERNAME main

These listeners are separate from ProxySQL Admin on 6032 and the normal MySQL proxy listener on 6033. For remote connections, configure TLS and server certificate verification; see Security.

Shared database and storage

MySQL and PostgreSQL clients read and modify the same DuckDB database. Each client has its own transaction and session settings. There are no per-user schema or table permissions; grant access only to users trusted with the whole database.

Choose storage with duckdb-database_path:

  • :memory: — shared by all plugin sessions and lost when ProxySQL stops.
  • a filesystem path — persistent DuckDB database.

Changing the path does not move existing data. Save the setting, stop traffic, and restart ProxySQL to open the new path. Verify the database before resuming traffic.

Running DuckDB SQL

Write DuckDB SQL, regardless of which protocol you use. ProxySQL does not translate general MySQL or PostgreSQL syntax into DuckDB syntax. Use an unused table name if events already exists.

CREATE TABLE events (
    event_time TIMESTAMP,
    category VARCHAR,
    value DOUBLE
);

INSERT INTO events VALUES
    (TIMESTAMP '2026-09-01 10:00:00', 'api', 12.5),
    (TIMESTAMP '2026-09-01 10:05:00', 'worker', 7.0),
    (TIMESTAMP '2026-09-01 10:10:00', 'api', 4.5);

SELECT category, COUNT(*) AS events, SUM(value) AS total
FROM events
GROUP BY category
ORDER BY category;

Send each statement as a separate request. Interactive clients normally split statements at the terminator; an API call containing DROP TABLE events; SELECT 1; is rejected.

Transactions

Use explicit transaction commands, each in a separate request:

BEGIN;
INSERT INTO events VALUES (CURRENT_TIMESTAMP, 'batch', 20);
COMMIT;

After an error in an explicit transaction, issue ROLLBACK before continuing. SET autocommit=0 and SET autocommit=1 are accepted for client compatibility but do not change transaction behavior. Use BEGIN to start a transaction.

Session settings

Use SET SESSION and RESET SESSION for settings on your connection. Send the following statements separately:

SET SESSION search_path='main';
SELECT current_setting('search_path');

Unscoped SET and RESET also use session scope. Clients cannot change engine-wide settings, including memory_limit/max_memory, threads/worker_threads, max_temp_directory_size and enable_external_access. Change the supported engine settings through the DuckDB Admin variables, then run LOAD DUCKDB VARIABLES TO RUNTIME.

SET GLOBAL and RESET GLOBAL are rejected. Configuration assignments such as PRAGMA name=value are also rejected; use SET SESSION for session settings. Session commands such as PRAGMA enable_optimizer and SET VARIABLE are allowed. EXPLAIN of SET, RESET, or PRAGMA is rejected.

A single SET NAMES ... command is accepted as a compatibility no-op. Other client initialization commands must be valid DuckDB SQL.

Metadata commands

The plugin supports these common discovery commands:

SHOW TABLES;
SHOW DATABASES;
SHOW SCHEMAS;
SELECT DATABASE();
SELECT CURRENT_DATABASE();
SELECT VERSION();
SELECT @@version;

SHOW DATABASES lists DuckDB catalogs; SHOW SCHEMAS lists schemas. SELECT DATABASE() and SELECT CURRENT_DATABASE() return memory for :memory: and the configured database path otherwise. The version queries return the embedded DuckDB version.

Result values

Both protocols report every result column as text, including numeric and date columns. Applications must parse values when they need another type. SQL NULL is returned as a protocol null.

Nested values such as lists, structs, and maps are normally returned as text. Some types in an INSERT, UPDATE, or DELETE ... RETURNING result can instead appear as NULL even when the stored value is not SQL NULL. Cast these expressions to VARCHAR explicitly in the RETURNING clause. See Client compatibility for result format limits.

Client-library guidance

Choose APIs that issue simple text queries:

  • MySQL: mysql_query, mysql_real_query, or equivalent non-prepared APIs.
  • PostgreSQL: PQexec or a driver mode that uses the simple-query protocol.

Prepared-statement APIs are unsupported. PostgreSQL drivers often choose the extended protocol automatically for parameters; configure a supported simple-query mode. Keep SQL-injection defenses in place when constructing SQL: use a library’s appropriate quoting functions and validate input. Do not concatenate untrusted values into query strings.