TypeScript icon, indicating that this package has built-in type declarations

    1.0.10-rc.7 • Public • Published

    immudb-node License

    Slack Discuss at

    Official immudb client for nodejs.



    immudb-node implements a grpc immudb client. A minimalist API is exposed for applications while cryptographic verifications and state update protocol implementation are fully implemented by this client. Latest validated immudb state may be keep in the local filesystem when initialising the client with the rootPath option, please read immudb research paper for details of how immutability is ensured by immudb.


    immudb-node assumes an already running immudb server. Running immudb is quite simple, please refer to the following link for downloading and running it:


    Just include immudb-node as a dependency in your project:

    const ImmudbClient = require('immudb-node')

    Supported Versions

    immudb-node supports the latest immudb release.


    Check out some examples


    Create a .env file based on a .env.example in the project root and replace the /path/to/immudb/ with your local path to immudb.

    You can use either of the following commands to check that all the unit tests pass:

    • npm run test: automatically download the latest immudb release, run it and then run tests
    • npm run test:dev: connect to an already running immudb on the host:port from the .env file on your machine and then run tests

    Step by step guide

    Creating a Client

    The following code snippets shows how to create a client.

    Using default configuration:

    const config = {
      address: '',
      rootPath: '.',
    ImmudbClient(config, (err, cl) => {
      if (err) {
        return console.log(err)
      // Interact with the client.

    User sessions

    Use login and logout methods to initiate and terminate user sessions:

    try {
      await cl.login({ username: 'usr1', password: 'pwd1' })
      // Interact with immudb using logged user.
      await cl.logout()
    } catch (err) {

    Or with callbacks

    cl.login({ username: 'usr1', password: 'pwd1' }, (err, res) => {
      if (err) {
        return console.log(err)
      // Interact with immudb using logged user.
      cl.logout(null, (err, res) => {
        if (err) {
          return console.log(err)
        // Logged out.

    Creating a database

    Creating a new database is quite simple:


    Setting the active database

    Specify the active database with:


    Traditional read and write

    immudb provides read and write operations that behave as a traditional key-value store i.e. no cryptographic verification is done. This operations may be used when validations can be post-poned:

    let res = await cl.set({ key: 'key1', value: 'value1' })
    res = await cl.get({ key: 'key1' })
    console.log(res.key, res.value, res.index)

    Verified or Safe read and write

    immudb provides built-in cryptographic verification for any entry. The client implements the mathematical validations while the application uses as a traditional read or write operation:

    try {
      let res = await cl.verifiedSet({ key: 'key1', value: 'value1' })
      res = await cl.verifiedGet({ key: 'key1' })
      console.log(res.key, res.value, res.index)
    } catch (err) {
      if (err.clientErr == cl.proofErr) {
        // Proof does not verify.

    Multi-key read and write

    Transactional multi-key read and write operations are supported by immudb and immudb-node.

    Atomic multi-key write (all entries are persisted or none):

      req = {
        keys: [{
          key: 'key1',
          value: 'value1'
          key: 'key2',
          value: 'value2'
      res = await cl.setAll(req)

    Atomic multi-key read (all entries are retrieved or none):

        req = {
          keys: [{
            key: 'key1',
            key: 'key2',
        res = await cl.getAll(req)

    Closing the client

    To programatically close the connection with immudb server use the shutdown operation:


    Note: after shutdown, a new client needs to be created to establish a new connection.


    We welcome contributions. Feel free to join the team!

    To report bugs or get help, use GitHub's issues.


    npm i immudb-node

    DownloadsWeekly Downloads






    Unpacked Size

    2.04 MB

    Total Files


    Last publish


    • vchain
    • hextar
    • temii
    • napiernpm