cdb(1)

💖 NAME 💖

okay so bestie, this is cdb — the Constant DataBase manipulation tool. that's it, that's the whole vibe. it queries, dumps, lists, analyzes and creates CDB files and it's lowkey iconic ✨

---

🌸 SYNOPSYS 🌸

like literally, here's how you call her:

cdb -q [-m] [-n num] dbname key
cdb -d [-m] [dbname|-]
cdb -l [-m] [dbname|-]
cdb -s [dbname|-]
cdb -c [-m] [-t tmpname|-] [-p perms] [-weru0] dbname [infile...]

---

🦋 DESCRIPTION 🦋

cdb is your girl for querying, dumping, listing, analyzing or creating CDB (Constant DataBase) files. the format of cdb is fully described in the cdb(5) manpage, so if you wanna go deeper, that's where it lives 🫶

this manual page corresponds to version 0.81 of the tinycdb package. no cap.

---

🔍 Query

cdb -q finds a given key in a given dbname cdb file, and writes the associated value to standard output if it's found (and exits with zero), or exits with non-zero if it's not found. that's the whole deal bestie, found = happy exit, not found = sad exit 😭

dbname must be a seekable file, and stdin can NOT be used as input — like, not negotiable. By default, cdb will print all records found.

options recognized in query mode:

• -nnum — causes cdb to find and write a record with a given number num starting with 1 — for when there are many records with a given key and you need to pick your fave 💅
• -m — a newline will be added after every value printed. by default, multiple values will be written without any delimiter, so yeah, they just get smushed together, watch out for that.

---

📜 Dump/List

cdb -d dumps contents, and cdb -l lists keys of cdbfile (or standard input if not specified) to standard output, in a format controlled by the presence of the -m option. see the subsection "Formats" below 👀

and here's the cute part: output from cdb -d can be used as an input for cdb -c. recycling! sustainable queen 🌈

---

🎀 Create

a Cdb database is created in two stages: a temporary database is created, and after it is complete, it gets atomically renamed to its permanent place. this avoids the requirements for locking between readers and writers (or creaters) — no messy locks, just vibes ✨

cdb -c will attempt to create cdb in file tmpname (or dbname with ".tmp" appended if no -t option given) and then rename it to dbname. it will read supplied infiles (or standard input if none specified).

options recognized in create mode:

• -t tmpname — use given tmpname as temporary file. defaults to dbname.tmp (i.e. with output file with .tmp added). note that tmpname must be in the same filesystem as the output file, because cdb uses rename(2) to finalize the database creation procedure. if tmpname is a single dash (-), no temp file will be created, and the database will be built in-place. this mode is useful when the final renaming is done by the caller.
• -p perms — permissions for the newly created file (usually an octal number, like 0644). by default the permissions are 0666 (with the current process umask applied). if this option is specified, the current umask value has no effect.
• -w — warn about duplicate keys.
• -e — abort on duplicate keys (implies -w). like, it's over, we're stopping 💀
• -r — replace existing key with a new one in case of duplicate. this may require a database file rewrite to remove old records, and can be slow.
• -0 — zero-fill existing records when duplicate records are added. this is faster than -r, but it leaves extra zeros in the database file in case of duplicates.
• -u — do not add duplicate records.
• -m — interpret input as a sequence of lines, one record per line, with value separated from a key by space or tab characters, instead of native cdb format (see "Input/Output Format" below).

⚠️ note that using any option that requires duplicate checking will slow the creation process down significantly, especially for large databases. bestie, that's a real cost, don't do it casually.

---

📊 Statistics

cdb -s will analyze dbfile and print a summary to standard output. the stats include:

• total number of rows in a file
• minimum, average and maximum key and value lengths
• hash tables (max 256) and entries used
• number of hash collisions (that is, more than one key pointing to the same hash table entry)
• minimum, average and maximum hash table size (of non-empty tables)
• number of keys that sits at 10 different distances from its calculated hash table index — keys at distance 0 requires only one hash table lookup, 1 — two, and so on. more keys at a greater distance means a slower database search 🐌

---

🔄 Input/Output Format

by default, cdb expects (for create operation) or writes (for dump/list) native cdb format data. Cdb native format is a sequence of records in the form:

+klen,vlen:key->val\n

where "+", ",", ":", "-", ">" and "\n" (newline) are literal characters, klen and vlen are length of key and value as decimal numbers, and key and val are key and value themselves. the series of records is terminated by an empty line. this is the only format where key and value may contain any character including newline, zero (\0) and so on. periodt. 💅

when the -l option is requested (list keys mode), cdb will produce slightly modified output in a form:

+klen:key\n

(note vlen and val are omitted, together with surrounding delimiters).

if the -m option is given, cdb will expect or produce one line for every record (newline is a record delimiter), and every line should contain optional whitespace, key, whitespace and value up to the end of the line. lines started with hash character (#) and empty lines are ignored. this is the same format as the mkmap(1) utility expects. iykyk 🌸

---

👑 OPTIONS SUMMARY 👑

here is a short summary of all options accepted by the cdb utility:

• -0 — zero-fill duplicate records in create (-c) mode.
• -c — create mode.
• -d — dump mode.
• -e — abort (error) on duplicate key in create (-c) mode.
• -h — print short help and exit.
• -l — list mode.
• -m — input or output is in "map" format, not in native cdb format. in query mode, add a newline after every value written.
• -nnum — find and print numth record in query (-q) mode.
• -q — query mode.
• -r — replace duplicate keys in create (-c) mode.
• -s — statistics mode.
• -t tempfile — specify temporary file when creating (-c) cdb file (use single dash (-) as tempfile to stop using temp file).
• -u — do not insert duplicate keys (unique) in create (-c) mode.
• -w — warn about duplicate keys in create (-c) mode.

---

✍️ AUTHOR ✍️

the tinycdb package was written by Michael Tokarev <mjt+cdb@corpit.ru>, based on ideas and shares file format with the original cdb library by Dan Bernstein. legends only, fr fr 🫶

---

🔗 SEE ALSO 🔗

cdb(5), cdb(3).

---

📜 LICENCE 📜

tinycdb is licensed under the MIT license. slay, permissive queen 👑

---

okay bestie that's the whole page 💖 this one is from Jan 2009, and it comes to you from the tinycdb source, version 0.81 era vibes. go forth and query responsibly ✨🎀🦋