# Developer Jumpstart for immudb

Slack (opens new window) Discuss at immudb@googlegroups.com (opens new window) License (opens new window)

# Contents

# Introduction

This guide helps developers quickly start with CodeNotary's immudb database and client. It guides you from start to finish with code samples in Node.js, Java, Python, Go, and .Net. After completing the guide, you will have the basic concepts necessary to begin using immudb within your organization.

Note: If you're using another development language, please read up on our immugw (opens new window) option.

This section is not yet ready for immudb 0.9. We are working on it in order to improve it and we are close to deliver. Stay tuned!

# What is immudb?

A lightweight, high-speed, immutable database solution capable of processing millions of transactions a second. It provides cryptographic verification of your data integrity without the cost and complexity associated with classic blockchain. You have the flexibility to host immudb on-premise or in the cloud.


Data is never overwritten. See the history of data updates.


Tamper-evident history system ensures data authenticity.


Data ownership is verifiable by clients and auditors.

The immudb is a non-relational, NoSQL database. Data is a collection of key-values with time stamps. You can add records, but deletion or modification isn’t allowed making your data immutable. When a record's value changes over time (such as a bank balance), you can get multiple instances with different time stamps to give you the complete change history of that record. Store a variety of common data types, verification checksums, or JSONs.

Depending on your use case, immudb might function as your application's primary or as a secondary database. As a secondary, complimentary database, use immudb to cross-check the data integrity of your important data (by verifying checksums or comparing stored data values). A secondary database enables you to quickly use immudb without completely re-engineering your existing application.

# Why use immudb?

It ensures the integrity of your organization's data. While Cyber Security is an important part of your organization’s business plan, immudb provides another layer of security to ensure data integrity even in the event your perimeter is breached during an attack. Data cannot be deleted or modified once stored into immudb. Additions of new data are logged and auditable, enabling you to view any suspect additions made during the intrusion.

Use cases:

  • Integration with your DevOps ensures code security throughout the development and deployment process. Embed immudb into your Azure DevOps (opens new window) with Jenkins and Kubernetes. Use just Jenkins (opens new window). Alternatively, integrate with Git Lab (opens new window) or GitHub (opens new window).

  • Guarantee File Integrity (opens new window) of your critical data. Examples include storing your organization's sensitive financial, credit card transactional, invoices, contracts, educational transcripts, and other important data.

  • Ensure integrity of your legal Documents and Invoices (opens new window), contracts, forms, and your downloads and emails.

  • Save your Internet of Things (IoT) sensor data as a failsafe plan for loss of data.

  • Keep your investment guidelines or stock market data tamperproof for your investment bank or client financial portfolios.

  • Store important log files to keep them tamperproof to meet regulations like PCI compliance.

  • Protect medical data, test results, or recipes from alteration.

# Installing the immudb database server

In this section, you will install the immudb database server. You have the following options for running immudb database server:

  • For those using Docker, get and launch our image from Docker Hub.

  • Download our latest immudb release from GitHub.

  • For the sake of brevity, this Quick Start leaves out getting and compiling the immudb source (refer to the Readme here (opens new window) to use this method).

# Get the Docker Image

  1. Pull the immudb Docker Image from Docker Hub (opens new window). Below are the commands when using a Linux shell.

    docker pull codenotary/immudb:latest
  2. You can run immudb in a container using the code that follows.

    docker run -it -d -p 3322:3322 -p 9497:9497 --name immudb codenotary/immudb:latest
  3. Your immudb should now be up and running. Check your container logs to verify this.

    docker logs immudb
  4. Skip down to the section about Creating an immudb client instance in your chosen programming language.

# Download the installer for the latest release

  1. Download the latest release from our GitHub (opens new window).

  2. Run immudb. Linux shell commands are shown below.

    ./immudb       # Runs immudb in the foreground
    ./immudb -d    # Runs immudb in the background
  3. To stop immudb, find the process ps -ax | grep immudb and then kill -15 <pid>. Alternatively, the Windows PowerShell commands are Get-Process immudb* | Stop-Process.

  4. Continue with the section that follows.

# Creating an immudb client

# Integration

Integrate the immudb Client into your application using the official Software Development Kits (SDKs).

# Connection and authentication

Immudb run on 3323 default port. Here we connecting a client with default options and authenticating using default username and password. It's possible to modify defaults on immudb server config folder inside immudb.toml

# Tamperproof read and write

You can write with built-in cryptographic verification. The client implements the mathematical validations, while your application uses a traditional read or write function.

# To get going quickly:

  • Get the immudb-client-example code (opens new window). Note: Only Golang SDK is currently upgraded for immudb 0.9.0
  • Learn about the basic coding you will use to interact with your immudb client and database. This guide goes from start to finish, in creating a new client instance, writing and reading data, and much more. Take a look at the SDKs api page.

# Conclusion

Congratulations for completing the development quick start guide. You've been guided through the essentials you need to know to begin using CodeNotary's immudb solution.

You now have:

  • An immudb database server and are familiar with basic authentication.
  • An immudb client.
  • A new immudb database.
  • An instance of the immudb client running.
  • Gone through reading and writing data with and without cryptographic verification.

We've only scratched the surface of immudb's capabilities. Here are some additional resources you might find helpful: