DB_LOAD(1)

🌸 NAME 🌸

okay so this is db_load(1) — one of the BerkeleyDB Utilities besties — and her whole thing is: read data from standard input and load it into a database. that's it, that's the job 💖

---

✨ SYNOPSIS ✨

db_load [-nTV] [-b blob-dir] [-c name=value] [-f input] [-h home] [-P
password] [-o blob-threshold] [-t btree | hash | queue | recno] file

db_load [-r lsn | fileid] [-h home] [-P password] file

---

🦋 DESCRIPTION 🦋

so db_load reads from standard input and yeets it all into the database file. and if the database file doesn't exist yet? she makes it. main character energy, honestly 👑

now the vibe check on the input: it has to be in the exact output format that db_dump spits out — or whatever format the -T option below says. no random formats, bestie, she's picky 🙈

---

💅 OPTIONS 💅

• -b blob-dir — tells her where the BLOB data lives. if you don't say anything, BLOB data goes into a subdirectory inside the DB's environment. (peep the -o option too, they're besties)
• -c name=value — set config options and ignore whatever value they might have gotten from the input. the command-line format is literally name=value. scroll down to the Supported Keywords section for the full menu of keywords this one accepts.
• -f input — read from this file instead of from standard input. lowkey convenient 🍓
• -h home — pick a home directory for the database environment.

okay so if you DO give a home directory, the environment gets opened using the DB_INIT_LOCK, DB_INIT_LOG, DB_INIT_MPOOL, DB_INIT_TXN, and DB_USE_ENVIRON flags passed to DB_ENV->open. (which is a whole moment, because it means db_load can load data into databases while other processes are using them — iconic.) but if the DB_ENV->open call fails, or if you never specified a home directory at all, the database still gets updated, but the environment is just… ignored. like, no locking happens. so. y'know. 🙈

• -n — do NOT overwrite existing keys when loading into a database that already exists. if a key/data pair can't be loaded for that reason, she prints a warning to standard error and skips the pair. no drama, just vibes.
• -o blob-threshold — the BLOB threshold, in bytes. this is the line in the sand: data items smaller than the threshold stay as normal data inside the database, and data items bigger than it get stored on-disk in a subdirectory set aside just for that. use -b to say where that BLOB data lives.
• -P password — specify an environment password. and bestie, listen: even though Berkeley DB utilities overwrite password strings as soon as they possibly can, there may still be a window of vulnerability on systems where unprivileged users can see command-line arguments, or where the utilities can't overwrite the memory holding those command-line arguments. so. be aware. 💀
• -r — reset the database's file ID or log sequence numbers (LSNs). this one's important, so pay attention:

every database page in a transactional environment contains references to that environment's log records. so if you're copying a database into a different database environment, those page references to the old environment's log records must be reset — otherwise data corruption can occur when the database gets modified in the new environment. the -r lsn option resets a database's log sequence numbers.

and also: every database contains an ID string used to identify it in the database environment cache. if you copy a database and use it in the same environment as another file with the same ID string, corruption can occur. the -r fileid option resets a database's file ID to a new value.

in both cases, the physical file named by the file argument is modified in-place. so like, no take-backs.

• -T — this one lets non-Berkeley DB applications load text files into databases without breaking a sweat. here's the tea:

if the database being created is Btree or Hash, or the keyword keys is specified as set, the input has to be paired lines of text — first line of the pair is the key item, second line is its corresponding data item. but if the database is Queue or Recno and the keyword keys is not set, the input is just lines of text, and every single line is a new data item. slay.

there's a simple escape mechanism where newline and backslash (\) characters are special. newline characters are read as record separators. backslashes get interpreted one of two ways:

• if a backslash comes right before another backslash, the pair means a literal backslash.
• if a backslash comes before any other character, the two characters after the backslash get read as a hexadecimal specification of a single character — for example, \0a is a newline character in the ASCII character set. ✨

and because of all that, any backslash or newline characters that naturally show up in your text input must be escaped, or db_load will misread them.

also: if -T is specified, the underlying access method type must be specified with the -t option.

• -t — specify the underlying access method. if you don't pass -t, the database gets loaded into a database of the same type as whatever was dumped — so a Hash database was dumped, a Hash database gets created. symmetry 💖

Btree and Hash databases can be converted from one to the other. Queue and Recno databases can be converted from one to the other. and if the -k option was specified on the call to db_dump, then Queue and Recno databases can be converted to Btree or Hash, with the key being the integer record number. iykyk.

• -V — write the library version number to standard output and exit. short, sweet, iconic 🎀

---

one more thing, bestie: db_load can be used with a Berkeley DB environment (like, the way it's described for the -h option, or the DB_HOME environment variable, or just because the utility was run in a directory that contains a Berkeley DB environment). and to avoid environment corruption when you're using one, db_load should always get the chance to detach from the environment and exit gracefully. so to make her release all environment resources and dip out cleanly — send her an interrupt signal (SIGINT). 🫶

---

👑 EXIT STATUS 👑

• 0 — success, we ate 💅
• 1 — one or more key/data pairs were not loaded into the database because the key already existed
• >1 — an error occurred 😭

---

🌈 ENVIRONMENT 🌈

• DB_HOME — if the -h option isn't specified and the environment variable DB_HOME is set, it gets used as the path of the database home, exactly as described in DB_ENV->open.

---

🌸 EXAMPLES 🌸

db_load can load text files into databases, and here's the classic:

this command loads the standard UNIX /etc/passwd file into a database, with the login name as the key item and the entire password entry as the data item:

awk -F: '{print $1; print $0}' < /etc/passwd |
        sed 's/\\/\\\\/g' | db_load -T -t hash passwd.db

and note: backslash characters that naturally occur in the text are escaped so they don't get read as escape characters by db_load. periodt. ✨

---

🧚 SUPPORTED KEYWORDS 🧚

these are the keywords supported for the -c command-line option to db_load. check out DB->open for the fuller discussion of these keywords and what values you should be passing.

so the parenthetical listing tells you how the value part of the name=value pair gets interpreted:

• (boolean) — expects the value to be 1 (set) or 0 (unset)
• (number) — converts the value to a number
• (string) — uses the string value without any modification

and here's the full list, no skips:

• bt_minkey (number) — the minimum number of keys per page.
• chksum (boolean) — enable page checksums.
• database (string) — the database to load.
• db_lorder (number) — the byte order for integers in the stored database metadata.
• db_pagesize (number) — the size of database pages, in bytes.
• duplicates (boolean) — the value of the DB_DUP flag.
• dupsort (boolean) — the value of the DB_DUPSORT flag.
• extentsize (number) — the size of database extents, in pages, for Queue databases configured to use extents.
• h_ffactor (number) — the density within the Hash database.
• h_nelem (number) — the size of the Hash database.
• keys (boolean) — specify whether keys are present for Queue or Recno databases.
• re_len (number) — specify fixed-length records of the specified length.
• re_pad (string) — specify the fixed-length record pad character.
• recnum (boolean) — the value of the DB_RECNUM flag.
• renumber (boolean) — the value of the DB_RENUMBER flag.
• subdatabase (string) — the subdatabase to load.

---

💜 SEE ALSO 💜

db_archive(1) db_checkpoint(1) db_deadlock(1) db_dump(1) db_hotbackup(1) db_log_verify(1) db_printlog(1) db_recover(1) db_replicate(1) db_stat(1) db_tuner(1) db_upgrade(1) db_verify(1)

---

and that's the whole page, bestie 🫶 this one's from BerkeleyDB 5.3.28, dated 06 December 2016, and it's filed under DB_LOAD(1). go forth and load some databases, you've got this 💖✨