SAP HANA Database Client for Node

To use the hdb driver in your project, install it from the npm registry:

npm install hdb

If you want to run tests or examples locally, you can clone the repository and install dependencies manually:

git clone https://github.com/SAP/node-hdb.git
cd node-hdb
npm install

By default, outgoing packets are restricted to 128KB. To handle larger SQL statements or LOBs, configure packetSize and packetSizeLimit in createClient.

• packetSize: The size of individual packets (default: 131072 / 128KB). Range: 65536 to 1073741823.
• packetSizeLimit: The maximum total size for an outgoing packet (default: same as packetSize). Range: packetSize to 1073741823.

Example: Allowing up to 1MB total size while keeping LOB chunks at 128KB:

var client = hdb.createClient({
  host : 'hostname',
  port : 30015,
  packetSize : Math.pow(2, 17), // 128KB
  packetSizeLimit : Math.pow(2, 20) // 1MB
});

A PhysicalConnectionSet is used to group multiple physical connections associated with a single logical connection. This is particularly relevant in scenarios involving connection redirection or multiple volumes.

Key Concepts

• Anchor Connection: One connection in the set is designated as the 'anchor'. This is typically the initial connection made before any redirection occurs. Use addAnchorConnection(pconn) to set this.
• Secondary Connections: Additional connections added via addConnection(pconn).

Common Operations

• getAnchorConnection(): Retrieves the designated anchor connection.
• getConnection(clientConnectionId): Retrieves a specific connection by its ID.
• closeAll(): Closes all connections in the set and clears the set.

The PhysicalConnection class manages the low-level TCP socket and the HDB protocol handshake.

Connection States

• Use isConnected() to check if the socket is open and the protocolVersion has been successfully negotiated.

Error Codes

During the connection lifecycle, the following error codes may be emitted via callbacks or event listeners:

• EHDBINIT: Invalid initialization reply received from the server.
• EHDBTIMEOUT: The initialization handshake timed out.
• EHDBCLOSE: The connection was closed by the server (sent via the onEnd callback).

Cleanup

• close(): Destroys the underlying socket.
• destroy(err): Destroys the socket and can pass an error object.
• closeAllListeners(eventName): Removes all listeners from the socket, or a specific event if eventName is provided.

To enable TLS/SSL, pass key, cert, and ca (or a pfx) to createClient. Alternatively, use the useTLS: true option to connect using Node.js's built-in trusted certificates.

If you need to validate the server's hostname against the certificate, use the checkServerIdentity property, which follows the standard Node.js tls.connect callback signature.

var client = hdb.createClient({
  host : 'hostname',
  port : 30015,
  key  : fs.readFileSync('client-key.pem'),
  cert : fs.readFileSync('client-cert.pem'),
  ca   : [fs.readFileSync('trusted-cert.pem')],
  useTLS: true
});

By default, every statement is automatically committed. To manage transactions manually, call client.setAutoCommit(false).

Use client.commit(callback) to finalize changes or client.rollback(callback) to undo them. After your transaction logic, remember to call client.setAutoCommit(true) to return to default behavior.

client.setAutoCommit(false);

client.exec('insert into NUMBERS values (1, "one")', function(err) {
  if (err) {
    return client.rollback(function() { /* handle rollback */ });
  }
  
  client.commit(function(commitErr) {
    client.setAutoCommit(true);
    if (commitErr) return console.error('Commit error');
    console.log('Transaction committed');
  });
});

If you need to process large datasets without loading everything into memory, use the execute() method (instead of exec()). This returns a resultSet object.

You can create an object stream or an array stream from the resultSet and pipe it to a writable stream.

Note: You must call rs.close() when finished to prevent resource leaks.

client.execute('select A, B from TEST.NUMBERS order by A', function(err, rs) {
  if (err) return console.error('Error:', err);
  
  rs.setFetchSize(2048);
  rs.createObjectStream()
    .pipe(new MyWriteStream())
    .on('finish', function (){
      if (!rs.closed) {
       rs.close();
      }
    });
});

You can set session variables (key-value pairs) that the HANA server can use. These are case-sensitive.

There are two ways to set them:

1. At connection time: Use the SESSIONVARIABLE:KEY prefix in the createClient options.
2. During a session: Use the client.setClientInfo(key, value) method. Variables set via setClientInfo are sent to the server during the next execute, prepare, or fetch operation.

var client = hdb.createClient({
  host             : 'hostname',
  port             : 30015,
  user             : 'user',
  password         : 'secret',
  "SESSIONVARIABLE:EXAMPLEKEY1" : "EXAMPLEVALUE1"
});

// Set additional info later
client.setClientInfo("EXAMPLEKEY2", "EXAMPLEVALUE2");