SAP HANA HDI Containers: Architecture, Deployment, and Troubleshooting

01What an HDI container is

An SAP HANA Deployment Infrastructure (HDI) container is a managed development space for database artifacts. It provides an isolated runtime context in which tables, views, procedures, calculation views, and related objects are deployed from source files.

An HDI container normally includes a container schema for application objects, a technical owner used by deployment tooling, and an access schema used by applications or other database users. The exact service configuration depends on the application architecture and the services available in the SAP HANA system.

HDI is most useful when database artifacts are treated as application source code. Developers define objects in files, deploy them through a controlled process, and let the deployment engine manage the resulting database objects. This approach supports repeatable deployments and clear separation between application content and administrative ownership.

For broader context, see the SAP HANA development overview.

02HDI container architecture

An HDI application commonly contains three cooperating parts:

• A database module containing design-time artifacts such as .hdbtable, .hdbview, procedure, role, and synonym definitions.
• A deployer module that applies the artifacts to the target HDI container.
• One or more application modules that connect through a bound HDI service or a generated database credential.

The HDI service supplies the container-specific database binding. The deployer uses that binding to create, alter, and remove objects in the container schema. Application code normally consumes objects through a controlled interface rather than connecting with the container owner.

A container is therefore more than a schema. A schema is a database namespace. An HDI container combines schemas, technical users, service bindings, deployment metadata, and access-management conventions around that namespace.

03HDI container versus schema

A traditional schema is usually created and managed directly by a database administrator. Objects can be created with SQL, and application users receive privileges on those objects through database roles or explicit grants.

An HDI container adds a source-driven lifecycle. The deployer reads design-time files and maintains the corresponding run-time objects. This makes the container a better fit for applications that need repeatable delivery, isolated ownership, and automated deployment.

Use a traditional schema when the workload is centrally administered and its object lifecycle is intentionally managed with direct SQL or established database procedures. Use an HDI container when the database model belongs to an application delivery process and should move through development, test, and production with controlled deployments.

The choice also affects ownership. In a traditional schema, an administrator may own and change objects directly. In an HDI container, direct manual changes to generated objects can be overwritten or can cause later deployments to fail. Treat the source artifacts and deployment configuration as the authoritative definition.

04Build an HDI database module

Start by defining the database artifacts that the application needs. Common examples include tables, views, table types, procedures, functions, calculation views, synonyms, and roles. Keep related artifacts in a clear directory structure so dependencies are easy to review.

For table definitions, use the supported .hdbtable format and keep the design-time file under source control. The guide to SAP HANA hdbtable and hdbview files is useful when deciding how to represent persistent objects.

Declare dependencies explicitly. A view that reads a table must be deployed after that table exists. A procedure that calls another procedure must have the required dependency available. Roles and grants should be designed with the same dependency awareness.

Use stable names and avoid embedding environment-specific values in database artifacts. Put environment-specific endpoints, credentials, and service settings in deployment configuration or service bindings instead of hard-coding them in the database module.

05Deploy an HDI container

A practical deployment sequence is:

1. Confirm that the target SAP HANA system is available and that the HDI service instance and binding are present.
2. Check the database module for syntax errors, unresolved dependencies, invalid references, and unintended destructive changes.
3. Build the database module and deploy it through the project’s delivery process.
4. Review the deployer output for the first failing artifact rather than starting with the final summary line.
5. Validate the deployed objects with SAP HANA database explorer or SAP HANA cockpit.
6. Test the application connection with the intended technical user and verify that its roles expose only the required objects.

The deployment process should be repeatable. The SAP HANA development CI/CD basics article provides related guidance for putting database deployments into a controlled delivery pipeline.

Avoid mixing manual production changes with source-controlled deployments. If an emergency database change is required, record the change in the project artifacts and deploy the reconciled state through the normal process.

06Manage grants and access

HDI access is normally separated into object ownership, application access, and external access. The technical owner manages deployment operations. The application user receives roles intended for runtime use. An external consumer receives only the access required for the published interface.

Create roles around business capabilities rather than assigning broad system privileges. A read-only role should expose only the required views or tables. A write role should be limited to the procedures or tables that the application must change.

Use container-aware grant artifacts for access between containers or between a container and an external object. Confirm that the referenced object exists in the target environment and that the target user or role is available before deployment.

When an application receives authorization errors, identify the exact database object and operation first. Then check the active user, its assigned roles, the object owner, and any cross-container grant configuration. Re-running deployment without resolving the privilege path rarely fixes an authorization failure.

07Troubleshoot deployment failures

Begin with the earliest error in the deployer log. Later messages often describe consequences of the first failure, such as missing objects or failed cleanup operations.

Syntax or parse errors usually point to an invalid artifact format, unsupported property, malformed expression, or an incorrectly named object. Isolate the artifact, validate it independently, and redeploy after correcting the source file.

Dependency errors indicate that an artifact refers to an object that has not been created or is not available in the expected container. Check file names, object names, synonyms, and deployment ordering.

Privilege errors require an access-path review. Confirm the service binding, deployment user, target schema, grant files, and referenced external objects. SAP HANA cockpit and SAP HANA database explorer can help confirm object ownership and runtime access.

Activation or runtime errors often appear after deployment succeeds. Test the object directly with the intended application user, inspect the generated role assignments, and verify that the application is using the expected service binding.

Destructive-change failures occur when a deployment would remove or alter data-bearing objects in a way the deployment engine cannot apply safely. Review the change, back up data where appropriate, and use a controlled migration strategy for structural changes.

08Operate HDI containers safely

Keep separate containers or service instances for separate environments. Development changes should move through review and validation before reaching production. Do not reuse credentials across environments.

Monitor deployment logs, service health, disk usage, and application connection failures. For wider operational procedures, the SAP HANA memory usage guide and SAP HANA start and stop guide cover related on-premise administration tasks.

Back up the underlying SAP HANA database according to the operational recovery plan. An HDI container is part of the database landscape, so recovery planning must include its data, required users and roles, service configuration, deployment sources, and any external objects on which the application depends.

Keep deployment sources, role definitions, binding configuration, and release records together. This gives operators enough information to rebuild the application database state and to determine which version was active when an incident occurred.

09HDI deployment checklist

Before deployment, confirm the following:

• The target HDI service and binding identify the intended SAP HANA system.
• Database artifacts use valid names and supported formats.
• Dependencies are available in the target container or are declared through supported access mechanisms.
• Roles provide the required access without unnecessary privileges.
• Environment-specific settings are externalized.
• Destructive changes have an approved data-handling plan.
• The deployer log is retained with the release record.
• Post-deployment tests run with the same access path used by the application.

After deployment, verify object availability, application connectivity, authorization behavior, and expected data access. Record the deployed version and any manual operational action required for the release.