Add SQL-to-Lightweight documentation with test-backed examples#516
Merged
Conversation
Adds docs/sql-to-lightweight.md (issue #368): a SQL -> Lightweight cookbook showing each common SQL operation in all three layers (raw SqlStatement, query builder, DataMapper) so users can choose how to write it. Covers SELECT (WHERE/IN/NULL/ORDER BY/LIMIT/pagination/DISTINCT/aggregates/GROUP BY), JOINs, INSERT (+bulk), UPDATE, DELETE, relationships, CREATE TABLE/migrations, transactions, and custom result shapes. Every C++ example is compiled and executed by src/tests/DocExampleTests.cpp against a real database. The examples and tests are kept in sync by scripts/check-doc-snippets.py, which pairs each `<!-- snippet: id -->` doc block with its `//! [id]` test region and fails on drift (with a unified diff and a `--fix` mode). Wired into the check_docs CI job. Tested: sqlite3 and mssql2022 (Docker) locally, 74 assertions in 11 cases. PostgreSQL covered by the CI matrix (no local ODBC driver available). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
documentation
Explain the problem If/ThenWhere solves (optional filter criteria without manual if-branching), the present/empty semantics of each call, and show a table of how the same builder emits different WHERE clauses as inputs vary. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Remove a stray </content> tag at end of file (unsupported html tag).
- Link to sql-migrations.md via its doxygen page id (#sql-migrations); it
declares an explicit {#sql-migrations} anchor, so a filename ref does not
resolve under WARN_AS_ERROR.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The new DocExampleTests.cpp (mirroring docs/sql-to-lightweight.md) broke two
CI jobs:
* clang-tidy (23 warnings-as-errors): resolved every finding at the source —
added `{}` default member initializers to the doc schema (silences
-Wmissing-designated-field-initializers at the partial-init call sites, and
matches the test suite's own Entities.hpp convention), initialised
DepartmentHeadcount::headcount, used `std::ignore =` on the nodiscard
ExecuteBatch, switched SeededCompany to designated init, and reworked the
unchecked std::optional accesses into guarded forms. The guarded DataMapper
load/update/relationship snippets now also demonstrate proper not-found
handling, which is better documentation.
* C++26 reflection build: the snippet regions must show the stable C++20
member-pointer API (&Employee::salary) that users write and that
check-doc-snippets.py pins byte-for-byte, so they cannot use the
reflection-only Member(...) test macro. Excluded this translation unit from
the experimental LIGHTWEIGHT_CXX26_REFLECTION build; it is still compiled and
executed against every DBMS in all other builds.
Doc snippet blocks updated to stay in sync (scripts/check-doc-snippets.py: OK).
Databases tested: sqlite3, mssql2022 (Docker) — both green (81 assertions,
11 test cases). PostgreSQL not runnable locally (no PG ODBC driver in this
env); emitted SQL is unchanged by these test-only edits and the PostgreSQL
job was already green in CI.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #368.
What
A new documentation page,
docs/sql-to-lightweight.md, that presents how common SQL queries map to the Lightweight API across all three layers — rawSqlStatement, the query builder, and the high-levelDataMapper— so users can pick the style that fits. Sections: SELECT (WHERE / AND-OR / IN / NULL / conditional filters / ORDER BY / LIMIT-TOP / pagination / DISTINCT / COUNT + aggregates / GROUP BY), JOINs (inner / left / multi-condition), INSERT (+ bulk), UPDATE, DELETE, relationships (BelongsTo/HasMany), CREATE TABLE / migrations, transactions, and custom result shapes.Examples are test-backed and kept in sync
Every C++ block in the doc is compiled and executed against a real database by
src/tests/DocExampleTests.cpp(11 test cases, 74 assertions). Each block carries a<!-- snippet: id -->tag whose code is identical to the//! [id]region in the test.scripts/check-doc-snippets.pyenforces that equality and fails CI on any drift (with a unified diff); it also has a--fixmode that regenerates the doc blocks from the tested regions. The check runs in the existingcheck_docsCI job, and the contract is documented inAGENT.md.Workflow to change an example: edit the
//! [id]region in the test, copy the lines into the matching doc block, runpython3 scripts/check-doc-snippets.py.Testing
dbms_test_matrix; no local ODBC driver was available to run it here.clang-formatclean; the new test file is registered insrc/tests/CMakeLists.txtso it runs in the full per-DBMS matrix.Notes
HasManyresolution quirk (the inverseBelongsTois matched by field position, not by type) — filed as HasMany resolves its inverse BelongsTo by field position, not by type/name #515. The doc/test schema keeps the relation members aligned and documents the constraint inline.Risk
Low — additive. New doc page, one new test translation unit (additive to
LightweightTest), one CI step, and registration lines. No library/runtime code changed.🤖 Generated with Claude Code