SAP HANA Clients: new features in SPS04

Along with all the other components in SAP HANA, the HANA Clients have a set of new features released in HANA SPS04 (April 2019). The HANA Client versions affected are 2.4 and above. This blog post gives an overview of most of the user-visible new features.

As always, remember that the HANA Clients are cross-compatible with the HANA Server: new HANA Clients can be used with an old HANA server back to HANA 1.0 SPS10, and old clients will work with new versions of HANA server. There are some features that require both a new HANA client and a new HANA server to work, but of course that is to be expected.

Licensing and availability

Before getting to the technical features, we’ve made some changes to make the clients more easy to access and use.

HANA Clients are now redistributable. This is particularly important for software vendors who support HANA in their products: you now have the rights to bundle the HANA database drivers with your applications. The relevant changes are to the SAP Software Use Rights. As long as you are covered by this agreement, clause 11.21 of the SUR provides you with redistribution rights for SAP HANA Client Software.

The text is reproduced here. The word “sublicense” implies the right to redistribute the HANA Client Software.

11.21. SAP HANA Client Software

Licensee may market and sublicense the HANA Client Software only for use in conjunction with Licensee’s own products. Any Third Party Products contained in or provided with the HANA Client Software may only be used as part of the HANA Client Software. Licensee must not charge any third party a fee or any other form of consideration for access to, or use of, the HANA Client Software. Licensee may not install files, as set forth at https://wiki.scn.sap.com/wiki/display/SAPHANA/SAP+HANA+Client+redistributable+files, into the HANA Client Software default install path.

We are also making the clients easier to access. Even if you do not have access to the SAP Software Downloads site, you can now get the client software under an SAP Developer License from https://tools.hana.ondemand.com#hana. And if you are a Java developer, the JDBC driver is available directly from Maven Central.

New APIs

One new API appears in this release. There is now a .NET Core driver. Initially available for Windows, we expect Linux and Mac releases to follow soon. Documentation is here.

Those interested in machine learning have two new machine learning APIs specifically for running machine learning tasks in HANA. These Python and R API libraries are included in the HANA Client, but if you want to know more about how to use them, go to the Predictive Analytics Library documentation.

Troubleshooting help

Troubleshooting complex problems often needs as much information as you can get from both the server side (logs and traces) and the client side.

Client APIs have been enhanced with functions to retrieve three kinds of resource information for an individual request: the server CPU time, server processing time, and server memory usage. See the Client Interface Programming Reference for the particular API you use. For example, in python these functions are methods on the cursor object:

cursor = conn.cursor()
cursor.execute(sql)
print("Server CPU Time:\t{} microseconds".format(cursor.server_cpu_time()))
print("Server Processing Time:\t{} microseconds".format(cursor.server_processing_time()))
print("Server Memory Usage:\t{} bytes".format(cursor.server_memory_usage()))
cursor.close()

Connections

Networks and deployment environments continue to change, and the HANA Client is changing so that it can operate in them. Here is a list of new connection-related items in the client software.

• IPv6: HANA connectivity is now supported in all-IPv6 networks. Usually you will not be supplying IPv6 addresses explicitly but will instead supply a host name and rely on name resolution through DNS. The feature means that connectivity will work properly even on networks where machines have only IPv6 addresses.
• WebSockets, for HANA Service: HANA Service databases (that is, HANA running in the SAP Cloud Platform) accept regular TCP/IP connections, but as the port number ranges are often blocked by corporate firewalls, using direct TCP/IP to HANA Service from inside a corporate network may be problematic. WebSockets provide TCP/IP over the HTTP or HTTPS default ports (80 and 443), which are typically permitted through corporate firewalls. For details, see the connection parameters described for your interface.
• SSL certificates as strings. When using secure connections, the client must supply a public or private certificate to the server (depending on which side has the private key). In traditional client/server environments, the certificate will be held in the file system. Some browser-based applications may not have access to the filesystem and may store certificates in another location. To make secure connections possible for these applications, you can now supply the certificate as a string, rather than as a filename, in the sslTrustStore or sslKeyStore connection parameters. The certificate must be in PEM format.
• Easier setup for CCL encryption: While Microsoft and OpenSSL encryption libraries are both supported, there are some applications (such as client-side encryption) that require the use of SAP Common Crypto Lib (CCL) libraries. Setting up CCL is not always easy. As a convenience, you can now use the hdbclienv batch file (Windows) or shell script (Linux) to set the environment variables you need. See the documentation for details.

Connection parameters: better behavior on multi-node systems

The HANA Client libraries are not just a pipe that acts as a conduit for requests. In multi-node HANA deployments, with failover and / or HANA System Replication, the client knows the topology of the entire deployment (which databases are available on which nodes), and plays an important part in routing requests to the correct node. As fetching large data volumes over a network is so much slower than fetching from memory. routing to the correct node can make a huge performance difference.

In addition, depending on latency and application, sending additional requests can be a performance anchor or can be a big performance boost: the additional requests themselves take time, but if they result in an expensive query being executed at the right node, they can save time too. Here is a list of features that provide better connectivity in multi-node systems.

• Two-layer partitioning-aware. Tables can be split across nodes based on the values in multiple columns. For example, you may partition a table by both a date column and a geography column. HANA Clients can now understand a two-level partitioning, and so route requests to the proper node based on two columns.
• Routing SQL direct execute requests: The ability to route a query to the best node relies on it being prepared and then executed, in separate requests. The routing is decided in the prepare requests. For applications that execute SQL queries directly (without a separate “prepare” request), the HANA client drivers accept a new connection property called routeDirectExecute. If you set this to “true” then it converts a direct execute request into separate prepare and execute requests, which leads to a better choice of node in the execute phase.
• Combine prepare and execute: Some applications that work with single-node databases don’t care about smart routing. In addition, if the client/server communication is over a high-latency network then there can be significant overhead from the additional round trip needed by carrying out separate prepare and execute statements. For this class of application, JDBC now provides a “deferredPrepare” connection property that combined the prepare and execute into a single request. Set to “false” by default, this is a special purpose property only for use with applications that have a particular workload pattern.
• Invisible takeover The HANA Server has been consistently adding features for smoother takeover in the case of server failures. HANA System Replication creates a secondary site that can takeover from the primary if the primary fails. The takeover process involves DNS changes so that host names are redirected to the new system. The HANA Client can now detect a takeover and, under some conditions, re-establish a connection with the takeover system.
• Force route to site: In sites using HANA System Replication, with Active/Active enabled, queries could be sent to either the primary site or to a secondary site. (Note: this is two *sites*, not two nodes of a single site). The ability to direct a specific query to a particular site can help balance the load between the two, and enable better overall scalability. The ODBC, JDBC, and node.js interfaces now support connection properties that you can use to direct specific queries to one site or the other. For complete documentation, see here.

That completes the roundup of HANA Client new features in HANA 2.0 SPS04.