ArpeOracle — Connection guide

Everything you can put in front of ArpeOracle to point it at an Oracle database, in one place: the three ways to supply connection details, every option the driver accepts, and the Oracle-specific rules (EZConnect, SID vs service name, TCPS wallets, Oracle Cloud Autonomous Database).

For how each authentication method works (O5LOGON, OCI IAM token, OAuth2/Entra ID, proxy, change-password, TLS), see Authentication. For the licence, see Licensing.

---

Three ways to connect

Every driver in the Arpeio family accepts the same three connection forms. They can be mixed; a discrete option always wins over the same field taken from a connection_string or a uri, regardless of the order they are set.

Form	Option key	Grammar	Best for
Discrete options	adbc.arpeoracle.<field>	one option per field	programmatic clients, secrets kept out of a single string
Connection string	adbc.arpeoracle.connection_string	ADO.NET Key=Value;… (+ Oracle EZConnect in Server)	pasting an existing string
Connection URI	uri	oracle://… URL	portable tooling, copy-paste from other Oracle ADBC tools

Python

import adbc_driver_manager.dbapi as dbapi

# Discrete options
conn = dbapi.connect(driver="arpeoracle", db_kwargs={
    "adbc.arpeoracle.server":       "localhost",
    "adbc.arpeoracle.port":         "1521",
    "adbc.arpeoracle.service_name": "orclpdb1",
    "adbc.arpeoracle.username":     "scott",
    "adbc.arpeoracle.password":     "tiger",
})

# Connection string (ADO.NET keywords, or Oracle EZConnect in Server)
conn = dbapi.connect(driver="arpeoracle", db_kwargs={
    "adbc.arpeoracle.connection_string":
        "Server=localhost:1521/orclpdb1;User ID=scott;Password=tiger",
})

# Connection URI (Oracle URL grammar)
conn = dbapi.connect(driver="arpeoracle", db_kwargs={
    "uri": "oracle://scott:tiger@localhost:2484/orclpdb1?ssl_mode=verify-full",
})

Precedence is per field: a field parsed from connection_string/uri is applied only if no discrete adbc.arpeoracle.* option already set it.

---

Option reference

All options are string-typed and live under the adbc.arpeoracle.* namespace. Set them as ADBC database options before the connection is opened. Statement and ingest options are set on the statement — see Statement & ingest options.

Target — where to connect

Option	Default	Meaning
adbc.arpeoracle.server	—	Host name or IP. Also accepts an Oracle EZConnect descriptor (host:port/service, see EZConnect), a full (DESCRIPTION=…) TNS descriptor, or a tnsnames.ora alias.
adbc.arpeoracle.tns_admin	—	Directory holding tnsnames.ora, for alias resolution. Unset: TNS_ADMIN, then $ORACLE_HOME/network/admin. Since v0.3.11.
adbc.arpeoracle.port	1521	TCP port, 1..65535. TCPS listeners conventionally use 2484 — set it explicitly.
adbc.arpeoracle.service_name	—	Oracle service name / PDB. The usual way to name a database.
adbc.arpeoracle.sid	—	Oracle SID. Selects a different CONNECT_DATA form on the wire — mutually exclusive with service_name: as discrete options, whichever is set last wins; in a connection string or uri, giving both is rejected.
adbc.arpeoracle.app_name	ArpeOracle	Program name reported to the server: V$SESSION.PROGRAM (and MODULE, which defaults from it) and the connect descriptor (since v0.3.6; before that it only reached the connect descriptor). V$SESSION_CONNECT_INFO.CLIENT_DRIVER always reports the driver itself (ArpeOracle <version>).

Authentication

Full method-by-method detail is in Authentication.

Option	Values	Meaning
adbc.arpeoracle.username / .password	string	Oracle credentials (O5LOGON challenge-response — the password is never sent in clear, even without TLS). The bare keys username / password are accepted as aliases.
adbc.arpeoracle.auth_method	password (default) / token / oauth2	Selects the login method. Only oauth2 is auto-selected, when access_token or token_file is set (an explicit non-oauth2 auth_method alongside them is rejected). token must be set explicitly.
adbc.arpeoracle.proxy_user	schema	Authenticate as username, open the session in this user's schema via Oracle CONNECT THROUGH proxy.
adbc.arpeoracle.new_password	string	Change username's password as part of login — the way in past an expired one.
adbc.arpeoracle.token_location	dir	OCI IAM database token: directory holding the token and its PEM private key (as oci iam db-token get writes). Used with auth_method=token, which must be set explicitly — this option alone does not select it.
adbc.arpeoracle.access_token	JWT	OAuth2 / Microsoft Entra ID bearer token, inline. Selects auth_method=oauth2.
adbc.arpeoracle.token_file	path	Same OAuth2 bearer token, read from a file (inline access_token wins if both are set).

Encryption / TLS (TCPS)

Option	Default	Meaning
adbc.arpeoracle.ssl_mode	disable	disable (plain TCP) / require (encrypt, cert not verified) / verify-ca (chain verified) / verify-full (chain and hostname — use this one).
adbc.arpeoracle.ssl_root_cert	—	PEM CA bundle for verify-ca/verify-full (else the CAs in the wallet, else OpenSSL's default locations: see Authentication → TLS).
adbc.arpeoracle.wallet_location	—	Directory holding ewallet.pem (client key + cert + CAs), python-oracledb-thin layout. This is exactly an unzipped Oracle Cloud ADB wallet.
adbc.arpeoracle.wallet_password	—	Unlocks an encrypted key inside the wallet.

TLS 1.2 is the minimum protocol version. wallet_location or ssl_root_cert together with ssl_mode=disable is rejected at connect rather than silently ignored — set ssl_mode as well. See Authentication → TLS for the TLS version floor, where trusted certificates come from on each OS, SNI and mutual TLS.

ssl_mode is disable by default, and the default NNE stance (accepted, below) encrypts only when the server requests or requires it — against a server left at its ACCEPTED default the connection is plaintext. O5LOGON keeps the password off the wire, but SQL text and result data are in clear until you set ssl_mode, set encryption=requested/required, or the server asks for Native Network Encryption.

Native Network Encryption (NNE)

Version

Since ArpeOracle v0.1.3.

Oracle's transport-layer encryption, negotiated after ACCEPT — no TCPS required. See Authentication for the other ways to protect a connection.

Option	Values	Meaning
adbc.arpeoracle.encryption	accepted (default) / rejected / requested / required	Client stance for AES-256 payload encryption (Oracle's SQLNET.ENCRYPTION_CLIENT). required fails the connect if the server will not encrypt.
adbc.arpeoracle.data_integrity	same four values	Client stance for the SHA-256 (or SHA-1) integrity checksum (Oracle's SQLNET.CRYPTO_CHECKSUM_CLIENT).

Values are case-insensitive. The stances behave exactly like Oracle's own clients (ODP.NET, OCI): the client offers the service at its level and the server decides. With the default accepted, the result follows the server's SQLNET.ENCRYPTION_SERVER / SQLNET.CRYPTO_CHECKSUM_SERVER:

Client ↓ / Server →	REJECTED	ACCEPTED (server default)	REQUESTED	REQUIRED
rejected	off	off	off	connect fails
accepted (default)	off	off	on	on
requested	off	on	on	on
required	connect fails	on	on	on

Each service is negotiated independently. rejected on both services is the opt-out: native services are not advertised at all and the handshake is the plain one byte-for-byte. Over TCPS an accepted stance does not advertise NNE (the transport is already encrypted); requested/required still do.

Version

Since ArpeOracle v0.3.8, accepted advertises NNE and lets the server decide. Before that, native services were only advertised for requested/required, so a default client got plaintext from a REQUESTED server and failed against a REQUIRED one.

Cost of the default. Advertising means every accepted connection over plain TCP makes one extra ANO round trip at connect — once per connection, so a parallel export pays it on every chunk connection — and a server set to REQUESTED now gets an AES-256 + checksum session by default, which costs throughput on bulk exports. Every encrypted connection negotiates whatever the stance (NNE keys are per session), so only a plaintext outcome can skip the round trip: encryption=rejected + data_integrity=rejected restores the old plaintext handshake with no extra round trip.

Only AES-256 and SHA-256/SHA-1 are offered — the legacy ciphers (DES/3DES/RC4) and MD5 are never proposed.

Timeouts & performance

Option	Default	Meaning
adbc.arpeoracle.login_timeout	30	TCP connect budget in seconds (0 = no limit).
adbc.arpeoracle.socket_timeout	0 (none)	Per-socket read timeout in seconds (0 = no limit).
adbc.arpeoracle.sdu	unset (8192)	Session Data Unit in bytes — the largest TNS DATA packet the driver offers, negotiated down to the server's own maximum. A larger SDU means fewer packets, and so fewer per-packet AES/MAC operations and syscalls, on a big fetch. Left unset, the driver advertises the protocol default (8192) and the CONNECT bytes are unchanged. Range 512..2097152; any other value, 0 included, is rejected.
adbc.arpeoracle.batch_size	32000	Rows per streamed Arrow batch (also Buffer Size in a connection string). A memory knob, not a throughput knob: from about 10,000 rows per batch upward throughput is essentially flat while memory grows linearly with the batch size, so pick the size that suits the consumer. Range 1..10000000.
adbc.arpeoracle.statement_cache_size	20	Number of server cursors held open and reused per connection, keyed by SQL text. Reusing a cursor skips the hard parse and prevents the per-statement cursor leak that would otherwise exhaust OPEN_CURSORS on a long-lived connection. 0 disables reuse (cursors are still closed, just not reused). Matches oracledb's stmtcachesize. Range 0..65535.

Version

adbc.arpeoracle.sdu is configurable since ArpeOracle v0.3.0. It is a database option only (no connection-string or URI keyword).

Type rendering (read path)

Option	Values	Meaning
adbc.arpeoracle.number_mapping	auto (default) / double / decimal:P,S	How Oracle's unconstrained NUMBER maps to Arrow. auto → lossless utf8; double → float64 (lossy); decimal:P,S → decimal128(P,S). See Data types.
adbc.arpeoracle.interval_mapping	parquet (default) / native	How INTERVAL columns map to Arrow (since v0.3.7). parquet → int64 months (YEAR TO MONTH) and utf8 ISO-8601 (DAY TO SECOND), both Parquet-writable; native → Arrow interval(month_day_nano), which has no Parquet representation. See Data types.

Licence

Option	Meaning
arpeio.adbc.license	Licence blob, inline.
arpeio.adbc.license_file	Path to a .lic file.
arpeio.adbc.license.status	Read-only (GetOption); reports <state>;code=<ARROW_LIC_*>;tier=<tier>;expires=<epoch>.

The driver also reads the shared ARPEIO_ADBC_LICENCE[_FILE] environment variables and an arpeio_adbc.lic file next to the library. Full resolution order in Licensing.

Standard ADBC connection options

These use the ADBC-standard keys (no arpeoracle namespace):

Option	Values	Meaning
adbc.connection.autocommit	true (default) / false	Autocommit mode, set on the connection (exactly true or false). With it off, Connection.Commit / Rollback drive an explicit transaction; with it on they are rejected. Switching it back on commits any open transaction.
adbc.connection.catalog	read-only	Reports the connected service name (an Oracle session reaches one catalog only).
adbc.connection.db_schema	read-only	Reports the current schema: the login username, upper-cased as Oracle folds it.

adbc.connection.autocommit is the only option that can be set on a connection; any other connection key is rejected (NOT_IMPLEMENTED).

Statement & ingest options

Set on the statement handle, not the database:

Option	Default	Meaning
arpeoracle.sdo.srid	—	Read path. Force a specific SRID onto every MDSYS.SDO_GEOMETRY (geoarrow.wkb) column in the result, overriding whatever SRID is stored in the geometry, and applied even when the result has no rows to inspect. A non-numeric, zero, negative, or out-of-range value is rejected with ADBC_STATUS_INVALID_ARGUMENT. Without it the driver surfaces each geometry column's own stored SDO_SRID. Since v0.3.1 (named arrowttc.sdo.srid until v0.3.3). See Data types.
arpeoracle.sdo.spatial_index	true	Ingest. true / false. After an ingest that writes geoarrow.wkb columns, register each one in USER_SDO_GEOM_METADATA and create its spatial index. A registration failure (e.g. a missing privilege) is reported as an error naming this option. No effect when the ingested data has no geometry column. Since v0.3.1 (named arrowttc.sdo.spatial_index until v0.3.3).
adbc.ingest.target_table	—	Target table for adbc_ingest.
adbc.ingest.mode	adbc.ingest.mode.create	adbc.ingest.mode.create / adbc.ingest.mode.append / adbc.ingest.mode.replace / adbc.ingest.mode.create_append (the ADBC-standard values; any other value is rejected).
adbc.ingest.target_db_schema	—	Target schema for ingest.
adbc.ingest.target_catalog	—	Oracle reaches one catalog per session; the connected service name is accepted, any other value is rejected (NOT_IMPLEMENTED).
adbc.ingest.temporary	false	Ingest into a GLOBAL TEMPORARY table (ON COMMIT PRESERVE ROWS). Only the exact value true enables it; anything else means false.

Setting a new SQL query on the statement clears the ingest options (target, mode, schema, temporary, and arpeoracle.sdo.spatial_index back to true).

---

Connection string (ADO.NET form)

adbc.arpeoracle.connection_string accepts the ADO.NET Key=Value;… grammar: case-insensitive keywords, quoted values, doubled-quote escapes. The Server keyword additionally accepts an Oracle EZConnect descriptor or a full TNS descriptor (see below). An unknown keyword, or the same option given twice, is rejected.

Keyword(s)	Option
Server, Data Source, Host, Address, Addr	server (+ EZConnect host:port/service, a full (DESCRIPTION=…) TNS descriptor, or a tnsnames.ora alias)
Port	port
Service Name, ServiceName, service_name, Database, Initial Catalog	service_name
SID	sid
User ID, UID, User, Username	username
Password, PWD	password
Application Name, App	app_name
Connection Timeout, Connect Timeout, Timeout	login_timeout
Socket Timeout, socket_timeout	socket_timeout
Buffer Size, buffer_size	batch_size
Number Mapping, number_mapping	number_mapping
Interval Mapping, interval_mapping	interval_mapping
SSL Mode, sslmode	ssl_mode
SSL Root Cert, sslrootcert	ssl_root_cert
Wallet Location, wallet_location	wallet_location
Wallet Password, wallet_password	wallet_password
Proxy User, proxy_user	proxy_user
New Password, new_password	new_password
Encryption, encryption	encryption
Data Integrity, data_integrity	data_integrity
Auth Method, auth_method	auth_method

Server=localhost:2484/orclpdb1;User ID=scott;Password=tiger;sslmode=verify-full

Database / Initial Catalog map to the service name — Oracle's unit of connection is a service (or a PDB), and callers coming from the sibling drivers reach for Database first. SID and Service Name are mutually exclusive.

Options with no connection-string or URI form

Some options exist only as discrete ADBC options:

Form	Not available there — set as a discrete option
Neither connection string nor uri	sdu, statement_cache_size, token_location, access_token, token_file, arpeio.adbc.license, arpeio.adbc.license_file
Connection string only (no uri parameter)	socket_timeout, batch_size, new_password, auth_method

Connection options (adbc.connection.*) and statement / ingest options are never read from a connection string or uri.

---

Connection URI

The standard ADBC uri option takes an Oracle-style URL, so a string copied from other Oracle ADBC tooling works unchanged.

<scheme>://[user[:password]@]host[:port][/service_name][?key=value&…]

• Schemes (case-insensitive, equivalent): oracle:// and the branded arpeoracle://. The scheme only selects the URL grammar — it never picks the driver, so oracle:// never collides with another Oracle ADBC driver installed alongside this one.
• The path segment is the Oracle service name. Use ?sid=<SID> for the SID CONNECT_DATA form instead; giving both a service name (path or ?service_name=) and a ?sid= is rejected.
• userinfo, host, and query values are percent-decoded; query values treat + as a space. Bracketed IPv6 hosts use [::1]:1521.
• For the ADO.NET key=value; form, use connection_string, not uri (a uri without a scheme:// is rejected with a pointer to connection_string).

Query parameters (names are case-insensitive; unknown or repeated parameters are rejected). Host and port come from the authority part, not from a query parameter:

Parameter(s)	Option
user	username
password	password
service_name	service_name
sid	sid
ssl_mode	ssl_mode
ssl_root_cert	ssl_root_cert
wallet_location	wallet_location
wallet_password	wallet_password
encryption	encryption
data_integrity	data_integrity
connect_timeout	login_timeout
application_name, app_name	app_name
number_mapping	number_mapping
interval_mapping	interval_mapping
proxy_user	proxy_user

oracle://scott:tiger@dbhost:2484/orclpdb1?ssl_mode=verify-full&wallet_location=/etc/oracle/wallet
oracle://scott:tiger@dbhost:1521/?sid=ORCL

---

EZConnect

Oracle lets a whole connect descriptor be written as host:port/service, and it is what most users reach for. ArpeOracle accepts it wherever a Server is given (discrete server, the Server connection-string keyword):

Server=dbhost                       # host only, service/SID given separately
Server=dbhost:1521/orclpdb1         # host:port/service
Server=//dbhost:1521/orclpdb1       # optional leading //
Server=dbhost,1521                  # ADO.NET host,port form (cross-driver muscle memory)

• The /service suffix sets the service name (use_sid=false).
• A bare IPv6 literal is rejected rather than mis-parsed — give the host and Port as separate keywords, or use the bracketed [::1] form in a uri.

---

TNS descriptor

A full connect descriptor can be pasted verbatim wherever a Server is given (discrete adbc.arpeoracle.server, or the Server / Data Source connection-string keyword) — it is detected by its leading (:

adbc.arpeoracle.server =
  (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=dbhost)(PORT=1521))
   (CONNECT_DATA=(SERVICE_NAME=orclpdb1)))

This is a convenience for callers that already hold a descriptor (e.g. a tnsnames.ora entry copied by hand, or an ODP.NET Data Source). ArpeOracle does not send it to the listener as-is; it decomposes the descriptor into the same server / port / service_name / sid fields the other forms fill, then builds its own descriptor at connect time. Consequences:

• Keys are case-insensitive; whitespace and newlines between tokens are allowed, so a descriptor formatted as in tnsnames.ora parses.
• The first ADDRESS must carry PROTOCOL, HOST and PORT, and CONNECT_DATA exactly one of SERVICE_NAME or SID; anything else is rejected.
• Only the first ADDRESS is used. A DESCRIPTION_LIST / ADDRESS_LIST (failover / load balancing) collapses to its first address — the rest are ignored.
• Only PROTOCOL=TCP and PROTOCOL=TCPS are supported. TCPS sets ssl_mode=require (encrypt, no server-certificate check) so the TLS listener is reached.
• A SECURITY section is dropped. That means TCPS from a descriptor is not verify-full: for server-certificate verification, or for Oracle Cloud ADB, pair the descriptor with the discrete ssl_mode / wallet_location / ssl_root_cert options (a discrete ssl_mode still wins over the descriptor's implied require), or use the discrete server / port / service_name fields shown under ADB below.

---

TNS alias (tnsnames.ora)

Version

Since ArpeOracle v0.3.11. Earlier versions do not resolve aliases: give the descriptor itself.

A server that is a bare name (letters, digits, _, ., -, with no port, /service or () and with no service name or SID given anywhere is looked up as a net service name in tnsnames.ora, as OCI, ODP.NET and python-oracledb do:

adbc.arpeoracle.server   = SALESDB
adbc.arpeoracle.username = scott
adbc.arpeoracle.password = tiger

or Data Source=SALESDB;User Id=scott;Password=tiger.

The file is searched in this order; the first one that exists is used:

1. <adbc.arpeoracle.tns_admin>/tnsnames.ora: when the option is set, only this directory is searched;
2. $TNS_ADMIN/tnsnames.ora;
3. $ORACLE_HOME/network/admin/tnsnames.ora.

The entry's value, a (DESCRIPTION=…) descriptor or an EZConnect string, is then handled exactly like one given directly (see TNS descriptor above: first ADDRESS only, TCPS implies ssl_mode=require unless ssl_mode is set). The alias is resolved once, at AdbcDatabaseInit.

Supported in the file: # comments, entries spanning several lines, several names for one entry (SALES, SALES_RO = (…)), case-insensitive names, and IFILE=<path> includes (a relative path is taken from the including file's directory). When a name is defined twice, the first definition wins.

• A bare name with a service name or SID (server=dbhost + service_name=orclpdb1) is a host, never an alias.
• If a tnsnames.ora is found but has no such entry, AdbcDatabaseInit fails with TNS alias 'X' not found in <file>. If no tnsnames.ora is found, the name stays a host name and the connect reports that no service name is set.
• sqlnet.ora is not read: NAMES.DEFAULT_DOMAIN is not appended to the alias (write the full name, e.g. SALESDB.WORLD), and wallet and encryption settings come from the driver options, not from sqlnet.ora. LDAP naming is not supported.

---

Oracle Cloud Autonomous Database (ADB)

Version

Since ArpeOracle v0.2.0.

A downloaded ADB instance wallet works as-is (mutual TLS). Point wallet_location at the unzipped wallet directory (which contains ewallet.pem), set wallet_password, use ssl_mode=verify-full, and connect to one of the wallet's _low / _tp / … services on port 1522:

Python

db_kwargs = {
    "adbc.arpeoracle.server":          "adb.<region>.oraclecloud.com",
    "adbc.arpeoracle.port":            "1522",
    "adbc.arpeoracle.service_name":    "<svc>_low.adb.oraclecloud.com",
    "adbc.arpeoracle.username":        "scott",
    "adbc.arpeoracle.password":        "tiger",
    "adbc.arpeoracle.ssl_mode":        "verify-full",
    "adbc.arpeoracle.wallet_location": "/home/you/wallet",
    "adbc.arpeoracle.wallet_password": "<wallet-pw>",
}

Oracle's cwallet.sso cannot be read — convert it with orapki wallet pkcs12_to_pem -wallet <dir> to produce ewallet.pem. ADB also accepts OCI IAM token and OAuth2 / Entra ID login instead of a password (both still require the wallet for mutual TLS) — see Authentication.

---

See also

• Authentication — O5LOGON / proxy / OCI IAM / OAuth2 / TLS
• Data types — Oracle → Arrow type mapping
• Compatibility — supported Oracle versions & cloud services
• Troubleshooting — common connection failures
• Examples — copy-paste recipes
• Licensing — supplying your Arpeio licence