Framework For Samples
Personally, I built the samples using VSCode locally which does require having a Node.js runtime installed on your system as well. But if you are unsure about installing any or all the perquisites, then I recommend one of the hosted options like SAP Business Application Studio or Devcontainers.
In all the samples and different approaches, we are about to look at, the connection to the SAP HANA database is always handled by the @sap/xsenv module. We will talk about that module more in a minute once we get into the samples, but for now it’s enough to know that it supports connecting to HANA regardless of if you are running the code on XSA, Cloud Foundry, Kyma/Kubernetes or even running locally. In the local scenario it uses a file named default-env.json to store all the connection details. Such a file can be created by using the hana-cli connect command.
And finally, the data model for the sample has been kept simple so that we can focus on the coding and differences between each of the approaches. I’ve not used any HDI containers or concepts. Only plain SQL connections with named DB users. All the tables/views/procedures I’m using in the samples come from the common SYS schema. I tested everything in SAP HANA Cloud Free Tier using the default DBADMIN user.
@sap/hana-client vs. hdb
Let’s start our discussion with the @sap/hana-client module. Afterall the subject line for this module is “Official SAP HANA Node.js Driver” and if you look up Node.js Application Programming in the SAP HANA Client Programming Documentation this is the one and only module/library that it talks about. So seemingly straight forward. Well not so fast…
There is also a Node.js module named hdb and the description on it says, “SAP HANA Database Client for Node”. Further reading reveals that both hdb and @sap/hana-client are support by SAP. So, both are “official” HANA client drivers in that regard. But there is some guidance here in the documentation for the hdb module: “When starting a new project, it is encouraged to use the fully featured @sap/hana-client driver”. That’s a clear-cut recommendation for one module over the other. That same documentation for the hdb module even has a nice comparison table (please always refer to the original documentation for the definitive version of this table):
From this recommendation it might seem you can discard hdb as a relic of time past (it was the first version of the HANA Client for Node.js before @sap/hana-client was delivered). But then you might be surprised to see that the SAP Cloud Application Programming Model supports both modules but since July 2021 defaults to hdb not @sap/hana-client. If there is so much more feature support in @sap/hana-client, why does CAP default to hdb?
There are some important architectural differences between @sap/hana-client and hdb that are critical for any developer to consider before choosing between the two. This is described right in the prerequisites for @sap/hana-client:
This driver communicates with the native HANA libraries, and thus requires platform-specific native binaries. The official hosted version includes precompiled libraries for Linux, Windows and Mac OS X.
By comparison @sap/hana-client is over 120Mb, almost all taken up by the prebuild folder with the OS specific precompiled libraries. And keep in mind that in a single project it’s possible for the same module multiple times (at different versions). You can quickly balloon your entire project to half a Gb or more.
Therefore, you must ask yourself the question: Do I really need one or more of those features that only the @sap/hana-client supports? If so, then certainly start with that module. But if not then consider the size and OS/Native library implications carefully.
This was a decision I also faced a few months ago. I’m the primary maintainer of the hana-cli sample code project. Since the beginning it had used @sap/hana-client (and @sap/hdbext + sap-hdbext-promisfied which we will talk about more in the next part of this blog post series). But the installation size and complexity of the resulting multiple copies of @sap/hana-client this created was starting to cause problems. Particularly when you start thinking about containerizing your services, a proliferation of multiple native libraries and size limitations becomes even more of a concern. Therefore, I made the decision in January, 2022 to rewrite the entire project to use hdb instead.
Luckily, the architectural differences are far more drastic than the coding differences between these two modules. Let’s look at two examples side by side. One that uses @sap/hana-client and one that uses hdb module to perform a basic SQL statement.
In both approaches we use @sap/xsenv to load a service definition with the label “hana“. This module is responsible for inspecting the environment and pulling and adapting the service details regardless of if the information is coming from a local default-env.json, a Cloud Foundry or XSA service binding or a Kubernetes/Kyma Secret. This makes your code with either HANA client module very portable to different deployment targets. The main difference is that the data structure that is returned from @sap/xsenv matches exactly the format expected by the hdb module’s createClient function.
The @sap/hana-client, on the other hand, expects slightly different metadata formatting. For example, it wants the host and port to be combined into a single field. There are also some naming differences. It doesn’t create a material difference, but it can be annoying if you are used to utilizing the @sap/xsenv module. Luckily, we will see in the next part of this blog post series how the wrapper module, @sap/hdbext, can help avoid this inconsistency between @sap/xsenv and @sap/hana-client.
Beyond the expected connection options formatting and the difference in naming and structure of the create* command (createClient vs. createConnection), the remaining code sample between the two modules is identical.
Part 1: hana-client vs. hdb – This blog post
Part 2: Promises – Coming Soon
Part 3: Wrappers and Express – Coming Soon
Part 4: XSJS and Cloud Application Programming Model – Coming Soon