Skip to content

Docs: captured SQL beside the queries on the remaining pages (pagination, soft-deletes, timestamps, transactions, connections, quickstart, RLS, upgrading) #778

Open

Description

@0x054

Problem

The docs rewrite (#698) shows the SQL Ferro sends beside each query on the Queries, Aggregations, Relationships and Mutations guides, regenerated by tests/test_docs_sql.py from each example's own .sql() (#725). The epic asked for it beside every query and every schema feature; the review panel on PR #777 (Spec, story 33) found the other pages that run queries show none, and two show SQL typed by hand. The maintainer accepted the four-page scope as a narrowing for the merge, with this issue as the path for the rest.

What to build

Extend the marker-and-regenerate mechanism to every remaining page that runs a query or shows schema SQL:

  • docs/pages/howto/pagination.md (after() / before() keyset paging), howto/soft-deletes.md, howto/timestamps.md, guide/transactions.md, guide/connections.md, getting-started/quickstart.md: add marked sql blocks beside the queries, with SQLite/PostgreSQL tabs where more than placeholders differ.
  • docs/pages/guide/row-level-security.md:39 (ENABLE / FORCE / CREATE POLICY) and the upgrading.md blocks: replace hand-typed SQL with regenerated blocks (through .sql(), the statement log, or the migration step-file pin, whichever produces them).
  • Add each page to PAGES in tests/test_docs_sql.py (or, once the panel's F22 follow-up lands, to the helper module), so an unmarked sql fence on any of them is refused.

Follow the recipe in docs/solutions/patterns/docs-page-conventions.md ("Generated SQL beside each query"). #767 (the Inspecting SQL guide page) uses the same mechanism and should land first or alongside.

Related

Activity

  1. added
    documentationImprovements or additions to documentation
    needs-triageNeeds evaluation by a maintainer
    on Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationneeds-triageNeeds evaluation by a maintainer

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions