HDBSQL Command Line Tool: Connection, SQL, and Troubleshooting Examples

The SAP HANA hdbsql command line tool lets administrators connect to a database, execute SQL, inspect results, and automate repeatable operations without opening a graphical client. It is useful for health checks, deployment scripts, backup verification, and incident response.

This guide explains how to connect with hdbsql, choose between interactive and batch execution, protect credentials, and diagnose common connection or SQL errors. Examples are intentionally generic so you can adapt them to your landscape and authorization model.

01What the hdbsql command line tool does

hdbsql is a command-line SQL client supplied with SAP HANA client software. It sends SQL statements to an SAP HANA database and displays the returned result in a terminal or output file.

Common uses include:

• Testing database connectivity from an application or administration host
• Running read-only health checks
• Executing a prepared SQL file during maintenance
• Capturing query results for support or audit records
• Automating operational checks in shell scripts

The client is not a substitute for authorization design or change control. A successful connection only proves that the supplied user can reach the selected database and authenticate. It does not mean the user should be granted broad administrative privileges.

02Prepare the hdbsql environment

Install a compatible SAP HANA client package on the host where you plan to run the command. Confirm that the executable is available in the operating system path, or call it with its full path.

A basic version check can help identify which client is being used:

hdbsql -v

The exact output depends on the client revision and operating system. When troubleshooting, compare the client version with the supported server and driver versions in your organization.

You also need the target host, SQL port, database name where applicable, a valid database user, and a method for handling authentication. Avoid placing a password directly in a command that may be stored in shell history or visible through process inspection.

For related SAP environment checks, see SAP version check.

03Connect with hdbsql

The simplest connection pattern supplies a server endpoint, user, and password:

hdbsql -n db-host.example.com:30015 -u APP_ADMIN -p 'your-password'

The -n option identifies the server and SQL port. The -u option specifies the database user, while -p supplies the password. Replace the example values with your approved connection details.

In a system using a tenant database, make sure the endpoint resolves to the intended database. A connection can succeed against the system database or another tenant while appearing to be a general connectivity test. Verify the host, port, and database context before running any write operation.

Depending on the client release and connection method, you may also provide an instance number or database name. Consult the installed client help for the options supported in your environment:

hdbsql -h

For recurring administration, a secure user store key is generally safer than placing a password in the command line. Create the key with the approved hdbuserstore workflow, then connect through the key:

hdbuserstore set HDB_PROD db-host.example.com:30015 DB_OPERATOR 'your-password'
hdbsql -U HDB_PROD

Protect the operating-system account and user store files. A secure key reduces password exposure, but it does not remove the need for least privilege, host hardening, and access review.

04Run SQL interactively

After connecting, enter a SQL statement and terminate it with a semicolon. For example:

SELECT CURRENT_UTCTIMESTAMP FROM DUMMY;

A small metadata query can confirm the database context:

SELECT DATABASE_NAME, HOST, SQL_PORT
FROM SYS.M_DATABASE;

Use read-only queries first when validating a new connection. The following pattern is useful for checking a table or view without changing data:

SELECT TOP 10 *
FROM "APP_SCHEMA"."CUSTOMERS";

The exact object name and required privileges depend on the schema. Quoted identifiers are case-sensitive in SAP HANA, so preserve the capitalization used when the object was created.

Interactive sessions are useful for exploration and one-off checks. They are less suitable for repeatable changes because a command typed manually is harder to review, reproduce, and audit.

05Run SQL from a file

Store repeatable statements in a reviewed SQL file and pass that file to hdbsql using the input-file option supported by your client release. A typical pattern is:

hdbsql -U HDB_PROD -I health-check.sql

A sample health-check.sql file might contain:

SELECT CURRENT_UTCTIMESTAMP FROM DUMMY;
SELECT DATABASE_NAME, HOST, SQL_PORT FROM SYS.M_DATABASE;

You can redirect output to a file when you need a record for a deployment or support investigation. Confirm the output and error-handling behavior of your installed client before using it in automation:

hdbsql -U HDB_PROD -I health-check.sql > health-check.out 2> health-check.err

For production changes, add review, backups where appropriate, transaction planning, and a tested rollback approach. Do not treat a shell script that continues after an SQL error as a successful deployment.

06Use hdbsql for administration checks

hdbsql is especially valuable when a graphical administration tool is unavailable or when a check must run from a jump host. Read-only queries can help confirm database status, resource conditions, and operational metadata.

Examples of safe starting points include checking the current database, inspecting selected monitoring views, and validating that expected services or objects are visible to the connected user. Monitoring views and columns can vary by SAP HANA revision, so use the system documentation for the release installed in your landscape.

For backup-related operations, pair command-line checks with your established backup and recovery procedure rather than improvising a recovery command during an incident. See SAP HANA backup and recovery and SAP HANA log backup for related operational topics.

For lifecycle actions such as starting or stopping a system, use the documented operating procedure and required administrative tools. hdbsql can help validate the result, but it should not be used casually for high-impact system changes. See SAP HANA start and stop.

07Control output for scripts

Human-readable output is convenient at a terminal, but automation benefits from predictable formatting. Review the hdbsql help output for switches that control headers, separators, output files, and error behavior in your client version.

When designing a script, make the expected result explicit. For example, a health check can query a known value and compare it with the expected response instead of merely checking whether the client started.

SELECT CASE
         WHEN 1 = 1 THEN 'OK'
         ELSE 'FAILED'
       END AS CHECK_RESULT
FROM DUMMY;

A robust wrapper should record the command context, target environment, timestamp, return code, and relevant error output. Never log passwords, secure store contents, or sensitive query results without an approved retention and masking policy.

08Troubleshoot hdbsql connection errors

Start with the failure category rather than repeatedly changing command options. The following sequence narrows most connection problems efficiently.

1. Confirm that the hdbsql executable is the expected client version.
2. Verify DNS resolution or host-file configuration for the database host.
3. Test network access to the SQL port from the same host and operating-system account.
4. Confirm that the endpoint belongs to the intended system database or tenant.
5. Check the user name, authentication method, and account status.
6. Review TLS requirements, certificates, and client configuration when encrypted communication is required.
7. Inspect the server and client-side error messages for the next specific action.

A network timeout usually indicates routing, firewall, listener, or endpoint problems. An authentication error points more often to the user, password, user store key, account status, or authentication policy. An authorization error means the connection succeeded but the requested object or operation is not permitted.

If repeated failed logons have locked an account, stop retrying and follow the approved account recovery process. See SAP HANA user privileges for the relationship between identity, roles, and permitted operations.

09Avoid common hdbsql mistakes

Wrong database context is one of the most consequential mistakes. A command may succeed while querying a different tenant or system database than intended. Display the current context and include the target environment in your operational notes.

Overprivileged automation users create unnecessary risk. Use a dedicated account with only the privileges required for the task, separate read-only checks from controlled change execution, and rotate credentials according to policy.

Other frequent problems include missing semicolons, incorrectly quoted case-sensitive identifiers, unsupported SQL syntax for the server revision, and shell quoting that changes a password or SQL argument before hdbsql receives it.

Do not paste production credentials into tickets, chat, shell history, or shared scripts. If a credential is exposed, treat it as compromised and follow the incident and rotation procedure.

10Build a repeatable hdbsql workflow

A dependable workflow separates connection validation, read-only inspection, change execution, and result verification.

1. Select the approved host, database endpoint, and least-privileged user.
2. Connect with a secure user store key where possible.
3. Run a harmless context query before any operational SQL.
4. Execute reviewed SQL from a version-controlled file for repeatable work.
5. Capture output and return status without exposing secrets.
6. Verify the result with an independent query or application check.
7. Record the target, operator, time, change reference, and outcome.

This approach makes hdbsql useful for both daily operations and certification preparation. Candidates studying SAP HANA administration should connect command-line syntax with broader topics such as user management, monitoring, backup, recovery, and controlled system changes.

11Summary

The hdbsql command line tool provides a practical interface for SAP HANA connectivity, SQL execution, and automation. The safest pattern is to use a compatible client, identify the correct tenant or system database, authenticate through a protected method, start with read-only checks, and run reviewed SQL files for repeatable tasks.

When a command fails, separate network, authentication, authorization, SQL, and output-format problems. That distinction reduces guesswork and helps administrators resolve incidents without adding unnecessary changes.