ADFA-5123: Document docdb SQL-authoring gotchas from ADFA-5088

[davidschachterADFA]

Summary

Adds two things learned writing SQL migration scripts against documentation.db during ADFA-5088:

• Provenance warning ("Where it lives"): a local copy's on-disk schema/content isn't ground truth just because it exists — it's independent of git history and can be stale. A stale local copy caused a real near-miss in ADFA-5088: a SQL script validated against it would have silently overwritten curated production tooltip content for several tags.
• A "Writing one-off SQL scripts against this database" subsection (under "Editing the database"): the sqlite3 CLI's .system dot-command can hit a content-dependent shell-parsing failure when a line chains multiple operators — keep each line to one plain command | pipe > file. And .bail on is required for BEGIN/COMMIT to actually be atomic (verified empirically: without it, a mid-script error still lets COMMIT through with whatever succeeded before it), plus a guard-table pattern for catching a failed/empty Brotli payload before it reaches the real table.

Test plan

• Doc-only change, spotlessCheck passes
• Referenced pattern (docs/docdb/ADFA-5088-preference-tooltips.sql) is the actual working script from ADFA-5088, validated end-to-end against a real documentation.db

🤖 Generated with Claude Code

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ab5baff1-b5f8-461c-a3c6-1fd051881ef9

📥 Commits

Reviewing files that changed from the base of the PR and between c1c8c16 and a2cc1c0.

📒 Files selected for processing (1)

• docs/documentation-database.md

---

📝 Walkthrough

• Added guidance to verify that a local documentation.db copy is current before using its schema or contents.
• Documented .system shell-parsing issues when chaining multiple operators.
• Documented .bail on and payload validation requirements for atomic SQL migration scripts.
• Added a secure owner-only temporary-directory pattern for Brotli files.
• Risk: Stale database copies can produce incorrect migration scripts.
• Risk: Insecure predictable filenames under /tmp can expose temporary files. The documented pattern avoids this risk.

Walkthrough

The documentation now explains how to verify documentation.db freshness and how to write safer one-off SQL scripts, including payload validation and secure temporary directories for Brotli files.

Changes

Documentation database guidance

Layer / File(s)	Summary
Database freshness guidance docs/documentation-database.md	The guide warns that stale or manually downloaded database copies can differ in schema and data.
One-off SQL script precautions docs/documentation-database.md	The guide documents simple .system commands, .bail on, payload validation, and owner-only temporary directories for Brotli files.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Mergeability Score: 🔵 Low · up to a2cc1

The documentation references a SQL script that is not included, so readers cannot verify the documented cleanup and directory-creation safeguards. The change remains localized and mergeable with explicit owner follow-up to add the script or correct the reference.

Possibly related PRs

• appdevforall/CodeOnTheGo#1661: Both PRs update docs/documentation-database.md; this PR adds freshness and one-off SQL safety guidance.

Poem

A rabbit checks the database with care,
Fresh schema and data are waiting there.
.bail on keeps errors in sight,
Safe Brotli files stay locked up tight.
Clean scripts hop safely through the night.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation change and its connection to the ADFA-5088 SQL-authoring lessons.
Description check	✅ Passed	The description directly explains the documentation updates, SQL-authoring guidance, security pattern, and validation performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch task/ADFA-5123-docdb-sql-gotchas

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}