ddbsh becomes a library, and you can embed it

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 injected IDDBClient, and output and
    EXPLAIN formatting. Every header under include/ddbsh/*.hpp is free of both
    the terminal and the AWS SDK.
  • ddbsh::aws, optional: AwsDDBClient, an IDDBClient backed by the AWS
    SDK for C++, plus AwsApiGuard for the SDK lifecycle. Headers under
    include/ddbsh/aws/ need the SDK.
  • ddbsh-cli, the ddbsh executable: 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:

#include "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-parse
auto 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 as
ddbsh::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-memory
ddbsh::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.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.