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

# SQL Studio with Hybrid Runner | SQL Studio Guide

> Learn how SQL Studio works with the Hybrid Ingestion Runner to execute queries securely within your own cloud infrastructure, keeping credentials and data in your environment.

# SQL Studio with Hybrid Runner

SQL Studio integrates with Collate's **[Hybrid Ingestion Runner](/ai-2-0/getting-started/lets-get-started/ingest-your-data/hybrid-ingestion-runner)**, ensuring that query execution happens within your own cloud infrastructure. This means credentials never leave your environment and query traffic stays inside your network — the same security model used for metadata ingestion.

## How It Works

When you create a database service in Collate, you select an **Ingestion Runner**: either the **Collate SaaS Runner** (hosted by Collate) or a **Hybrid Runner** (deployed in your infrastructure). SQL Studio's Query Runner inherits whichever runner is configured for the service. There is no separate runner selection for SQL Studio.

### Runner Inheritance

The runner selected at service creation time is inherited by SQL Studio — no separate selection is needed.

```
Service Creation
     │
     ├── Ingestion Runner: Collate SaaS Runner
     │       └── Query Runner uses: Collate SaaS Runner
     │
     └── Ingestion Runner: Hybrid Runner
             └── Query Runner uses: Hybrid Runner
```

When a user triggers a **test connection** or **executes a query** in SQL Studio, the backend's pipeline client routes the request to the same runner that handles the service's ingestion workflows. This is identical to how metadata ingestion, profiling, and lineage workflows are dispatched.

### Execution Flow

The following diagram illustrates how a query flows through the system when a Hybrid Runner is configured:

```
┌──────────────────────────────────────────────────────────────────┐
│                     COLLATE SaaS (Cloud)                         │
│                                                                  │
│  1. User writes & runs query in SQL Studio                       │
│  2. Backend receives request                                     │
│  3. Pipeline client identifies runner for the service            │
│  4. Request is dispatched to the Hybrid Runner                   │
│                                                                  │
└──────────────────────────┬───────────────────────────────────────┘
                           │  Secure channel
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│               YOUR INFRASTRUCTURE (Hybrid Runner)                │
│                                                                  │
│  5. Hybrid Runner receives the execution request                 │
│  6. Credentials are fetched from your Secrets Manager            │
│     (AWS / Azure / GCP / Kubernetes, etc.)                       │
│  7. Runner connects to the database and executes the query       │
│  8. Results are returned to the Collate SaaS backend             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│                     COLLATE SaaS (Cloud)                         │
│                                                                  │
│  9. Backend returns results to the user's browser                │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

### Key Points

Keep the following in mind when using SQL Studio with either runner type.

* **Same runner, same path**: The Query Runner uses the exact same runner as the service's ingestion pipelines. If your service is configured with a Hybrid Runner, SQL Studio queries automatically go through it.
* **No extra configuration**: There is no separate runner setting for SQL Studio. The runner choice is made once at service creation time.
* **Credential isolation**: When using a Hybrid Runner, credentials stored in your Secrets Manager (AWS, Azure, GCP, Kubernetes, etc.) are fetched at runtime by the runner in your infrastructure. Collate's SaaS never accesses or stores these secrets directly.

## Comparing SaaS Runner vs Hybrid Runner for SQL Studio

The following table outlines the key differences between the two runner types for SQL Studio query execution.

| Aspect                       | Collate SaaS Runner                          | Hybrid Runner                                     |
| ---------------------------- | -------------------------------------------- | ------------------------------------------------- |
| **Query execution location** | Collate's cloud                              | Your infrastructure                               |
| **Credential storage**       | Encrypted in Collate                         | Your Secrets Manager (AWS/Azure/GCP/K8s, etc.)    |
| **Network path**             | Collate cloud → Your database                | Your infra → Your database (internal)             |
| **Setup effort**             | None (default)                               | Requires Hybrid Runner deployment                 |
| **Best for**                 | Cloud-hosted databases with public endpoints | Private databases, strict compliance requirements |

## Prerequisites

Confirm the following are in place before using SQL Studio with a Hybrid Runner.

1. **Hybrid Runner deployed and connected**: Verify in **Settings** > **Preferences** > **Ingestion Runners** that your runner shows as **Connected**
2. **Service created with the Hybrid Runner selected**: The database service must have the Hybrid Runner chosen as its Ingestion Runner during service creation
3. **Query Runner application installed**: Install the [Query Runner](/ai-2-0/admin-guide/applications/query-runner) app from the Marketplace
4. **SQL Studio configured for the service**: Complete the [Admin Configuration](/ai-2-0/how-to-guides/sql-studio/admin-configuration) for the service
5. **Secrets stored in your Secrets Manager**: Service connection credentials must be stored in your Secrets Manager (AWS, Azure, GCP, Kubernetes, etc.) and referenced with the `secret:` prefix

## How Secrets Are Handled

SQL Studio's secret handling depends on which runner is configured for the service:

### With Collate SaaS Runner

When the SaaS Runner handles the service, Collate manages credential storage directly.

* User credentials (OAuth tokens, passwords, service account keys) are encrypted and stored in Collate's database
* The SaaS Runner uses these credentials directly when executing queries

### With Hybrid Runner

When a Hybrid Runner handles the service, credentials remain in your own infrastructure.

* **Service connection credentials** (host, port, account) are stored in your Secrets Manager and referenced with the `secret:` prefix (e.g., `secret:/my/database/password`)
* **User authentication credentials** (Basic Auth) — Users also enter secret references (using the `secret:` prefix) instead of raw credentials. At runtime, the Hybrid Runner fetches these from your Secrets Manager within your infrastructure.
* At runtime, the Hybrid Runner fetches all referenced secrets from your Secrets Manager and establishes the database connection — entirely within your infrastructure. Collate's SaaS never accesses these secrets directly.

## Next Steps

Use these guides to set up and start using SQL Studio with a Hybrid Runner.

* **Set up the Hybrid Runner**: Follow the [Hybrid Ingestion Runner](/ai-2-0/getting-started/lets-get-started/ingest-your-data/hybrid-ingestion-runner) guide for deployment and configuration
* **Configure SQL Studio**: See [Admin Configuration](/ai-2-0/how-to-guides/sql-studio/admin-configuration) for service-level setup
* **Connect as a user**: See [User Authentication](/ai-2-0/how-to-guides/sql-studio/user-authentication) to authenticate and connect to your services
* **Start querying**: Head to [Query Execution](/ai-2-0/how-to-guides/sql-studio/query-execution) to learn how to write and run queries