{"id":5068,"library":"sqlalchemy-hana","title":"SQLAlchemy dialect for SAP HANA","description":"SQLAlchemy dialect for SAP HANA. It enables Python applications to connect to SAP HANA databases using SQLAlchemy's ORM and Core features, leveraging the `hdbcli` driver for connectivity. The library is currently at version 4.5.0 and follows semantic versioning, indicating that breaking changes are introduced only in major releases.","status":"active","version":"4.5.0","language":"en","source_language":"en","source_url":"https://github.com/SAP/sqlalchemy-hana","tags":["database","SAP HANA","SQLAlchemy","ORM","dialect","hdbcli"],"install":[{"cmd":"pip install sqlalchemy-hana","lang":"bash","label":"Basic installation"},{"cmd":"pip install sqlalchemy-hana[alembic]","lang":"bash","label":"With Alembic support"}],"dependencies":[{"reason":"Required DBAPI driver for connecting to SAP HANA.","package":"hdbcli","optional":false},{"reason":"Core SQLAlchemy library; version 2.x is required for sqlalchemy-hana 4.x.","package":"SQLAlchemy","optional":false},{"reason":"Requires Python 3.10+.","package":"Python","optional":false}],"imports":[{"symbol":"create_engine","correct":"from sqlalchemy import create_engine"},{"note":"Used for managing SQL views which are not bound to SQLAlchemy metadata.","symbol":"CreateView","correct":"from sqlalchemy_hana.elements import CreateView"},{"note":"Used for managing SQL views which are not bound to SQLAlchemy metadata.","symbol":"DropView","correct":"from sqlalchemy_hana.elements import DropView"},{"note":"Provides SAP HANA specific data types.","symbol":"types","correct":"from sqlalchemy_hana import types"},{"note":"Provides SAP HANA specific error handling and wrapper methods.","symbol":"errors","correct":"from sqlalchemy_hana import errors"}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, text\n\n# Environment variables for connection details (replace with your actual values or user store key)\nHANA_USER = os.environ.get('HANA_USER', 'your_username')\nHANA_PASSWORD = os.environ.get('HANA_PASSWORD', 'your_password')\nHANA_HOST = os.environ.get('HANA_HOST', 'your_hana_host')\nHANA_PORT = os.environ.get('HANA_PORT', '30015') # Default port for SAP HANA\nHANA_TENANT_DB = os.environ.get('HANA_TENANT_DB', '') # Optional: for tenant databases\nHANA_USERKEY = os.environ.get('HANA_USERKEY', '') # Optional: for hdbuserstore key\n\nconnection_string = f\"hana://{HANA_USER}:{HANA_PASSWORD}@{HANA_HOST}:{HANA_PORT}\"\nif HANA_TENANT_DB:\n    connection_string += f\"/{HANA_TENANT_DB}\"\n\nif HANA_USERKEY:\n    connection_string = f\"hana://userkey={HANA_USERKEY}\"\n\n\ntry:\n    # Create an engine to connect to SAP HANA\n    engine = create_engine(connection_string, echo=False)\n\n    # Establish a connection and execute a simple query\n    with engine.connect() as connection:\n        result = connection.execute(text(\"SELECT 'Hello from SAP HANA!' AS greeting FROM DUMMY\"))\n        for row in result:\n            print(row.greeting)\n\n    print(\"Successfully connected to SAP HANA and executed a query.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure HANA_USER, HANA_PASSWORD, HANA_HOST, HANA_PORT, \"\n          \"and hdbcli are correctly configured or HANA_USERKEY is set.\")","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade 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.","message":"Migration 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.","severity":"breaking","affected_versions":"<4.0.0 to 4.0.0+"},{"fix":"Add `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)`.","message":"By 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.","severity":"gotcha","affected_versions":"All versions (when migrating from older data models)"},{"fix":"Be 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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually create and drop views using `connection.execute(CreateView(my_view))` and `connection.execute(DropView(my_view))`.","message":"SQL 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For support or issues, refer to the project's GitHub issues page: `https://github.com/SAP/sqlalchemy-hana/issues`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}