docs: regenerate v2 API docs for the new SQL write endpoint#127
Merged
Conversation
Pulls v2.yaml from ld's taylor/api-v2-sql-write branch, which turns
POST /api/v2/databases/{owner}/{database}/sql into a dual-purpose
endpoint: a SqlReadRequest body behaves as before, a SqlWriteRequest
body ({from_branch, to_branch, query}) kicks off an async write.
The generator didn't support oneOf request-body schemas — it silently
dropped the request-body table and example payload for any endpoint
shaped that way. Fixed generate-api-v2.mjs to render one table/example
per oneOf variant, labeled by schema title, and regenerated
database.md and models.md. Also fixed a stale hand-written link in
README.md's index (old operationId/title for this endpoint).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Merged origin/main into ld's taylor/api-v2-sql-write locally to pick up its "drop stale plan-phase reference" cleanup. No schema or endpoint changes — just four description strings in models.md losing their internal (§5.x) plan-doc references. Note: that merge on the ld side has an unresolved conflict in sql.ts (application code, not the spec) — left for manual resolution there, not touched from this repo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The endpoint-mapping table was missing the async write flow entirely
(POST .../write/{from_branch}/{to_branch} and its GET .../write poll
endpoint), left out before v2 had a write-capable SQL endpoint. Map
them to the new dual-purpose POST .../sql (runSqlPost) and the
standard operations-polling pattern used elsewhere in this table.
The v2 index (README.md) already covers this endpoint correctly from
an earlier commit — no change needed there.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
ld's api-v2-sql-write branch merged to main (#23820) and was then redesigned in a follow-up (#23932, "split POST /sql into read-only + new /sql-writes"): the dual-purpose oneOf body on POST /sql is gone. POST /sql is read-only again (runSqlReadQueryPost); the async write moved to its own POST /sql-writes (runSqlWriteQuery). Pulled the latest v2.yaml from ld-clone's main and regenerated. Updated README.md's index and migration.md's endpoint-mapping table to point at the new operation. Also fixes a generator bug: the sub-resource grouping in database.md didn't know about the new "sql-writes" path segment, so it fell back to a raw "## sql-writes" heading instead of folding into the existing "## SQL" section. The spec itself also picked up its own cleanup upstream — the stale "phase-4" internal-jargon wording I flagged earlier is gone, replaced with concrete endpoint references. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The redesign in api-v2-sql-split replaced the one endpoint that needed this (dual-purpose POST /sql) with two separate single-schema endpoints. The only oneOf left in the spec is nested inside a property (CreateBranchRequest.from), which this code never handled anyway. Reverting to the simpler single-schema requestBodySection/curlExample — confirmed the regenerated output is byte-identical to before this revert. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Pulled the latest v2.yaml from ld-clone's main (#23937, api-v2-sql-read-body-query). SqlWriteRequest's SQL-statement field is now `q`, matching SqlReadRequest, instead of `query`. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Tables with long unbroken <code> cells (e.g. the v2 migration guide's endpoint-mapping table) overflowed the content column with no way to see the clipped text — table had no horizontal scroll affordance, unlike <pre> blocks which already use overflow-x-auto. Add a rehype plugin that wraps every rendered <table> in a .table-scroll div, and give that wrapper overflow-x-auto (moved the mb-4 spacing there too, off the table itself). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… paths Swap the scroll-wrapper approach for wrapping: drop the rehype table-wrap plugin and instead let cell content break (overflow-wrap: anywhere) with table-layout: fixed so columns share the container width predictably. Also drop the redundant /api/v2 prefix from the v2 column of the migration guide's endpoint-mapping table, matching the v1alpha1 column's style (which never had /api/v1alpha1 in it) — shorter, more symmetric, and less prone to overflow in the first place. Co-Authored-By: Claude Sonnet 5 <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
1 participant
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.
Summary
v2.yamlfromld'staylor/api-v2-sql-writebranch:POST /api/v2/databases/{owner}/{database}/sqlis now dual-purpose — aSqlReadRequestbody behaves as before, aSqlWriteRequestbody ({from_branch, to_branch, query}) kicks off an async write and returns202+OperationRef.generate-api-v2.mjs: it only handled a single flat request-body schema, so aoneOfrequest body silently produced no request-body table and no example payload. Now renders one table + one example peroneOfvariant, labeled by schema title.README.md's endpoint index (old title/operationIdfor this endpoint).database.mdandmodels.md(two new schemas:SqlReadRequest,SqlWriteRequest).Test plan
npm run generate-api-v2 --workspace site/doltruns cleannpm run build:doltandnpm run compileboth pass#runSqlPost) and bothSqlReadRequest/SqlWriteRequesttables and examples🤖 Generated with Claude Code