Cloud

Enable Redpanda SQL on a BYOC Cluster

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 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

Redpanda SQL is currently available only on BYOC clusters running on AWS.

Prerequisites

To enable Redpanda SQL, you need:

Enable Redpanda SQL

You can enable Redpanda SQL on a new or existing BYOC cluster.

On a new cluster

  • Cloud Console

  • Cloud API

  1. Log in to Redpanda Cloud.

  2. Start creating a new BYOC cluster on AWS. For details and prerequisites, see Create a BYOC Cluster on 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.

  4. Complete the remaining cluster configuration and deploy.

  1. Authenticate to the Cloud API. For details, see Authenticate to the Cloud API.

  2. Make a POST /v1/clusters request with rpsql.enabled set to true in the cluster spec:

    curl -X POST "https://api.redpanda.com/v1/clusters" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster": {
      "name": "<cluster-name>",
      "cloud_provider": "CLOUD_PROVIDER_AWS",
      "type": "TYPE_BYOC",
      "region": "<region>",
      "zones": [ <zones> ],
      "throughput_tier": "<tier>",
      "resource_group_id": "<resource-group-id>",
      "rpsql": {
        "enabled": true
      }
    }
  }'

    For the full request body and field reference, see the Create Cluster API.

  3. The request returns the ID of a long-running operation. Poll the GET /v1/operations/{operation.id} endpoint until the operation completes.

On an existing cluster

  • Cloud Console

  • Cloud API

  1. Log in to Redpanda Cloud 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.

  1. Authenticate to the Cloud API. For details, see Authenticate to the Cloud API.

  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} request, replacing {cluster.id} with your cluster ID:

    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} endpoint until the operation completes:

    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

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

  • Cloud API

  1. Log in to Redpanda Cloud 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.

Make a PATCH /v1/clusters/{cluster.id} request with the new replica count. Replace {cluster.id} with your cluster ID and <n> with the desired replica count. The replicas field is an integer node count with a minimum of 1:

curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rpsql":{"replicas":<n>}}'

The request returns the ID of a long-running operation. Poll GET /v1/operations/{operation.id} until the operation completes.

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+ required):

  1. Log in to Redpanda Cloud with rpk cloud login:

    rpk cloud login

  2. Retrieve a temporary authentication token for the SQL engine:

    rpsql_token=$(rpk cloud auth token)

  3. Connect with psql using the bearer token:

    psql "host=<sql-external-endpoint> port=5432 dbname=oxla user=ignored password=$rpsql_token options='-c auth_method=bearer' sslmode=require"

Inspect your SQL cluster

Redpanda SQL provides built-in commands to inspect the state of your SQL cluster:

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

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

  • Cloud API

  1. Log in to Redpanda Cloud 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.

Make a PATCH /v1/clusters/{cluster.id} request with rpsql.enabled set to false. Replace {cluster.id} with your cluster ID:

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} until the operation completes.

Next steps

  • Quickstart: Connect to Redpanda SQL with psql and run your first query.

  • Authenticate to Redpanda SQL: Connect with an OIDC bearer token, OIDC client credentials, or a SCRAM password for clients that don’t support OIDC.

  • Redpanda SQL reference: Explore the full SQL syntax, data types, functions, and clauses.