# Enable Redpanda SQL on a BYOC Cluster > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt) --- title: Enable Redpanda SQL on a BYOC Cluster latest-operator-version: v26.2.1 latest-console-tag: v3.10.0 latest-connect-version: 4.105.0 latest-redpanda-tag: v26.2.1 docname: get-started/deploy-sql-cluster page-component-name: cloud-data-platform page-version: master page-component-version: master page-component-title: Cloud page-relative-src-path: get-started/deploy-sql-cluster.adoc page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/sql/pages/get-started/deploy-sql-cluster.adoc description: Enable the Redpanda SQL engine on a BYOC cluster so you can query streaming data with standard PostgreSQL syntax. page-topic-type: how-to personas: platform_admin, data_engineer learning-objective-1: Enable Redpanda SQL on a new or existing BYOC cluster learning-objective-2: Scale or disable the SQL engine learning-objective-3: Verify that the SQL engine is running and ready to accept connections page-git-created-date: "2026-05-26" page-git-modified-date: "2026-08-03" --- Enable Redpanda SQL on a Bring Your Own Cloud (BYOC) cluster so you can query streaming data in Redpanda topics using standard PostgreSQL syntax. You can also run queries that span both the streaming topic and its Iceberg history for Iceberg-enabled topics. See [Query Iceberg-enabled topics](https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-iceberg-topics/) for that workflow. After reading this page, you will be able to: - Enable Redpanda SQL on a new or existing BYOC cluster - Scale or disable the SQL engine - Verify that the SQL engine is running and ready to accept connections > 📝 **NOTE** > > This page covers enabling Redpanda SQL on BYOC clusters on AWS and GCP. For BYOVPC clusters, see [Enable Redpanda SQL on a BYOVPC Cluster on AWS](https://docs.redpanda.com/cloud-data-platform/sql/get-started/enable-sql-byovpc-aws/) or [Enable Redpanda SQL on a BYOVPC Cluster on GCP](https://docs.redpanda.com/cloud-data-platform/sql/get-started/enable-sql-byovpc-gcp/). > 💡 **TIP** > > If you manage your infrastructure with Terraform, see [Enable Redpanda SQL on a BYOC cluster](https://docs.redpanda.com/cloud-data-platform/manage/terraform-provider/#enable-redpanda-sql-on-a-byoc-cluster) in the Terraform provider guide. ## [](#prerequisites)Prerequisites To enable Redpanda SQL, you need: - A Redpanda Cloud organization on [usage-based billing](https://docs.redpanda.com/cloud-data-platform/billing/billing/). - Admin permissions in your Redpanda Cloud organization. - If using the [Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/topic/topic-cloud-api-overview) to enable SQL, a valid bearer token for the API. See [Authenticate to the Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/authentication). ## [](#enable-redpanda-sql)Enable Redpanda SQL You can enable Redpanda SQL on a new or existing BYOC cluster. You’re billed for the SQL engine while it’s enabled, even when it’s idle. To stop the charges, [disable the engine](#disable-redpanda-sql). For pricing, see [Redpanda SQL billing metrics](https://docs.redpanda.com/cloud-data-platform/billing/billing/#redpanda-sql-billing-metrics). > 📝 **NOTE** > > Redpanda SQL deploys to a single [availability zone](https://docs.redpanda.com/cloud-data-platform/reference/glossary/#availability-zone-az) (AZ), even when the cluster spans multiple AZs. In the `rpsql` block, set `zones` to one of the cluster’s zones. If you omit it, Redpanda uses the cluster’s first zone. The AZ is locked when you first enable Redpanda SQL and cannot be changed afterward. ### [](#on-a-new-cluster)On a new cluster #### Cloud Console 1. Log in to [Redpanda Cloud](https://cloud.redpanda.com). 2. Start creating a new BYOC cluster on AWS or GCP. For details and prerequisites, see [Create a BYOC Cluster on AWS](https://docs.redpanda.com/cloud-data-platform/get-started/cluster-types/byoc/aws/create-byoc-cluster-aws/) or [Create a BYOC Cluster on GCP](https://docs.redpanda.com/cloud-data-platform/get-started/cluster-types/byoc/gcp/create-byoc-cluster-gcp/). 3. In the cluster creation form, locate the **Redpanda SQL engine** card. Toggle the engine on and use the **RPU** slider to set the compute size. For more on RPUs, compute, and cost calculations, see [Redpanda SQL billing metrics](https://docs.redpanda.com/cloud-data-platform/billing/billing/#redpanda-sql-billing-metrics). 4. Complete the remaining cluster configuration and deploy. #### Cloud API 1. [Authenticate to the Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/authentication). 2. Make a [`POST /v1/clusters`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster) request with `rpsql.enabled` set to `true` in the cluster spec: ```bash curl -X POST "https://api.redpanda.com/v1/clusters" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cluster": { "name": "", "cloud_provider": "", "type": "TYPE_BYOC", "region": "", "zones": [ ], "throughput_tier": "", "resource_group_id": "", "rpsql": { "enabled": true, "replicas": , "zones": [""] } } }' ``` Replace the placeholders with your own values: - ``: `CLOUD_PROVIDER_AWS` or `CLOUD_PROVIDER_GCP`. - ``: Set the initial number of SQL compute nodes (minimum 1). - `` (optional): For multi-AZ clusters, specify which of the cluster’s availability zones to deploy for the SQL engine. Provide a single zone string from the cluster’s `zones` list. 3. The request returns the ID of a long-running operation. Poll the [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) endpoint until the operation completes. ### [](#on-an-existing-cluster)On an existing cluster > 📝 **NOTE** > > If your BYOC cluster on AWS was created before May 28, 2026, rerun `rpk cloud byoc aws apply --redpanda-id=` to update the agent’s IAM permissions before enabling Redpanda SQL. > > If your BYOC cluster on GCP was created before August 4, 2026, rerun `rpk cloud byoc gcp apply --redpanda-id= --project-id=` to update the agent’s permissions and service accounts before enabling Redpanda SQL. #### Cloud Console 1. Log in to [Redpanda Cloud](https://cloud.redpanda.com) and open your cluster. 2. From the left navigation, select **Dataplane settings**. 3. On the **Cluster** tab, find the **RP SQL** row and click **Edit**. 4. In the **Enable Redpanda SQL engine** dialog, use the **RPU** slider to set the compute size, then click **Enable Redpanda SQL engine**. #### Cloud API 1. [Authenticate to the Cloud API](https://docs.redpanda.com/api/doc/cloud-controlplane/authentication). 2. Locate the cluster ID in the **Details** section of the cluster overview in the Cloud Console. 3. Make a [`PATCH /v1/clusters/{cluster.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) request, replacing `{cluster.id}` with your cluster ID: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}?update_mask=rpsql.enabled,rpsql.replicas,rpsql.zones" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"rpsql":{"enabled":true,"replicas":,"zones":[""]}}' ``` Replace the `rpsql` placeholders with your own values: - ``: Set the initial number of SQL compute nodes (minimum 1). - `` (optional): For multi-AZ clusters, specify which of the cluster’s availability zones to deploy for the SQL engine. Provide a single zone string from the cluster’s `zones` list. > 📝 **NOTE** > > The `update_mask` query parameter must list every `rpsql` field in the request body. If you omit the optional `zones` field, also remove `rpsql.zones` from `update_mask`. 4. The request returns the ID of a long-running operation. Poll the [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) endpoint until the operation completes: ```bash curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" ``` When the operation is complete, the response shows `"state": "STATE_COMPLETED"`. ## [](#scale-redpanda-sql)Scale Redpanda SQL Redpanda SQL scales horizontally by RPU. Adjust the compute size as your workload grows. To remove Redpanda SQL from a cluster, disable the SQL engine instead. ### Cloud Console 1. Log in to [Redpanda Cloud](https://cloud.redpanda.com) and open your cluster. 2. From the left navigation, select **Dataplane settings**. 3. On the **Cluster** tab, find the **RP SQL** row and click **Edit**. 4. In the **Edit Redpanda SQL engine** dialog, drag the **RPU** slider to the desired compute size, then click **Save changes**. ### Cloud API 1. Make a [`PATCH /v1/clusters/{cluster.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) request, replacing `{cluster.id}` with your cluster ID: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}?update_mask=rpsql.replicas" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"rpsql":{"replicas":}}' ``` Replace `` with the desired number of SQL compute nodes (minimum 1). 2. The request returns the ID of a long-running operation. Poll [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) until the operation completes: ```bash curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" ``` When the operation is complete, the response shows `"state": "STATE_COMPLETED"`. ## [](#verify-the-sql-engine-is-running)Verify the SQL engine is running After you enable Redpanda SQL, a **Redpanda SQL** tile appears in the cluster overview under **Products**. The tile shows the engine status, active sessions, queries per minute, and node count. When the **Nodes** indicator shows all nodes as ready (for example, **1/1**), the engine is provisioned and accepting connections. Provisioning can take up to 30 minutes. For the API flow, poll the long-running operation until it returns `STATE_COMPLETED`. To verify the SQL engine is running, use the connection details on the **SQL** tab under **Connection details** to connect with a PostgreSQL client, such as `psql` (v16 or later required). You can also query data directly using the [SQL editor](https://docs.redpanda.com/cloud-data-platform/sql/query-data/sql-editor/) in the left navigation. To connect using a bearer token ([`rpk` v26.1.6+](https://docs.redpanda.com/cloud-data-platform/manage/rpk/rpk-install/) required): 1. Log in to Redpanda Cloud with `rpk cloud login`: ```bash rpk cloud login ``` 2. Retrieve a temporary authentication token for the SQL engine using [`rpk cloud auth token`](https://docs.redpanda.com/cloud-data-platform/reference/rpk/rpk-cloud/rpk-cloud-auth-token/): ```bash rpsql_token=$(rpk cloud auth token) ``` 3. Connect with `psql` using the bearer token: ```bash psql "host= port=5432 dbname=oxla user=ignored password=$rpsql_token options='auth_method=bearer' sslmode=require" ``` ## [](#inspect-your-sql-cluster)Inspect your SQL cluster Redpanda SQL provides built-in commands to inspect the state of your SQL cluster: ```sql SHOW NODES; -- List SQL compute nodes and their status SHOW REDPANDA CATALOGS; -- List Redpanda catalogs SHOW ICEBERG CATALOGS; -- List Iceberg catalogs SHOW REDPANDA TABLES; -- List SQL tables mapped to Redpanda topics SHOW QUERIES; -- List currently running queries ``` ## [](#disable-redpanda-sql)Disable Redpanda SQL > ⚠️ **WARNING** > > Disabling Redpanda SQL tears down the SQL compute engine and clears its catalog state (catalog metadata, table mappings, and role/grant data). In-flight queries fail when SQL is disabled. Redpanda topic data, Schema Registry subjects, and any Iceberg-committed history for Iceberg-enabled topics are not affected. The Redpanda cluster itself continues to run normally; only the SQL engine and its associated state are removed. Re-enabling SQL on the same cluster provisions a fresh engine: no prior catalog state, table mappings, or grants are restored. You must re-create catalogs, tables, and grants after re-enabling. ### Cloud Console 1. Log in to [Redpanda Cloud](https://cloud.redpanda.com) and open your cluster. 2. From the left navigation, select **Dataplane settings**. 3. On the **Cluster** tab, find the **RP SQL** row and click **Edit**. 4. In the **Edit Redpanda SQL engine** dialog, click **Disable**. ### Cloud API Make a [`PATCH /v1/clusters/{cluster.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) request with `rpsql.enabled` set to `false`. Replace `{cluster.id}` with your cluster ID: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}?update_mask=rpsql.enabled" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"rpsql":{"enabled":false}}' ``` The request returns the ID of a long-running operation. Poll [`GET /v1/operations/{operation.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) until the operation completes. ## [](#next-steps)Next steps - [Quickstart](https://docs.redpanda.com/cloud-data-platform/sql/get-started/sql-quickstart/): Connect to Redpanda SQL with `psql` and run your first query. - [SQL editor](https://docs.redpanda.com/cloud-data-platform/sql/query-data/sql-editor/): Write and run queries directly in the Cloud Console without a separate SQL client. - [Authenticate to Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/connect-to-sql/authenticate/): Connect with an OIDC bearer token, OIDC client credentials, or a SCRAM password for clients that don’t support OIDC. - [Redpanda SQL reference](https://docs.redpanda.com/cloud-data-platform/reference/sql/): Explore the full SQL syntax, data types, functions, and clauses.