SQL GA

modules/get-started/pages/whats-new-cloud.adoc

@@ -8,6 +8,10 @@ This page lists new features added to Redpanda Cloud.
 
 == May 2026
 
+=== Redpanda SQL
+
+Redpanda SQL is available on BYOC clusters running on AWS. Run real-time SQL queries on Redpanda topic data, including the Iceberg history of Iceberg-enabled topics, using standard PostgreSQL syntax. Connect with `psql` or any PostgreSQL driver. See the xref:sql:get-started/sql-quickstart.adoc[Quickstart] and xref:sql:get-started/overview.adoc[Overview].
+
 === Centralized egress for BYOC on AWS: beta
 
 You can route all BYOC cluster egress through your own AWS Transit Gateway and hub VPC instead of a per-VPC NAT Gateway, so outbound traffic exits through your centralized inspection point. This is useful for regulated environments that prohibit per-VPC NAT Gateways and for consolidating egress behind a single, predictable public IP for outbound allowlisting. Centralized egress is in a glossterm:beta[] release and is enabled per organization. Contact your account team for access. See xref:networking:byoc/aws/nat-free-egress.adoc[Configure Centralized Egress with AWS Transit Gateway].

modules/reference/pages/sql/comment-support.adoc

@@ -0,0 +1,61 @@
+= Comment Support
+:description: Redpanda SQL fully supports comments in your queries.
+:page-topic-type: reference
+
+Redpanda SQL fully supports comments in your queries. Comments provide a way to add explanatory notes and improve the readability of queries, making it easier for developers and stakeholders to understand complex queries.
+
+There are two types of comments in Redpanda SQL: single-line and multi-line (block).
+
+== Single line comments
+
+A single-line comment in Redpanda SQL starts with two consecutive hyphens (--) and extends to the end of the line. Use these comments to annotate specific parts of a query with brief explanations or notes that help readers understand the query.
+
+=== Syntax
+
+[source,sql]
+----
+-- This is an example single line comment
+----
+
+== Multi-line (block) comments
+
+Redpanda SQL also supports multi-line comments, often referred to as block comments. These comments begin with `/*` and end with `*/`, allowing for multi-line explanations or temporarily disabling sections of the query.
+
+=== Syntax
+
+[source,sql]
+----
+/*
+This is an example multi-line comment.
+It can span multiple lines and is useful for providing detailed explanations.
+*/
+----
+
+== Comment placement
+
+In Redpanda SQL, single-line comments should always be placed at the end of the line they refer to, whereas multi-line comments can be positioned anywhere within the query.
+
+=== Comment on a single line
+
+[source,sql]
+----
+SELECT column1, column2 -- This is an example single line comment
+FROM default_redpanda_catalog=>table_name;
+----
+
+=== Comment on multiple lines
+
+[source,sql]
+----
+SELECT /* comment 1 */ column1, column2
+FROM default_redpanda_catalog=>table_name /* comment 2 */
+WHERE column3 = 42 /* comment 3 */ ;
+----
+
+== Best practices for commenting
+
+To maximize the benefits of comments in Redpanda SQL queries, follow these best practices:
+
+* Be concise. Write clear and concise comments that provide meaningful insights into the specific parts of the query.
+* Update comments during code changes. Whenever the query is modified, update the associated comments to reflect the changes accurately.
+* Avoid over-commenting. While comments are helpful, excessive commenting can clutter the code and reduce readability.

modules/reference/pages/sql/index.adoc

@@ -0,0 +1,13 @@
+= SQL Reference
+:description: This section provides information about the syntax and semantics of SQL queries, clauses, data types, and functions that Redpanda SQL supports.
+
+This section provides information about the syntax and semantics of SQL queries, clauses, data types, and functions that Redpanda SQL supports. The information in this section is divided into groups according to the kind of operation they perform as follows:
+
+* xref:reference:sql/sql-statements/index.adoc[SQL Statements]: Learn how to create a request for data or information from one or more database tables using supported statements.
+* xref:reference:sql/sql-clauses/index.adoc[SQL Clauses]: Learn how to write user-friendly queries and analyze data using different constraints and conditions.
+* xref:reference:sql/sql-data-types/index.adoc[SQL Data Types]: Learn how to implement supported data types to run your operations, such as text, timestamp, numeric, and many more.
+* xref:reference:sql/sql-functions/index.adoc[SQL Functions]: See how you can combine statements, data types, and other references into specific functions for particular tasks.
+* xref:reference:sql/information-schema.adoc[Information Schema]: Inspect database object metadata and privilege grants through SQL-standard `information_schema` views.
+* xref:reference:sql/schema.adoc[Schema]: Learn about a logical container that holds database objects and relationships of data in a database.
+* xref:reference:sql/comment-support.adoc[Comment Support]: Add comments in your queries for better documentation and collaboration.
+* xref:reference:sql/transactions.adoc[Transactions]: Learn more about managing your transactions.

modules/reference/pages/sql/information-schema.adoc

@@ -0,0 +1,78 @@
+= Information Schema
+:description: Information schema views in Redpanda SQL expose database object metadata and grants through SQL-standard views.
+:page-topic-type: reference
+
+The `information_schema` namespace provides SQL-standard views over database object metadata. Use these views to inspect catalogs, tables, schemas, columns, and privilege grants without querying the underlying PostgreSQL system catalogs directly.
+
+== Available views
+
+Standard views follow the SQL specification, with semantics consistent with https://www.postgresql.org/docs/current/information-schema.html[PostgreSQL's `information_schema`^]. Redpanda SQL also adds one extension view for per-relation EXTERNAL SOURCE grants.
+
+[cols="<40%,<60%",options="header"]
+|===
+|View |Description
+
+|`information_schema.character_sets`
+|Character sets available in the current database.
+
+|`information_schema.columns`
+|Columns of tables and views visible to the current role.
+
+|`information_schema.key_column_usage`
+|Columns constrained as keys (primary keys, unique constraints, foreign keys).
+
+|`information_schema.referential_constraints`
+|Foreign-key constraints visible to the current role.
+
+|`information_schema.role_external_relation_grants`
+|Per-relation EXTERNAL SOURCE grants. Redpanda SQL extension that captures grants whose stored relation pattern is anything other than `\*` (catalog-level grants surface in `information_schema.role_table_grants` instead).
+
+|`information_schema.role_table_grants`
+|Privileges granted on tables and table-like objects to the current role.
+
+|`information_schema.role_usage_grants`
+|USAGE privileges granted to the current role.
+
+|`information_schema.table_constraints`
+|Table constraints (primary key, unique, foreign key, check) visible to the current role.
+
+|`information_schema.tables`
+|Tables and views visible to the current role.
+|===
+
+== information_schema.role_external_relation_grants
+
+Per-relation EXTERNAL SOURCE grants. Rows whose stored relation pattern is anything other than `\*`. Catalog-level EXTERNAL SOURCE grants (stored pattern `\*`) surface in `information_schema.role_table_grants`, like foreign-table grants in PostgreSQL.
+
+When you `GRANT ... ON EXTERNAL SOURCE catalog_name => 'pattern'`, the pattern is stored verbatim. Redpanda SQL does not normalize or canonicalize it. Patterns are either a fully-qualified relation name like `ns1.ns2.my_table` or a name with a trailing wildcard like `ns1.public_tables*`. See xref:reference:sql/sql-statements/grant.adoc[GRANT] for the full grant syntax and xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] for the access model.
+
+Visibility mirrors `information_schema.role_table_grants`. A regular role sees rows where it is the grantee. A superuser sees grants for every non-superuser.
+
+Use this view to find the exact stored relation pattern when you need to xref:reference:sql/sql-statements/revoke.adoc[revoke] a grant. `REVOKE` requires the pattern argument to match a stored grant exactly. Revoking a pattern that was never granted returns an error, so query this view first to see what's currently registered.
+
+[cols="<30%,<15%,<10%,<45%",options="header"]
+|===
+|Column |Type |Nullable |Description
+
+|`grantor` |`text` |No |Role that granted the privilege.
+|`grantee` |`text` |No |Role that holds the privilege.
+|`database_name` |`text` |No |Database the grant applies to.
+|`schema_name` |`text` |No |Schema the grant applies to.
+|`source_name` |`text` |No |External source (catalog or storage) the grant applies to.
+|`relation_pattern` |`text` |No |Relation-name pattern the grant matches. Wildcards (`\*`) are allowed in the pattern.
+|`privilege_type` |`text` |No |Privilege granted, such as `SELECT`.
+|`is_grantable` |`text` |No |`YES` if the grantee can grant this privilege to other roles; `NO` otherwise.
+|===
+
+[source,sql]
+----
+SELECT grantee, source_name, relation_pattern, privilege_type
+FROM information_schema.role_external_relation_grants
+WHERE grantee = 'analyst';
+----
+
+== Suggested reading
+
+* xref:reference:sql/sql-statements/grant.adoc[GRANT]
+* xref:reference:sql/sql-statements/revoke.adoc[REVOKE]
+* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL]

modules/reference/pages/sql/schema.adoc

@@ -0,0 +1,228 @@
+= Schemas
+:description: Schemas are namespaces that organize tables and other database objects in Redpanda SQL.
+:page-topic-type: reference
+
+A schema is a namespace that groups related database objects, including tables, views, indexes, sequences, data types, operators, and functions. Schemas let you organize objects into logical groups so their names do not collide.
+
+Redpanda SQL supports multiple schemas in a single database. For example, in a database named `mydb`, you might define schemas such as `auth`, `model`, and `business`.
+
+== Default schema
+
+By default, Redpanda SQL uses the `public` schema. When you reference an unqualified table name, it is equivalent to `public.table_name`. The same rule applies to `CREATE`, `DROP`, and `SELECT` statements.
+
+== Syntax
+
+=== Create a schema
+
+[source,sql]
+----
+CREATE SCHEMA [IF NOT EXISTS] schema_name;
+----
+
+* `schema_name`: Name of the schema to create.
+* `IF NOT EXISTS`: Optional. Prevents an error if the schema already exists.
+
+=== Create a table in a schema
+
+[source,sql]
+----
+CREATE TABLE schema_name.table_name(
+...
+);
+----
+
+* `schema_name`: Name of an existing schema.
+* `table_name`: Name of the table to create.
+
+=== Query a table in a schema
+
+[source,sql]
+----
+SELECT * FROM schema_name.table_name;
+----
+
+* `schema_name`: Name of the schema.
+* `table_name`: Name of the table to query.
+
+=== Drop a schema
+
+To drop an empty schema:
+
+[source,sql]
+----
+DROP SCHEMA [IF EXISTS] schema_name;
+----
+
+* `schema_name`: Name of the schema to drop.
+* `IF EXISTS`: Optional. Prevents an error if the schema does not exist.
+
+To drop a schema that contains tables, use `CASCADE` to drop the schema and its contents:
+
+[source,sql]
+----
+DROP SCHEMA schema_name CASCADE;
+----
+
+== Examples
+
+=== Create a schema and table
+
+. Create a schema:
++
+[source,sql]
+----
+CREATE SCHEMA app_data;
+----
+
+. Create a table in the `app_data` schema and insert rows:
++
+[source,sql]
+----
+CREATE TABLE app_data.functions(
+  id int,
+  function_name text,
+  active bool
+);
+
+INSERT INTO app_data.functions(id, function_name, active)
+VALUES
+('1111', 'Numeric', 'TRUE'),
+('2222', 'Text', 'TRUE'),
+('3333', 'Timestamp', 'TRUE'),
+('4444', 'JSON', 'TRUE'),
+('5555', 'Boolean', 'TRUE');
+----
+
+. Verify the table contents:
++
+[source,sql]
+----
+SELECT * FROM app_data.functions;
+----
+
+. The query returns:
++
+[source,sql]
+----
++------+---------------+---------+
+| id   | function_name | active  |
++------+---------------+---------+
+| 1111 | Numeric       | t       |
+| 2222 | Text          | t       |
+| 3333 | Timestamp     | t       |
+| 4444 | JSON          | t       |
+| 5555 | Boolean       | t       |
++------+---------------+---------+
+----
+
+=== Use IF NOT EXISTS
+
+The `IF NOT EXISTS` option lets the `CREATE SCHEMA` query succeed without error when the schema already exists. The schema is not modified.
+
+==== Without IF NOT EXISTS
+
+. Create a schema:
++
+[source,sql]
+----
+CREATE SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+CREATE SCHEMA
+----
+
+. Run the same `CREATE SCHEMA` statement again. The query fails with an error:
++
+[source,sql]
+----
+CREATE SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+ERROR:  Schema: analytics already exists
+----
+
+==== With IF NOT EXISTS
+
+Run the same `CREATE SCHEMA` statement with `IF NOT EXISTS`. The query succeeds without error:
+
+[source,sql]
+----
+CREATE SCHEMA IF NOT EXISTS analytics;
+----
+
+[source,sql]
+----
+CREATE
+----
+
+=== Drop a schema
+
+To drop a schema and all its tables, use `CASCADE`:
+
+[source,sql]
+----
+DROP SCHEMA app_data CASCADE;
+----
+
+If the schema is empty, you can drop it without `CASCADE`:
+
+[source,sql]
+----
+DROP SCHEMA app_data;
+----
+
+=== Use IF EXISTS
+
+The `IF EXISTS` option lets the `DROP SCHEMA` query succeed without error when the schema does not exist.
+
+==== Without IF EXISTS
+
+. Drop a schema:
++
+[source,sql]
+----
+DROP SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+DROP
+----
+
+. Run the same `DROP SCHEMA` statement again. The query fails with an error:
++
+[source,sql]
+----
+DROP SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+ERROR:  schema "analytics" does not exist
+----
+
+==== With IF EXISTS
+
+Run the same `DROP SCHEMA` statement with `IF EXISTS`. The query succeeds without error:
+
+[source,sql]
+----
+DROP SCHEMA IF EXISTS analytics;
+----
+
+[source,sql]
+----
+DROP
+----