SAP HANA Helper for Python (hdbhelper-py)

Description

With the standard hdbcli driver, connecting to SAP HANA from environment credentials and calling stored procedures requires substantial boilerplate:

# Parse VCAP_SERVICES or default-env.json manually...
import json, os
data = json.loads(os.environ["VCAP_SERVICES"])
creds = data["hana"][0]["credentials"]
host, port, user, password = creds["host"], creds["port"], creds["user"], creds["password"]

from hdbcli import dbapi
conn = dbapi.connect(address=host, port=port, user=user, password=password,
                     encrypt=True, sslValidateCertificate=True)
cursor = conn.cursor()
cursor.execute("SET SCHEMA MY_SCHEMA")

# Call a stored procedure with table output
cursor.callproc('MY_SCHEMA."MY_PROC"', [])
columns = [col[0] for col in cursor.description]
rows = [dict(zip(columns, row)) for row in cursor.fetchall()]
cursor.close()
conn.close()

With hdbhelper, the same code becomes:

from hdbhelper import open_from_env

with open_from_env() as db:
    # Simple query
    rows = db.exec_sql("SELECT SESSION_USER, CURRENT_SCHEMA FROM DUMMY")
    print(rows)

    # Stored procedure — automatic parameter binding and result mapping
    proc = db.load_procedure("MY_SCHEMA", "MY_PROC")
    result = proc.call()
    print(result.output_scalar)
    print(result.result_sets)

Installation

pip install -e .           # development install
pip install -e ".[dev]"    # with test dependencies (pytest, pytest-asyncio)

Note: hdbcli is SAP's proprietary Python HANA driver, available on PyPI. Some enterprise environments use internal mirrors — consult your team's Python package index configuration if the standard PyPI install fails.

Usage

Creating a connection

Load credentials from VCAP_SERVICES environment variable or default-env.json:

from hdbhelper import open_from_env

db = open_from_env()
# ... use db ...
db.close()

Or use as a context manager for automatic cleanup:

with open_from_env() as db:
    rows = db.exec_sql("SELECT CURRENT_USER FROM DUMMY")

From a specific env file:

from hdbhelper import open_from_env_file

with open_from_env_file("/path/to/default-env.json") as db:
    ...

With explicit configuration:

from hdbhelper import open, ConnectionConfig

with open(ConnectionConfig(
    host="my-hana.hanacloud.ondemand.com",
    port=443,
    user="DBADMIN",
    password="secret",
    schema="MY_SCHEMA",
    encrypt=True,
)) as db:
    ...

Override the target container or schema:

db = open_from_env(target_container="my-hdi-container", schema="CUSTOM_SCHEMA")

Querying

# Execute SQL and get results as list[dict[str, Any]]
rows = db.exec_sql("SELECT SESSION_USER, CURRENT_SCHEMA FROM DUMMY")

# Parameterised query
rows = db.exec_sql("SELECT * FROM MY_TABLE WHERE ID = ?", (42,))

# Schema helpers
schema = db.current_schema()
db.set_schema("NEW_SCHEMA")

# Resolve schema wildcards
schema = db.schema_calc("**CURRENT_SCHEMA**")  # → actual schema name
schema = db.schema_calc("*")                    # → "%"

Stored procedures

# Load procedure metadata
proc = db.load_procedure("MY_SCHEMA", "MY_PROC")

# Call with input parameters — results as Python dicts
result = proc.call("input_value_1", 42)
print(result.output_scalar)   # dict[str, Any] — scalar OUT parameters
print(result.result_sets)     # list[list[dict[str, Any]]] — table OUT parameters

Inspect procedure parameters before calling:

for p in proc.params:
    print(p.name, p.parameter_type, p.data_type)

Async usage

async_hdbhelper wraps the sync API using asyncio.to_thread, making it safe to use from async code without blocking the event loop:

import asyncio
from async_hdbhelper import async_open_from_env

async def main():
    async with await async_open_from_env() as db:
        rows = await db.exec_sql("SELECT SESSION_USER FROM DUMMY")
        print(rows)

        proc = await db.load_procedure("MY_SCHEMA", "MY_PROC")
        result = await proc.call("input_value")
        print(result.output_scalar)

asyncio.run(main())

API Reference

Connection functions

DB methods

DB also supports the context manager protocol (with open_from_env() as db:).

Procedure

ProcedureResult has two fields: output_scalar: dict[str, Any] for scalar OUT parameters and result_sets: list[list[dict[str, Any]]] for table OUT parameters.

Async (async_hdbhelper)

AsyncDB mirrors all DB methods as coroutines and supports async with.

Environment Configuration

Connection credentials are loaded from default-env.json (same format as the Node.js and Go packages):

{
  "VCAP_SERVICES": {
    "hana": [{
      "name": "my-hana-service",
      "tags": ["hana"],
      "credentials": {
        "host": "...",
        "port": 443,
        "user": "...",
        "password": "...",
        "schema": "...",
        "encrypt": true
      }
    }]
  }
}

• Use default-env-admin.json for admin connections (resolve_env_path(admin=True)).
• Set the TARGET_CONTAINER environment variable to select a specific service binding by name rather than by tag.
• TLS is enabled automatically when encrypt: true is present in the credentials.

Requirements

• Python 3.12 or higher
• hdbcli — SAP HANA Python client driver
• SAP HANA Cloud or on-premise HANA instance

Known Issues

None

How to obtain support

This project is provided "as-is": there is no guarantee that raised issues will be answered or addressed in future releases.

License

Copyright (c) 2026 SAP SE or an SAP affiliate company. All rights reserved. This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.