camus-dump

camus-dump is a logical backup utility for CamusDB. It connects to a database, reads schema metadata and rows, and writes SQL that can be replayed later through camus-cli or another CamusDB SQL client.

Use it when you want an inspectable SQL backup, a table-level export, or a consistent logical snapshot of a database.

Install

Install the global tool:

dotnet tool install --global CamusDB.Dump

The executable name is:

camus-dump

Basic Usage

Dump a database to standard output:

camus-dump --endpoint http://localhost:5096 --database factory

Dump one table, group 100 rows per INSERT, and write to a file:

camus-dump \
  --endpoint http://localhost:5096 \
  --database factory \
  --table orders \
  --batch 100 \
  --output orders.sql

Take a consistent database snapshot that can replay onto an existing schema:

camus-dump \
  --endpoint http://localhost:5096 \
  --database factory \
  --single-transaction \
  --if-not-exists \
  --output factory.sql

By default, camus-dump uses the gRPC protocol and http://localhost:5096, which is CamusDB's default client gRPC port. Use --protocol rest with the REST endpoint when you want REST/JSON instead.

Connection Options

Option	Description
-c, --connection-source	Full connection string. Other connection options fill in keys that the connection string does not already set.
-e, --endpoint	Server endpoint or comma-separated endpoint pool. Defaults to http://localhost:5096.
-d, --database	Database to dump. Defaults to test.
--protocol	grpc by default, or rest. The endpoint port must match the selected protocol.
--timeout	Per-statement timeout in seconds. Defaults to 10.

Example with a connection string:

camus-dump \
  --connection-source "Endpoint=http://localhost:5096;Database=factory;Protocol=grpc"

Authentication

CamusDB authentication is off by default. Against an authenticated server, pass credentials or a bearer token:

CAMUSDB_PASSWORD=app-secret \
camus-dump -e https://camus.internal:5096 -d factory -u app

Prompt for the password:

camus-dump -e https://camus.internal:5096 -d factory -u app --ask-password

Use a token obtained elsewhere:

camus-dump -e https://camus.internal:5096 -d factory --access-token "camus_..."

Option	Description
-u, --user	User to authenticate as.
-p, --password	User password. Prefer CAMUSDB_PASSWORD or --ask-password so the password does not appear in the process list.
-W, --ask-password	Prompt for the password on the terminal.
--access-token	Bearer token obtained elsewhere, used instead of logging in.
--token-lifetime	Seconds to reuse a minted token when the server reports no expiry. Defaults to 600.

The password is exchanged once for a short-lived bearer token. Statements use the token, not the password. Over gRPC, authentication uses the CamusAuth service on the same channel that carries dump queries.

The dump reads schema and table data. With authentication enabled, the user needs privileges that allow the relevant SHOW and SELECT operations.

Use https:// for non-loopback authenticated deployments. CamusDB rejects credential-bearing plaintext requests outside loopback when TLS is required.

Choosing What To Dump

Option	Description
-t, --table	Dump only these tables. Accepts comma-separated names or repeated options.
-x, --exclude-table	Skip these tables. Accepts comma-separated names or repeated options.
-w, --where	Dump only rows matching this condition.
--no-create-table	Do not emit CREATE TABLE.
--no-data	Do not emit INSERT.
--no-indexes	Do not emit secondary index DDL.

Example:

camus-dump -e http://localhost:5096 -d factory \
  --table orders \
  --where 'status = "open"' \
  --output open-orders.sql

Shaping The Output

Option	Description
-b, --batch	Rows per INSERT statement. Defaults to 1.
-o, --output	Write to a file instead of standard output.
--defer-indexes	Emit each table's CREATE INDEX statements after its data.
--add-drop-table	Emit DROP TABLE IF EXISTS before each CREATE TABLE.
--if-not-exists	Emit CREATE TABLE IF NOT EXISTS, useful when replaying onto an existing schema.
--create-database	Emit CREATE DATABASE IF NOT EXISTS for the dumped database.
--single-transaction	Read every table from one lock-free Serializable snapshot, producing a database-consistent dump.
--strict	Fail instead of emitting NULL for values that have no exact SQL literal.
--no-header	Omit the leading comment header.

Use --single-transaction when the database may be changing while the dump is running and you need all dumped tables to reflect one consistent snapshot.

Use --defer-indexes for large restores when you want table data loaded before secondary indexes are built.

Dump Contents

Depending on the selected options, the dump can include:

• optional header comments
• CREATE DATABASE IF NOT EXISTS
• DROP TABLE IF EXISTS
• CREATE TABLE statements
• INSERT INTO statements
• secondary CREATE INDEX IF NOT EXISTS statements

Typical shape:

CREATE DATABASE IF NOT EXISTS factory;

CREATE TABLE IF NOT EXISTS `orders` (
  `id` OID NOT NULL DEFAULT (gen_id()),
  `name` STRING(20) NULL,
  PRIMARY KEY (`id`)
);

INSERT INTO `orders` (`id`, `name`)
VALUES
  (STR_ID('507f1f77bcf86cd799439011'), 'first order'),
  (STR_ID('507f1f77bcf86cd799439012'), 'second order');

Literal Encoding

camus-dump emits values as CamusSQL literals that parse back to the same stored value:

Type	Dump form
OID	STR_ID('...')
STRING	Plain '...' when possible, or E'...' for control characters
INT64	Integer literal
FLOAT64, FLOAT32	Numeric literal
BOOL	true or false
BYTES	X'...' hex bytes literal
DATE	Quoted yyyy-MM-dd string
DATETIME	Quoted ISO-8601 datetime string
UUID	Quoted canonical UUID string
ARRAY	ARRAY[...]
NULL	NULL

Strings round-trip even when they contain a backslash, a trailing backslash, both quote characters, a newline, or a NUL. See Data Types for the literal rules.

Indexes are dumped both inline in CREATE TABLE and as separate CREATE INDEX IF NOT EXISTS statements. This keeps index definitions available when --no-create-table is used and lets --defer-indexes build indexes after row loading.

Lossy Values

Most stored values have exact SQL literal forms. When a value cannot be restored exactly, camus-dump reports it.

Non-finite floats have no CamusSQL literal:

• NaN
• +Infinity
• -Infinity

By default, the dump emits NULL for those values, adds warning comments to the dump, and prints a count to standard error at the end. Use --strict to fail instead.

DATETIME literals carry millisecond precision. If a dumped datetime must be truncated to milliseconds, the tool reports that too; --strict turns it into a failure.

Restore A Dump

Restore by feeding the generated SQL to camus-cli:

camus-cli -c "Endpoint=http://localhost:5096;Protocol=grpc"

Then run:

source ./factory.sql

If the dump does not include --create-database, create and select the target database first:

CREATE DATABASE IF NOT EXISTS factory;
use factory;
source ./factory.sql

See camus-cli for interactive shell usage.

When To Use It

Use camus-dump when you want:

• a logical SQL backup
• a table-level export
• a readable dump for review or source control
• a consistent snapshot across tables
• a restore path through ordinary CamusSQL

For interactive replay and manual restore, use camus-cli.