Install & Compatibility
Where this runs
tested against v4.6.1 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.692s · 60.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.9s · import 0.610s · 58MB
59MB installed
● package 59MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine
CreateView
✓ from sqlalchemy_hana.elements import CreateView
Used for managing SQL views which are not bound to SQLAlchemy metadata.
DropView
✓ from sqlalchemy_hana.elements import DropView
Used for managing SQL views which are not bound to SQLAlchemy metadata.
types
✓ from sqlalchemy_hana import types
Provides SAP HANA specific data types.
errors
✓ from sqlalchemy_hana import errors
Provides SAP HANA specific error handling and wrapper methods.
This quickstart demonstrates how to establish a connection to an SAP HANA database using `sqlalchemy-hana` and execute a simple SQL query. It uses environment variables for connection parameters for security and flexibility. Alternatively, an HDB User Store key can be used with `hana://userkey=my_user_store_key`.
import os
from sqlalchemy import create_engine, text
# Environment variables for connection details (replace with your actual values or user store key)
HANA_USER = os.environ.get('HANA_USER', 'your_username')
HANA_PASSWORD = os.environ.get('HANA_PASSWORD', 'your_password')
HANA_HOST = os.environ.get('HANA_HOST', 'your_hana_host')
HANA_PORT = os.environ.get('HANA_PORT', '30015') # Default port for SAP HANA
HANA_TENANT_DB = os.environ.get('HANA_TENANT_DB', '') # Optional: for tenant databases
HANA_USERKEY = os.environ.get('HANA_USERKEY', '') # Optional: for hdbuserstore key
connection_string = f"hana://{HANA_USER}:{HANA_PASSWORD}@{HANA_HOST}:{HANA_PORT}"
if HANA_TENANT_DB:
connection_string += f"/{HANA_TENANT_DB}"
if HANA_USERKEY:
connection_string = f"hana://userkey={HANA_USERKEY}"
try:
# Create an engine to connect to SAP HANA
engine = create_engine(connection_string, echo=False)
# Establish a connection and execute a simple query
with engine.connect() as connection:
result = connection.execute(text("SELECT 'Hello from SAP HANA!' AS greeting FROM DUMMY"))
for row in result:
print(row.greeting)
print("Successfully connected to SAP HANA and executed a query.")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure HANA_USER, HANA_PASSWORD, HANA_HOST, HANA_PORT, "
"and hdbcli are correctly configured or HANA_USERKEY is set.")
Debug
Known issues
breakingMigration from `sqlalchemy-hana` 3.x (or older) to 4.x requires `SQLAlchemy 2.x` and `Python 3.10+`. Older `sqlalchemy-hana` versions often targeted `SQLAlchemy 1.x` and might have used the `pyhdb` driver, which is no longer supported by current `sqlalchemy-hana` versions that exclusively use `hdbcli`. This necessitates updating `SQLAlchemy` and potentially adjusting code for `SQLAlchemy 2.x`'s API changes.fixUpgrade SQLAlchemy to version 2.x and Python to 3.10+. Replace any `pyhdb` driver configurations with `hdbcli`. Review SQLAlchemy's 2.x migration guide for API changes in your application.
affects: <4.0.0 to 4.0.0+
gotchaBy default, `sqlalchemy-hana` now uses native boolean types. Older versions represented booleans as integers. For compatibility with existing databases or applications expecting integer representation, `use_native_boolean=False` must be passed to the `create_engine` function.fixAdd `use_native_boolean=False` to your `create_engine` call if you need to maintain integer representation for boolean columns. Example: `create_engine('hana://...', use_native_boolean=False)`. affects: All versions (when migrating from older data models)
gotcha`UPSERT` statements are supported but with limitations. Notably, caching for `UPSERT` operations is explicitly disabled due to implementation details. This may impact performance expectations for bulk `UPSERT` operations and might require alternative strategies or custom SQL.fixBe aware of potential performance implications for `UPSERT`. Consider using SQLAlchemy's bulk insert/update features with a custom `on_conflict_do_update` clause if more control or specific performance is needed, although a unified implementation is still pending in SQLAlchemy itself.
affects: All versions
gotchaSQL views are not bound to the SQLAlchemy metadata object. Therefore, they cannot be automatically created or dropped with `MetaData.create_all()` or `MetaData.drop_all()`. Views need to be explicitly managed using `CreateView` and `DropView` functions from `sqlalchemy_hana.elements`.fixManually create and drop views using `connection.execute(CreateView(my_view))` and `connection.execute(DropView(my_view))`.
affects: All versions
gotcha`sqlalchemy-hana` is an open-source project and is not an official SAP product. As such, it is not covered by SAP support. Users should rely on the project's GitHub repository for issues, community support, and contributions.fixFor support or issues, refer to the project's GitHub issues page: `https://github.com/SAP/sqlalchemy-hana/issues`.
affects: All versions
Errors
Common errors & fixes
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:hana
The `sqlalchemy-hana` package, which registers the 'hana' dialect with SQLAlchemy, is not installed or not accessible in the current Python environment.
fixpip install sqlalchemy-hana
ModuleNotFoundError: No module named 'hdbcli'
The `hdbcli` package, which is the required SAP HANA database driver for `sqlalchemy-hana`, is not installed.
sqlalchemy.exc.OperationalError: (hdbcli.dbapi.Error) (-93000, 'Invalid connection information')
The connection string (DSN) provided for the SAP HANA database is incorrect, or the database server is unreachable or not configured for the given credentials.
fixVerify the connection string details (host, port, user, password, schema/tenantDB) and ensure network connectivity to the HANA database, e.g., `engine = create_engine('hana://<user>:<password>@<host>:<port>')`. Upgrade
Version history
4.6.1latest on PyPI · released Jul 17, 2026
Audit
Dependencies
hdbclirequiredRequired DBAPI driver for connecting to SAP HANA.
SQLAlchemyrequiredCore SQLAlchemy library; version 2.x is required for sqlalchemy-hana 4.x.
PythonrequiredRequires Python 3.10+.