Logical databases

Applies to: development sources with cluster protocol 5, or protocol 6 for experimental group sync. Not available in the published APT 0.1.0-2 packages. Use matching servers, tools and SDKs.

Organize records

A cluster contains databases, each with raw key/value records and tables. A table contains keyed rows and typed columns. The default database is named default. Existing clients continue to use it without changing keys or partition placement.

Choose a database when constructing a client. Names contain 1–64 ASCII letters, digits, underscores or hyphens and are case sensitive. Writing the first record creates an observed database; no create command is required. Empty databases have no separate catalog entry. There is no database rename or drop command.

from smkv import Client

with Client("127.0.0.1:7379", database="orders") as client:
    client.put(b"status", b"ready")
    client.table("customers").put(b"customer-42", {"active": True})

The same table and key in another database identifies a different record. Raw keys and table rows are separate within each database. Updates, deletes, TTL and replica acknowledgments apply to the selected database. Database and table encoding both count against the configured key-size limit.

Inspect and scan

smkv --addr 127.0.0.1:7379 --database orders put status ready
smkv --addr 127.0.0.1:7379 --database orders get status
smkv-ctl --seed 127.0.0.1:7381 databases
smkv-ctl --seed 127.0.0.1:7381 scan --database orders --table customers

The catalog reports observed entries and index key bytes by node and partition; primary and replica copies are identified separately. Expired entries may remain until cleanup. Key bytes exclude values, allocator overhead and retained history. Catalog samples list at most 256 database names per partition, with explicit databases_truncated indication when incomplete. Capacity sampling inspects the index; it is not a high-frequency metrics endpoint.

In SMKV Web, the overview lists observed databases and the Tables view has a Database field. QPS and latency graphs remain cluster-wide. Scan cursors are bound to the database, table and query. Changing any of these requires restarting the scan. Scans retain lower priority than point reads and writes. Offline smkv key commands support only default.

Permissions and shared resources

Authentication and TLS remain optional. When authentication is enabled, add an optional databases array to an identity in the users file:

{"name":"orders-app","role":"read_write","token_sha256":"<64-character SHA-256 digest>","databases":["orders"]}

Omitting databases permits all databases allowed by the role; an empty array permits no data access. Restrictions apply to raw keys, rows and scans. Restricted identities cannot administer the cluster or perform peer/export operations. Topology and aggregate observations remain cluster-wide.

Databases share workers, partitions, disk, capacity protections, replication and failure domains. There are no per-database resource quotas, eviction policies, durability settings or transactions. Use separate clusters for resource isolation.

Backup, S3 sync and upgrades

Full exports/imports preserve all database identities. Selective database restore is not supported. Named-database snapshots require database-aware restore binaries.

Experimental S3 group sync covers all databases in an enrolled cluster and includes the database in each event's identity. The same key in different databases does not conflict. Imported changes retain their database and are not republished. Origin checkpoints and bootstrap preserve names across different partition layouts; full backups remain separate. All group members handling named databases must use compatible database-aware sync builds.

Older cluster protocols cannot join these clusters. Plan a new-cluster migration for incompatible versions; do not perform a rolling replacement or downgrade a store after named-database writes. Existing unannotated default-only stores remain readable. See backup and restore and group sync.