Registry / database / hdbcli

hdbcli

JSON →
library2.29.27pypypi✓ verified 23d ago

hdbcli is the official SAP HANA Python Client, implementing the Python Database API Specification v2.0 (PEP 249). It enables Python applications to connect to SAP HANA databases, execute SQL statements, and manage data. The library is actively maintained by SAP, with the current version 2.28.19 released on March 27, 2026, and typically sees regular updates.

pip install hdbcli
INSTALL
IMPORT
SIG · HDBCLI
H
hdbcli
databasepythonv2.29.27
Install
1.8s avg
Import
200ms
Disk
29MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.29.27 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 31.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.8s · import 0.200s · 32MB
29MB installed
● package 29MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

dbapi
from hdbcli import dbapi
The primary interface for connecting to SAP HANA databases following PEP 249 is exposed via the 'dbapi' module within hdbcli.

This quickstart demonstrates how to establish a connection to an SAP HANA database using `hdbcli`, execute a simple `SELECT` statement, create a table, insert data, and fetch results. It uses environment variables for secure credential management. Remember to set `HANA_HOST`, `HANA_PORT`, `HANA_USER`, and `HANA_PASSWORD` in your environment.

import os from hdbcli import dbapi # Retrieve credentials from environment variables for security host = os.environ.get('HANA_HOST', 'your_hana_host.com') port = os.environ.get('HANA_PORT', '30015') # Example for single-tenant, adjust as needed user = os.environ.get('HANA_USER', 'YOUR_USER') password = os.environ.get('HANA_PASSWORD', 'YOUR_PASSWORD') try: # Establish a connection to the SAP HANA database # For HANA Cloud, port is typically 443 with encryption=True (default). # For on-premise, adjust port (e.g., 3NN13/3NN15) and encryption. conn = dbapi.connect(address=host, port=int(port), user=user, password=password) print(f"Successfully connected to HANA at {host}:{port}") # Create a cursor object cursor = conn.cursor() # Execute a simple query cursor.execute("SELECT CURRENT_UTCTIMESTAMP FROM DUMMY") # Fetch the result result = cursor.fetchone() print(f"Current UTC Timestamp from HANA: {result[0]}") # Execute an update/insert (example: creating a table and inserting data) try: cursor.execute("DROP TABLE MY_TEST_TABLE_HDBCLI") print("Dropped existing MY_TEST_TABLE_HDBCLI.") except dbapi.Error as e: if "Cannot drop table" not in str(e): # Ignore if table doesn't exist print(f"Error dropping table: {e}") cursor.execute("CREATE TABLE MY_TEST_TABLE_HDBCLI (ID INTEGER PRIMARY KEY, NAME VARCHAR(255))") print("Created MY_TEST_TABLE_HDBCLI.") sql_insert = "INSERT INTO MY_TEST_TABLE_HDBCLI (ID, NAME) VALUES (?, ?)" cursor.execute(sql_insert, (1, 'Item One')) cursor.execute(sql_insert, (2, 'Item Two')) print("Inserted two rows.") # Fetch inserted data cursor.execute("SELECT * FROM MY_TEST_TABLE_HDBCLI") rows = cursor.fetchall() print("Data in MY_TEST_TABLE_HDBCLI:") for row in rows: print(row) # Commit the transaction (if autocommit is off, which it isn't by default in hdbcli) # conn.commit() # Not strictly necessary if autocommit is on (default in hdbcli) except dbapi.Error as e: print(f"HANA Database error: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: # Close the cursor and connection if 'cursor' in locals() and cursor: cursor.close() if 'conn' in locals() and conn: conn.close() print("Connection closed.")
Debug
Known issues
gotchaUnlike PEP 249, `hdbcli` has `autocommit` turned ON by default. This means changes are committed automatically after each DML statement (INSERT, UPDATE, DELETE) unless explicitly managed.
fix
Be aware of the autocommit behavior. If explicit transaction control is desired, you must manage transactions manually (e.g., using `conn.begin()`, `conn.commit()`, `conn.rollback()`).
affects: All versions
gotchaWhen connecting to SAP HANA Cloud, the port number is typically 443, and encryption is always enabled by default. For on-premise HANA tenant databases, the port is often 3NN13, and for single-tenant 3NN15 (where NN is the SAP instance number). Ensure correct port and encryption settings for your specific HANA instance.
fix
Consult your SAP HANA database's connection details. Adjust the `port` parameter in `dbapi.connect()` accordingly. For HANA Cloud, `encryption=True` is often the default or required.
affects: All versions
gotchaThe `hdbcli` package is distributed under the SAP Developer License Agreement, which is a proprietary license. Review the license terms for usage restrictions and compliance.
fix
Refer to the SAP Developer License Agreement (linked from PyPI and documentation) for full details.
affects: All versions
deprecatedThe installation of `hdbcli` via `.tar.gz` sdist is deprecated. Version 2.28 and later now default to `.whl` (wheel) files for installation. The `tar.gz` sdist will be removed in future versions.
fix
Always use `pip install hdbcli` to ensure installation from the preferred `.whl` distribution. Avoid manual installation from `.tar.gz` files where possible.
affects: 2.28 and later
gotchaThere are known limitations for the 32-bit Windows driver, specifically regarding the maximum length of LOB columns and the maximum rowcount that can be returned (both limited to 2,147,483,647).
fix
If working with very large data volumes, use a 64-bit Python environment on Windows.
affects: All versions (32-bit Windows)
gotchaCommunity reports indicate that specific `hdbcli` versions might exhibit connection issues with certain SAP HANA database versions, sometimes requiring version pinning for compatibility across different HANA instances.
fix
If encountering unexpected connection failures, try pinning to a known working `hdbcli` version or consult SAP support and documentation for compatibility matrices between `hdbcli` and your SAP HANA database version.
affects: Potentially specific minor/patch versions (e.g., 2.18.22 mentioned with issues)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hdbcli'
The 'hdbcli' package is not installed in the active Python environment, or there are compatibility issues with the Python version or architecture (e.g., 32-bit Python trying to install a 64-bit wheel).
fix
Ensure you are using a supported Python version and architecture (typically 64-bit Python 3.x) and install the package using `pip install hdbcli`. If `pip install hdbcli` fails with 'No matching distribution found', try upgrading pip or manually installing a compatible wheel from PyPI.
hdbcli.dbapi.Error: (10, "authentication failed:..")
The provided username or password for connecting to the SAP HANA database is incorrect, or the database user lacks the necessary privileges to connect. Firewall rules or IP restrictions on the HANA side might also prevent authentication.
fix
Verify the username and password against the SAP HANA database. Check the database user's permissions and ensure that the IP address from which the connection is being attempted is allowed by the HANA database's network configuration.
hdbcli.dbapi.Error: (-10709, 'Connection failed (...): No connection could be made because the target machine actively refused it')
The SAP HANA database server is unreachable at the specified address and port, often due to incorrect host or port details, network connectivity issues, a firewall blocking the connection, or the HANA database service not running.
fix
Double-check the `address` (hostname or IP) and `port` parameters in the `dbapi.connect()` call. Confirm network connectivity to the HANA host from your client machine and ensure no firewalls are blocking the HANA database port. Verify that the SAP HANA instance is running. For HANA Cloud, the port is typically 443; for tenant databases, it's often 3NN13 (where NN is the instance number).
ImportError: No module named 'pyhdbcli'
This error occurs when the 'hdbcli' package is installed, but a critical internal component, 'pyhdbcli', cannot be found or imported. This often points to a corrupted or incomplete installation of `hdbcli` or issues with the Python environment's path configuration.
fix
Uninstall and then reinstall 'hdbcli' in a clean Python virtual environment to ensure all components are correctly installed. Use `pip uninstall hdbcli` followed by `pip install hdbcli`. Ensure your Python environment is consistent.
Upgrade
Version history
2.29.27latest on PyPI · released Aug 27, 2026
Audit
Dependencies
SAP HANA Client installationoptionalWhile `pip install hdbcli` provides the Python driver, some advanced features, troubleshooting, or specific environments might benefit from or require a full SAP HANA Client installation on the system, which includes underlying native libraries.
Agent activity
35 hits · last 30 days
node
34
Resources
hdbcli — pip install hdbcli · libregistry