Skip to main content

Databases

Databases in CamusDB must be created explicitly before use. Opening, querying, or running table DDL against an unknown database returns DatabaseDoesntExist instead of creating storage implicitly.

Create A Database​

CREATE DATABASE app;

Use IF NOT EXISTS when setup scripts should be idempotent:

CREATE DATABASE IF NOT EXISTS app;

After creation, connect to that database with camus-cli app, use app;, a driver connection string, an HTTP request whose databaseName is app, or a gRPC request whose database is app.

Branch A Database​

CREATE DATABASE feature_checkout BRANCH FROM app;

Database branching creates an isolated point-in-time clone of an existing database. The branch starts from the source database's schema and data view, but writes and DDL in the branch stay private to that branch.

Use branches to test features, rehearse migrations, or reproduce issues against production-like data without affecting the base database. See Database Branching for the full workflow and operational notes.

List Databases​

SHOW DATABASES;
SHOW BRANCHES FROM app;
SHOW ANCESTORS FROM feature_checkout;

SHOW DATABASES is a server-level statement. It does not require an already open database context.

Use SHOW BRANCHES FROM <database> to list every descendant branch of a database. Use SHOW ANCESTORS FROM <database> to inspect the parent chain of a branch. See Database Branching for column details.

Drop A Database​

DROP DATABASE app;
DROP DATABASE IF EXISTS app;
DROP DATABASE app FORCE;

DROP DATABASE removes the registry entry for the database name immediately, but the database data is retained as a recoverable orphan for the configured retention window. The name is free to reuse, SHOW DATABASES no longer lists it, and opening the dropped name returns DatabaseDoesntExist.

Use SHOW ORPHAN DATABASES to inspect recoverable dropped databases, then recover one under a new name with CREATE DATABASE ... RELINK TO:

SHOW ORPHAN DATABASES;
CREATE DATABASE app_recovered RELINK TO '7';

Use FORCE only when the database should be physically deleted immediately and permanently:

DROP DATABASE app FORCE;

DROP DATABASE IF EXISTS is a no-op when the database name is absent. A forced drop creates no orphan and cannot be recovered. See Recover Dropped Objects for the recovery workflow, retention settings, and limits.

Rename A Database​

RENAME DATABASE app TO app_prod;
ALTER DATABASE app RENAME TO app_prod;

Both forms are equivalent. ALTER DATABASE ... RENAME TO matches the table rename word order, while RENAME DATABASE ... TO ... remains supported.

Renaming changes only the registry binding from name to internal storage id. The storage id, table ids, row keys, index keys, statistics keys, and database comment remain the same.

Important behavior:

  • opening the old name fails after the rename completes
  • opening the new name resolves to the same storage id
  • in-flight work can continue because the human-readable name is not part of row or index storage keys
  • renaming to an existing name fails
  • reserved names cannot be used as rename targets
  • comments set with COMMENT ON DATABASE survive the rename

Stable Storage Identity​

Every database receives a stable opaque storage id when it is created. The id is allocated from a persistent monotonic sequence, encoded as a short base62 string, and is not reused after DROP DATABASE.

The id is an internal storage identity, not a SQL value and not an ObjectId. Applications should address databases by name.

The human-readable name is stored in the database registry, but the registry entry points at the stable storage id. Database data lives in the shared Kahuna keyspace under keys that begin with that database id.

Tables use the same identity model. A newly created table receives a stable short base62 table id from a persistent monotonic sequence. Table ids are used inside row, index, statistics, and schema keys; SQL continues to address tables by name.

Using ids instead of names means a database or table rename does not move data and does not rewrite table or index keys.

Reserved Names​

These names are reserved:

NamePurpose
_systemInternal database registry and cluster metadata namespace.
information_schemaReserved for future SQL compatibility.

Creating or renaming a database to either name returns DatabaseNameReserved.

Error Codes​

CodeNameTypical cause
CADB0010DatabaseDoesntExistOpening, querying, dropping, renaming, or running table DDL against an unknown database.
CADB0012DatabaseAlreadyExistsCREATE DATABASE targets an existing name, or a database rename targets an existing name.
CADB0018DatabaseNameReservedCREATE DATABASE or a database rename uses _system or information_schema.
CADB0019DatabaseCreationIncompleteReserved for an incomplete database-create recovery condition from older standalone storage layouts. It is not expected on the current shared-storage create path.
CADB0508DatabaseHasLiveDescendantsDROP DATABASE targets a database that still has live branch descendants. Drop descendant branches first.
CADB0510OrphanNotFoundCREATE DATABASE ... RELINK TO references an unknown, already recovered, or reclaimed orphan id.