Database Management
Multi-database support is included in immudb server. immudb automatically creates an initial database named defaultdb.
Managing users and databases requires the appropriate privileges. A user with PermissionAdmin rights can manage everything. Non-admin users have restricted access and can only read or write databases to which they have been granted permission.
Each database can be configured with a variety of settings. While some values can be changed at any time (though it may require a database reload to take effect), following ones are fixed and cannot be changed: FileSize, MaxKeyLen, MaxValueLen, MaxTxEntries and IndexOptions.MaxNodeSize.
Database creation#
This example shows how to create a new database and how to write records to it.
To create a new database, use CreateDatabaseV2 method.
Go
1package main
2
3import (
4 "context"
5 "log"
6
7 "github.com/codenotary/immudb/pkg/api/schema"
8 immudb "github.com/codenotary/immudb/pkg/client"
9)
10
11func main() {
12 client := immudb.NewClient()
13 ctx := context.Background()
14
15 err := client.OpenSession(ctx,
16 []byte(`immudb`),
17 []byte(`immudb`),
18 "defaultdb",
19 )
20 if err != nil {
21 log.Fatal(err)
22 }
23
24 defer client.CloseSession(ctx)
25
26 res, err := client.CreateDatabaseV2(
27 ctx,
28 "mydb",
29 &schema.DatabaseNullableSettings{
30 // this setting determines how many
31 // transactions can be handled concurrently
32 MaxConcurrency: &schema.NullableUint32{Value: 10},
33 },
34 )
35 if err != nil {
36 log.Fatal(err)
37 }
38 log.Print("Database created, server response: ", res)
39}Java
1package io.codenotary.immudb.helloworld;
2
3import io.codenotary.immudb4j.*;
4
5public class App {
6
7 public static void main(String[] args) {
8 FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
9 .withStatesFolder("./immudb_states")
10 .build();
11
12 ImmuClient client = ImmuClient.newBuilder()
13 .withServerUrl("127.0.0.1")
14 .withServerPort(3322)
15 .withStateHolder(stateHolder)
16 .build();
17
18 client.login("immudb", "immudb");
19
20 client.createDatabase("db1");
21 }
22
23}Python
1from immudb import ImmudbClient
2
3URL = "localhost:3322" # immudb running on your machine
4LOGIN = "immudb" # Default username
5PASSWORD = "immudb" # Default password
6DB = b"defaultdb" # Default database name (must be in bytes)
7
8def main():
9 client = ImmudbClient(URL)
10 client.login(LOGIN, PASSWORD, database = DB)
11
12 client.createDatabase("db1")
13
14if __name__ == "__main__":
15 main()Node.js
1import ImmudbClient from 'immudb-node'
2import Parameters from 'immudb-node/types/parameters'
3
4const IMMUDB_HOST = '127.0.0.1'
5const IMMUDB_PORT = '3322'
6const IMMUDB_USER = 'immudb'
7const IMMUDB_PWD = 'immudb'
8
9const cl = new ImmudbClient({ host: IMMUDB_HOST, port: IMMUDB_PORT });
10
11(async () => {
12 await cl.login({ user: IMMUDB_USER, password: IMMUDB_PWD })
13
14 const createDatabaseReq: Parameters.CreateDatabase = {
15 databasename: 'myimmutabledb'
16 }
17
18 const createDatabaseRes = await cl.createDatabase(createDatabaseReq)
19 console.log('success: createDatabase', createDatabaseRes)
20})().NET
1var client = new ImmuClient();
2await client.Open("immudb", "immudb", "defaultdb");
3
4var dbName = "mydatabase";
5await client.CreateDatabase(dbName);
6await client.UseDatabase(dbName);
7
8await client.Close();Others
If you’re using another development language, please refer to the immugw option.
Listing databases#
This example shows how to list existent databases using DatabaseListV2 method.
Go
1package main
2
3import (
4 "context"
5 "log"
6
7 immudb "github.com/codenotary/immudb/pkg/client"
8)
9
10func main() {
11 client := immudb.NewClient()
12 ctx := context.Background()
13
14 err := client.OpenSession(
15 ctx,
16 []byte(`immudb`),
17 []byte(`immudb`),
18 "defaultdb",
19 )
20 if err != nil {
21 log.Fatal(err)
22 }
23
24 defer client.CloseSession(ctx)
25
26 res, err := client.DatabaseListV2(ctx)
27 if err != nil {
28 log.Fatal(err)
29 }
30
31 for _, db := range res.Databases {
32 log.Printf(
33 "database: %s, loaded: %v",
34 db.Name,
35 db.Loaded,
36 )
37 }
38}Java
1package io.codenotary.immudb.helloworld;
2
3import io.codenotary.immudb4j.*;
4
5public class App {
6
7 public static void main(String[] args) {
8 FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
9 .withStatesFolder("./immudb_states")
10 .build();
11
12 ImmuClient client = ImmuClient.newBuilder()
13 .withServerUrl("127.0.0.1")
14 .withServerPort(3322)
15 .withStateHolder(stateHolder)
16 .build();
17
18 client.login("immudb", "immudb");
19
20 List<String> dbs = client.databases();
21 // List of database names
22 }
23
24}Python
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
Node.js
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
.NET
1var client = new ImmuClient();
2await client.Open("immudb", "immudb", "defaultdb");
3
4var databases = await client.Databases();
5foreach(var database in databases)
6{
7 Console.WriteLine(database);
8}
9
10await client.Close();Others
If you’re using another development language, please refer to the immugw option.
Database loading/unloading#
Databases can be dynamically loaded and unloaded without having to restart the server. After the database is unloaded, all its resources are released. Unloaded databases cannot be queried or written to, but their settings can still be changed.
Upon startup, the immudb server will automatically load databases with the attribute Autoload set to true. If a user-created database cannot be loaded successfully, it remains closed, but the server continues to run normally.
As a default, autoloading is enabled when creating a database, but it can be disabled during creation or turned on/off at any time thereafter.
Following example shows how to load and unload a database using LoadDatabase and UnloadDatabase methods.
Go
1package main
2
3import (
4 "context"
5 "log"
6
7 "github.com/codenotary/immudb/pkg/api/schema"
8 immudb "github.com/codenotary/immudb/pkg/client"
9)
10
11func main() {
12 client := immudb.NewClient()
13 ctx := context.Background()
14
15 err := client.OpenSession(
16 ctx,
17 []byte(`immudb`),
18 []byte(`immudb`),
19 "defaultdb",
20 )
21 if err != nil {
22 log.Fatal(err)
23 }
24 defer client.CloseSession(ctx)
25
26 unloadRes, err := client.UnloadDatabase(
27 ctx,
28 &schema.UnloadDatabaseRequest{
29 Database: "mydb",
30 },
31 )
32 if err != nil {
33 log.Fatal(err)
34 }
35
36 log.Print("Database unloaded, server response: ", unloadRes)
37
38 // Do db maintenance - e.g. backup physical files from disk
39
40 loadRes, err := client.LoadDatabase(
41 ctx,
42 &schema.LoadDatabaseRequest{
43 Database: "mydb",
44 },
45 )
46 if err != nil {
47 log.Fatal(err)
48 }
49
50 log.Print("Database loaded, server response: ", loadRes)
51}Java
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
Python
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
Node.js
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
.NET
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
Others
If you’re using another development language, please refer to the immugw option.
Database settings#
Database settings can be individually changed using UpdateDatabaseV2 method.
Each database can be configured with a variety of settings. While some values can be changed at any time (though it may require a database reload to take effect), following ones are fixed and cannot be changed: FileSize, MaxKeyLen, MaxValueLen, MaxTxEntries and IndexOptions.MaxNodeSize.
Note: Replication settings take effect without the need of reloading the database.
Following example shows how to update database using UpdateDatabaseV2 method.
Go
1package main
2
3import (
4 "context"
5 "fmt"
6 "log"
7
8 "github.com/codenotary/immudb/pkg/api/schema"
9 immudb "github.com/codenotary/immudb/pkg/client"
10)
11
12func main() {
13 client := immudb.NewClient()
14 ctx := context.Background()
15
16 err := client.OpenSession(
17 ctx,
18 []byte(`immudb`),
19 []byte(`immudb`),
20 "defaultdb",
21 )
22 if err != nil {
23 log.Fatal(err)
24 }
25
26 defer client.CloseSession(ctx)
27
28 res, err := client.UpdateDatabaseV2(
29 ctx,
30 "mydb",
31 &schema.DatabaseNullableSettings{
32 TxLogCacheSize: &schema.NullableUint32{Value: 1000},
33 },
34 )
35 if err != nil {
36 log.Fatal(err)
37 }
38
39 fmt.Println("Database settings updated, server response: ", res)
40}Java
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
Python
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
Node.js
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
.NET
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
Others
If you’re using another development language, please refer to the immugw option.
Configuration options#
Following main database options are available:
| Name | Type | Description |
|---|---|---|
| replicationSettings | Replication Setings | Repliation settings are described below |
| indexSettings | Index Settings | Index settings are described below |
| fileSize | Uint32 | maximum file size of files on disk generated by immudb |
| maxKeyLen | Uint32 | maximum length of keys for entries stored in the database |
| maxValueLen | Uint32 | maximum length of values for entries stored in the database |
| maxTxEntries | Uint32 | maximum number of entries inside one transaction |
| excludeCommitTime | Bool | if set to true, commit time is not added to transaction headers allowing reproducible database state |
| maxConcurrency | Uint32 | max number of concurrent operations on the db |
| maxIOConcurrency | Uint32 | max number of concurrent IO operations on the db |
| txLogCacheSize | Uint32 | size of transaction log cache |
| vLogMaxOpenedFiles | Uint32 | maximum number of open files for payload data |
| txLogMaxOpenedFiles | Uint32 | maximum number of open files for transaction log |
| commitLogMaxOpenedFiles | Uint32 | maximum number of open files for commit log |
| syncFrequency | duration | set the fsync frequency during commit process (default 20ms) |
| write-buffer-size | uint32 | set the size of in-memory buffers for file abstractions (default 4194304) |
| writeTxHeaderVersion | Uint32 | transaction header version, used for backwards compatibility |
| autoload | Bool | if set to false, do not load database on startup |
Replication settings:
| Name | Type | Description |
|---|---|---|
| replica | Bool | if true, the database is a replica of another one |
| primaryDatabase | String | name of the database to replicate |
| primaryHost | String | hostname of the primary immudb instance |
| primaryPort | Uint32 | tcp port of the primary immudb instance |
| primaryUsername | String | username used to connect to the primary immudb instance |
| primaryPassword | String | password used to connect to the primary immudb instance |
Additional index options:
| Name | Type | Description |
|---|---|---|
| flushThreshold | Uint32 | threshold in number of entries between automatic flushes |
| syncThreshold | Uint32 | threshold in number of entries between flushes with sync |
| cacheSize | Uint32 | size of btree node cache |
| maxNodeSize | Uint32 | max size of btree node in bytes |
| maxActiveSnapshots | Uint32 | max number of active in-memory btree snapshots |
| renewSnapRootAfter | Uint64 | threshold in time for automated snapshot renewal during data scans |
| compactionThld | Uint32 | minimum number of flushed snapshots to enable full compaction of the index |
| delayDuringCompaction | Uint32 | extra delay added during indexing when full compaction is in progress |
| nodesLogMaxOpenedFiles | Uint32 | maximum number of files opened for nodes data |
| historyLogMaxOpenedFiles | Uint32 | maximum number of files opened for nodes history |
| commitLogMaxOpenedFiles | Uint32 | maximum number of files opened for commit log |
| flushBufferSize | Uint32 | in-memory buffer size when doing flush operation |
| cleanupPercentage | Float | % of data to be cleaned up from during next automatic flush operation |