ArpePGSQL — Connection guide

Everything you can put in front of ArpePGSQL to point it at a PostgreSQL server, in one place: the three ways to supply connection details, every option the driver accepts, and the PostgreSQL-specific rules (TLS / sslmode, SCRAM channel binding, integrated authentication on Windows).

For how each authentication method works (SCRAM-SHA-256 + channel binding, Windows integrated authentication), 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.arpepgsql.<field>	one option per field	programmatic clients, secrets kept out of a single string
Connection string	adbc.arpepgsql.connection_string (alias connection_string)	ADO.NET Key=Value;…	pasting an existing SQL Server / SqlClient-style string
Connection URI	uri	postgresql://… URL	portable tooling, copy-paste from libpq / psql / ADBC tools

Python

import adbc_driver_manager.dbapi as dbapi

# Discrete options
conn = dbapi.connect(driver="arpepgsql", db_kwargs={
    "adbc.arpepgsql.server":   "localhost",
    "adbc.arpepgsql.database": "tpch",
    "adbc.arpepgsql.username": "alice",
    "adbc.arpepgsql.password": "<password>",
    "adbc.arpepgsql.sslmode":  "require",
}, autocommit=True)

# Connection string (ADO.NET grammar)
conn = dbapi.connect(driver="arpepgsql", db_kwargs={
    "adbc.arpepgsql.connection_string":
        "Server=localhost;Database=tpch;User ID=alice;Password=<password>",
}, autocommit=True)

# Connection URI (libpq grammar)
conn = dbapi.connect(driver="arpepgsql", db_kwargs={
    "uri": "postgresql://alice:<password>@localhost:5432/tpch?sslmode=require",
}, autocommit=True)

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

---

Option reference

All options are string-typed and live under the adbc.arpepgsql.* namespace (a few also accept a short bare alias, noted below). Set them as ADBC database options before the connection is opened. Statement/ingest options are set on the statement — see Statement & ingest options.

Database-level vs connection-level keys

Every option on this page is a database option (db_kwargs, AdbcDatabaseSetOption), copied to each connection when it is created. Most adbc.arpepgsql.* names are also accepted as connection options (conn_kwargs, AdbcConnectionSetOption), except connection_string, trusted, the timeouts, buffer_size and the licence options, which are database-only. The short bare aliases do not all work at both levels:

Bare key	Database level	Connection level
database, username, password, port, application_name, krbsrvname, geospatial, uuid_casing, numeric_format, numeric_special, copy_format	✓	✓
hostname, trusted, connection_string, uri	✓	—
server, app_name, auth_mode, sslmode, ssl_root_cert, channel_binding, encrypt, trust_server_cert, require_password_encryption, krb5_spn	—	✓

A bare key in the last row passed as a database option is rejected with NOT_IMPLEMENTED ("Unknown database option"). In db_kwargs, always use the adbc.arpepgsql.* form (for example adbc.arpepgsql.sslmode, adbc.arpepgsql.krb5.spn). Note the spelling difference for the SPN override: the database form is dotted (adbc.arpepgsql.krb5.spn), the connection-level bare form uses an underscore (krb5_spn).

Target — where to connect

Option	Alias	Default	Meaning
adbc.arpepgsql.connection_string	connection_string	—	ADO.NET Key=Value;… string, see Connection string. Database level only.
uri	—	—	libpq-style postgresql://… URI, see Connection URI. Database level only.
adbc.arpepgsql.server	hostname (database), server (connection)	—	Host name or address. As a discrete option an IPv6 literal is given bare (::1); inside a connection_string or uri it takes the bracketed form [::1]. In a connection_string value, a tcp: prefix and a :port or ,port suffix are also accepted (db.example.com:5433, tcp:db.example.com,5433; host:port since v0.4.6).
adbc.arpepgsql.port	port	5432	TCP port, 1..65535.
adbc.arpepgsql.database	database	server default (the role's default DB)	Initial database. A connection sees exactly one database at a time (no cross-database queries); switch with adbc.connection.catalog.
adbc.arpepgsql.username	username	PGUSER (required; PostgreSQL needs a role name)	Login role.
adbc.arpepgsql.password	password	PGPASSWORD, else the password file	Password for the password-family auth methods. See PostgreSQL environment variables.
adbc.arpepgsql.application_name	application_name (also app_name at connection level)	unset (not sent; server default)	Program name reported in the startup packet (application_name GUC, pg_stat_activity.application_name).

Authentication

Full method-by-method detail is in Authentication; the TLS / channel-binding options are under TLS & encryption options and the integrated path under Integrated authentication (Windows).

Option	Values	Meaning
adbc.arpepgsql.username / .password	string	Password-family credentials (SCRAM-SHA-256 / MD5 / cleartext, negotiated by the server). Aliases username / password. When unset, PGUSER / PGPASSWORD / the password file are used (since v0.4.5), see PostgreSQL environment variables.
adbc.arpepgsql.trusted	true/1/yes/sspi/SSPI, false/0/no	Integrated auth with the logged-in Windows identity (SSPI). Windows only — not available on Linux. Set username to the database role to log in as; a password is rejected. Alias trusted (database level only).
adbc.arpepgsql.auth_type	sql/SqlPassword, integrated/sspi/trusted	Selects the auth mode explicitly (integrated is Windows only). Any other value (the Entra ID / certificate families) is rejected with NOT_IMPLEMENTED (ArpePGSQL is the driver — it cannot delegate to a client library). Connection-level alias auth_mode.
adbc.arpepgsql.krb5.spn	SPN	Integrated auth (Windows): use this service principal name verbatim instead of the derived POSTGRES/<server> (e.g. POSTGRES/db.example.com). Takes precedence over krbsrvname. Connection-level alias krb5_spn.
adbc.arpepgsql.krbsrvname	name	Integrated auth (Windows): replace the service part of the derived SPN (default POSTGRES, giving POSTGRES/<server>). Ignored when krb5.spn is set. Alias krbsrvname.

TLS & encryption options

Option	Default	Meaning
adbc.arpepgsql.sslmode	prefer	disable / prefer / require / verify-ca / verify-full, via the FEBE SSLRequest handshake. require encrypts but does not verify the certificate; only verify-ca/verify-full do (and verify-full also checks the hostname).
adbc.arpepgsql.ssl_root_cert	PGSSLROOTCERT, else OpenSSL's default locations (details)	PEM root-CA file used by verify-ca / verify-full. PGSSLROOTCERT is read since v0.4.5.
adbc.arpepgsql.channel_binding	prefer	prefer / require / disable. require enforces SCRAM-SHA-256-PLUS channel binding over TLS and refuses a PLUS-stripping downgrade.
adbc.arpepgsql.encrypt	false	Compatibility bridge for the ADO.NET TLS vocabulary (true/1/yes, false/0/no). An explicit sslmode always wins; only when none is given does encrypt=true map to verify-full (or require when trust_server_cert=true). Prefer sslmode directly.
adbc.arpepgsql.trust_server_cert	false	Part of the same bridge (see encrypt). Prefer sslmode directly.
adbc.arpepgsql.require_password_encryption	false	true/1/yes refuses to send a cleartext or MD5 password when the transport is not TLS-encrypted, closing the downgrade path left open by sslmode=prefer. Off by default (libpq-compatible). Also available as RequirePasswordEncryption in a connection string and require_password_encryption in a URI. Since v0.3.7.

⚠️ Security — the default sslmode=prefer gives no MITM protection. Like libpq, prefer falls back to plaintext when the server answers the SSLRequest with N, and that reply is read before TLS so it is unauthenticated. Over an untrusted network use sslmode=verify-full and/or channel_binding=require. See TLS & sslmode below.

Timeouts & performance

Option	Default	Meaning
adbc.arpepgsql.login_timeout	30	TCP connect budget in seconds.
adbc.arpepgsql.socket_timeout	0	Per-I/O recv/send timeout in seconds (0 = none). Set it to bound a long-running or stalled query.
adbc.arpepgsql.query_timeout	0	Per-query timeout in seconds (0 = no limit).
adbc.arpepgsql.buffer_size	32000	Rows per streamed Arrow batch (per connection); also the default statement batch_size. Values above 10,000,000 are capped; 0 or a non-number is ignored.
adbc.arpepgsql.copy_format	auto (default) / binary / text	Read-path extraction strategy. auto uses the fast binary COPY path on real PostgreSQL and falls back to the text row path for PostgreSQL-wire-compatible engines that don't emit a binary COPY stream (e.g. CedarDB); the fallback is detected in-band and cached per connection. binary forces binary COPY (clear error if unsupported). text always uses the text row path. Alias copy_format. Env override when the option is unset or auto: ARPEIO_ADBC_COPY_FORMAT. Since v0.4.2.

PostgreSQL-wire-compatible engines. Databases that only speak the PostgreSQL protocol (CedarDB, CockroachDB, Redshift, Materialize, …) may not implement binary COPY TO. In auto (the default) the driver detects this once per connection and uses the text row path, so extraction works unchanged. For best throughput on such a server, set copy_format=text to skip the initial binary-COPY attempt.

Type rendering (read path)

Option	Values	Meaning
adbc.arpepgsql.uuid_casing	lower (default) / upper	Hex-digit case of uuid values rendered to Arrow utf8. lower matches RFC 4122 and PostgreSQL's text output. lowercase / uppercase are accepted spellings. Alias uuid_casing.
adbc.arpepgsql.numeric_format	decimal (default) / string	How NUMERIC columns are returned. decimal maps numeric(p,s) to decimal128 (p ≤ 38) or decimal256 (p ≤ 76) and falls back to utf8 for larger or unconstrained numeric. string returns every NUMERIC column as utf8 in PostgreSQL's text form — lossless, NaN included. Alias numeric_format. Since v0.4.3.
adbc.arpepgsql.numeric_special	error (default) / null	What to do when a NUMERIC NaN / ±Infinity reaches a decimal128/decimal256 column (Arrow decimals cannot represent it). error fails the read with a message naming the column; null reads the value as NULL. Ignored when numeric_format=string. Alias numeric_special. Since v0.4.3 — breaking: before v0.4.3 such values were silently read as NULL (binary paths) or 0 (text path); set null to restore the binary-path behaviour.
adbc.arpepgsql.geospatial	geoarrow.wkb (default) / wkb / binary	How PostGIS geometry/geography columns are read. geoarrow is accepted for geoarrow.wkb; varbinary and disable for binary. Alias geospatial. See Data types → Geospatial.

numeric_format and numeric_special can also be changed on an open connection (AdbcConnectionSetOption); the change applies from the next query, without reconnecting.

Licence

Option	Meaning
arpeio.adbc.license	Licence blob, inline.
arpeio.adbc.license_file	Path to a .lic file.
arpeio.adbc.license.status	Read-only (database 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 arpepgsql namespace):

Option	Values	Meaning
adbc.connection.autocommit	true (default) / false	Autocommit mode (true or 1 enables it; any other value disables it). Also accepted as a database option, inherited by new connections. With false, a transaction begins with the next statement after each commit()/rollback() (manual-commit mode holds across transactions since v0.4.3). Non-temporary adbc_ingest runs on its own session and commits independently of the connection's transaction; TEMP ingest runs inside it. Set true for the single-connection TRUNCATE/adbc_ingest pattern.
adbc.connection.catalog	database name	Switch to another database on the same server. PostgreSQL binds a session to one database, so this reconnects: temp tables, SET values and advisory locks do not carry over, and the schema becomes the new database's default; manual-commit mode carries over. Refused (INVALID_STATE) inside an open transaction or while a result set is still being read; an unknown database is NOT_FOUND. Since v0.4.3.
adbc.connection.db_schema	schema name	Current schema: checked to exist in the current database (NOT_FOUND otherwise), then applied with SET search_path TO "<schema>".

Transaction isolation level and session read-only are not yet exposed as ADBC options on ArpePGSQL; set them from SQL (SET TRANSACTION …, SET default_transaction_read_only) on the connection if needed.

Statement & ingest options

Set on the statement handle, not the database:

Option	Default	Meaning
adbc.arpepgsql.batch_size	inherits buffer_size (32000)	Rows per Arrow batch for this statement, 1..max_batch_size.
adbc.arpepgsql.max_batch_size	1000000	Upper bound for batch_size; must be ≥ the current batch_size.
adbc.arpepgsql.memory_budget_mb	256	Decode memory budget, 16..8192 MB.
adbc.ingest.target_table	—	Target table for adbc_ingest / bulk ingest.
adbc.ingest.mode	create	create / append / replace / create_append, or the long ADBC forms adbc.ingest.mode.create / .append / .replace / .create_append. Any other value is rejected with NOT_IMPLEMENTED.
adbc.ingest.target_catalog	—	Target database for ingest.
adbc.ingest.target_db_schema	—	Target schema for ingest. Ignored for a temporary ingest (TEMP tables live in pg_temp).
adbc.ingest.temporary	false	true or 1 ingests into a TEMP table (same-session fast path); any other value means false.

Legacy bulk options & no-ops (back-compat)

Recognised so strings copied from other Arpeio drivers still load:

Option	Default	Effect
adbc.arpepgsql.prefetch	—	No-op (the double-buffered prefetch path was removed — streaming already overlaps recv with decode).
arpepgsql.bulk_batch_size	10000000	1..100000000. Maximum rows per CopyData chunk during ingest; chunks are also flushed at ~4 MiB, which is usually reached first.
arpepgsql.bulk_tablock, arpepgsql.bulk_keep_identity, arpepgsql.bulk_check_constraints, arpepgsql.bulk_fire_triggers, arpepgsql.bulk_keep_nulls	—	No-ops: stored, never used. SQL-Server-era ingest hints with no PostgreSQL COPY equivalent.

Any other key is rejected with NOT_IMPLEMENTED ("Unknown statement option").

---

Connection string (ADO.NET form)

adbc.arpepgsql.connection_string accepts the ADO.NET Key=Value;… grammar: case-insensitive keywords, quoted values, doubled-quote escapes. Both the ADO.NET keywords (inherited from ArpeMSSQL for cross-family compatibility) and, since v0.4.6, the PostgreSQL / Npgsql ones (Host, Port, Username, SSL Mode, …) are accepted, so a string copied from an Npgsql setup loads as is. Keywords map onto the options above.

Keyword(s)	Option
Server, Host, Data Source, Address, Addr, Network Address	server (value may be host, host:port, host,port, tcp:host[,port], or [ipv6] followed by :port / ,port; other protocol prefixes are rejected)
Port	port (a port written in Server / Host wins, as in Npgsql)
Database, Initial Catalog	database
User ID, UID, User, Username	username
Password, PWD	password
Application Name, App	application_name
Encrypt	encrypt
TrustServerCertificate, Trust Server Certificate	trust_server_cert
SSL Mode, SslMode	sslmode (libpq spellings, plus Npgsql's VerifyCA / VerifyFull; Allow maps to prefer; any case)
Root Certificate, SSL Root Cert, SslRootCert	ssl_root_cert
Channel Binding, ChannelBinding	channel_binding
RequirePasswordEncryption	require_password_encryption
Connection Timeout, Connect Timeout, Timeout	login_timeout
Integrated Security, Trusted_Connection, Trusted Connection	trusted (SSPI/true/yes/1 → integrated (Windows only), false/no/0 → SQL login)
Authentication	SqlPassword / Sql Password → SQL login; any ActiveDirectory* value → NOT_IMPLEMENTED; anything else → INVALID_ARGUMENT
Authenticator	winsspi / sspi / krb5 → integrated (Windows only), sql → SQL login
Service Principal Name, ServicePrincipalName, service_principal_name	krb5.spn
KrbSrvName	krbsrvname

Boolean keywords (Encrypt, TrustServerCertificate, RequirePasswordEncryption) take yes/no/true/false/1/0, case-insensitive. Unknown keywords are rejected. The Host, Port, Username, SSL Mode, Root Certificate and Channel Binding keywords, host:port in Server / Host, and the Trust Server Certificate spelling are new in v0.4.6; on earlier versions set sslmode, channel_binding and ssl_root_cert as discrete options or through the URI.

Server=localhost;Database=tpch;User ID=alice;Password=secret;Integrated Security=false
Host=db.example.com;Port=5433;Database=tpch;Username=alice;Password=secret;SSL Mode=VerifyFull

---

Connection URI

Version

Since ArpePGSQL v0.3.6.

The standard ADBC uri option takes a libpq-style PostgreSQL URI, so a string copied from psql, a DATABASE_URL, or other PostgreSQL ADBC tooling works unchanged.

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

• Schemes (case-insensitive, equivalent): postgresql://, postgres://, and the branded arpepgsql://. The scheme only selects the URL grammar — it never picks the driver, so postgresql:///postgres:// never collide with another PostgreSQL ADBC driver installed alongside this one.
• The path segment is the database name (as in libpq) — not an instance name.
• host, userinfo, and query values are percent-decoded; a + in a query value decodes to a space. IPv6 hosts use the bracketed form: postgresql://[::1]:5432/tpch.

Query parameters (unknown or repeated parameters are rejected, as is a parameter for a field the URI already sets, such as user next to a user@ in the authority):

Parameter	Option
user	username
password	password
dbname	database (alternative spelling for callers who put it in the query)
application_name	application_name
connect_timeout	login_timeout
sslmode	sslmode
channel_binding	channel_binding
sslrootcert	ssl_root_cert
krbsrvname	krbsrvname
require_password_encryption	require_password_encryption

Parameter names are matched case-insensitively. Since v0.4.6, sslmode also takes Npgsql's VerifyCA / VerifyFull (and Allow, mapped to prefer), in any case. Options with no URI parameter (copy_format, numeric_*, geospatial, uuid_casing, timeouts other than connect_timeout, krb5.spn) are set as discrete options next to uri.

For the ADO.NET Key=Value; form use connection_string instead of uri.

---

TLS & sslmode

ArpePGSQL negotiates TLS with the PostgreSQL SSLRequest handshake. The sslmode values mirror libpq:

sslmode	Encrypts	Verifies certificate	Verifies hostname
disable	no	—	—
prefer (default)	if the server offers it	no	no
require	yes	no	no
verify-ca	yes	yes (chain to ssl_root_cert, else OpenSSL's default locations)	no
verify-full	yes	yes	yes

• prefer gives no MITM protection. The server's response to SSLRequest (S = TLS, N = plaintext) is read before TLS, so an on-path attacker can strip it and observe the cleartext / MD5 / SCRAM-without-binding exchange. Over an untrusted network use verify-full.
• SCRAM channel binding (channel_binding=require) binds the SCRAM exchange to the server certificate (SCRAM-SHA-256-PLUS), defeating a MITM that proxies the SASL flow even without verify-full. It needs TLS, so it is unavailable under sslmode=disable.
• verify-ca / verify-full load the CA chain from ssl_root_cert, else PGSSLROOTCERT, else OpenSSL's default locations. Those hold no CAs on RHEL and Windows; see Authentication → TLS for what happens on each OS, the TLS version floor, SNI and the OpenSSL configuration file.

The encrypt / trust_server_cert options are a compatibility bridge for callers who think in the ADO.NET vocabulary and are mapped to sslmode only when no explicit sslmode is given. Prefer setting sslmode directly.

---

PostgreSQL environment variables and .pgpass

Version

Since ArpePGSQL v0.4.5.

Settings that no option, connection string or URI gives fall back to the standard PostgreSQL client environment, the same variables Npgsql reads. They are read once, at AdbcDatabaseInit, and an explicit option always wins:

Variable	Fills	Notes
PGUSER	username
PGPASSWORD	password	Not used with integrated authentication.
password file	password	Only when no password is given and PGPASSWORD is unset. PGPASSFILE, else ~/.pgpass (Windows: %APPDATA%\postgresql\pgpass.conf).
PGSSLROOTCERT	ssl_root_cert

The password file uses libpq's format, one entry per line:

hostname:port:database:username:password

• * in any of the first four fields matches anything.
• \ escapes : and \.
• Lines starting with # are comments.
• The first matching line wins.
• Matching uses the configured server, port, database and username, and is case-sensitive.
• On Linux a file that group or others can read is ignored, with a warning on stderr, as libpq does: chmod 0600 ~/.pgpass.

PGHOST, PGPORT, PGDATABASE and PGSSLMODE are not read (Npgsql doesn't read them either): give the server, port, database and sslmode explicitly. PGSSLCERT / PGSSLKEY have no effect, since TLS client-certificate authentication isn't supported.

---

Integrated authentication (Windows)

Version

Since ArpePGSQL v0.2.0.

Platform

Integrated (trusted) authentication is available with the Windows driver only, through Windows SSPI. The Linux driver supports password-family authentication (SCRAM-SHA-256, MD5, cleartext) only; requesting integrated authentication on Linux fails at connect time with "Trusted/integrated authentication is unavailable".

Set adbc.arpepgsql.auth_type=integrated (or adbc.arpepgsql.trusted=true) to authenticate as the logged-in Windows user, with no password. Set adbc.arpepgsql.username to the PostgreSQL role to log in as; the server checks that your Windows identity maps to it (pg_hba.conf / pg_ident.conf). The driver uses the Windows Negotiate package and answers the server's gss or sspi pg_hba.conf method. Mutual authentication is always required and enforced: the driver refuses AuthenticationOk from a server that never completed the exchange, and refuses password-family requests while this mode is active. Register the server's SPN in Active Directory so Kerberos can be used.

Python

conn = dbapi.connect(driver="arpepgsql", db_kwargs={
    "adbc.arpepgsql.server":    "db.example.com",
    "adbc.arpepgsql.database":  "mydb",
    "adbc.arpepgsql.username":  "alice",
    "adbc.arpepgsql.auth_type": "integrated",
    # optional: target SPN when it differs from POSTGRES/db.example.com
    # "adbc.arpepgsql.krb5.spn": "postgres/db.example.com",
})

The target service principal name is derived as POSTGRES/<server> (no port), using the server value as given — connect by the fully qualified host name under which the SPN is registered, not by IP address. Change the service part with adbc.arpepgsql.krbsrvname, or set the whole SPN with adbc.arpepgsql.krb5.spn.

---

See also

• Authentication — SCRAM, channel binding, Windows integrated authentication
• Data types — PostgreSQL → Arrow type mapping
• Compatibility — supported PostgreSQL versions & forks
• Troubleshooting — common connection failures
• Examples — copy-paste recipes
• Licensing — supplying your Arpeio licence