DuckDB client compatibility

The MySQL and PostgreSQL endpoints accept DuckDB SQL over simple text-query connections. Choose clients that can disable prepared statements and use the simple-query protocol.

Support matrix

Choosing a client API

For MySQL, use mysql_query, mysql_real_query, or an equivalent text-query API. Prepared-statement requests return error 1045 (28000), Command not supported; in this case, changing credentials will not fix the unsupported API.

For PostgreSQL, use PQexec or a driver mode that sends simple queries. Parameterized operations often select the unsupported extended protocol automatically. An error with SQLSTATE 0A000 can indicate that the driver is using this protocol.

Use the driver’s supported quoting facilities and validate untrusted input when constructing text queries. Do not replace parameter binding with unsafe string concatenation.

One statement per request

Send each SQL statement separately. For example, use one call for CREATE TABLE t(i INTEGER) and another for INSERT INTO t VALUES (1). A request containing both statements is rejected. A comment-only request also fails because it contains no executable statement.

SQL dialect and discovery commands

Use DuckDB SQL. MySQL- or PostgreSQL-specific syntax can fail even when the connection uses that protocol. Check any initialization SQL your client issues automatically.

The following compatibility commands are supported:

• SELECT @@version and SELECT VERSION() return the embedded DuckDB version.
• SELECT DATABASE() and SELECT CURRENT_DATABASE() return memory for an in-memory database, or the configured database path.
• SHOW TABLES lists tables.
• SHOW DATABASES lists DuckDB catalogs.
• SHOW SCHEMAS lists schemas.
• SET autocommit=0, SET autocommit=1, and a single SET NAMES ... command are accepted as no-ops. Use explicit BEGIN/COMMIT/ROLLBACK for transactions.

Commands are case-insensitive and accept normal whitespace and a trailing semicolon. Other statements must be valid DuckDB SQL and comply with the session-setting restrictions.

Result metadata and formats

Every result column is described as text. Applications that need numbers, dates, timestamps, arrays, or binary data must interpret the returned values. SQL NULL is represented as a protocol null.

Common scalar types are returned as text, including booleans, signed and unsigned integers, floating-point values, dates, times, timestamps, decimals, and intervals. Floating-point output uses up to 15 significant digits. Cast to VARCHAR in your SQL if you need DuckDB’s string formatting instead.

Nested and other special types, including LIST, STRUCT, MAP, ARRAY, UNION, UUID, ENUM, BIT, and specialized timestamp types, are normally converted to text automatically. Some INSERT, UPDATE, or DELETE ... RETURNING results cannot use this conversion. An unsupported result type can then appear as NULL even when its value is not SQL NULL. Cast such expressions to VARCHAR in the RETURNING clause to avoid that ambiguity.

Strings and BLOB values can contain embedded NUL bytes. BLOB values are sent as raw bytes with text column metadata; client libraries may interpret them as text. Select an encoded representation such as hex(blob_column) when you need portable text output.

Errors and transactions

SQL errors use the endpoint’s normal error response. PostgreSQL errors include SQLSTATE values where an error category is available; unclassified errors use XX000.

PostgreSQL transaction status is reported as idle (I), in transaction (T), or failed transaction (E). After an error in an explicit transaction, issue ROLLBACK before continuing.

Operational limits

There is no configurable per-query timeout. When the configured connection limit is reached, new clients may see a connection reset without a structured protocol error. See Configuration reference for memory, thread, and connection limits.