The original ddbsh was one program: parsing, planning, execution,
formatting, the AWS client, readline, and process-global state, coordinated by
a singleton CDDBSh and global flex/bison state. Fine for a CLI, a blocker for
reuse. The refactor pulled the engine out into a C++23 library and put an
embedding API on top.
Three targets, two boundaries
ddbsh::ddbsh, the engine: lexer, parser, command model, expression
engine, planner, execution against an injectedIDDBClient, and output andEXPLAINformatting. Every header underinclude/ddbsh/*.hppis free of both
the terminal and the AWS SDK.ddbsh::aws, optional:AwsDDBClient, anIDDBClientbacked by the AWS
SDK for C++, plusAwsApiGuardfor the SDK lifecycle. Headers underinclude/ddbsh/aws/need the SDK.ddbsh-cli, theddbshexecutable: arguments, prompt, readline and
history, the config file, signals. It contains no parsing or execution.
A test, engine_boundary_check, fails the build if an SDK-free header includes<aws/...>. Configure with DDBSH_BUILD_AWS=OFF and you get the engine with no
AWS SDK at all, which is how the WebAssembly build is configured.
The singleton became an explicit Session you construct. The parser is
reentrant flex (%option reentrant) with a bison C++ skeleton
(%skeleton "lalr1.cc"), its generated types hidden behind a PIMPL, so several
sessions can run in one process. Errors became values:Result<T> = std::expected<T, ddbsh::Error>. The library never calls exit()
or abort(). The CLI maps each Error to the original’s byte-exact message, so
the golden .exp output did not change. std::expected is the reason the
project targets C++23.
Embedding: handle, prepare, bind, execute, fetch, read
The API follows ODBC and Sybase DB-Library. ddbsh::aws::open(region) resolves
credentials through the standard AWS chain, manages the SDK lifecycle, and
returns a handle:
"ddbsh/aws/database.hpp"auto db = ddbsh::aws::open("us-east-1");if (!db) { std::fputs(db.error().message.c_str(), stderr); return 1; }auto prep = db->prepare("select * from catalog where id = ? and year = ?;");if (!prep) { std::fputs(prep.error().message.c_str(), stderr); return 1; }prep->bind(1, std::string("film")).bind(2, 2010LL);auto rows = db->query(*prep);if (!rows) { std::fputs(rows.error().message.c_str(), stderr); return 1; }for (const ddbsh::Row& row : *rows) { std::optional<std::string> title = row.get_string("title");}prep->bind(1, std::string("book")).bind(2, 2020LL); // re-run, no re-parseauto more = db->query(*prep); // check `more` the same way
prepare() parses once. Parameters are positional ?, 1-based. Named :name
markers are not offered because the grammar’s {key:value} map literal would
make them ambiguous. An unbound parameter is an error. Binds are typed, so you
can bind values the grammar has no literal for, such asddbsh::Value::string_set({...}), number_set, and binary_value.
query() is the single-SELECT shortcut. For batches and writes, exec()
returns a Results you walk the DB-Library way: next_result() steps result
sets, next_row() steps rows, and column() reads a Cell. A Cell tells
apart an absent attribute (missing()), a DynamoDB NULL (is_null()), and a
typed value. render() and render_all() reproduce ddbsh’s exact output.
Offline, at no cost
A Connection accepts any IDDBClient, including the in-memoryddbsh::testing::MemoryClient, which links only ddbsh::ddbsh:
ddbsh::testing::MemoryClient client;ddbsh::Connection db(ddbsh::SessionConfig{"local", ""}, client);db.exec("create table t ( id string ) primary key ( id hash );");db.exec("insert into t ( id, v ) values ( \"a\", 1 );");
It stores whole items keyed by primary key, evaluates the FilterExpressions
the engine emits, and supports opt-in paging and transactions. Consumers link
through find_package(ddbsh); examples/ddbshlib_features_sample/ runs all of
this without an AWS account.