Skip to content

README.md

Latest commit

 

History

History
134 lines (99 loc) · 5.64 KB

README.md

File metadata and controls

134 lines (99 loc) · 5.64 KB

cosmokv — CLI shell for CosmoKv databases

Interactive command-line shell for CosmoKv embedded databases, in the spirit of sqlite3. REPL, one-shot SQL, stdin scripts, and four output formats. Ships as a dotnet global tool.

Install

dotnet tool install -g CosmoSQLClient.CosmoKv.Cli

After install, the binary is on PATH as cosmokv.

Usage

cosmokv                                    # REPL on a transient DB
cosmokv [--format=FMT] <database>          # REPL on <database>
cosmokv [--format=FMT] <database> [sql]    # one-shot SQL
cosmokv [--format=FMT] <database> -        # read SQL from stdin
cosmokv --help

<database> is either a bare directory path (e.g. ./mydb — sqlite3-style) or a full connection string (DataSource=./mydb;CreateIfMissing=false). The bare form is shorthand for DataSource=<path>;CreateIfMissing=true — the directory is auto-created if missing. Use the connection-string form when you want to require the database to already exist (set CreateIfMissing=false).

With no <database>, the REPL opens against a transient temp directory and removes it on exit — handy for trying things out. Use .open FILENAME from inside the REPL to switch to a persistent database (and keep your subsequent work).

REPL

Run with just a database path to drop into the interactive shell. Statements end with ; and may span multiple lines.

$ cosmokv ./mydb
cosmokv 2.5.0 — :help for commands, :quit to leave
cosmokv> CREATE TABLE Users (
    ...> Id BIGINT IDENTITY PRIMARY KEY,
    ...> Email NVARCHAR(256) NOT NULL);
0 rows affected.
cosmokv> INSERT INTO Users (Email) VALUES ('a@b'), ('c@d');
2 rows affected.
cosmokv> SELECT * FROM Users;
Id  Email
--  -----
1   a@b  
2   c@d  
(2 rows)
cosmokv> .quit

One-shot

Pass SQL as the last positional argument. Useful for shell scripting and ad-hoc queries.

cosmokv ./mydb "SELECT COUNT(*) AS n FROM Users"

Stdin

Pass - instead of inline SQL to pipe a script in. The CLI splits on semicolons (outside string literals) and runs each statement in order.

cat schema.sql | cosmokv ./mydb -

Output formats

--format=FMT (or .format FMT inside the REPL) selects how rows are rendered. Pipe to other tools for processing.

cosmokv --format=json ./mydb "SELECT Id, Email FROM Users" | jq '.[].Email'
cosmokv --format=csv  ./mydb "SELECT * FROM Users" > users.csv
cosmokv --format=tsv  ./mydb "SELECT * FROM Users" | column -t -s $'\t'
Format Notes
table (default) Aligned columns with a header rule.
csv RFC 4180-ish: values containing the delimiter or quotes get quoted.
tsv Tab-separated; tab/newline characters in values are flattened to spaces.
json Single array of objects per result set. Booleans and numerics are native JSON values.

REPL dot-commands

Dot-commands work only at the start of a fresh line (not mid-statement) and consume the whole line.

Command Behaviour
.help List dot-commands.
.open FILENAME Close the current connection and reopen on FILENAME (auto-created). Promotes a transient session to persistent.
.databases Show the current data source (transient: … or main: …).
.tables Names of every user table, alphabetically.
.schema [TABLE] CREATE TABLE script for TABLE (or every table if omitted). Round-trips through the parser, so you can replay it.
.indexes [TABLE] CREATE INDEX scripts for TABLE (or every table).
.dump Schema + INSERT statements for the entire database — like sqlite3's .dump. Safe to replay against an empty CosmoKv.
.backup FILENAME Write a COSMOBAK snapshot to FILENAME. MVCC — writes continue uninterrupted. Refuses to overwrite an existing file.
.vacuum Run value-log GC to reclaim space from tombstoned/overwritten large values. Prints the number of vlog files dropped.
.format FMT Switch the output format mid-session.
.quit / .exit / Ctrl-D Leave the shell.

Examples

Snapshot a database to a script:

cosmokv ./prod-db ".dump" > snapshot.sql
cosmokv ./fresh-db - < snapshot.sql

Pipe a query result into another tool:

cosmokv --format=json ./mydb "SELECT * FROM Events WHERE created_at > '2026-05-01'" \
  | jq 'group_by(.user_id) | map({user_id: .[0].user_id, n: length})'

Run a migration script:

cosmokv ./mydb - < migrations/001_schema.sql

Limitations

  • Statement splitting is lexical only — it understands single-quoted strings but not block comments or T-SQL GO. A trailing ; ends the current statement.
  • No readline-style history or autocomplete; if you want those, wrap the CLI with rlwrap.
  • .dump rewrites every row as a fully-qualified INSERT. For tables with millions of rows, prefer .backup FILENAME — it writes a COSMOBAK snapshot directly without the parse/encode round-trip.
  • .backup only writes plaintext snapshots. To re-encrypt with a different key, use BackupAsync(stream, backupKey) in code.
  • Opening an encrypted store from the shell requires a connection string with EncryptionKey=<base64> (32-byte AES-256 key, base64-encoded). Bare-path .open ./mydb opens unencrypted.

Related