Driver for SAP HANA¶

Driver Version v0.1.0-alpha.1 Tested With SAP HANA 2.0

This driver provides access to SAP HANA , a high-performance in-memory relational database management system. It uses a vendored, Arrow-aware fork of SAP’s go-hdb driver under the hood, so no separate SAP client SDK or native client libraries are required.

Note

SAP HANA has its own technology called “ADBC” (ABAP Database Connectivity ), which is an ABAP-level SQL API unrelated to this project. This driver implements Apache Arrow ADBC (Arrow Database Connectivity), a cross-language API standard for Arrow-native database access.

Note

This project is not affiliated with SAP.

Installation¶

The driver for SAP HANA can be installed with dbc :

dbc install --pre sap-hana

Note

Only prerelease versions of the driver are currently available, so you must use --pre with dbc 0.2.0 or newer to install the driver.

Connecting¶

Provide a SAP HANA connection string as the uri option. SAP HANA URIs use the native go-hdb format:

hdb://[user[:password]@]host[:port][?param1=value1&param2=value2...]

For basic authentication, either embed credentials in the URI or pass username and password separately:

dbapi.connect(
  driver="sap-hana",
  db_kwargs={
    "uri": "hdb://hanahost.example.com:443",
    "username": "DBUSER",
    "password": "Password123!",
  }
)

The examples here use Python with the adbc-driver-manager package, but the same options apply through other ADBC driver managers. See adbc-quickstarts for end-to-end examples.

Supported URI query parameters include:

databaseName: connect to a tenant database.
defaultSchema: set the initial default schema.
timeout: connection timeout in seconds.
pingInterval: background ping interval in seconds.
TLSServerName: TLS server name used for hostname verification/SNI.
TLSRootCAFile: one or more root CA files. Repeat the parameter to specify multiple files.
TLSInsecureSkipVerify: disable server certificate verification.

Note

Reserved characters in URI elements must be URI-encoded. For example, @ becomes %40.

Authentication¶

Additional authentication modes:

X.509 client certificate authentication.
JWT authentication, using a bearer token supplied through an option.

Constraints:

sap-hana.auth.x509.cert_file must be paired with sap-hana.auth.x509.key_file.
sap-hana.auth.x509.cert must be paired with sap-hana.auth.x509.key.
File-based and inline X.509 options are mutually exclusive.
X.509 authentication and JWT authentication are mutually exclusive.

Example using X.509 files:

dbapi.connect(
  driver="sap-hana",
  db_kwargs={
    "uri": "hdb://hanahost.example.com:443",
    "sap-hana.auth.x509.cert_file": "/path/to/test_x509_user.crt",
    "sap-hana.auth.x509.key_file": "/path/to/test_x509_user.key",
  }
)

For X.509 authentication:

Prefer a credential-free URI for X.509 authentication.
File-based X.509 auth expects separate certificate and key files. A combined PEM bundle is not accepted by sap-hana.auth.x509.cert_file / sap-hana.auth.x509.key_file.
sap-hana.tls.root_ca_file controls client-side trust of the SAP HANA server certificate only.
On the SAP HANA side, X.509 authentication also requires a PSE with PURPOSE X509, the trusted CA certificate added to that PSE, and ALTER USER <user> ENABLE X509.
The CREATE X509 PROVIDER ... WITH ISSUER ... value must match the issuer DN as SAP HANA stores it, which can differ from OpenSSL’s text rendering. In this test setup, HANA stored /ST=ON as SP=ON.

Example using JWT authentication:

dbapi.connect(
  driver="sap-hana",
  db_kwargs={
    "uri": "hdb://hana.example.com:443",
    "sap-hana.auth.jwt.token": token,
  }
)

Note

JWT requires server-side validation configuration. HANA Express does not support the JWT PSE setup used by this repository; use a full SAP HANA 2.0 SPS 04+ instance.

TLS Configuration¶

TLS can be configured either in the URI (TLSServerName, TLSRootCAFile, TLSInsecureSkipVerify) or with driver-specific ADBC options:

sap-hana.tls.server_name
sap-hana.tls.root_ca_file
sap-hana.tls.insecure_skip_verify

When the driver-specific TLS options are set, they override any TLS settings present in the URI.

If no TLS options are provided and the URI uses port 443, the driver enables TLS automatically and uses the hostname as the TLS server name.

Feature & Type Support¶

Feature	Support
Bulk Ingestion	Create	✅
	Append	✅
	Create/Append	✅
	Replace	✅
	Temporary Table	✅
	Specify target catalog	❌
	Specify target schema	✅
	Non-nullable fields are marked NOT NULL	✅
Catalog (GetObjects)	depth=catalogs	✅
	depth=db_schemas	✅
	depth=tables	✅
	depth=columns (all)	✅
Get Parameter Schema	✅
Get Table Schema	✅
Prepared Statements	✅
Transactions	✅

Types¶

SAP HANA to Arrow¶

SAP HANA Type	Arrow Type
BIGINT	int64
BINARY, VARBINARY, BSTRING	binary [1] [2]
BIT	❌
BOOLEAN	bool
CHAR, VARCHAR, STRING, ALPHANUM	string [3] [4] [5]
DATE, DAYDATE	date32[day] [6]
DECIMAL, SMALLDECIMAL	decimal128 [7] [8]
DOUBLE	double [9]
INTEGER	int32
JSON	❌
REAL	float [10]
SMALLINT	int16 [11]
TIME, SECONDTIME	time64[us] [12]
TIMESTAMP, LONGDATE, SECONDDATE	timestamp[us] (with time zone) [13] [14] [15]

Arrow to SAP HANA¶

Arrow Type	SAP HANA Type
Arrow Type	Bind	Ingest
binary	VARBINARY
binary_view	VARBINARY
bool	BOOLEAN
date32[day]	DATE
decimal128	DECIMAL
double	DOUBLE PRECISION
fixed_size_binary	VARBINARY
float	REAL
int16	SMALLINT
int32	INT
int64	BIGINT
large_binary	VARBINARY
large_string	VARCHAR
string	VARCHAR
string_view	VARCHAR
time32[ms]	TIME
time32[s]	TIME
time64[ns]	TIME
time64[us]	TIME
timestamp[ms]	DATETIME
timestamp[ms] (with time zone)	TIMESTAMP
timestamp[ns]	DATETIME
timestamp[ns] (with time zone)	TIMESTAMP
timestamp[s]	DATETIME
timestamp[s] (with time zone)	TIMESTAMP
timestamp[us]	DATETIME
timestamp[us] (with time zone)	TIMESTAMP

Note

Regular string and binary columns such as VARCHAR, NVARCHAR, and VARBINARY are decoded directly into Arrow arrays. Large object types such as BLOB, CLOB, NCLOB, TEXT, and BINTEXT are read through SAP HANA’s LOB streaming mechanism and then surfaced as Arrow binary or string values. This mainly affects performance and memory behavior; it does not change the final Arrow type family returned by the driver.

Catalog Metadata/GetObjects behavior¶

SAP HANA does not expose the standard SQL catalog.schema.table hierarchy in the same way as systems with multiple independent catalogs. This driver therefore surfaces a synthetic single catalog named db, with schemas beneath it.

Behavior to be aware of:

adbc.connection.catalog always returns db.
Setting adbc.connection.catalog is not supported.
adbc.connection.db_schema is supported and maps to SET SCHEMA.
GetObjects currently lists TABLE and VIEW objects.
GetObjects excludes the SYS schema and schemas matching _SYS_*.

SQL Compatibility Notes¶

Before execution, the driver performs two small SAP HANA-specific query normalizations:

A top-level SELECT statement without a FROM clause has FROM DUMMY appended automatically.
Unquoted temporal type names such as TIMESTAMP(6) and TIME(7) have the precision suffix stripped.

This behavior is intended to smooth over common portability issues and validation-style queries. It is not a full SQL parser, and quoted strings/comments are left untouched.

Memory and Performance Tuning¶

When reading data, the most important tuning knobs are:

sap-hana.statement.fetch_size, which controls how many rows SAP HANA returns per fetch round-trip.
sap-hana.statement.read_batch_rows, which controls the target number of rows per Arrow record batch.

Higher fetch_size values usually reduce round-trips and improve throughput on high-latency connections, but they also increase the amount of data buffered per fetch. Higher read_batch_rows values reduce Arrow batch fragmentation, but they increase peak batch size in memory.

Note

read_batch_rows is a best-effort row cap. Because the driver appends whole fetch pages at a time, an individual Arrow batch may be slightly larger than the configured value.

Options¶

Options Affecting Connections¶

uri

Type: string. Required.

The SAP HANA connection URI.

username and password

Type: string. Default: not set.

Standard ADBC options for basic authentication. Use these instead of embedding credentials in the URI.

sap-hana.auth.x509.cert_file and sap-hana.auth.x509.key_file

Type: string. Default: not set.

Paths to a PEM-encoded client certificate and PEM-encoded private key for X.509 client-certificate authentication.

sap-hana.auth.x509.cert and sap-hana.auth.x509.key

Type: string. Default: not set.

Inline PEM-encoded client certificate and private key content for X.509 client-certificate authentication.

sap-hana.auth.jwt.token

Type: string. Default: not set.

JWT bearer token used for JWT authentication.

sap-hana.tls.server_name

Type: string. Default: not set.

TLS server name used for hostname verification and SNI. This overrides the URI query parameter TLSServerName if both are provided.

sap-hana.tls.insecure_skip_verify

Type: boolean. Default: false.

Disable TLS certificate and hostname verification. This overrides the URI query parameter TLSInsecureSkipVerify if both are provided.

sap-hana.tls.root_ca_file

Type: string. Default: not set.

Comma-separated list of root CA files to trust. This overrides the URI query parameter TLSRootCAFile if both are provided.

adbc.connection.db_schema

Type: string.

Set or get the current schema for the connection. Setting this option sends SET SCHEMA.

adbc.connection.catalog

Type: string. Read-only value: db.

SAP HANA is surfaced through a single synthetic catalog named db. Changing the current catalog is not supported.

Options Affecting Queries¶

sap-hana.statement.fetch_size

Type: positive integer. Default: 50000.

Controls the SAP HANA fetch size used for query result round-trips. This may be set on the database, connection, or statement. Statement values override connection/database values for that statement.

sap-hana.statement.read_batch_rows

Type: positive integer. Default: 100000.

Target maximum number of rows per returned Arrow record batch. This may be set on the database, connection, or statement.

Options Affecting Bulk Ingest¶

The driver supports Arrow-based bulk ingest through the standard ADBC ingest options.

adbc.ingest.target_table

Type: string. Required for ingest.

The target table name.

adbc.ingest.mode

Values: adbc.ingest.mode.create, adbc.ingest.mode.append, adbc.ingest.mode.replace, adbc.ingest.mode.create_append. Default: adbc.ingest.mode.create.

Controls whether the target table should be created, appended to, replaced, or created-if-missing/appended-if-present.

adbc.ingest.target_db_schema

Type: string. Default: not set.

The schema to create or append the target table in. This is ignored for temporary-table ingest.

adbc.ingest.temporary

Values: true or false. Default: false.

When enabled, create a SAP HANA local temporary table. The driver prefixes the table name with # and issues CREATE LOCAL TEMPORARY TABLE.

Automatic table creation during ingest supports Arrow scalar types that map cleanly to SAP HANA DDL:

booleans
signed and unsigned integers
floating-point values
dates, times, and timestamps
strings and binaries
decimal128 and decimal256

When the driver creates a table automatically:

string-like Arrow columns become NVARCHAR(5000)
binary-like Arrow columns become VARBINARY(5000)
decimal columns become DECIMAL(p,s)

If you need larger text/binary columns, different HANA-native types, or nested Arrow types, pre-create the table yourself and ingest with append mode.

FAQ/Troubleshooting¶

`table not found` errors for mixed-case names¶

SAP HANA uppercases unquoted identifiers. If a table was created with quoted, mixed-case identifiers, refer to it using the exact quoted name. If it was created unquoted, use the uppercase name that HANA stores internally.

`cannot close connection while a statement reader is active`¶

Query readers hold the connection until reader.Release() is called. Release the active record reader before closing the connection.

Compatibility¶

This driver was tested on the following versions of SAP HANA:

Driver for SAP HANA¶

Installation¶

Connecting¶

Authentication¶

TLS Configuration¶

Feature & Type Support¶

Types¶

SAP HANA to Arrow¶

Arrow to SAP HANA¶

Catalog Metadata/GetObjects behavior¶

SQL Compatibility Notes¶

Memory and Performance Tuning¶

Options¶

Options Affecting Connections¶

Options Affecting Queries¶

Options Affecting Bulk Ingest¶

FAQ/Troubleshooting¶

table not found errors for mixed-case names¶

cannot close connection while a statement reader is active¶

Compatibility¶

`table not found` errors for mixed-case names¶

`cannot close connection while a statement reader is active`¶