Download the PHP package iliaal/pdo_duckdb without Composer

pdo_duckdb

A PDO driver for DuckDB, the in-process analytical (OLAP) database. Connect to DuckDB through the standard PDO API you already use for SQLite, MySQL, and PostgreSQL.

Requirements

• PHP 8.1 or newer with the pdo extension
• For a source build only: DuckDB 1.5.3 or newer (libduckdb + duckdb.h), available as a prebuilt bundle from the DuckDB installation page or via your package manager. Prebuilt installs (below) need nothing else.

🚀 Installation

PIE

On Linux (x86_64/arm64), macOS (Apple Silicon), and Windows x64, PIE downloads a self-contained prebuilt binary. No DuckDB install or build toolchain needed. On Linux the prebuilt baseline is glibc 2.36 (Debian 12); Apple Silicon binaries target macOS 11.0. On other platforms, older operating systems, or older PHP, use a source build, which needs libduckdb + duckdb.h; point it at the prefix if they aren't in a standard location:

From source

Then enable it in php.ini (after pdo):

DSN

Connection options

Append DuckDB configuration as ;key=value pairs on the DSN, or pass them as a PDO::DUCKDB_ATTR_CONFIG array:

Any DuckDB setting name works (access_mode, memory_limit, threads, ...); an unknown option fails the connection. PDO::DUCKDB_ATTR_CONFIG is connect-time only and is refused with persistent handles, because PDO's persistent key does not include driver option arrays.

Persistent connections reuse the same DuckDB connection for a matching DSN. DuckDB session/catalog state such as temporary tables, SET options, attachments, and :memory: contents can therefore survive across requests in the same PHP process; do not use persistence as a tenant or request isolation boundary.

When open_basedir is set, external file access stays disabled whatever you pass. The driver also rejects path/security-sensitive DuckDB settings such as allowed_directories, allowed_paths, allowed_configs, temp_directory, extension_directory, and extension auto-install/load knobs, and locks DuckDB configuration after the sandbox profile is applied. The database-file path check and DuckDB's open are separate filesystem operations because DuckDB has no descriptor-based open API. For file-backed databases, keep every writable path component below trusted, non-writable directory ancestry so an attacker cannot replace a checked path by renaming a file or symlink before DuckDB opens it.

🛠️ Bulk insert (Appender)

For fast bulk loads, PDO::duckdbAppender() returns a Pdo\Duckdb\Appender wrapping DuckDB's native appender, far faster than row-by-row INSERT:

flush() commits buffered rows and leaves the appender usable. close() flushes, finalizes the native appender, and marks the PHP object closed. Relying on the destructor alone still closes (and warns on failure); prefer an explicit close(). Soft validation failures (ValueError/TypeError for arity, types, ranges) leave the appender live so you can retry the row. Hard DuckDB failures on append/flush/close poison the appender — later use throws Error and you must create a new one. The same hard path applies when DuckDB rejects a PHP string cast into a typed column (e.g. 'not-a-date' into DATE, or a non-numeric string into DECIMAL): that is a native append failure, not a soft ValueError, so buffered rows for that appender are lost and you must create a new appender.

appendRow(...$values) takes one argument per column (left to right) and returns the appender for chaining. PHP null/bool/int/float/string map to DuckDB values; DuckDB casts them to the target column types. For nested columns, pass a PHP array: a list fills LIST/ARRAY, and an associative array fills STRUCT (by field name) or MAP.

Pass a column list as the third argument to append only some columns; the rest take their DEFAULT (or NULL). Handy for tables with generated keys or timestamps:

On PHP 8.4+, PDO::connect('duckdb:…') returns a Pdo\Duckdb instance and duckdbAppender() lives on that subclass. On new PDO('duckdb:…') (and on PHP 8.1-8.3) the method is available on the PDO object directly; note PHP 8.5 emits a deprecation for driver methods called on the base PDO class, so prefer PDO::connect() on 8.4+.

🔍 Query helpers

Two driver-specific methods, available on the same object as duckdbAppender():

Profiling metric values are strings, or PHP null when DuckDB reports a SQL NULL for that metric; cast the numeric strings as needed.

🧩 DuckDB extensions

DuckDB extensions load through ordinary SQL, no special API:

Usage notes

• Placeholders. Positional ? and named :name placeholders are supported; PDO rewrites them to DuckDB $N parameters. A repeated :name is bound once. Because : is reserved for placeholders, inline STRUCT/MAP literals must keep a space after the colon ({'k': 1}, not {'k':1}) in prepared queries.
• Cursors are forward-only. DuckDB hands results back one chunk at a time in a single direction, so PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL is rejected at prepare() rather than failing later on the first backwards fetch. Use fetchAll() and index the array if you need random access.
• Transactions. beginTransaction() / commit() / rollBack() map to DuckDB BEGIN TRANSACTION / COMMIT / ROLLBACK. DuckDB is autocommit-by-default with no session toggle, so setAttribute(PDO::ATTR_AUTOCOMMIT, false) is rejected; use beginTransaction() for explicit transactions. The driver also reflects raw transaction-control SQL through inTransaction() so persistent handles cannot retain an invisible transaction after PHP releases a PDO object. This includes DuckDB's END and ABORT aliases and transaction control wrapped by EXPLAIN ANALYZE; DuckDB reports only the outer EXPLAIN statement type, so the driver tracks the wrapped effect explicitly after successful execution.
• open_basedir. When open_basedir is set, DuckDB's SQL-level external file access (read_csv, COPY, ATTACH, httpfs, …) is disabled so the sandbox holds at the SQL layer, not just for the database file path. If open_basedir is tightened after a handle already exists, the driver clears DuckDB path allowlists before disabling external access and locks the connection configuration. You can still activate an extension compiled into DuckDB, such as LOAD json; the sandbox blocks extension files and downloads. Locking the configuration blocks every later SET, including ones with no security relevance (threads, memory_limit, preserve_insertion_order, default_null_order, …). Pass those at connect time instead, in the DSN tail or PDO::DUCKDB_ATTR_CONFIG, where the sandbox allows anything that is not path- or extension-related. TimeZone is the exception: it is a SQL-only setting with no duckdb_set_config equivalent, so under open_basedir it stays at DuckDB's default for the life of the handle.
• lastInsertId() is not supported; DuckDB has no implicit rowid. Use a sequence and currval() if you need generated keys.
• Type mapping. Integers up to 64-bit signed return as int, BOOLEAN as PHP int 0/1 (not bool), FLOAT/DOUBLE as float, BLOB as a binary string, and everything else (VARCHAR, DATE/TIME/TIMESTAMP, DECIMAL, HUGEINT/UBIGINT, nested types) as its canonical string form. getColumnMeta() reports the real DuckDB type name per column, pdo_type matching the fetch shape (PDO::PARAM_INT for BOOLEAN and integer widths), plus precision/scale for DECIMAL. Nested values with boolean, integer, DECIMAL, DATE, and UUID leaves use a direct renderer; nested values whose leaves need DuckDB's quoting rules keep DuckDB's own renderer. Nested fetches intentionally return canonical strings, not PHP arrays; use SQL projections such as unnest, struct_extract, or json when you want a different PHP-facing shape. GEOMETRY (from the spatial extension) returns its WKB bytes as a hex string; call ST_AsText() in SQL if you want WKT. TIMESTAMPTZ native fetches render the instant in UTC (+00), at the top level and as a nested leaf; select CAST(col AS VARCHAR) if you need DuckDB's session-TimeZone rendering. DuckDB's C result API cannot extract non-NULL VARIANT cells safely, so fetching one reports a PDO error; cast it to VARCHAR (or another concrete SQL type) in the query. SQL NULL remains PHP null.

• Streaming results. By default execute() returns a materialized result: DuckDB buffers the full result set before PDO fetches, so a large SELECT is bounded by available memory. For large scans, set PDO::DUCKDB_ATTR_UNBUFFERED to fetch chunks lazily through DuckDB's pending-result API instead:

  The driver does not add a one-active-stream guard. With the tested DuckDB C API, another statement can run while an unbuffered result is partially consumed, and the first result can continue afterward. Use PDOStatement::closeCursor() when you want to release the native result early.

  Persistent connections reset DUCKDB_ATTR_UNBUFFERED to false on every checkout (check_liveness). Pass it again in the constructor options or call setAttribute after each new PDO(..., [PDO::ATTR_PERSISTENT => true]).

Status

Early release. Result columns are decoded with DuckDB's data-chunk/vector API: native scalars go straight to PHP values, nested and extended types via their canonical string form.

🔗 Native PHP extensions

Companion native PHP extensions:

• php_excel: native Excel I/O via LibXL. 7-10× faster than PhpSpreadsheet, full XLS/XLSX with formulas, formatting, and styling.
• mdparser: native CommonMark + GFM markdown parser via md4c. 15-30× faster than pure-PHP libraries.
• php_clickhouse: native ClickHouse client speaking the wire protocol directly. Picks up where SeasClick left off.
• fastjson: drop-in faster ext/json, backed by yyjson. 6× encode, 2.7× decode, 5× validate.
• phpser: decoder-optimized binary serializer for cache workloads. Faster than igbinary on packed numerics and DTO batches.
• fast_uuid: high-throughput UUID generation (v1/v4/v7), batched CSPRNG and SIMD hex formatter, ramsey-compatible API.
• fastchart: native chart-rendering extension. 38 chart types behind one fluent OO API, SVG-canonical with PNG/JPG/WebP and optional PDF output.
• statgrab: system statistics (CPU, memory, disk, network) via libstatgrab, no parsing /proc by hand.
• phonetic: native phonetic name matching (Double Metaphone, Beider-Morse, Daitch-Mokotoff, NYSIIS, Match Rating), the encoders PHP core lacks.

License

BSD 3-Clause. See LICENSE.

Follow @iliaa on X • Blog • If this got DuckDB into your PHP stack, ⭐ star it!