immudb runs on port 3323 as the default. The code samples below illustrate how to connect your client to the server and authenticate using default options and the default username and password.
You can modify defaults on the immudb server in immudb.toml in the config folder.
The Login method returns a token required for all interactions with the server.
c, err := client.NewImmuClient(client.DefaultOptions())if err !=nil{
log.Fatal(err)}
ctx := context.Background()// login with default username and password and storing a token
lr , err := c.Login(ctx,[]byte(`immudb`),[]byte(`immudb2`))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
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
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
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
If you're using another development language, please read up on our immugw option.
To enable mutual authentication, a certificate chain must be provided to both the server and client.
That will cause each to authenticate with the other simultaneously.
In order to generate certs, use the openssl tool:
generate.sh.
./generate.sh localhost mysecretpassword
This generates a list of folders containing certificates and private keys to set up a mTLS connection.
client, err := c.NewImmuClient(
c.DefaultOptions().WithMTLsOptions(
c.MTLsOptions{}.WithCertificate("{path-to-immudb-src-folder}/tools/mtls/4_client/certs/localhost.cert.pem").WithPkey("{path-to-immudb-src-folder}/tools/mtls/4_client/private/localhost.key.pem").WithClientCAs("{path-to-immudb-src-folder}/tools/mtls/2_intermediate/certs/ca-chain.cert.pem").WithServername("localhost"),).WithMTLs(true),)if err !=nil{
log.Fatal(err)}
ctx := context.Background()// login with default username and password
lr , err := client.Login(ctx,[]byte(`immudb`),[]byte(`immudb`))
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
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
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
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
If you're using another development language, please read up on our immugw option.
You also have the option to run immudb with authentication disabled. However, without authentication enabled, it's not possible to connect to a server already configured with databases and user permissions. If a valid token is present, authentication is enabled by default.
If immudb is launched with a private signing key, each signed request can be verified with the public key.
In this way the identity of the server can be proven.
Check state signature to see how to generate a valid key.
c, err := client.NewImmuClient(client.DefaultOptions().WithServerSigningPubKey("../../immudb/src/wrong.public.key"))if err !=nil{
log.Fatal(err)}
ctx := context.Background()
lr , err := c.Login(ctx,[]byte(`immudb`),[]byte(`immudb`))if err !=nil{
log.Fatal(err)}
md := metadata.Pairs("authorization", lr.Token)
ctx = metadata.NewOutgoingContext(context.Background(), md)if_, err := c.Set(ctx,[]byte(`immudb`),[]byte(`hello world`)); err !=nil{
log.Fatal(err)}var state *schema.ImmutableState
if state, err = c.CurrentState(ctx); err !=nil{
log.Fatal(err)// if signature is not verified here is trigger an appropriate error}
fmt.Print(state)
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
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
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
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
If you're using another development language, please read up on our immugw option.
It's the responsibility of the immudb client to track the server state. That way it can check each verified read or write operation against a trusted state.
The component in charge of state handling is the StateService.
To set up the stateService 3 interfaces need to be implemented and provided to the StateService constructor:
Cache interface in the cache package. Standard cache.NewFileCache provides a file state store solution.
StateProvider in the stateService package. It provides a fresh state from immudb server when the client is being initialized for the first time. Standard StateProvider provides a service that retrieve immudb first state hash from a gRPC endpoint.
UUIDProvider in the stateService package. It provides the immudb identifier. This is needed to allow the client to safely connect to multiple immudb instances. Standard UUIDProvider provides the immudb server identifier from a gRPC endpoint.
Following an example how to obtain a client instance with a custom state service.
The format for writing and reading data is the same both in Set and VerifiedSet, just as it is for reading data both in both Get and VerifiedGet.
The only difference is that VerifiedSet returns proofs needed to mathematically verify that the data was not tampered.
Note that generating that proof has a slight performance impact, so primitives are allowed without the proof.
It is still possible get the proofs for a specific item at any time, so the decision about when or how frequently to do checks (with the Verify version of a method) is completely up to the user.
It's possible also to use dedicated auditors to ensure the database consistency, but the pattern in which every client is also an auditor is the more interesting one.
The fundamental property of immudb is that it's an append-only database.
This means that an update is a new insert of the same key with a new value.
It's possible to retrieve all the values for a particular key with the history command.
History accepts the following parameters:
Key: a key of an item
Offset: the starting index (excluded from the search). Optional
Limit: maximum returned items. Optional
Desc: items are returned in reverse order. Optional
SetReference is like a "tag" operation. It appends a reference on a key/value element.
As a consequence, when we retrieve that reference with a Get or VerifiedGet the value retrieved will be the original value associated with the original key.
Its VerifiedReference counterpart is the same except that it also produces the inclusion and consistency proofs.
The sorted set data type provides simplest secondary index you can create with immudb. That's a data structure that represents a set of elements ordered by the score of each element, which is a floating point number.
The score type is a float64 to accommodate the maximum number of uses cases.
64-bit floating point gives a lot of flexibility and dynamic range, at the expense of having only 53-bits of integer.
When an integer64 is cast to a float there could be a loss of precision, but the insertion order is guaranteed by the internal database index that is appended to the internal index key.
ZAdd can reference an item by key or by index.
ZScan accepts following arguments:
Set: the name of the collection
SeekKey
SeekScore
SeekAtTx
InclusiveSeek
Limit: the maximum items returned,
Desc: items are returned in score ascending or descending order
MinScore: minimum score filter
MaxScore: maximum score filter
SinceTx
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!
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
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
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
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
If you're using another development language, please read up on our immugw option.
GetAll, SetAll and ExecAll are the foundation of transactions in immudb. They allow the execution of a group of commands in a single step, with two important guarantees:
All the commands in a transaction are serialized and executed sequentially. No request issued by another client can ever interrupt the execution of a transaction. This guarantees that the commands are executed as a single isolated operation.
Either all of the commands are processed, or none are, so the transaction is also atomic.
ExecAll permits many insertions at once. The difference is that is possible to to specify a list of a mix of key value set, reference and zAdd insertions.
The argument of a ExecAll is an array of the following types:
It's possible to persist and reference items that are already persisted on disk. In that case is mandatory to provide the index of the referenced item. This has to be done for:
Op_ZAdd
Op_Ref
If zAdd or reference is not yet persisted on disk it's possible to add it as a regular key value and the reference is done onFly.
Starting with version 0.7.0 of immudb, we introduced multi-database support.
By default, the first database is either called defaultdb or based on the environment variable IMMUDB_DBNAME.
Handling users and databases requires the appropriate privileges.
Users with PermissionAdmin can control everything. Non-admin users have restricted permissions and can read or write only their databases, assuming sufficient privileges.
This example shows how to create a new database and how to write records to it.
To create a new database, use CreateDatabase method.
To write into a specific database an authenticated context is required.
Start by calling the UseDatabase method to obtain a token.
A token is used for both authorization and routing commands to a specific database.
To set up an authenticated context, it's sufficient to put a token inside metadata.