PHPackages                             iliaal/pdo\_duckdb - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. iliaal/pdo\_duckdb

ActivePhp-ext[Database & ORM](/categories/database)

iliaal/pdo\_duckdb
==================

PDO driver for DuckDB, the in-process analytical database.

00PHPCI passing

Since Jun 18Pushed todayCompare

[ Source](https://github.com/iliaal/pdo_duckdb)[ Packagist](https://packagist.org/packages/iliaal/pdo_duckdb)[ RSS](/packages/iliaal-pdo-duckdb/feed)WikiDiscussions master Synced today

READMEChangelog (3)DependenciesVersions (1)Used By (0)

pdo\_duckdb
===========

[](#pdo_duckdb)

A [PDO](https://www.php.net/pdo) driver for [DuckDB](https://duckdb.org/), the in-process analytical (OLAP) database. Connect to DuckDB through the standard PDO API you already use for SQLite, MySQL and PostgreSQL.

```
$db = new PDO('duckdb:/path/to/analytics.duckdb');
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

$stmt = $db->prepare('SELECT region, SUM(amount) AS total FROM sales WHERE year = ? GROUP BY region');
$stmt->execute([2026]);
foreach ($stmt as $row) {
    printf("%s: %s\n", $row['region'], $row['total']);
}
```

Requirements
------------

[](#requirements)

- PHP 8.1 or newer with the `pdo` extension
- For a source build only: the DuckDB C library (`libduckdb` + `duckdb.h`) — download a prebuilt `libduckdb` bundle from the [DuckDB installation page](https://duckdb.org/docs/installation/)or install it via your package manager. Prebuilt installs (below) need nothing else.

Installation
------------

[](#installation)

### PIE

[](#pie)

```
pie install iliaal/pdo_duckdb
```

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 other platforms or older PHP it falls back to a source build, which needs `libduckdb` + `duckdb.h`; point it at the prefix if they aren't in a standard location:

```
pie install iliaal/pdo_duckdb --with-pdo-duckdb=/opt/duckdb
```

### From source

[](#from-source)

```
phpize
./configure --with-pdo-duckdb=/opt/duckdb
make
make install
```

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

```
extension=pdo_duckdb
```

DSN
---

[](#dsn)

```
duckdb:/path/to/database.duckdb   # file-backed database
duckdb::memory:                   # in-memory database
duckdb:                           # in-memory database (empty path)

```

Bulk insert (Appender)
----------------------

[](#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`:

```
$db->exec('CREATE TABLE events (id INTEGER, name VARCHAR, ts TIMESTAMP)');

$app = $db->duckdbAppender('events');      // optional 2nd arg: schema name
foreach ($rows as $r) {
    $app->appendRow($r['id'], $r['name'], $r['ts']);
}
$app->flush();                              // or $app->close() to finalize
```

`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.

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+.

DuckDB extensions
-----------------

[](#duckdb-extensions)

DuckDB extensions load through ordinary SQL — no special API:

```
$db->exec('LOAD json');                     // bundled extensions load offline
$db->exec('INSTALL httpfs; LOAD httpfs;');  // downloadable extensions
```

Usage notes
-----------

[](#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.
- **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.
- **`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.
- **`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`, `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.

Status
------

[](#status)

Early release. Result columns are decoded with DuckDB's data-chunk/vector API (native scalars straight to PHP values; nested/extended types via their canonical string form). Note that `execute()` returns a **materialized** result: DuckDB buffers the full result set in memory before PDO begins fetching, so a large `SELECT` is bounded by available memory rather than streamed row-by-row. True streaming (the pending-result API) is a planned follow-up.

License
-------

[](#license)

BSD 3-Clause. See [LICENSE](LICENSE).

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2838354?v=4)[iliaa](/maintainers/iliaa)[@iliaa](https://github.com/iliaa)

---

Top Contributors

[![iliaal](https://avatars.githubusercontent.com/u/158724?v=4)](https://github.com/iliaal "iliaal (43 commits)")

### Embed Badge

![Health badge](/badges/iliaal-pdo-duckdb/health.svg)

```
[![Health](https://phpackages.com/badges/iliaal-pdo-duckdb/health.svg)](https://phpackages.com/packages/iliaal-pdo-duckdb)
```

###  Alternatives

[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k116.5M113](/packages/jdorn-sql-formatter)[propel/propel1

Propel is an open-source Object-Relational Mapping (ORM) for PHP5.

8351.6M87](/packages/propel-propel1)[yemenopensource/filament-excel

This package useful for importing excel files into models.

194.2k](/packages/yemenopensource-filament-excel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)