ArpeDb2
v0.4.0Linux · Windows (x64)On-premise
A native ADBC driver for IBM Db2, written in C, returning Apache Arrow
RecordBatches end to end. It speaks the DRDA (Distributed Relational
Database Architecture) wire protocol directly over TCP or TLS, so you don't
need a Db2 client, CLI/ODBC or JCC on the machine. The released binaries are
self-contained: OpenSSL is linked in, and nothing beyond the operating system's
C library is needed at runtime. It is validated on Db2 for LUW 12.1 and on
Db2 for i (IBM i 7.5); see
Compatibility.
Reading these docs. The badge above is the version this documentation describes. Options and features added recently are flagged inline with a Since vX.Y.Z note; the What's new page is the release-by-release view. See Versioning.
Highlights
- Native DRDA. The driver builds and parses the Db2 wire format itself and runs the logon, the queries and the loads on its own socket. A new query costs one network round trip, and a large result is read one block ahead of the decoder.
- Db2 for LUW and Db2 for i. One driver for both families: it recognises the server at connect and adapts the catalog queries, the text encoding (EBCDIC CCSIDs on IBM i) and the package handling. Db2 for z/OS is not supported yet.
- Password, Kerberos and token logons. User and password with the
encrypted logon negotiated by default, Kerberos (
auth.mechanism=kerberos), and an access token or API key sent as the password over verified TLS. - TLS 1.2 / 1.3.
sslmodefromrequiretoverify-full, with the system trust store or your own CA file. - Arrow-native extract. Result rows are decoded straight into Arrow column
buffers, 32000 rows per batch by default.
DECIMALbecomesdecimal128(p,s), LOBs andXMLare read in bounded memory, and every column carries its Db2 type in the Arrow field metadata. - Bound parameters and bulk ingest.
?markers on queries and DML, many rows per round trip, andadbc_ingestincreate,append,replaceandcreate_appendmodes, with periodic commits for parallel loads and an optional list of rejected rows. - Stored procedures.
CALLwithIN,OUTandINOUTparameters and several result sets. - Built for unattended jobs. Alternate servers and connect retry for HADR, TCP keepalive, login and query timeouts, cancel, and a protocol trace for support.
- Load name
arpedb2. Options live underadbc.arpedb2.*.
Connect in seconds
Load the driver by name (arpedb2) from any ADBC client, with discrete
options as below, an ADO.NET connection string, or a db2:// URI (see
Three ways to connect).
- Python
- C / C++
- C#
- Go
- Java
- R
- Rust
import adbc_driver_manager.dbapi as dbapi
with dbapi.connect(driver="arpedb2", db_kwargs={
"adbc.arpedb2.server": "db2.example.com",
"adbc.arpedb2.port": "50000",
"adbc.arpedb2.database": "sample",
"adbc.arpedb2.username": "db2inst1",
"adbc.arpedb2.password": "<pw>",
}, autocommit=True) as conn:
cur = conn.cursor()
cur.execute("SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY")
table = cur.fetch_arrow_table()
#include <arrow-adbc/adbc.h>
// (error checks elided for brevity)
AdbcError e = {}; AdbcDatabase db = {}; AdbcConnection conn = {}; AdbcStatement st = {};
AdbcDatabaseNew(&db, &e);
AdbcDatabaseSetOption(&db, "driver", "arpedb2", &e);
AdbcDatabaseSetOption(&db, "adbc.arpedb2.server", "db2.example.com", &e);
AdbcDatabaseSetOption(&db, "adbc.arpedb2.port", "50000", &e);
AdbcDatabaseSetOption(&db, "adbc.arpedb2.database", "sample", &e);
AdbcDatabaseSetOption(&db, "adbc.arpedb2.username", "db2inst1", &e);
AdbcDatabaseSetOption(&db, "adbc.arpedb2.password", "<pw>", &e);
AdbcDatabaseInit(&db, &e);
AdbcConnectionNew(&conn, &e); AdbcConnectionInit(&conn, &db, &e);
AdbcStatementNew(&conn, &st, &e);
AdbcStatementSetSqlQuery(&st, "SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY", &e);
ArrowArrayStream stream = {}; int64_t n = -1;
AdbcStatementExecuteQuery(&st, &stream, &n, &e); // consume `stream`
using Apache.Arrow.Adbc;
using Apache.Arrow.Adbc.DriverManager;
using var driver = AdbcDriverManager.FindLoadDriver("arpedb2", loadOptions: AdbcLoadFlags.Default);
using var database = driver.Open(new Dictionary<string, string> {
["adbc.arpedb2.server"] = "db2.example.com",
["adbc.arpedb2.port"] = "50000",
["adbc.arpedb2.database"] = "sample",
["adbc.arpedb2.username"] = "db2inst1",
["adbc.arpedb2.password"] = "<pw>" });
using var connection = database.Connect(null);
using var statement = connection.CreateStatement();
statement.SqlQuery = "SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY";
using var stream = statement.ExecuteQuery().Stream!; // IArrowArrayStream
var drv drivermgr.Driver
db, _ := drv.NewDatabase(map[string]string{
"driver": "arpedb2",
"adbc.arpedb2.server": "db2.example.com",
"adbc.arpedb2.port": "50000",
"adbc.arpedb2.database": "sample",
"adbc.arpedb2.username": "db2inst1",
"adbc.arpedb2.password": "<pw>",
})
conn, _ := db.Open(ctx)
stmt, _ := conn.NewStatement()
_ = stmt.SetSqlQuery("SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY")
reader, _, _ := stmt.ExecuteQuery(ctx) // array.RecordReader
defer reader.Release()
Map<String, Object> params = new HashMap<>();
JniDriver.PARAM_DRIVER.set(params, "arpedb2");
params.put("adbc.arpedb2.server", "db2.example.com");
params.put("adbc.arpedb2.port", "50000");
params.put("adbc.arpedb2.database", "sample");
params.put("adbc.arpedb2.username", "db2inst1");
params.put("adbc.arpedb2.password", "<pw>");
try (BufferAllocator a = new RootAllocator();
AdbcDatabase db = new JniDriver(a).open(params);
AdbcConnection conn = db.connect();
AdbcStatement st = conn.createStatement()) {
st.setSqlQuery("SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY");
try (AdbcStatement.QueryResult r = st.executeQuery()) {
ArrowReader reader = r.getReader();
}
}
library(adbcdrivermanager)
db <- adbc_database_init(adbc_driver("arpedb2"),
adbc.arpedb2.server = "db2.example.com",
adbc.arpedb2.port = "50000",
adbc.arpedb2.database = "sample",
adbc.arpedb2.username = "db2inst1",
adbc.arpedb2.password = "<pw>")
con <- adbc_connection_init(db)
table <- read_adbc(con, "SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY") |> arrow::as_arrow_table()
use adbc_core::{Connection, Database, Driver, Statement, LOAD_FLAG_DEFAULT};
use adbc_core::options::{AdbcVersion, OptionDatabase, OptionValue};
use adbc_driver_manager::ManagedDriver;
let mut driver = ManagedDriver::load_from_name("arpedb2", None, AdbcVersion::default(), LOAD_FLAG_DEFAULT, None)?;
let mut db = driver.new_database_with_opts([
(OptionDatabase::Other("adbc.arpedb2.server".into()), OptionValue::String("db2.example.com".into())),
(OptionDatabase::Other("adbc.arpedb2.port".into()), OptionValue::String("50000".into())),
(OptionDatabase::Other("adbc.arpedb2.database".into()), OptionValue::String("sample".into())),
(OptionDatabase::Other("adbc.arpedb2.username".into()), OptionValue::String("db2inst1".into())),
(OptionDatabase::Other("adbc.arpedb2.password".into()), OptionValue::String("<pw>".into())),
])?;
let mut conn = db.new_connection()?;
let mut stmt = conn.new_statement()?;
stmt.set_sql_query("SELECT * FROM SYSCAT.TABLES FETCH FIRST 10 ROWS ONLY")?;
let reader = stmt.execute()?; // impl RecordBatchReader
TLS is opt-in: with the default sslmode=disable the connection is not
encrypted. The driver then asks the server for the encrypted password logon
first. When the server does not offer it (the Db2 default,
AUTHENTICATION=SERVER), the password is sent in clear and the driver prints
this line once on standard error:
ArpeDb2: sending a clear-text password over an UNENCRYPTED connection (the server does not offer encrypted password logon); an active network attacker could capture it. Use TLS (adbc.arpedb2.sslmode=require or higher) or set adbc.arpedb2.require_password_encryption to refuse.
To protect the password and the data, point adbc.arpedb2.port at the
server's SSL port and set adbc.arpedb2.sslmode to verify-full, plus
adbc.arpedb2.sslrootcert if the server's CA is not in the system store: see
TLS.
New here? Install ArpeDb2 first, then see the Connection guide.