{"id":2529,"library":"hdbcli","title":"SAP HANA Python Client (hdbcli)","description":"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.","status":"active","version":"2.28.19","language":"en","source_language":"en","source_url":"https://help.sap.com/viewer/f1b440ded6144a54ada97ff95dac7adf/latest/en-US/39eca89d94ca464ca52385ad50fc7dea.html","tags":["SAP","HANA","client","database","SQL","PEP 249","proprietary"],"install":[{"cmd":"pip install hdbcli","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"While `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.","package":"SAP HANA Client installation","optional":true}],"imports":[{"note":"The primary interface for connecting to SAP HANA databases following PEP 249 is exposed via the 'dbapi' module within hdbcli.","symbol":"dbapi","correct":"from hdbcli import dbapi"}],"quickstart":{"code":"import os\nfrom hdbcli import dbapi\n\n# Retrieve credentials from environment variables for security\nhost = os.environ.get('HANA_HOST', 'your_hana_host.com')\nport = os.environ.get('HANA_PORT', '30015') # Example for single-tenant, adjust as needed\nuser = os.environ.get('HANA_USER', 'YOUR_USER')\npassword = os.environ.get('HANA_PASSWORD', 'YOUR_PASSWORD')\n\ntry:\n    # Establish a connection to the SAP HANA database\n    # For HANA Cloud, port is typically 443 with encryption=True (default).\n    # For on-premise, adjust port (e.g., 3NN13/3NN15) and encryption.\n    conn = dbapi.connect(address=host, port=int(port), user=user, password=password)\n    print(f\"Successfully connected to HANA at {host}:{port}\")\n\n    # Create a cursor object\n    cursor = conn.cursor()\n\n    # Execute a simple query\n    cursor.execute(\"SELECT CURRENT_UTCTIMESTAMP FROM DUMMY\")\n\n    # Fetch the result\n    result = cursor.fetchone()\n    print(f\"Current UTC Timestamp from HANA: {result[0]}\")\n\n    # Execute an update/insert (example: creating a table and inserting data)\n    try:\n        cursor.execute(\"DROP TABLE MY_TEST_TABLE_HDBCLI\")\n        print(\"Dropped existing MY_TEST_TABLE_HDBCLI.\")\n    except dbapi.Error as e:\n        if \"Cannot drop table\" not in str(e): # Ignore if table doesn't exist\n            print(f\"Error dropping table: {e}\")\n\n    cursor.execute(\"CREATE TABLE MY_TEST_TABLE_HDBCLI (ID INTEGER PRIMARY KEY, NAME VARCHAR(255))\")\n    print(\"Created MY_TEST_TABLE_HDBCLI.\")\n\n    sql_insert = \"INSERT INTO MY_TEST_TABLE_HDBCLI (ID, NAME) VALUES (?, ?)\"\n    cursor.execute(sql_insert, (1, 'Item One'))\n    cursor.execute(sql_insert, (2, 'Item Two'))\n    print(\"Inserted two rows.\")\n\n    # Fetch inserted data\n    cursor.execute(\"SELECT * FROM MY_TEST_TABLE_HDBCLI\")\n    rows = cursor.fetchall()\n    print(\"Data in MY_TEST_TABLE_HDBCLI:\")\n    for row in rows:\n        print(row)\n\n    # Commit the transaction (if autocommit is off, which it isn't by default in hdbcli)\n    # conn.commit() # Not strictly necessary if autocommit is on (default in hdbcli)\n\nexcept dbapi.Error as e:\n    print(f\"HANA Database error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Close the cursor and connection\n    if 'cursor' in locals() and cursor:\n        cursor.close()\n    if 'conn' in locals() and conn:\n        conn.close()\n        print(\"Connection closed.\")","lang":"python","description":"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."},"warnings":[{"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()`).","message":"Unlike 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the SAP Developer License Agreement (linked from PyPI and documentation) for full details.","message":"The `hdbcli` package is distributed under the SAP Developer License Agreement, which is a proprietary license. Review the license terms for usage restrictions and compliance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `pip install hdbcli` to ensure installation from the preferred `.whl` distribution. Avoid manual installation from `.tar.gz` files where possible.","message":"The 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.","severity":"deprecated","affected_versions":"2.28 and later"},{"fix":"If working with very large data volumes, use a 64-bit Python environment on Windows.","message":"There 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).","severity":"gotcha","affected_versions":"All versions (32-bit Windows)"},{"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.","message":"Community 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.","severity":"gotcha","affected_versions":"Potentially specific minor/patch versions (e.g., 2.18.22 mentioned with issues)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}