ArpeDb2 — Compatibility
Which IBM Db2 families, versions and client platforms ArpeDb2 is known to work with. Three support states are used across the Arpeio driver family:
| State | Meaning |
|---|---|
| ✅ Validated | Tested directly against this target before release. |
| 🟢 Supported | Expected to work and covered by the same protocol surface, but not run continuously. Report issues and they will be treated as bugs. |
| 🟡 Not yet validated | Should be compatible on protocol grounds, but unverified. No promise yet. |
ArpeDb2 speaks the DRDA wire protocol natively over TCP (with optional TLS), without a Db2 client, CLI/ODBC or JCC. The type mapping is in Data types.
Db2 families
DRDA is one protocol for three Db2 families, which differ in catalog, type mapping and text encoding. The driver recognises the family from the product identifier the server sends at connect.
| Family | State | Notes |
|---|---|---|
| Db2 for LUW (Linux, UNIX, Windows) | ✅ Validated | The full feature set. |
| Db2 for i (IBM i, AS/400) | ✅ Validated on IBM i 7.5 | Queries, DML, bound parameters, bulk ingest, CALL, metadata and statistics. See Db2 for i. Since v0.3.3. |
| Db2 for z/OS | ❌ Not supported | Not implemented yet. |
Db2 for LUW versions
| Version | State | Notes |
|---|---|---|
| Db2 12.1 | ✅ Validated | Including VECTOR columns (12.1.2 and later). |
| Db2 11.5 | 🟢 Supported | Same DRDA surface and type set as the validated version. |
| Db2 11.1 and earlier | 🟡 Not yet validated | Older DRDA levels; untested. |
Db2 for i
Validated on IBM i 7.5. What to know before you connect:
- Port. The DRDA server of IBM i listens on 446, and on 448 for TLS. Set
adbc.arpedb2.portaccordingly. - Package. Every statement runs in a DRDA package, and IBM i has none until a client binds it. The driver binds its package once, in your job's current library, the first time it is needed. Binding needs the authority to create objects in that library. See Packages.
- Text.
CHARandVARCHARcolumns arrive in each column's CCSID (EBCDIC, including the Japanese, Chinese and Korean code pages) and are converted to UTF-8. See Character. - Types. The built-in Db2 for i types all read. The differences from Db2
for LUW (
BOOLEAN,ROWID,DATALINK,NUMERIC, decimals wider than 31 digits) are in Data types. - Isolation level. The four ADBC levels and
defaultwork, each through its own package. See Isolation level. - Writes to a table that is not journaled fail with
SQLCODE -7008under every isolation level but no-commit. Set the isolation level toadbc.arpedb2.transaction.isolation.no_commit, addWITH NCto the statement, or journal the table. See Troubleshooting. - Metadata on a shared system.
GetObjectsandGetStatisticsread theQSYS2catalog and list only the libraries you can see. The system libraries (QSYS,QSYS2,SYSIBM,SYSIBMADM,SYSPROC,SYSTOOLS) are left out unless thedb_schemafilter names one exactly. An unfiltered call still reads every library you can see: pass a schema filter. - Statistics. The row count comes from
QSYS2.SYSTABLESTAT, which the system keeps current. Null and distinct counts come fromQSYS2.SYSCOLUMNSTAT, which only has rows for columns the system has collected statistics on.
Authentication methods
| Method | Platform | State |
|---|---|---|
| User and password | all | ✅ Validated |
| Encrypted user and password (AES or DES) | all | ✅ Validated, against Db2 12.1 SERVER_ENCRYPT and Db2 for i |
| Kerberos | Linux | ✅ Validated. MIT Kerberos is loaded from the host. |
| Kerberos | Windows (SSPI) | 🟡 Not yet validated against Active Directory |
| Token or API key as the password, over verified TLS | all | 🟢 Supported |
TLS 1.2 / 1.3 (require, verify-ca, verify-full) | all | ✅ Validated |
| Client certificates (mutual TLS) | — | ❌ Not supported |
See Authentication for the setup of each.
Client platforms
| Platform | State | Notes |
|---|---|---|
| Linux x64 | ✅ Validated | Self-contained .so: OpenSSL is linked in. glibc 2.28 or newer (RHEL 8, Rocky 8 and later distributions). |
| Windows x64 | 🟢 Supported | Self-contained .dll: OpenSSL is linked in, and TLS trusts the Windows certificate store. |
| macOS, Linux arm64 | ❌ Not supported | No released binary. |
ADBC conformance
ArpeDb2 implements the ADBC 1.1.0 API and passes the upstream ADBC driver validation suite with no failure. The tests it does not run are Db2 limitations or calls the driver reports as not implemented.
| Area | State |
|---|---|
ExecuteQuery, ExecuteUpdate | Implemented. Large results stream with bounded memory. |
ExecuteSchema | Implemented, without running the query. |
Prepare, Bind, BindStream | Implemented for queries and DML. A query takes one parameter row; DML takes many, sent many rows per round trip. |
GetParameterSchema | Implemented: the types the server describes for each ?. |
| Stored procedures | CALL with IN, OUT and INOUT parameters (LOBs included) and several result sets. See Examples. |
| Bulk ingest | create, append, replace, create_append, a target schema, temporary tables. See Bulk ingest. |
| Transactions | Autocommit on by default, Commit, Rollback, isolation levels. See Transactions. |
Cancel (statement and connection) | Implemented. The connection must be reopened afterwards: see Cancelling a request. |
GetInfo | Implemented. |
GetObjects | Implemented, with LIKE pattern filters. Constraints: PRIMARY KEY, UNIQUE, FOREIGN KEY and CHECK. System schemas are left out unless the db_schema filter names one exactly. |
GetTableSchema | Implemented, with the same mapping and ARPEDB2:type metadata as a query. |
GetTableTypes | Implemented. |
GetStatistics, GetStatisticNames | Row, null and distinct counts from the catalog statistics, marked approximate, or exact counts with approximate=false. On Db2 for LUW the catalog statistics are filled by RUNSTATS. |
| Current schema | Readable and settable through adbc.connection.db_schema. |
ExecutePartitions, ReadPartition | ❌ Not supported. |
| Substrait plans | ❌ Not supported. |
Bulk ingest
Ingest uses the standard ADBC options (adbc.ingest.target_table,
adbc.ingest.target_db_schema, adbc.ingest.mode, adbc.ingest.temporary)
on a statement with data bound by Bind or BindStream, and sends the rows
as parameterised INSERT requests of up to 1000 rows each. The column types
it creates are in
Data types → Ingest.
- Under autocommit, the load is one unit of work, committed at the end, or
every
adbc.arpedb2.ingest.commit_interval_rowsrows. A load that fails is rolled back, except for the rows such an interval already committed. - With autocommit off, the load joins your transaction, DDL included: a
Rollbackundoes the rows and theCREATE TABLEorDROP TABLEof the load. A failed load rolls back to a savepoint and leaves your earlier work in the transaction untouched. replacedrops the existing table only after it has checked that the new one can be created: a column type the driver cannot create leaves the existing table as it was.- Temporary ingest creates a declared global temporary table in
SESSION. It needs a user temporary table space and cannot be combined withadbc.ingest.target_catalogoradbc.ingest.target_db_schema. - Parallel loads into one table need
ingest.commit_interval_rows: see Parallel loads. - Bad rows can be set aside instead of failing the load: see Rejected rows.
Errors
A Db2 error carries the SQLCODE as the vendor code and the SQLSTATE of the server. The ADBC status is chosen from the SQLSTATE:
| SQLSTATE | Example | ADBC status |
|---|---|---|
42704, 42703, 42883, 42884 | SQLCODE -204 (undefined name), -206 (undefined column), -440 (no such routine) | NOT_FOUND |
42710 | SQLCODE -601 (object already exists) | ALREADY_EXISTS |
42501 | SQLCODE -551 (not authorized) | UNAUTHORIZED |
42xxx, other | SQLCODE -104 (syntax) | INVALID_ARGUMENT |
23xxx | SQLCODE -803 (duplicate key), -407 (NULL in a NOT NULL column) | INTEGRITY |
22xxx | SQLCODE -802 (arithmetic overflow), -302 (value too large) | INVALID_DATA |
28xxx | wrong user or password | UNAUTHENTICATED |
08xxx | connection lost | IO |
57014 | SQLCODE -952 (processing cancelled) | CANCELLED |
40001 | SQLCODE -911 (deadlock or lock timeout: the transaction was rolled back, retry it) | UNKNOWN |
The SQLCODE and SQLSTATE are also set on an error raised while a result is being read, so retry logic can rely on them.
See also
- Connection: connecting to each of the above
- Authentication: logon mechanisms and TLS
- Data types: the Db2 ↔ Arrow type mapping
- Troubleshooting: when a supported target does not connect