- Rust 76.2%
- Python 20.2%
- Makefile 3.6%
|
All checks were successful
Build & Release Windows Extension / Build oracle.duckdb_extension (windows_amd64) & Publish Release (push) Successful in 4m24s
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> |
||
|---|---|---|
| .cargo | ||
| .forgejo/workflows | ||
| scripts | ||
| src | ||
| test | ||
| .gitignore | ||
| .mise.toml | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
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.
-
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. -
Put it on
PATHfor 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" -
Install and load the extension in a DuckDB started with
-unsigned. Installing needs DuckDB'shttpfsextension for HTTPS, which DuckDB autoloads:duckdb -unsignedINSTALL '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
latestURL always points to the newest build. To pin a version, replacelatestwith a release tag such asv0.1.0.7. Run theINSTALLagain (withFORCE INSTALL) to update. After installing, later sessions only needLOAD oracle;.Without internet access from DuckDB, download
oracle.duckdb_extensionfrom the release page and runINSTALL '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 ldconfigORACLE_CLIENT_LIB_DIRis 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, soLD_LIBRARY_PATHorldconfigis still needed. -
ORACLE_CLIENT_CONFIG_DIR(or the standardTNS_ADMIN) points attnsnames.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 |
connectworks like SQL*Plus:user/password@connect_identifier. The connect identifier can be EZConnect (host:port/service,//host/service, EZConnect Plus with options), atnsnames.oraalias, or a full(DESCRIPTION=...)descriptor./@aliasuses external authentication (for example an Oracle wallet).- The
user/passwordnamed parameters override the credentials in the string. The fallbacks are theORACLE_USER/ORACLE_PASSWORDenvironment 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'); tableis inserted into SQL verbatim, so it follows Oracle's identifier rules.emp,SCOTT.EMPand"MixedCase"all work. Column names come back as Oracle reports them (usually upper case).array_sizeis the number of rows per network round trip (default 1000). It's also used as the prefetch size.oracle_queryandoracle_scanrefuse anything that isn't a query before executing it. Useoracle_executefor 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
WHEREclauses after fetching. To filter on the Oracle side, usefilter := '...'ororacle_query. Projection is pushed down inoracle_scan. - Each scan opens its own session and reads on one thread.
oracle_queryexecutes the statement during bind to learn its result columns. That cursor is reused for the actual scan, butDESCRIBEorPREPAREalso 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.