Skip to main content
Version: v3.x

Data isolation with buckets

Buckets are a way to isolate different ledgers within the same database server. This is useful when you want to separate data for different clients, or different applications, or different environments.

Buckets are implemented using PostgreSQL schemas. To isolate, the data, each bucket has its own schema. Then you can implement access control at the schema level to prevent access to data from one bucket to another.

Creating a bucket

Buckets are automatically created when you create a new ledger. By default, if the bucket is not specified, the ledger is created in the _default bucket.

Using fctl, you can specify the bucket when creating a new ledger:

fctl ledger create <ledger-name> --bucket <bucket-name>

Alternatively, to create a ledger on a specific bucket, use the command:

$ curl -X POST http://localhost:3068/v2/testing -d '{"bucket": "bucket0"}'
$ curl http://localhost:3068/v2/testing | jq
{
"data": {
"bucket": "bucket0",
"metadata": {},
"features": {
"ACCOUNT_METADATA_HISTORY": "SYNC",
"HASH_LOGS": "SYNC",
"INDEX_ADDRESS_SEGMENTS": "ON",
"INDEX_TRANSACTION_ACCOUNTS": "ON",
"MOVES_HISTORY": "ON",
"MOVES_HISTORY_POST_COMMIT_EFFECTIVE_VOLUMES": "SYNC",
"TRANSACTION_METADATA_HISTORY": "SYNC"
},
"id": 2,
"name": "testing",
"addedAt": "2024-10-03T08:27:11.540373Z"
}
}

Features

Each usage of the ledger service, is different. Some usage involve a high write throughput, some other involve high read throughput, custom aggregation etc...

So, each ledger can be configured with a set of features. By default, when creating a ledger, all features are enabled.

To create a ledger with specific features, use the command:

$ curl -X POST http://localhost:3068/v2/testing2 -d '{"features": {"HASH_LOGS": "DISABLED"}}'
$ curl http://localhost:3068/v2/testing2 | jq
{
"data": {
"bucket": "_default",
"metadata": {},
"features": {
"ACCOUNT_METADATA_HISTORY": "SYNC",
"HASH_LOGS": "DISABLED",
"INDEX_ADDRESS_SEGMENTS": "ON",
"INDEX_TRANSACTION_ACCOUNTS": "ON",
"MOVES_HISTORY": "ON",
"MOVES_HISTORY_POST_COMMIT_EFFECTIVE_VOLUMES": "SYNC",
"TRANSACTION_METADATA_HISTORY": "SYNC"
},
"id": 3,
"name": "testing2",
"addedAt": "2024-10-03T08:40:40.545229Z"
}
}

When overriding features, all not specified features will receive the default configuration.

warning

Current set of feature is not stable, some can be added, or removed.

Current set of features

NameDefault valuePossible configurationDescription
ACCOUNT_METADATA_HISTORYSYNCSYNC | DISABLEDHistorize metadata changes on accounts
TRANSACTION_METADATA_HISTORYSYNCSYNC | DISABLEDHistorize metadata changes on transactions
HASH_LOGSSYNCSYNC | DISABLEDHash logs
INDEX_ADDRESS_SEGMENTSONON | OFFIndex accounts addresses segments
INDEX_TRANSACTION_ACCOUNTSONON | OFFIndex transactions accounts set
MOVES_HISTORYONON | OFFHistorize funds movements by account
MOVES_HISTORY_POST_COMMIT_EFFECTIVE_VOLUMESSYNCSYNC | DISABLEDCompute and maintains post commit effective volumes