# 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.1.4 latest-console-tag: v3.7.3 latest-connect-version: 4.93.0 latest-redpanda-tag: v26.1.9 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-05-26" --- Enable Redpanda SQL on a Bring Your Own Cloud (BYOC) cluster so you can query streaming data in Redpanda topics using standard PostgreSQL syntax. For Iceberg-enabled topics, queries can span both the streaming topic and its Iceberg history. 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** > > Redpanda SQL is currently available only on BYOC clusters running on AWS. ## [](#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. ### [](#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. 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/). 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/topic/topic-cloud-api-overview). For details, see [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": "CLOUD_PROVIDER_AWS", "type": "TYPE_BYOC", "region": "", "zones": [ ], "throughput_tier": "", "resource_group_id": "", "rpsql": { "enabled": true } } }' ``` For the full request body and field reference, see the [Create Cluster API](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster). 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 #### 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/topic/topic-cloud-api-overview). For details, see [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}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"rpsql":{"enabled":true}}' ``` 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 Make a [`PATCH /v1/clusters/{cluster.id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) request with the new replica count. Replace `{cluster.id}` with your cluster ID and `` with the desired replica count. The `replicas` field is an integer node count with a minimum of 1: ```bash curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"rpsql":{"replicas":}}' ``` 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. ## [](#verify-the-sql-engine-is-running)Verify the SQL engine is running After you enable Redpanda SQL, the cluster overview page in the Cloud Console shows the **SQL** tab and the **Details** pane displays the number of SQL nodes deployed with the cluster. The **SQL** tab appears as soon as you enable SQL, but you can’t connect until the engine is fully provisioned. Provisioning can take up to 30 minutes. Wait for the node-ready status indicator on the overview page to show the engine is ready. 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 to connect with a PostgreSQL client, such as `psql` (v16 or later required). 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: ```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='-c 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}" \ -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. - [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.