Getting started with immudb Development

    • Connect to the database
    • Insert and retrieve data

    TIP

    To learn how to develop for immudb with Python in a guided online environment, visit the immudb Playground at https://play.codenotary.com (opens new window)

    In the most common scenario, you would perform write and read operations on the database talking to the server. In this case your application will be a client to immudb.

    The immudb server manages the requests from the outside world to the store. In order to insert or retrieve data, you need to talk with the server.

    SDKs make it comfortable to talk to the server from your favourite language, without having to deal with details about how to talk to it.

    SDK Architecture

    The most well-known immudb SDK is written in , but there are SDKs available for Python, NodeJS, Java and others.

    For other unsupported programming languages, immugw Getting started with immudb Development - 图4 (opens new window) provides a REST gateway that can be used to talk to the server via generic HTTP.

    You may download the immudb binary from . Once you have downloaded immudb, rename it to , make sure to mark it as executable, then run it. The following example shows how to obtain v1.0.0 for linux amd64:

    Alternatively, you may use Docker to run immudb in a ready-to-use container. In a terminal type:

    1. docker run -ti -p 3322:3322 codenotary/immudb:latest

    (you can add the -d --rm --name immudb options to send it to the background).

    In order to use the SDK, you need to download and import the libraries:

    1. # Make sure your project is using Go Modules
    2. go mod init example.com/hello
    3. #go get github.com/codenotary/immudb/pkg/client
    5. ```go
    6. // Then import the package
    7. import (
    8.     immuclient "github.com/codenotary/immudb/pkg/client"
    9. )

    Just include immudb4j as a dependency in your project:

    if using Maven:

    1.     <dependency>
    2.         <groupId>io.codenotary</groupId>
    3.         <artifactId>immudb4j</artifactId>
    4.         <version>0.9.0.6</version>
    5.     </dependency>

    if using Gradle:

    1.     compile 'io.codenotary:immudb4j:0.9.0.6'

    immudb4j is currently hosted on both Maven Central Getting started with immudb Development - 图7 (opens new window) and .

    Install the package using pip:

    1.     pip3 install immudb-py

    Then import the client as follows:

    1.     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 Getting started with immudb Development - 图9 (opens new window)

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

    Use Microsoft’s NuGet Getting started with immudb Development - 图11 (opens new window) package manager to get immudb4DotNet.

    Creating a Client.

    • Using the default configuration.

      1.   var client = new CodeNotary.ImmuDb.ImmuClient("localhost"))

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

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

    If you’re using another language, then read up on our immugw Getting started with immudb Development - 图13 (opens new window) option.

    The first step is to connect to the database, which listens by default in port 3322, authenticate using the default user and password (immudb / immudb), and get a token which can be used in subsequent requests:

    1. import (
    2.     "context"
    3.     immuclient "github.com/codenotary/immudb/pkg/client"
    4.     "google.golang.org/grpc/metadata"
    5. )
    7. client, err := immuclient.NewImmuClient(client.DefaultOptions())
    8. if err != nil {
    10. }
    11. ctx := context.Background()
    12. // login with default username and password and storing a token
    13. lr , err := client.Login(ctx, []byte(`immudb`), []byte(`immudb`))
    14. if err != nil {
    15.     log.Fatal(err)
    16. }
    17. // set up an authenticated context that will be required in future operations
    18. md := metadata.Pairs("authorization", lr.Token)
    19. ctx = metadata.NewOutgoingContext(context.Background(), md)
    1. client = ImmuClient.newBuilder()
    2.     .withServerUrl("localhost")
    3.     .withServerPort(3322)
    4.     .build();
    5. client.login("immudb", "immudb");
    1. from immudb.client import ImmudbClient
    2. ic=ImmudbClient()
    3. ic.login("immudb","immudb")
    1. const cl = new ImmudbClient();
    3. (async () => {
    4.   try {
    5.     const loginReq: Parameters.Login = { user: 'immudb', password: 'immudb' }
    6.     const loginRes = await cl.login(loginReq)
    7. // ...
    8. } catch (err) {
    9.     console.log(err)
    10.   }
    11. })()

    This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on

    If you’re using another development language, please read up on our immugw Getting started with immudb Development - 图15 (opens new window) option.

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

    This feature is not yet supported or not documented. Do you want to make a feature request or help out? Open an issue on

    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 Getting started with immudb Development - 图17 (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

    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 Getting started with immudb Development - 图19 (opens new window)

    If you’re using another development language, please read up on our option.

    In order to use SQL from the Go SDK, you create a immudb client and login to the server like usual. First make sure you import:

    1. "github.com/codenotary/immudb/pkg/client"
    2. "google.golang.org/grpc/metadata"

    Then you can create the client and login to the database:

    1. c, err := client.NewImmuClient(client.DefaultOptions())
    2.     if err != nil {
    3.         log.Fatal(err)
    4.     }
    6.     ctx := context.Background()
    9.     if err != nil {
    10.         log.Fatal(err)
    11.     }
    13.     md := metadata.Pairs("authorization", lr.Token)
    14.     ctx = metadata.NewOutgoingContext(ctx, md)

    To perform SQL statements, use the SQLExec function, which takes a SQLExecRequest with a SQL operation:

    1.     _, err = c.SQLExec(ctx, `
    2.         BEGIN TRANSACTION
    3.           CREATE TABLE people(id INTEGER, name VARCHAR, salary INTEGER, PRIMARY KEY id);
    4.           CREATE INDEX ON people(name)
    5.         COMMIT
    6.     `, map[string]interface{}{})
    7.         if err != nil {
    8.         log.Fatal(err)
    9.     }

    This is also how you perform inserts:

    1.     _, err = c.SQLExec(ctx, "UPSERT INTO people(id, name, salary) VALUES (@id, @name, @salary);", map[string]interface{}{"id": 1, "name": "Joe", "salary": 1000})
    2.     if err != nil {
    3.         log.Fatal(err)
    4.     }

    Once you have data in the database, you can use the SQLQuery method of the client to query.

    Both SQLQuery and SQLExec allows named parameters. Just encode them as @param and pass map[string]{}interface as values:

    1.     res, err := c.SQLQuery(ctx, "SELECT t.id as d,t.name FROM (people AS t) WHERE id <= 3 AND name = @name", map[string]interface{}{"name": "Joe"}, true)
    2.     if err != nil {
    3.         log.Fatal(err)
    4.     }

    res is of the type *schema.SQLQueryResult. In order to iterate over the results, you iterate over res.Rows. On each iteration, the row r will have a member Values, which you can iterate to get each column.

    1.     for _, r := range res.Rows {
    2.         for _, v := range r.Values {
    3.             log.Printf("%s\n", schema.RenderValue(v.Value))
    4.         }