> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL Workspaces Architecture (Private Preview)

> Understand how SQLWorkspace, SQLCatalog, the SQLWorkspace engine, SQL Studio, and PostgreSQL clients work together.

SQL Workspaces provide a managed architecture for processing streams from StreamNative Pulsar and Kafka clusters with PostgreSQL-compatible SQL.

<Note title="Private Preview">
  SQL Workspaces are available by invitation only. During Private Preview, manage SQLWorkspace and SQLCatalog resources through the StreamNative Cloud Console. You can query a workspace through SQL Studio or its native PostgreSQL endpoint.
</Note>

<CardGroup cols={2}>
  <Card title="Get started" icon="play" href="/sql/get-started/get-started">
    Create a workspace, add a catalog, and run a query.
  </Card>

  <Card title="Understand access control" icon="key" href="/sql/access-control/access-control-overview">
    Learn how cloud resource and SQLWorkspace engine permissions work.
  </Card>

  <Card title="Understand SQLWorkspace" icon="database" href="/sql/overview/sqlworkspace">
    Learn about the engine model, placement, lifecycle, and query endpoints.
  </Card>

  <Card title="Understand SQLCatalog" icon="link" href="/sql/overview/sqlcatalog">
    Learn how Pulsar and Kafka clusters map to databases and topic sources.
  </Card>
</CardGroup>

## Architecture

```text theme={null}
StreamNative Cloud control plane
+----------------------------------------------------------------+
| Cloud Console                                                  |
|   |                                                            |
|   +-- manages --> SQLWorkspace (engine and placement)          |
|   +-- manages --> SQLCatalog(s) (cluster connections)          |
+-------------------------------+--------------------------------+
                                | reconciles
                                v
SQLWorkspace data plane
+----------------------------------------------------------------+
| SQLWorkspace engine                                            |
|   RisingWave -- metadata --> Amazon RDS for PostgreSQL         |
|              +-- state ----> Amazon S3                         |
|                                                                |
| Pulsar/Kafka -- periodic discovery --> SQLCatalog database(s)  |
|                                             |                  |
|                                             +--> topic sources |
|                                                                |
| SQL Studio -------- WebSocket query path ----+                 |
| PostgreSQL clients -- native TLS/pgwire -----+--> engine       |
+----------------------------------------------------------------+
```

## Components

| Component               | Responsibility                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **SQLWorkspace**        | Defines the placement and lifecycle of a managed SQLWorkspace engine and its query endpoints.                                                                                                                                                                                                                                                                                  |
| **SQLWorkspace engine** | Executes SQL and maintains streaming computations. The engine model is pluggable, but [RisingWave](/sql/overview/engine/risingwave) is the only supported engine during Private Preview. On AWS, the engine uses managed [Amazon RDS for PostgreSQL](/sql/overview/engine/metadata-store) for metadata and [Amazon S3](/sql/overview/engine/object-storage) for durable state. |
| **SQLCatalog**          | Connects one supported StreamNative cluster to a workspace and represents it as a database in the SQLWorkspace engine. During Private Preview, SQLCatalog supports only Pulsar and Kafka clusters.                                                                                                                                                                             |

## Control flow

1. A user creates a SQLWorkspace in an eligible hosted location or ready BYOC Cloud Environment through the Cloud Console.
2. StreamNative provisions the selected SQLWorkspace engine and its managed metadata and object storage. During Private Preview, the engine is RisingWave and SQLWorkspace engine infrastructure is supported only on AWS.
3. The user adds a Pulsar or Kafka cluster as a SQLCatalog.
4. StreamNative creates a database for the catalog and periodically discovers eligible topics to create missing source objects.
5. The user creates tables or materialized views based on the managed topic sources for subsequent processing.

## Query flow

1. Pulsar or Kafka delivers new events to the connected topics.
2. The topic sources make those events available to the SQLWorkspace engine.
3. The SQLWorkspace engine evaluates ad hoc queries or continuously maintains materialized views.
4. Users submit SQL and retrieve results through SQL Studio or a PostgreSQL-compatible client.