# Getting started with immudb Development
This guide provides developers with the first steps of using immudb from their application and from their favourite programming language:
- 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)
# Clients
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.
# SDKs
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.
The most well-known immudb SDK is written in Golang (opens new window), but there are SDKs available for Python, NodeJS, Java and others.
For other unsupported programming languages, immugw provides a REST gateway that can be used to talk to the server via generic HTTP.
# Getting immudb running
You may download the immudb binary from the latest releases on Github (opens new window). Once you have downloaded immudb, rename it to immudb
, make sure to mark it as executable, then run it. The following example shows how to obtain v1.0.0 for linux amd64:
wget https://github.com/vchain-us/immudb/releases/download/v1.0.0/immudb-v1.0.0-linux-amd64
mv immudb-v1.0.0-linux-amd64 immudb
chmod +x immudb
# run immudb in the foreground to see all output
./immudb
# or run immudb in the background
./immudb -d
Alternatively, you may use Docker to run immudb in a ready-to-use container. In a terminal type:
docker run -ti -p 3322:3322 codenotary/immudb:latest
(you can add the -d --rm --name immudb
options to send it to the background).
# Connecting from your programming language
# Importing the SDK
In order to use the SDK, you need to download and import the libraries:
# Connection and authentication
The first step is to connect to the database, which listens by default in port 3322 and authenticate using the default user and password (immudb / immudb
):
Note: You can change the server default options using environment variables, flags or the
immudb.toml
configuration file.
# 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.
# SQL Operations with the Go SDK
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:
"github.com/codenotary/immudb/pkg/api/schema"
"github.com/codenotary/immudb/pkg/client"
Then you can create the client and open a new session to the database:
import (
"log"
"context"
immudb "github.com/codenotary/immudb/pkg/client"
)
c, err := immudb.NewClient()
if err != nil {
log.Fatal(err)
}
err = c.OpenSession(context.TODO(), []byte(`immudb`), []byte(`immudb`), "defaultdb")
if err != nil {
log.Fatal(err)
}
To perform SQL statements, use the SQLExec
function, which takes a SQLExecRequest
with a SQL operation:
_, err = c.SQLExec(ctx, `
BEGIN TRANSACTION
CREATE TABLE people(id INTEGER, name VARCHAR, salary INTEGER, PRIMARY KEY id);
CREATE INDEX ON people(name)
COMMIT
`, map[string]interface{}{})
if err != nil {
log.Fatal(err)
}
This is also how you perform inserts:
_, err = c.SQLExec(ctx, "UPSERT INTO people(id, name, salary) VALUES (@id, @name, @salary);", map[string]interface{}{"id": 1, "name": "Joe", "salary": 1000})
if err != nil {
log.Fatal(err)
}
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:
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)
if err != nil {
log.Fatal(err)
}
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.
for _, r := range res.Rows {
for _, v := range r.Values {
log.Printf("%s\n", schema.RenderValue(v.Value))
}
}