Skip to Content
SQL ReferenceStorage Commands

Storage Commands

KalamDB supports multiple storage backends for cold-tier data. These commands manage storage configuration, health checks, and maintenance.

For practical table-level storage selection (STORAGE_ID, USE_USER_STORAGE, and verification queries), see /docs/server/sql-reference/storage-id-usage. For S3-compatible local deployment setup, see /docs/server/integrations/minio. For the underlying hot/cold architecture and manifest state machine, see /docs/server/architecture/storage-tiers and /docs/server/architecture/manifests.

CREATE STORAGE

SQL
CREATE STORAGE <storage_id>  TYPE '<filesystem|s3|gcs|azure>'  [NAME '<storage_name>']  [DESCRIPTION '<description>']  [PATH '<path>']  [BUCKET '<bucket_or_s3_url>']  [REGION '<region>']  [BASE_DIRECTORY '<path_or_url>']  [SHARED_TABLES_TEMPLATE '<template>']  [USER_TABLES_TEMPLATE '<template>']  [CREDENTIALS '<json_credentials>']  [CONFIG '<json_config>'];

Examples

Local filesystem:

SQL
CREATE STORAGE local  TYPE 'filesystem'  PATH './data';

Amazon S3:

SQL
CREATE STORAGE s3_prod  TYPE 's3'  BUCKET 'my-bucket'  REGION 'us-west-2'  CREDENTIALS '{"access_key_id":"...","secret_access_key":"..."}';

Google Cloud Storage:

SQL
CREATE STORAGE gcs_prod  TYPE 'gcs'  BUCKET 'my-gcs-bucket'  CREDENTIALS '{"service_account_key":"..."}';

Azure Blob Storage:

SQL
CREATE STORAGE azure_prod  TYPE 'azure'  BUCKET 'my-container'  CREDENTIALS '{"account_name":"...","account_key":"..."}';

Storage Type Aliases

SQL TypeAliasBase Directory Prefix
filesystem—Local path (e.g., ./data/storage)
s3—s3://bucket/prefix
gcsgsgs://bucket/prefix
azureazaz://container/prefix

CONFIG JSON Fields by Backend

S3 CONFIG

JSON
{  "type": "s3",  "region": "us-east-1",  "endpoint": "http://127.0.0.1:9120",  "allow_http": true,  "access_key_id": "...",  "secret_access_key": "...",  "session_token": "..."}
FieldTypeDefaultNotes
regionstring"us-east-1"AWS region or custom region for S3-compatible
endpointstringnullCustom endpoint for MinIO / S3-compatible
allow_httpbooleanfalseMust be true for non-TLS endpoints
access_key_idstringnullStatic credentials (omit for IAM roles)
secret_access_keystringnullStatic credentials
session_tokenstringnullTemporary session credentials

For S3-compatible local setup, see /docs/server/integrations/minio.

GCS CONFIG

JSON
{  "type": "gcs",  "service_account_json": "{...}"}
FieldTypeDefaultNotes
service_account_jsonstringnullService account JSON key. Omit to use Application Default Credentials (ADC).

Azure CONFIG

JSON
{  "type": "azure",  "account_name": "mystorageaccount",  "access_key": "...",  "sas_token": "..."}
FieldTypeDefaultNotes
account_namestringnullAzure storage account name
access_keystringnullAccount access key
sas_tokenstringnullShared Access Signature token (alternative to access_key)

Local/Filesystem CONFIG

JSON
{  "type": "local",  "root": "./data/storage"}
FieldTypeDefaultNotes
rootstringnullInformational; actual path comes from BASE_DIRECTORY or PATH.

ALTER STORAGE

SQL
ALTER STORAGE <storage_id>  [SET NAME '<new_name>']  [SET DESCRIPTION '<new_description>']  [SET SHARED_TABLES_TEMPLATE '<new_template>']  [SET USER_TABLES_TEMPLATE '<new_template>']  [SET CONFIG '<json_config>'];

DROP STORAGE

SQL
DROP STORAGE <storage_id>;DROP STORAGE IF EXISTS <storage_id>;

SHOW STORAGES

SQL
SHOW STORAGES;

STORAGE CHECK

Verify storage backend health:

SQL
STORAGE CHECK <storage_id>;STORAGE CHECK <storage_id> EXTENDED;

STORAGE FLUSH

Force flushing data from hot tier (RocksDB) to cold tier (Parquet):

SQL
-- Flush a specific tableSTORAGE FLUSH TABLE <namespace>.<table_name>; -- Flush all tables in a namespaceSTORAGE FLUSH ALL IN <namespace>;STORAGE FLUSH ALL IN NAMESPACE <namespace>; -- Flush everythingSTORAGE FLUSH ALL;

STORAGE COMPACT

Merge and optimize cold-tier Parquet segments:

SQL
-- Compact a specific tableSTORAGE COMPACT TABLE <namespace>.<table_name>; -- Compact all tables in a namespaceSTORAGE COMPACT ALL IN <namespace>;STORAGE COMPACT ALL IN NAMESPACE <namespace>; -- Compact everythingSTORAGE COMPACT ALL;

SHOW MANIFEST

Display the storage manifest (schema + segment index):

SQL
SHOW MANIFEST;
Last updated on
Storage ID UsageBuilt-in Functions