Developer Jumpstart for immudb

(opens new window) (opens new window) (opens new window)

Contents

• Introduction
  • What is immudb
  • Why use immudb
• Installing the immudb database server
  • Get the Docker Image
  • Download the installer for the latest release
• Creating an immudb client instance in your chosen programming language
  • Integration
  • Connection and authentication
  • Tamperproof read and write
  • Integration
  • To get going quickly
• Conclusion

Introduction

This guide helps developers quickly get started with Codenotary's immudb database and client. It guides you from start to finish with code examples 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 refer to the 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.

Immutable Data is never overwritten. See the history of data updates.	Auditable Tamper-evident history system ensures data authenticity.	Secure 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.

• For additional technical background on immudb and its performance, see the Readme (opens new window) within Codenotary's immudb GitHub Project.
• For additional information on immudb, see our documentation (opens new window).

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
   

   • immudb also runs as a service which is explained in this Readme (opens new window) to use this method).

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).

# Make sure your project is using Go Modules
go mod init app
# Install immudb sdk
go get -u github.com/codenotary/immudb

// Then import the package
import (
  "github.com/codenotary/immudb/pkg/client"
)

Just include immudb4j as a dependency in your project:

if using Maven:

    <dependency>
        <groupId>io.codenotary</groupId>
        <artifactId>immudb4j</artifactId>
        <version>0.2.0</version>
    </dependency>

if using Gradle:

    compile 'io.codenotary:immudb4j:0.2.0'

Java SDK repository (opens new window)

immudb4j is currently hosted on both Maven Central (opens new window) and Github Packages (opens new window).

Install the package using pip:

    pip3 install immudb-py

Then import the client as follows:

    from immudb import ImmudbClient

Note: immudb-py need grpcio module from google. On Alpine linux, you need these packages in order to correctly build (and install) grpcio:

• linux-headers
• python3-dev
• g++

Python SDK repository (opens new window)

Include the immudb-node as a dependency in your project.

	const immudbClient = require('immudb-node')

Node.js SDK repository (opens new window)

Use Microsoft's NuGet (opens new window) package manager to get immudb4DotNet.

Creating a Client.

• Using the default configuration.

    var client = new Codenotary.ImmuDb.ImmuClient("localhost"))
  

• The immudb implements IDisposable, so you can wrap it with "using".

  using (var client = new Codenotary.ImmuDb.ImmuClient("localhost", 3322)){}
  

.Net SDK repository (opens new window)

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

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

Login method return a token needed in all interactions with the server.

client, err := c.NewImmuClient(client.DefaultOptions())
if err != nil {
    log.Fatal(err)
}
ctx := context.Background()
// login with default username and password and storing a token
lr , err := client.Login(ctx, []byte(`immudb`), []byte(`immudb`))
if err != nil {
    log.Fatal(err)
}
// set up an authenticated context that will be required in future operations
md := metadata.Pairs("authorization", lr.Token)
ctx = metadata.NewOutgoingContext(context.Background(), md)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw (opens new window) option.

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.

    vtx, err := client.VerifiedSet(ctx, []byte(`hello`), []byte(`immutable world`))
	if  err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Set and verified key '%s' with value '%s' at tx %d\n", []byte(`hello`), []byte(`immutable world`), vtx.Id)

	ventry, err := client.VerifiedGet(ctx, []byte(`hello`))
	if  err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Sucessfully verified key '%s' with value '%s' at tx %d\n", ventry.Key, ventry.Value, ventry.Tx)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Java sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Python sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on Node.js sdk github project (opens new window)

This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on .Net sdk github project (opens new window)

If you're using another development language, please refer to the immugw (opens new window) option.

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:

• Learn more through our documentation (opens new window).
  • Learn more about the immudb SDKs (opens new window).
  • Try out immuadmin (opens new window)
• Follow Codenotary's blog (opens new window) for more immudb articles and release announcements.
• Additional technical background on immudb and its performance, see the Readme (opens new window) within Codenotary's immudb GitHub Project.