SQL GA - Get started#571
Conversation
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
andrewhsu
left a comment
andrewhsu
left a comment
There was a problem hiding this comment.
CREATE TABLE command needs to change to match web ui
kbatuigas
force-pushed
the
DOC-1856-document-feature-sql-engine-deployment-in-cloud
branch
from
ae3ae40 to
2dd0c5a
Compare
kbatuigas
force-pushed
the
DOC-1856-document-feature-sql-engine-deployment-in-cloud
branch
from
2dd0c5a to
fb15751
Compare
|
|
||
| To enable, scale, or disable SQL on an existing cluster, you also need the cluster ID, which you can find in the *Details* section of the cluster overview in the Cloud Console. | ||
|
|
||
| // TODO: Confirm UI functionality |
There was a problem hiding this comment.
@c-julin should have knowledge about this matter
| -H "Content-Type: application/json" | ||
| ---- | ||
| + | ||
| When the operation is complete, the response shows `"state": "STATE_COMPLETED"`. |
There was a problem hiding this comment.
We need to talk a bit more about it, I'll send you a link to slack thread.
There was a problem hiding this comment.
Added some guidance here https://github.com/redpanda-data/cloud-docs/pull/571/changes#diff-53e047807d28a0255b66ea613665a131405259a0926d855ba2b3ab3dd13fbe5bR129 but this is based on current state afaik, we can update later if the UX is changed
There was a problem hiding this comment.
you should sync with @c-julin on this one :)
|
|
||
| Redpanda SQL supports horizontal scaling from 1 to 9 nodes per cluster. Scaling to 0 is not supported. To remove Redpanda SQL from a cluster, disable the SQL engine instead. | ||
|
|
||
| // TODO: Confirm UI functionality |
|
|
||
| == Verify the SQL engine is running | ||
|
|
||
| After you enable Redpanda SQL, the cluster overview page in the Cloud console shows the *SQL* tab. The *Details* pane also displays the number of SQL nodes deployed with the cluster. Provisioning may take several minutes. |
There was a problem hiding this comment.
30mins is a safe boundary here imho
|
|
||
| [,sql] | ||
| ---- | ||
| SHOW NODES; -- List SQL compute nodes and their status |
There was a problem hiding this comment.
I'll think adding some queries related to CATALOG objectst may be a good idea, someone from Oxla core should be able to provide insights on this matter.
| * https://www.postgresql.org/download/[`psql`^] (PostgreSQL client) installed on your local machine. | ||
|
|
||
| // TODO: Verify the exact connection string format and where users get credentials. | ||
| // From PRD: SCRAM auth preserved, connection string available in Cloud Console and API response. |
There was a problem hiding this comment.
This is 'the legacy auth method' that Oxla is preserving for tools like PowerBI etc. @grzebiel / @paulzhang97 can provide more insights.
There was a problem hiding this comment.
We've discussed it f2f. Should be clear now.
TLDR: connection string is availble in console. rpk version supporting rpk claud auth token required
There was a problem hiding this comment.
Connection string available in Console, mentioned in this step https://github.com/redpanda-data/cloud-docs/pull/571/changes#diff-0aaa7195ceaa99e1ae1dfb70388ac642bf4af38bba78aa1f6d43c1d1a9342e44R115
legacy connections discussed in further detail https://github.com/redpanda-data/cloud-docs/pull/580/changes#diff-464751f0d8b4943851c484fba03b6b5a9325c429f993852df10f91f31e7eb24bR119 please also have a look @grzebiel
|
|
||
| Redpanda SQL is deny-all by default. All queries to Redpanda SQL run under a single super-user SASL credential associated with `default_redpanda_catalog`, but the engine enforces per-user table access through Redpanda SQL `GRANT` statements. To let a non-admin user query a table, the admin creates a role and grants access: | ||
|
|
||
| // TODO: Confirm the exact GRANT mechanism with engineering. Open questions: |
There was a problem hiding this comment.
discussed on f2f meeting.
TLDR: two permissions available in the RBAC: dataplane->sql->{access, manage}.
manage -> sql superuser able to read and grand accessess to all the topics/tables
access -> regular user. No access to any catalog unless granted by superuser.
Standard sql grant system to manage access to catalogs
There was a problem hiding this comment.
Access mechanism explained in separate PR https://github.com/redpanda-data/cloud-docs/pull/580/changes
kbatuigas
force-pushed
the
DOC-1856-document-feature-sql-engine-deployment-in-cloud
branch
from
2731f43 to
a0b51f4
Compare
|
Hey Kat, just FYI we now have a settings page UI for enabling/scaling/disabling oxla on an existing cluster so we could upadrte this page with screenshots instead of getting the user to run curl api requests. The UI is still changing but it is there |
|
|
||
| If you don't have a topic with a corresponding schema in Schema Registry yet, follow these steps to create an `orders` topic with a small set of sample records. | ||
|
|
||
| You also need permissions to create topics, register schemas, and produce records. |
There was a problem hiding this comment.
Isn't this a prereq then?
There was a problem hiding this comment.
It's really only a prereq for this optional section, so it doesn't belong in the top level Prerequisites
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
PR Review: SQL GA - Get started (#571) — re-review
Files reviewed: 3 new .adoc files (455 additions; net +9 in sql-quickstart.adoc, net −9 in deploy-sql-cluster.adoc since my earlier review)
Overall assessment: Same overall picture as my earlier review on 2026-05-21. Three new commits today refine the content (Protobuf → JSON sample, UI flow simplification, schema_subject optional). Critical xref issues to sibling PRs are unchanged; What's New entry still missing.
What's changed since my earlier review
| Commit | Date | Change |
|---|---|---|
caa0b78c |
2026-05-21 23:16 | "Use JSON in quickstart" — sample data switched from Protobuf to JSON Schema. Topic + schema creation flow now uses the Cloud UI's Produce record form (JSON values), not rpk produce. (42+/32-) |
9cf94e47 |
2026-05-22 18:00 | "Add SQL deployment UI changes" — simplified the On a new cluster flow in deploy-sql-cluster.adoc (7+/16-, net −9 lines). UI step reductions, presumably to match the current Cloud Console layout. |
eef885d8 |
2026-05-22 18:57 | "schema subject is optional" — clarifies that schema_subject defaults to topic-name strategy. (1+/2-) |
mergeStateStatus is now CLEAN (was BLOCKED yesterday). Only blocker is the stale CHANGES_REQUESTED from @mattschumpert and @andrewhsu.
Jira ticket alignment
Ticket: DOC-1856 — "Document feature SQL engine deployment in Cloud."
Status: Unchanged from my earlier review. ✅ Satisfies the ticket. The new commits don't alter ticket alignment — they're editorial refinements within the same scope.
Critical issues (must fix)
-
Two broken xrefs (carried over from my earlier review — still unresolved):
File:line xref target Provided by deploy-sql-cluster.adoc:9andsql-quickstart.adoc:8sql:query-data/query-iceberg-topics.adocPR #575 (still OPEN) sql-quickstart.adoc:198sql:manage/manage-access.adocPR #580 (still OPEN) The Next Steps
query-streaming-topics.adocandquery-iceberg-topics.adocxrefs are now commented out atsql-quickstart.adoc:204–206— those have moved out of immediate scope. Only the two inline references in the page intros / Grant section above are still active and unresolved onrp-sql. -
Missing What's New entry — still missing. No SQL GA entry in
modules/get-started/pages/whats-new-cloud.adoc. Same recommendation as before: a single coordinated "Redpanda SQL: General availability" entry should cover the get-started + query + auth pages together (PRs #571 / #574 / #575 / #580 / #584).
Suggestions (should consider)
-
Three open inline comments from @Feediver1 are real editorial issues worth resolving. Quick summary so they aren't lost in the thread:
-
sql-quickstart.adoc:33"Isn't this a prereq then?" — line 33 reads "You also need permissions to create topics, register schemas, and produce records." That's a permission requirement, which is a prerequisite for running the optional sample-data section. Either move it into the section's intro as "Section prerequisites:" or fold it into the main Prerequisites list with a "(if you don't have a pre-existing topic)" qualifier. Right now it floats between the intro and the step list. -
sql-quickstart.adoc:86"Orders?" — the JSON Schema"title": "Order"(singular) describes one record of theorders(plural) topic. JSON Schema convention is singular-noun-for-record-type, so it's technically correct. But for readers scanning quickly, the singular/plural shift between schema title and topic name can confuse. Easiest fix: change"title": "Order"→"title": "Orders"(slight schema-naming compromise, but matches the topic name and avoids the cognitive bump). Either is defensible — author's call. -
sql-quickstart.adoc:126suggestion"On a successful connection" → "Upon a successful connection"— minor wording preference. "Upon" is slightly more formal/precise; "On" is also valid.
-
-
Remaining
// TODO: Verify current psql banner text.atsql-quickstart.adoc:128. Carried from my earlier review. Still an open content-verification item; not a blocker, but worth resolving before publish. -
PR body still has the unfilled
<add-your-issue-number-here>placeholder. Trivial fix.
Impact on other files
modules/ROOT/nav.adoc✓ — both new pages already in nav (lines 343–345).modules/get-started/pages/whats-new-cloud.adoc❌ — still no SQL GA entry (Critical #2 above).- Cross-references: Same as my earlier review. All non-sibling xrefs verified valid.
- Sibling PR dependencies:
- #574 (DOC-1990, streaming-topic query) — review posted; still open.
- #575 (DOC-2006, Iceberg query) — review posted; still open. Required for the
query-iceberg-topics.adocxref. - #580 (DOC-1999, OIDC + access) — review posted; still open. Required for the
manage-access.adocxref. - #584 (DOC-2000, OOM troubleshooting) — review posted; still open.
CodeRabbit findings worth considering
None. CodeRabbit's check passed with no actionable findings on the current state.
Outstanding review activity — status
- @mattschumpert CHANGES_REQUESTED (2026-05-21, about Iceberg data deletion wording on disable). My earlier review verified that concern is addressed at
deploy-sql-cluster.adoc:211–216("Redpanda topic data, Schema Registry subjects, and any Iceberg-committed history… are not affected"). TheCHANGES_REQUESTEDis stale. - @andrewhsu CHANGES_REQUESTED (2026-05-08, about the
CREATE TABLEsyntax). My earlier review verified the syntax is now correct. Andrew's also stale. - @jacekseligarp APPROVED (2026-05-21) on the Cloud-API side.
Net: Two stale CHANGES_REQUESTED + one APPROVED. The PR is content-complete; needs @mattschumpert and @andrewhsu to dismiss/refresh.
What works well
- The JSON-schema switch is a real improvement. Protobuf sample data required a Schema-Registry-aware producer client; the JSON Schema + UI Produce record flow lets readers complete the quickstart entirely from the Cloud Console with no client setup. That makes the quickstart genuinely usable.
- The
schema_subjectoptional clarification is correct and reduces friction — most users won't realize the topic-name strategy is the default. - Deploy-page UI simplification matches what the current Cloud Console actually does.
- Mature review-response pattern. Three follow-up commits since my earlier review, each focused and well-named.
- Frontmatter, heading case, and code-block conventions all hold up (verified earlier; new commits didn't regress).
mergeStateStatusis now CLEAN — the only block left is the staleCHANGES_REQUESTEDstate from Matt and Andrew.- CI fully green.
Re-review via /docs-team-standards:pr-review.
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Approving with the understanding that PR 597 adds What's New, and you get @mattschumpert and @andrwng to circle back and remove block/approve.
Updates the Enable Redpanda SQL page so the horizontal-scaling range is 1 to 9 nodes (down from 1 to 12) per the PM SME 2026-05-07. Adds a TODO on the Disable Redpanda SQL section listing the specific behaviors to confirm with engineering before publication: what state is purged, what is deleted from object storage, the effect on topic and Schema Registry data, in-flight query error behavior, and re-enable semantics. Updates the quickstart so it explicitly targets an admin who can view the SQL connection details in the Cloud Console, and adds an optional admin-run mini-section showing how to grant a non-admin user SELECT access on a Redpanda SQL table. Includes a TODO referencing qa-questions.md #21 to refine the role/grant example once engineering confirms whether the SQL GRANT statement alone enforces per-user table access or whether an additional ACL/Kafka-side step is required. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Andrew Hsu <xuzuan@gmail.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
kbatuigas
force-pushed
the
DOC-1856-document-feature-sql-engine-deployment-in-cloud
branch
from
3afb807 to
b3f2d91
Compare
kbatuigas
deleted the
DOC-1856-document-feature-sql-engine-deployment-in-cloud
branch
7 participants
Description
This pull request adds comprehensive "Get Started" documentation for Redpanda SQL, including new guides for enabling, connecting to, and using Redpanda SQL on BYOC clusters. The changes introduce a new navigation structure and detailed step-by-step instructions for both the Cloud Console and API workflows, as well as a hands-on quickstart for querying streaming data.
New Redpanda SQL onboarding documentation:
index.adoc), a quickstart guide for connecting and querying withpsql(sql-quickstart.adoc), and a detailed guide for enabling, scaling, and disabling Redpanda SQL on BYOC clusters (deploy-sql-cluster.adoc). [1] [2] [3]Navigation and structure updates:
nav.adocto include links to the new "Get Started," "Quickstart," and "Enable Redpanda SQL" guides under the Redpanda SQL section, improving discoverability and organization of onboarding content.Resolves https://github.com/redpanda-data/documentation-private/issues/
Review deadline: 19 May
Page previews
Checks