native oracle extension for duckdb
  • Rust 76.2%
  • Python 20.2%
  • Makefile 3.6%
Find a file
Daniel Markow 4a4b022811
All checks were successful
Build & Release Windows Extension / Build oracle.duckdb_extension (windows_amd64) & Publish Release (push) Successful in 4m24s
Fix release workflow failing with SIGPIPE in DLL checks
The runner executes steps with `bash -eo pipefail`; `objdump | grep -q`
made objdump die with SIGPIPE (exit 141) once grep matched. Capture the
objdump and footer output in variables and grep those instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 14:32:40 +00:00
.cargo Add Forgejo workflow that releases a prebuilt Windows extension 2026-11-18 14:26:45 +00:00
.forgejo/workflows Fix release workflow failing with SIGPIPE in DLL checks 2026-11-18 14:32:40 +00:00
scripts Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
src Add Forgejo workflow that releases a prebuilt Windows extension 2026-11-18 14:26:45 +00:00
test Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
.gitignore Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
.mise.toml Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
AGENTS.md Add Forgejo workflow that releases a prebuilt Windows extension 2026-11-18 14:26:45 +00:00
Cargo.lock Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
Cargo.toml Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
LICENSE Add DuckDB extension for Oracle over OCI / Oracle Net 2026-11-08 06:56:47 +00:00
Makefile Add Forgejo workflow that releases a prebuilt Windows extension 2026-11-18 14:26:45 +00:00
README.md Add Forgejo workflow that releases a prebuilt Windows extension 2026-11-18 14:26:45 +00:00

oracle-duck

this was entirely vibe-code using Opus 5.5 - use with caution

A DuckDB extension, written in Rust, that reads from (and runs statements on) Oracle databases. It talks to Oracle through OCI over Oracle Net (TNS), Oracle's native protocol, via ODPI-C and the oracle crate. There's no ODBC driver or driver manager.

Target server: Oracle Database 19c (any version Instant Client 19+ can reach works, 12.1 and newer). Target DuckDB: 2.0 (built against the stable C extension API v1.2.0, so newer DuckDB releases can load it too).

LOAD 'build/release/oracle.duckdb_extension';

-- read a table or view (only the columns you use are fetched)
SELECT ename, sal FROM oracle_scan('scott/tiger@dbhost:1521/ORCLPDB1', 'EMP') WHERE deptno = 10;

-- send any query to Oracle and get its result set
SELECT * FROM oracle_query('scott/tiger@dbhost:1521/ORCLPDB1',
                           'SELECT deptno, COUNT(*) n FROM emp GROUP BY deptno');

-- copy into DuckDB
CREATE TABLE emp AS FROM oracle_scan('scott/tiger@dbhost:1521/ORCLPDB1', 'SCOTT.EMP');

-- DDL / DML / PL/SQL on the Oracle side (autocommits)
SELECT * FROM oracle_execute('scott/tiger@dbhost:1521/ORCLPDB1', 'UPDATE emp SET sal = sal * 1.1');

Quick start on Windows (prebuilt)

Every push to main builds the extension for Windows x64 and publishes it as a release on git.markow.dev/daniel/oracle-duck/releases. You don't need Rust or a local build.

  1. Install Oracle Instant Client for Windows x64. Download Basic Light or Basic from Oracle's Instant Client downloads and unzip it, for example to C:\oracle\instantclient_23_26. Also install the Microsoft Visual C++ Redistributable that the download page lists for that version.

  2. Put it on PATH for the DuckDB process. Either set it permanently (System Properties → Environment Variables) or set it in the shell you start DuckDB from:

    $env:PATH = "C:\oracle\instantclient_23_26;$env:PATH"
    # alternatively: $env:ORACLE_CLIENT_LIB_DIR = "C:\oracle\instantclient_23_26"
    
  3. Install and load the extension in a DuckDB started with -unsigned. Installing needs DuckDB's httpfs extension for HTTPS, which DuckDB autoloads:

    duckdb -unsigned
    
    INSTALL 'https://git.markow.dev/daniel/oracle-duck/releases/download/latest/oracle.duckdb_extension';
    LOAD oracle;
    
    SELECT * FROM oracle_query('scott/tiger@dbhost:1521/ORCLPDB1', 'SELECT sysdate FROM dual');
    

    The latest URL always points to the newest build. To pin a version, replace latest with a release tag such as v0.1.0.7. Run the INSTALL again (with FORCE INSTALL) to update. After installing, later sessions only need LOAD oracle;.

    Without internet access from DuckDB, download oracle.duckdb_extension from the release page and run INSTALL 'C:\path\to\oracle.duckdb_extension';. Keep the file name: DuckDB derives the extension name from it.

Requirements

  • Oracle Instant Client (Basic or Basic Light, 19c or newer) for the platform DuckDB runs on. It's loaded at runtime, not at build time, so building needs no Oracle software. On Linux it also needs libaio (libaio1 / libaio1t64 / libaio).

  • The Instant Client directory must be findable by the dynamic loader before DuckDB starts. On Windows, use PATH (see above). On Linux:

    export LD_LIBRARY_PATH=/opt/oracle/instantclient_23_26:$LD_LIBRARY_PATH   # Linux
    # or: echo /opt/oracle/instantclient_23_26 | sudo tee /etc/ld.so.conf.d/oracle.conf && sudo ldconfig
    

    ORACLE_CLIENT_LIB_DIR is also honoured (it's passed to ODPI-C). It's enough on macOS and Windows. On Linux, Instant Client's own libraries have no RUNPATH, so LD_LIBRARY_PATH or ldconfig is still needed.

  • ORACLE_CLIENT_CONFIG_DIR (or the standard TNS_ADMIN) points at tnsnames.ora / sqlnet.ora / a wallet.

Build

Rust is managed with mise (.mise.toml).

mise install
mise exec -- make release      # -> build/release/oracle.duckdb_extension
mise exec -- make debug        # -> build/debug/oracle.duckdb_extension
mise exec -- make test clippy  # unit tests + lints

make runs cargo build and then scripts/append_metadata.py, which appends DuckDB's extension metadata footer (platform, C API version, extension version). The platform is detected from uname -m (linux_amd64 / linux_arm64). Override it with make PLATFORM=....

Cross-compiling for Windows

sudo apt-get install mingw-w64              # Debian/Ubuntu
rustup target add x86_64-pc-windows-gnu
mise exec -- make windows                   # -> build/windows_amd64/oracle.duckdb_extension

The linker and static C runtime are set in .cargo/config.toml, so the DLL only depends on system DLLs. The DuckDB C API is a plain C ABI, so a mingw-built extension loads in the official (MSVC-built) DuckDB for Windows.

CI / releases

.forgejo/workflows/release.yml runs on every push to main, on v* tags, and on manual dispatch. It runs the unit tests, cross-compiles the Windows extension, checks its exports and DLL dependencies, and publishes oracle.duckdb_extension as a Forgejo release. On a branch push the tag is v<Cargo version>.<run number>; on a tag push it's the tag itself. Only the newest 4 releases are kept.

Loading the extension in DuckDB

The extension is unsigned (only extensions from DuckDB's own repositories are signed). DuckDB refuses unsigned extensions unless you allow them when it starts. You can't enable this later with SET in a running session.

DuckDB CLI

Start the shell with -unsigned and the Instant Client directory on LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=/opt/oracle/instantclient_23_26:$LD_LIBRARY_PATH
duckdb -unsigned

Option A: load straight from the build directory, once per session:

LOAD '/path/to/oracle-duck/build/release/oracle.duckdb_extension';

Option B: install once, then load by name. INSTALL copies the file to ~/.duckdb/extensions/<duckdb version>/<platform>/. After that, LOAD oracle works in any session started with -unsigned:

INSTALL '/path/to/oracle-duck/build/release/oracle.duckdb_extension';
LOAD oracle;

Re-run INSTALL (with FORCE INSTALL if needed) after rebuilding, and again after upgrading DuckDB, because the install directory is per DuckDB version.

Check that it's loaded:

SELECT function_name FROM duckdb_functions() WHERE function_name LIKE 'oracle%';
-- oracle_execute, oracle_query, oracle_scan

SELECT * FROM oracle_query('scott/tiger@dbhost:1521/ORCLPDB1', 'SELECT sysdate FROM dual');

As a one-liner:

LD_LIBRARY_PATH=/opt/oracle/instantclient_23_26 duckdb -unsigned \
  -c "LOAD oracle" \
  -c "SELECT * FROM oracle_scan('scott/tiger@dbhost:1521/ORCLPDB1', 'EMP')"

Client APIs (Python, etc.)

Set allow_unsigned_extensions in the connection config:

import duckdb  # start Python with LD_LIBRARY_PATH pointing at Instant Client
con = duckdb.connect(config={"allow_unsigned_extensions": "true"})
con.load_extension("/path/to/oracle-duck/build/release/oracle.duckdb_extension")
con.sql("SELECT * FROM oracle_query('scott/tiger@dbhost:1521/ORCLPDB1', 'SELECT 1 FROM dual')").show()

Troubleshooting

Error Cause / fix
... signature is either missing or invalid and unsigned extensions are disabled start DuckDB with -unsigned / allow_unsigned_extensions=true
DPI-1047: Cannot locate a 64-bit Oracle Client library Linux: Instant Client (or its libnnz.so / libaio.so.1) isn't on LD_LIBRARY_PATH of the DuckDB process. Windows: the Instant Client directory isn't on PATH, it's a 32-bit client, or the Visual C++ Redistributable is missing
... built for platform X, but DuckDB is Y rebuild on the same OS/architecture as DuckDB, or pass make PLATFORM=...
ORA-12541 / ORA-12514 / ORA-01017 Oracle-side: no listener, unknown service name, bad credentials

Functions

Function Returns
oracle_query(connect, sql, [user, password, array_size]) the rows of a SELECT / WITH query, run as-is on Oracle
oracle_scan(connect, table, [filter, user, password, array_size]) the rows of a table/view; projection pushdown; filter becomes the WHERE clause
oracle_execute(connect, sql, [user, password]) one row, rows_affected BIGINT, after running DDL, DML or a PL/SQL block and committing
  • connect works like SQL*Plus: user/password@connect_identifier. The connect identifier can be EZConnect (host:port/service, //host/service, EZConnect Plus with options), a tnsnames.ora alias, or a full (DESCRIPTION=...) descriptor. /@alias uses external authentication (for example an Oracle wallet).
  • The user / password named parameters override the credentials in the string. The fallbacks are the ORACLE_USER / ORACLE_PASSWORD environment variables. To keep passwords out of query text, use DuckDB variables: SET VARIABLE ora = 'scott/tiger@db/pdb'; SELECT * FROM oracle_scan(getvariable('ora'), 'EMP');
  • table is inserted into SQL verbatim, so it follows Oracle's identifier rules. emp, SCOTT.EMP and "MixedCase" all work. Column names come back as Oracle reports them (usually upper case).
  • array_size is the number of rows per network round trip (default 1000). It's also used as the prefetch size.
  • oracle_query and oracle_scan refuse anything that isn't a query before executing it. Use oracle_execute for writes.

Type mapping

Oracle DuckDB
NUMBER(p,0), p ≤ 9 INTEGER
NUMBER(p,0), 10 ≤ p ≤ 18 BIGINT
NUMBER(p,0), 19 ≤ p ≤ 38 (incl. INTEGER) DECIMAL(p,0)
NUMBER(p,s), s > 0 DECIMAL(max(p,s), s), exact
NUMBER (no precision), FLOAT, BINARY_DOUBLE DOUBLE
BINARY_FLOAT FLOAT
VARCHAR2, NVARCHAR2, CHAR, NCHAR, CLOB, NCLOB, LONG, ROWID, XMLTYPE, JSON VARCHAR
RAW, LONG RAW, BLOB BLOB
DATE, TIMESTAMP TIMESTAMP (Oracle DATE has a time part; fractions beyond µs are truncated)
TIMESTAMP WITH [LOCAL] TIME ZONE TIMESTAMPTZ (converted to UTC)
INTERVAL DAY TO SECOND, INTERVAL YEAR TO MONTH INTERVAL
BOOLEAN (23ai) BOOLEAN

Other types (objects, collections, BFILE, REF CURSOR) produce an error. Convert them in SQL (TO_CHAR, JSON_SERIALIZE, ...) inside oracle_query.

Expressions in oracle_query such as COUNT(*) or SUM(x) have the unconstrained NUMBER type and arrive as DOUBLE. Use CAST(COUNT(*) AS NUMBER(18)) for an integer.

Limitations

  • No ATTACH. DuckDB's C extension API (the stable ABI that Rust extensions use) doesn't expose storage extensions or catalogs, so access goes through table functions.
  • No automatic filter pushdown. The C API doesn't pass filters to table functions. DuckDB applies WHERE clauses after fetching. To filter on the Oracle side, use filter := '...' or oracle_query. Projection is pushed down in oracle_scan.
  • Each scan opens its own session and reads on one thread.
  • oracle_query executes the statement during bind to learn its result columns. That cursor is reused for the actual scan, but DESCRIBE or PREPARE also runs the query once.
  • Dates before 1582-10-15 (Oracle uses the Julian calendar there; DuckDB uses proleptic Gregorian) and BC dates aren't converted.

Tests

mise exec -- make test   # unit tests: connect-string parsing, NUMBER parsing, type mapping, dates
ORACLE_TEST_DSN='scott/tiger@dbhost:1521/ORCLPDB1' LD_LIBRARY_PATH=/opt/oracle/instantclient_23_26 \
  mise exec -- make integration PYTHON=/path/to/python-with-duckdb

test/integration.py needs the duckdb Python package. It loads the extension and checks registration and connection errors offline. With ORACLE_TEST_DSN set, it creates DUCKDB_ORACLE_IT with every supported type and checks values, NULLs, projection, count(*), filter, joins, multi-chunk fetches, credentials and error paths, then drops the table. The test user needs CREATE TABLE.

License

MIT © 2026 Daniel Markow.

This repository contains no Oracle software. Oracle Instant Client is downloaded separately and is covered by Oracle's own license terms. ODPI-C, which the oracle crate compiles in, is licensed under UPL 1.0 / Apache 2.0.