Generate a Berkeley DB C Starter with db5.3_codegen

You will turn a small Berkeley DB description into a C source file containing environment and database handles, plus bdb_startup and bdb_shutdown functions. The command is documented by Berkeley DB 5.3, but this machine has an awkward packaging detail: db5.3-util version 5.3.28+dfsg2-7 and db-util version 1:5.3.21ubuntu2 install the manpages, while neither package installs a db5.3_codegen or db_codegen executable here.

Allow about twenty minutes for the schema and generated C to be checked. You need the Berkeley DB development headers and library separately from the utility package, and a writable project directory. These examples only create a description file and generated source. They do not create database files, alter an environment or require sudo.

1. Check which part is installed

Start with read-only checks. The two command names are aliases for the same documented generator, with the versioned name preferred when it is available:

$ dpkg-query -W -f='${Package} ${Version}\n' db5.3-util db-util
db5.3-util 5.3.28+dfsg2-7
db-util 1:5.3.21ubuntu2
$ command -v db5.3_codegen || true
$ command -v db_codegen || true
$ dpkg -L db5.3-util db-util | grep -E '/(db5.3_codegen|db_codegen)$' || true

On the package set described above, the last three checks print no executable path. That is a packaging fact, not a syntax failure in your schema. Do not replace the missing program with db_sql_codegen: that is a different, SQL DDL based tool with a different input language.

2. Create a minimal description

Make a new working directory and write a description with one environment and two databases. The input language is whitespace-tokenised, ignores blank lines and hash comments, and is case-insensitive. Keep braces as separate tokens so a typo is easy to spot:

$ mkdir -p "$HOME/bdb-codegen-demo"
$ cd "$HOME/bdb-codegen-demo"
$ install -m 0644 /dev/null schema.desc
$ editor schema.desc

Put this in schema.desc:

environment inventory {
    home /var/lib/example-inventory
    cachesize 0 1048576 1
    private
    database products {
        type btree
        pagesize 4096
    }
    database by_sku {
        primary products
        secondary_offset 0 32
        type btree
        pagesize 4096
    }
}

The home value is part of the generated environment configuration, not a request for db5.3_codegen to create that directory now. The sample uses a secondary database because it shows an important boundary: primary products and secondary_offset 0 32 cause a callback stub to be generated, but you still need to check that the primary data really contains a 32-byte secondary key at offset zero.

The cache size is three values: gigabytes, bytes and number of caches. Here it means zero gigabytes, 1,048,576 bytes and one cache. It is not a single byte count. Adjust it to the application and host rather than copying this value into production.

3. Review the input before generation

Read the file back and check the tokens without changing anything:

$ sed -n '1,120p' schema.desc
$ grep -nE '^(environment|database|home|cachesize|private|primary|secondary_offset|type|pagesize|})' schema.desc

There must be three tokens on an environment or database opening line: the keyword, a name and {. A home line has two tokens. cachesize has the keyword plus its three values, despite an error in the installed manual's sentence saying two tokens. The examples and the tool's stated meaning make the required three values clear. Database types supported by this interface are btree, hash, queue and recno.

4. Generate into a new file

Use the versioned command when it exists. The -i option selects the description file and -o supplies an output prefix. For C generation, the resulting file is the prefix followed by .c:

$ db5.3_codegen -a c -i schema.desc -o inventory_generated
$ test -s inventory_generated.c && echo 'generated source exists'
generated source exists

The unversioned alias accepts the same options:

$ db_codegen -a c -i schema.desc -o inventory_generated

Do not run both commands against the same output prefix as part of a blind script. The second run may replace the first output. The default input is standard input, and the default output prefix is application, so a command with no options can unexpectedly read from a terminal and create application.c. Naming both files makes automation and review safer.

$ test ! -e inventory_generated.c || {
    printf '%s\n' 'refusing to overwrite inventory_generated.c' >&2
    exit 1
}
$ db5.3_codegen -a c -i schema.desc -o inventory_generated

If a generated file is wrong, preserve it for comparison, choose a new prefix, correct schema.desc, and generate again. Undo is simply to remove the generated file after checking that it is not the only copy of useful edits. The utility does not maintain a backup or a migration history.

5. Inspect the generated C

Generation success means that the description was accepted and output was written. It does not mean that the application design is correct:

$ grep -nE '^(DB_ENV|DB)[[:space:]]*\*|bdb_(startup|shutdown)' inventory_generated.c
$ sed -n '1,220p' inventory_generated.c

For this input, expect public handles named inventory_dbenv, inventory_products and inventory_by_sku, together with bdb_startup and bdb_shutdown. The exact declarations and generated formatting are version-specific, so review the file produced by your installed build rather than comparing it byte-for-byte with an example from another Berkeley DB release.

Look for the generated secondary callback stub. A primary relationship does not understand your application's record layout by itself. Modify and test the callback for the actual key bytes before relying on the index. Likewise, custom creates a comparison stub for a B-tree, and key_type creates an integral-type comparison routine. Treat either stub as unfinished application code.

6. Use the generated lifecycle deliberately

The generated bdb_startup function is intended to create and configure the environment and databases. The generated bdb_shutdown function is intended to close them gracefully. Call startup before using the public handles and shutdown on every normal exit path. If transaction is present, the environment and database become transactional; that changes the application's error handling and recovery obligations. Test those paths before enabling it on a live data set.

The sample's private environment is deliberately local to the process. Do not copy it into a multi-process design without checking the Berkeley DB environment rules and the generated code. The configured home path may require an administrator to create and permission, but that is a deployment step outside code generation. If you later create it under /var/lib, stop first, confirm the service account and backup plan, and use elevated privileges only for that filesystem operation.

7. Check version and failure status

Ask the available executable for its library version before recording generated output in a build:

$ db5.3_codegen -V
$ printf 'exit status: %s\n' "$?"
exit status: 0

-V prints the library version and exits. A normal generation should also return status zero. Any status greater than zero means an error occurred. With -v, request verbose diagnostics while keeping the same input and output checks:

$ db5.3_codegen -v -a c -i schema.desc -o inventory_generated

For a parse failure, inspect braces, token counts, database type and spelling first. For a missing executable on this Ubuntu installation, revisit step 1. Do not use sudo to hide a command lookup or schema error.