# Caching Queries (/cache/cache)
import { Callout } from 'fumadocs-ui/components/callout'

Once your application is sending SQL queries through Readyset Cache, you can see which queries are cacheable.
**Deep caches can be created only once all tables have finished the initial snapshotting process.**

<Callout type="info">
  Snapshotting and replication are only required for **deep caches**, which incrementally maintain query
  results from your database's replication stream. **Shallow caches** are TTL-based and served without a
  snapshot, so they do not depend on snapshotting progress. See
  [Deep Caching](/concepts/deep-caching) and [Shallow Caching](/concepts/shallow-caching) for the
  difference.
</Callout>

Before attempting to create a deep cache, check Readyset Cache's overall snapshotting progress by connecting
a SQL shell to Readyset Cache and running the following custom SQL command:

```sql
SHOW READYSET STATUS;
```

Look for the row labeled `Snapshot Status` -- it should be either `In Progress` or `Completed`.

```text
name            |   value
----------------+----------
Snapshot Status | Completed
(1 row)
```

Once you see the status is `Completed` Readyset Cache is ready to cache queries.

<Callout type="info">
  If Readyset restarts during the initial snapshot, tables whose snapshot already completed are not re-snapshotted; only tables that were still being snapshotted restart from the beginning. See [Snapshotting](/reference/snapshots).
</Callout>

If you are unsure what queries to cache, you can [run diagnostics with both Postgres and MySQL](/reference/profiling-queries) to ascertain
costly queries.

## 1. Creating a Cache

It's important to note that Readyset Cache sits between your application and your database. SQL traffic must pass through Readyset Cache so
that it can cache desired queries. You can check to see that an application is successfully connected to Readyset Cache
by using the Readyset Cache shell and running the commands `show proxied queries` (you should see queries) or `show connections` (you should see two connections - one
being you in the Readyset Cache shell and the other being your application).

Once you've [identified queries](/reference/profiling-queries) that can benefit from caching with Readyset Cache,
use Readyset Cache's custom SQL commands to check if the queries are supported and then to cache supported queries in Readyset Cache.

## 2. Checking query support

To view all queries that Readyset Cache has proxied to the upstream database and check if they can be cached in Readyset Cache,
connect to Readyset Cache via the shell and run:

```sql
SHOW PROXIED QUERIES;
```

This command returns a virtual table with four columns:

* **QueryID:** A unique identifier for the query.
* **Proxied Query:** The text of the query being proxied.
* **Readyset Cache supported:** Whether or not Readyset Cache can cache the query.
  * If the value is `pending`, check again until you see `yes` or `no`.  If the value remains pending for more than 15 seconds, the query is unsupported.
  * If the value is `yes`, Readyset Cache can cache the query.
  * If the value is `no`, Readyset Cache cannot cache the query.
* **Count:** The number of times Readyset Cache has seen this query.

<Callout type="info">
  To successfully cache the results of a query, Readyset Cache must support the SQL features and syntax in the query. For more details, see 

  [SQL Support](/concepts/deep-caching/supported-data-types)

  . ​If an unsupported feature is important to your use case, 

  [submit a feature request](https://github.com/readysettech/readyset/issues/new/choose)

  .
</Callout>

## 3. Cache queries

Readyset Cache supports two kinds of caches:

* **Deep caches** use streaming dataflow to incrementally maintain query results from your
  database's replication stream, so cached results stay up to date automatically. They require the
  initial snapshot to be complete. See [Deep Caching](/concepts/deep-caching).
* **Shallow caches** are TTL-based: they store query results in memory and serve them until they
  expire, without building a materialized view. They support a broader range of queries and do not
  depend on snapshotting. See [Shallow Caching](/concepts/shallow-caching).

### Deep caches

To create a deep cache, use:

```sql
CREATE DEEP CACHE [<name>] [WITH (<option>[, <option>...])] FROM <query>;
```

* The `DEEP` modifier builds a materialized view in the dataflow graph. With no modifier, the cache type follows the server's [`--cache-mode`](/reference/config-options#--cache-mode) setting, which defaults to `shallow`, so specify `DEEP` explicitly to create a deep cache regardless of that setting.
* `<name>` is optional. If a cache is not named, Readyset Cache automatically assigns an identifier.
* `<query>` is the full text of the query or the unique identifier (i.e. `query_id`) assigned to the query by Readyset Cache, as seen in output of `SHOW PROXIED QUERIES`.
* `WITH (...)` carries an optional comma-separated list of options. The most common ones are `ALWAYS` and `UNTIL WRITE`, which control how the cached query is served when the connection is inside a transaction (for example, an ORM that wraps every statement in `BEGIN`/`COMMIT`). With no option, the cached query is proxied upstream for the entire transaction. `WITH (UNTIL WRITE)` serves the cached query from Readyset Cache until the transaction observes a write, after which it is proxied upstream for the rest of that transaction. `WITH (ALWAYS)` serves the cached query from Readyset Cache regardless of transaction state. See the [Command Reference](/command-reference#create-cache) for the full option list.

For example, to cache from the query `SELECT "words".* FROM "words" WHERE ("words"."id" = $1) ORDER BY "words"."id" ASC`:

```sql
CREATE DEEP CACHE FROM SELECT "words".* FROM "words" WHERE ("words"."id" = $1) ORDER BY "words"."id" ASC;
```

You can also grab the query ID from `show proxied queries` and use that identifier to cache a query.
For instance, running `show proxied queries` shows this table:

```
      query_id      |                     query                     | readyset_supported | count
--------------------+-----------------------------------------------+--------------------+-------
 q_bb6bd342f17bd8cd | SELECT                                       +| yes                |   219
                    |   *                                          +|                    |
                    | FROM                                         +|                    |
                    |   "employees"."employee"                     +|                    |
                    | WHERE                                        +|                    |
                    |   ("last_name" = $1)                          |                    |
```

You can create a cache for the `select` query above with its ID (`q_bb6bd342f17bd8cd`) like so:

```
CREATE DEEP CACHE FROM q_bb6bd342f17bd8cd;
```

This makes it easier to create caches from a list of queries found in `show proxied queries`.

### Shallow caches

To create a shallow cache:

```sql
CREATE SHALLOW CACHE [<name>] [WITH (POLICY TTL <n> {SECONDS | MILLISECONDS | MS}[, <option>...])] FROM <query>;
```

For full syntax and options, see [Shallow Caches](/command-reference#shallow-caches) in the command reference.

## 4. View cached queries

To show all queries that have been cached, use:

```sql
SHOW CACHES;
```

To show a specific cached query, use:

```sql
SHOW CACHES where query_id = <query ID>;
```

This command returns a virtual table with 2 columns:

* **Name:** The name assigned to the query by the user, or the ID assigned to the query by Readyset Cache.
* **Query Text:** The SQL source of the query. This is the canonical structure of the query, not the original SQL passed to Readyset Cache.

## 5. Remove cached queries

To remove a cache from Readyset Cache, use:

```sql
DROP CACHE <id>;
```

* `<id>` is either the name assigned to the query by the user or the ID assigned to the query by Readyset Cache, as seen in the output of `SHOW CACHES`.

After removing a query from Readyset Cache, any instances of this query will be proxied to the upstream database.


# AWS Aurora (/cache/connect/cloud-databases/aws-aurora)
import { Cards, Card } from 'fumadocs-ui/components/card'

Configure an AWS Aurora database to work with Readyset Cache. Choose the guide for your database engine:

<Cards>
  <Card title="Postgres" href="/cache/connect/cloud-databases/aws-aurora/postgres" />

  <Card title="MySQL" href="/cache/connect/cloud-databases/aws-aurora/mysql" />
</Cards>


# MySQL (/cache/connect/cloud-databases/aws-aurora/mysql)




import { Callout } from 'fumadocs-ui/components/callout'

If you're using AWS Aurora MySQL, you'll need to make a few configuration changes
via the AWS console to enable Readyset Cache to properly replicate tables.

## Instructions

<Callout type="info">
  Note: Readyset Cache only needs access to the write node of any Aurora cluster.
</Callout>

### 1. Establish a network connection

<Callout type="info">
  Note: these directions assume you are using Readyset Cache in a different VPC than the upstream database you're connecting to. If Readyset Cache is within the same VPC as your database, you can ignore this step.
</Callout>

To make sure Readyset Cache can connect with your database, the database will have to be publicly accessible.

1. Click on RDS, which can be found by searching for it in the search bar, under the Services menu, or in your Recently Visited area. Within RDS under the Resources section, select DB instances.
2. Choose the write node instance you want to use.
3. Click the Modify button in the upper right corner.
4. In the Connectivity section, click on Additional configurations.

<img alt="Connectivity 1" src={__img0} placeholder="blur" />

5. Under Public access, choose Publicly accessible.

<img alt="Connectivity 2" src={__img1} placeholder="blur" />

6. Click on Continue at the bottom of the page.
7. Select when you want to apply the change and click Modify DB instance.

### 2. Enable binary logging

Readyset Cache replicates changes from the MySQL binary log, so binlog must be enabled with row-based logging at the cluster level.

<Callout type="info">
  Note: To use Readyset Cache with Aurora, you must configure a DB cluster parameter group. Binlog settings must be applied at the cluster level.
</Callout>

1. Under the Resources section, select [Parameter groups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithDBInstanceParamGroups.html) and create a new DB Cluster Parameter Group for your Aurora MySQL version.
2. Edit the group and set `binlog_format` to `ROW` and `binlog_row_image` to `FULL`.
3. Associate the cluster parameter group with your Aurora cluster.
4. Reboot the writer instance if required for the parameters to take effect.

For the full list of binlog variables Readyset Cache expects, see [General MySQL configuration](/cache/connect/mysql).

### 3. Set binlog retention

Ensure the binary logs are retained long enough for Readyset Cache to complete its initial snapshot. Connect to the write node and run:

```sql copy
call mysql.rds_set_configuration('binlog retention hours', 24);
```

A reasonable value here is one hour of retention for every 150 GB of database size.

### 4. Grant privileges to the Readyset Cache user

Grant the Readyset Cache user the privileges it needs to snapshot and replicate. See [General MySQL configuration](/cache/connect/mysql#3-ensure-readyset-cache-user-has-sufficient-privileges) for the full list and an example `GRANT` statement.


# Postgres (/cache/connect/cloud-databases/aws-aurora/postgres)










import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

If you're using AWS Aurora Postgres, you'll need to make a few configuration changes
via the AWS console to enable Readyset Cache to properly replicate tables.

## Instructions

<Callout type="info">
  Note: Readyset Cache only needs access to the write node of any Aurora cluster.
</Callout>

### 1. Establish a network connection

<Callout type="info">
   Note: these directions assume you are using Readyset Cache in a different VPC than the upstream database you're connecting to.
  If Readyset Cache is within the same VPC as your database, you can ignore this step.
</Callout>

To make sure Readyset Cache can connect with your database, the database will have to be publicly accessible.

1. Log in to your AWS account.
2. Click on RDS, which can be found by searching for it in the search bar, under the Services menu, or in your Recently Visited area. Within RDS under the Resources section, select DB instances.
3. Choose  the instance you want to use.
4. Click the Modify button in the upper right corner.
5. In the Connectivity section, click on Additional configurations.

<img alt="Connectivity 1" src={__img0} placeholder="blur" />

6. Under Public access, choose Publicly accessible.

<img alt="Connectivity 2" src={__img1} placeholder="blur" />

7. Click on Continue at the bottom of the page.
8. Select when you want to apply the change and click Modify DB instance.

### 2. Turn on logical replication

<Callout type="info">
  Note: More information on logical replication and Aurora can be found 

  [in AWS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Replication.Logical.html)

  .
</Callout>

1. Log in to your AWS account.
2. Click on RDS, which can be found by searching for it in the search bar, under the Services menu, or in your Recently Visited area.
3. Under the Resources section, select [Parameter groups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithDBInstanceParamGroups.html) in the upper right.

<Callout type="info">
  Note: To use Readyset Cache with Aurora, you must create a new parameter group.
</Callout>

4. Select Create Parameter group from the upper right corner.
5. Choose Aurora postgres 15 from the dropdown menu.
6. Under Group Name select DB Cluster Parameter Group from the dropdown. For Readyset Cache to work this *must* be at the cluster-level.

<img alt="AWS Example" src={__img2} placeholder="blur" />

7. Choose a name and add an optional description and then hit the Create button.
8. Return to Parameter groups and select the name of your newly-created group.
9. Select Edit from the top right corner.
10. Search for `rds.logical_replication` and change the value from 0 to 1.
11. Go back to the dashboard and select your Aurora write node instance and then select Edit in the top right corner.
12. Open Additional configurations at the bottom of the page. Under Database options there's a dropdown to select a DB parameter group. Select the appropriate Parameter group for the DB cluster parameter group.

<img alt="AWS Parameter Groups 2" src={__img3} placeholder="blur" />

13. To check that this worked, run the following command:

```sql copy
SELECT name,setting FROM pg_settings WHERE name = 'rds.logical_replication';
```

If you're not seeing:

```sql
          name           | setting
-------------------------+---------
 rds.logical_replication | on
```

You may need to reboot your instance. To do that go to your write node instance and click on the Actions menu in the upper right corner and select Reboot.

<img alt="Reboot AWS RDS" src={__img4} placeholder="blur" />

### 3. Enable superuser permissions

If you are using RDS and Readyset Cache with the same [user account](https://aws.amazon.com/blogs/database/managing-postgresql-users-and-roles/) you used to set up the database, permissions do not need to be enabled.

If you need to add a new user account or access Readyset Cache with a different one, you'll need to enable superuser permissions. To do that, enter the following in the `psql` command line interface:

```sql copy
UPDATE pg_user SET usesuper=true where usename = CURRENT_USER;
```


# AWS RDS (/cache/connect/cloud-databases/aws-rds)
import { Cards, Card } from 'fumadocs-ui/components/card'

Configure an AWS RDS database to work with Readyset Cache. Choose the guide for your database engine:

<Cards>
  <Card title="Postgres" href="/cache/connect/cloud-databases/aws-rds/postgres" />

  <Card title="MySQL" href="/cache/connect/cloud-databases/aws-rds/mysql" />
</Cards>


# MySQL (/cache/connect/cloud-databases/aws-rds/mysql)






import { Callout } from 'fumadocs-ui/components/callout'

If you're using AWS RDS MySQL, you'll need to make a few configuration changes
via the AWS console to enable Readyset Cache to properly replicate tables.

Before each step listed below, you'll need to:

* Log in to your AWS account.
* Click on RDS, which can be found by searching for it in the search bar, under the Services menu, or in your Recently Visited area.

## Instructions

### 1. Establish a network connection

<Callout type="info">
  Note: these directions assume you are using Readyset Cache in a different VPC than the upstream database you're connecting to. If Readyset Cache is within the same VPC as your database, you can ignore this step.
</Callout>

To make sure Readyset Cache can connect with your database, it's easiest if you install Readyset Cache in the same VPC as your database. If Readyset Cache is located in another VPC, you can set up VPC peering; otherwise, the database will have to be publicly accessible.

1. Within RDS under the Resources section, select DB instances.

<img alt="AWS Resources" src={__img0} placeholder="blur" />

2. Choose the instance you want to make publicly accessible.
3. Click the Modify button in the upper right corner.
4. In the Connectivity section, click on Additional configurations.

<img alt="AWS Connectivity" src={__img1} placeholder="blur" />

5. Under Public access, choose Publicly accessible.

<img alt="AWS Connectivity 2" src={__img2} placeholder="blur" />

6. Click on Continue at the bottom of the page.
7. Select when you want to apply the change and click Modify DB instance.

### 2. Enable binary logging

Readyset Cache replicates changes from the MySQL binary log, so binlog must be enabled and configured with row-based logging.

1. RDS enables the binary log only when automated backups are turned on. Under your instance's Modify page, set the backup retention period to a value greater than 0 days.
2. Under the Resources section, select [Parameter groups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithDBInstanceParamGroups.html). Modify an existing group or create a new one, then associate it with your instance.
3. Set `binlog_format` to `ROW` and `binlog_row_image` to `FULL`.
4. Apply the changes and reboot the instance if required for the parameters to take effect.

For the full list of binlog variables Readyset Cache expects, see [General MySQL configuration](/cache/connect/mysql).

### 3. Set binlog retention

Ensure the binary logs are retained long enough for Readyset Cache to complete its initial snapshot. Connect to your instance and run:

```sql copy
call mysql.rds_set_configuration('binlog retention hours', 24);
```

A reasonable value here is one hour of retention for every 150 GB of database size.

### 4. Grant privileges to the Readyset Cache user

Grant the Readyset Cache user the privileges it needs to snapshot and replicate. See [General MySQL configuration](/cache/connect/mysql#3-ensure-readyset-cache-user-has-sufficient-privileges) for the full list and an example `GRANT` statement.


# Postgres (/cache/connect/cloud-databases/aws-rds/postgres)
















import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

If you're using AWS RDS Postgres, you'll need to make a few configuration changes
via the AWS console to enable Readyset Cache to properly replicate tables.

Before each step listed below, you'll need to:

* Log in to your AWS account.
* Click on RDS, which can be found by searching for it in the search bar, under the Services menu, or in your Recently Visited area.

## Instructions

### 1. Establish a network connection

<Callout type="info">
   Note: these directions assume you are using Readyset Cache in a different VPC than the upstream database you're connecting to. If Readyset Cache is within the same VPC as your database, you can ignore this step.
</Callout>

To make sure Readyset Cache can connect with your database, it's easiest if you install Readyset Cache in the same VPC as your database. If Readyset Cache is located in another VPC, you can set up VPC peering; otherwise, the database will have to be publicly accessible.

1. Within RDS under the Resources section, select DB instances.

<img alt="AWS Resources" src={__img0} placeholder="blur" />

2. Choose the instance you want to make publicly accessible.
3. Click the Modify button in the upper right corner.
4. In the Connectivity section, click on Additional configurations.

<img alt="AWS Connectivity" src={__img1} placeholder="blur" />

5. Under Public access, choose Publicly accessible.

<img alt="AWS Connectivity 2" src={__img2} placeholder="blur" />

6. Click on Continue at the bottom of the page.
7. Select when you want to apply the change and click Modify DB instance.

### 2. Turn on logical replication

1. Under the Resources section, select [Parameter groups](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithDBInstanceParamGroups.html) in the upper right.

<img alt="AWS Resources" src={__img3} placeholder="blur" />

2. If you already have Parameter groups, you'll want to modify an existing group. If you don't have an existing parameter group, you'll need to create a new one following [these steps](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithDBInstanceParamGroups.html) first.

   Select the Parameter group you want to modify and then click Edit in the upper right corner.

<img alt="AWS Parameter Group" src={__img4} placeholder="blur" />

3. Search for `rds.logical_replication` and change the value from 0 to 1.
4. If you used an existing Parameter group, skip to step 5. If you created a new Parameter group, you will need to associate your group with this instance. To do that, go to your RDS dashboard, click your instance name and select Modify in the upper right corner. Open Additional configurations at the bottom of the page. Under Database options there's a dropdown to
   select a DB parameter group. Select the appropriate Parameter group.

<img alt="AWS Parameter Groups 2" src={__img5} placeholder="blur" />

Click on Continue at the bottom of the page. Select when you want to apply the change and click
Modify DB instance.
5\. To check that this worked, you can return to Resources and select Parameter groups (see step 3). Select the Parameter group you edited and search for `rds.logical_replication` under Parameters:

<img alt="AWS Parameter Groups 3" src={__img6} placeholder="blur" />

If you're not seeing a value of 1, you may need to reboot your instance. To do that go to your instance and click on the Actions menu in the upper right corner and select Reboot.

<img alt="AWS Example" src={__img7} placeholder="blur" />

### 3. Enable superuser permissions

When you initially set up your RDS instance, you created an [admin user and password](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_SettingUp.html#sign-up-for-aws). If you use this admin user account when configuring your database for Readyset Cache, you will not need to enable superuser permissions

However, if you are using a different database user than the default admin, you will need to enable superuser permissions.  To do that, execute the following:

```sql copy
UPDATE pg_user SET usesuper=true where usename = CURRENT_USER;
```


# Cloud Databases (/cache/connect/cloud-databases)
import { Cards, Card } from 'fumadocs-ui/components/card'

Many managed database services need a few provider-specific settings before Readyset Cache can
replicate from them. Choose your hosting provider for step-by-step configuration instructions:

<Cards>
  <Card title="Neon" href="/cache/connect/cloud-databases/neon" />

  <Card title="Supabase" href="/cache/connect/cloud-databases/supabase" />

  <Card title="AWS RDS" href="/cache/connect/cloud-databases/aws-rds" />

  <Card title="AWS Aurora" href="/cache/connect/cloud-databases/aws-aurora" />
</Cards>


# Neon (/cache/connect/cloud-databases/neon)


import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'

This guide walks you through running Readyset Cache against a [Neon](https://neon.tech) Postgres database using RDST, the Readyset Data and SQL Toolkit.

<Callout type="info">
  This guide is intended for local or test deployments using Docker. For production deployments, see the [production installation guide](https://readyset.io/docs/cache/install-rs/binaries).
</Callout>

## Prerequisites

* **curl** installed
* **Docker** installed and running
* A Neon account with a Postgres project

## Steps

<Steps>
  <Step>
    ### Install RDST

    Install RDST without sudo or a preinstalled Python:

    ```sh
    curl -fsSL https://downloads.readyset.io/packages/rdst-cli/install.sh | sh
    export PATH="$HOME/.local/bin:$PATH"
    ```

    Verify the installation:

    ```sh
    rdst version
    ```
  </Step>

  <Step>
    ### Get your Neon connection string

    In the [Neon Console](https://console.neon.tech), open your project and navigate to the **Connection Details** panel. Copy the connection string. It will look like this:

    ```
    postgresql://<user>:<password>@<endpoint-id>.<region>.aws.neon.tech/<dbname>
    ```

    <Callout type="info">
      Neon has extra parameters in the connection string to enable SSL (?sslmode=require). This is not required for Readyset Cache configuration.
    </Callout>
  </Step>

  <Step>
    ### Initialize RDST

    Run the RDST setup wizard:

    ```sh
    rdst init
    ```
  </Step>

  <Step>
    ### Set your password as an environment variable

    RDST uses environment variables to store the database password for security purposes.

    ```sh
    export NEON_PASSWORD="<neon-database-password>"
    ```
  </Step>

  <Step>
    ### Configure your Neon database as a target

    Add your Neon database as a named target:

    ```sh
    rdst configure add --target neon --connection-string "postgresql://<user>:<password>@<endpoint-id>.<region>.aws.neon.tech/<dbname>"
    ```

    Once RDST creates the target, deploy the cache.

        <img alt="Deploy Readyset Cache" src={__img0} placeholder="blur" />
  </Step>
</Steps>

## Next Steps

* [Connect to Readyset Cache from a database shell](/cache/connect)
* [Connect from your application](/cache/connect/connect-an-application-via-an-orm)
* [Create your first cache](/cache/cache)


# Supabase (/cache/connect/cloud-databases/supabase)




import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

This guide walks you through running Readyset Cache against a [Supabase](https://supabase.com) Postgres database using RDST, the Readyset Data and SQL Toolkit.

<Callout type="info">
  This guide is intended for local or test deployments using Docker. For production deployments, see the [production installation guide](https://readyset.io/docs/cache/install-rs/binaries).
</Callout>

## Prerequisites

* **curl** installed
* **Docker** installed and running
* A Supabase account with a Postgres project

## Steps

<Steps>
  <Step>
    ### Install RDST

    Install RDST without sudo or a preinstalled Python:

    ```sh
    curl -fsSL https://downloads.readyset.io/packages/rdst-cli/install.sh | sh
    export PATH="$HOME/.local/bin:$PATH"
    ```

    Verify the installation:

    ```sh
    rdst version
    ```
  </Step>

  <Step>
    ### Get your Supabase connection string

    In the [Supabase Dashboard](https://supabase.com/dashboard), open your project and go to **Project Settings > Database**. Choose the connection type that matches your network:

    <Tabs items={['Transaction Pooler', 'Session Pooler', 'Direct connection']}>
      <Tab value="Transaction Pooler">
        Use this if your network only supports IPv4. In the **Connection string** panel, select **Transaction Pooler**. It will look like this:

        ```
        postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres
        ```
      </Tab>

      <Tab value="Session Pooler">
        Use this as an alternative IPv4 option when you need session-level features that Transaction Pooler does not support. In the **Connection string** panel, select **Session Pooler**. It will look like this:

        ```
        postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres
        ```
      </Tab>

      <Tab value="Direct connection">
        Readyset Cache does not fully support IPv6. To use a direct connection, you must first [enable the IPv4 add-on](https://supabase.com/docs/guides/platform/ipv4-address) for your Supabase project. Once enabled, select **Direct connection** in the **Connection string** panel. It will look like this:

        ```
        postgresql://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres
        ```
      </Tab>
    </Tabs>

        <img alt="Supabase connection string" src={__img0} placeholder="blur" />
  </Step>

  <Step>
    ### Initialize RDST

    Run the RDST setup wizard:

    ```sh
    rdst init
    ```
  </Step>

  <Step>
    ### Set your password as an environment variable

    RDST uses environment variables to store the database password for security purposes.

    ```sh
    export SUPABASE_PASSWORD="<supabase-database-password>"
    ```
  </Step>

  <Step>
    ### Configure your Supabase database as a target

    Add your Supabase database as a named target, using the connection string you copied in the previous step:

    ```sh
    rdst configure add --target supabase --connection-string "<your-connection-string>"
    ```

    Once RDST creates the target, deploy the cache.

        <img alt="Deploy Readyset Cache" src={__img1} placeholder="blur" />
  </Step>
</Steps>

## Next Steps

* [Connect to Readyset Cache from a database shell](/cache/connect)
* [Connect from your application](/cache/connect/connect-an-application-via-an-orm)
* [Create your first cache](/cache/cache)


# Connect an Application via an ORM (/cache/connect/connect-an-application-via-an-orm)
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

To connect an application to Readyset Cache, simply swap your application's connection string to the Readyset Cache connection string.

## Support Levels

There are three levels of support Readyset Cache provides for external drivers.

### Verified

The Readyset Cache team has validated that the ORM can connect to and cache queries from Readyset Cache as of the version specified.

If you encounter an issue with a Verified ORM, open an issue on GitHub.

### In Development

We've identified the ORM as one we'd like to support and are actively working on supporting it in the future.

### Unverified

This ORM has not been tested by the Readyset Cache team. Many untested ORMs will still work with Readyset Cache out of the box.

We're happy to help your team validate a new ORM with Readyset Cache - file an issue on GitHub and we'll investigate.

## ORM Support

<Tabs items={['MySQL', 'Postgres']}>
  <Tab value="MySQL">
    <Tabs items={['TypeScript / JavaScript', 'Python', 'Java', 'Go']}>
      <Tab value="TypeScript / JavaScript">
        | Driver    | Supported? | Minimum version | Tutorial |
        | --------- | ---------- | --------------- | -------- |
        | Sequelize | Verified   | 6.3.5           |          |
        | TypeORM   | Verified   | 0.2.25          |          |
      </Tab>

      <Tab value="Python">
        | Driver      | Supported? | Minimum version                | Tutorial |
        | ----------- | ---------- | ------------------------------ | -------- |
        | Django      | Verified   | 3.1.4                          |          |
        | PyMySQL     | Verified   | 1.0.2                          |          |
        | mysqlclient | Verified   | Latest (2.2.0 as of 2023/6/30) |          |
        | SQLAlchemy  | Verified   | 1.3.13                         |          |
      </Tab>

      <Tab value="Java">
        | Driver    | Supported?     | Minimum version     | Tutorial |
        | --------- | -------------- | ------------------- | -------- |
        | Spring    | In Development | 2.3.2 (Spring Boot) |          |
        | Hibernate | Unverified     |                     |          |
      </Tab>

      <Tab value="Go">
        | Driver | Supported? | Minimum version | Tutorial |
        | ------ | ---------- | --------------- | -------- |
        | gorm   | Verified   | 1.20.2          |          |
      </Tab>
    </Tabs>

    <Tabs items={['Ruby', 'Rust', 'Haskell', 'PHP', 'mysqldump']}>
      <Tab value="Ruby">
        | Driver  | Supported? | Minimum version | Tutorial                                                                |
        | ------- | ---------- | --------------- | ----------------------------------------------------------------------- |
        | Rails 5 | Verified   | 5.2.4           |                                                                         |
        | Rails 6 | Verified   | 6.1.3.1         | [Rails with Readyset Cache](/cache/connect/ruby-on-rails-with-readyset) |
        | Rails 7 | Verified   | 7.0.8           | [Rails with Readyset Cache](/cache/connect/ruby-on-rails-with-readyset) |
      </Tab>

      <Tab value="Rust">
        | Driver       | Supported? | Minimum version | Tutorial |
        | ------------ | ---------- | --------------- | -------- |
        | Diesel       | Verified   | 2.1.0           |          |
        | MySql        | Verified   | 20.1.0          |          |
        | MySql\_async | Verified   | 0.31.3          |          |
        | sqlx         | Verified   | 0.6.2           |          |
      </Tab>

      <Tab value="Haskell">
        | Driver       | Supported? | Minimum version | Tutorial |
        | ------------ | ---------- | --------------- | -------- |
        | MySQL-simple | Verified   | >= 0.4          |          |
      </Tab>

      <Tab value="PHP">
        | Driver    | Supported?     | Minimum version                  | Tutorial |
        | --------- | -------------- | -------------------------------- | -------- |
        | Laravel   | Verified       | Latest (10.2.4 as of 2023/06/30) |          |
        | Flarum    | Verified       | Latest (1.8.0 as of 2023/06/30)  |          |
        | Drupal    | In Development |                                  |          |
        | Spiral    | Verified       | Latest                           |          |
        | WordPress | Verified       |                                  |          |
      </Tab>

      <Tab value="mysqldump">
        | Driver | Supported? | Minimum version | Tutorial |
        | ------ | ---------- | --------------- | -------- |
        | Export | Verified   | 5.7             |          |
        | Import | Verified   | 5.7             |          |
      </Tab>
    </Tabs>
  </Tab>

  <Tab value="Postgres">
    <Tabs items={['TypeScript / JavaScript', 'Python', 'Java', 'Go']}>
      <Tab value="TypeScript / JavaScript">
        | Driver        | Supported? | Minimum version | Tutorial |
        | ------------- | ---------- | --------------- | -------- |
        | Prisma        | Verified   | 4.11.0          |          |
        | Sequelize     | Verified   | 6.3.5           |          |
        | TypeORM       | Verified   | 0.2.25          |          |
        | node-postgres | Unverified |                 |          |
      </Tab>

      <Tab value="Python">
        | Driver     | Supported? | Minimum version | Tutorial |
        | ---------- | ---------- | --------------- | -------- |
        | Django     | Verified   | 3.1.4           |          |
        | SQLAlchemy | Verified   | 1.3.13          |          |
      </Tab>

      <Tab value="Java">
        | Driver    | Supported?     | Minimum version     | Tutorial |
        | --------- | -------------- | ------------------- | -------- |
        | JDBC      | Verified       | 8.0.32              |          |
        | Spring    | In Development | 2.3.2 (Spring Boot) |          |
        | Hibernate | Unverified     |                     |          |
      </Tab>

      <Tab value="Go">
        | Driver | Supported? | Minimum version                  | Tutorial |
        | ------ | ---------- | -------------------------------- | -------- |
        | gorm   | Verified   | 1.20.2                           |          |
        | Skeema | Verified   | Latest (1.10.1 as of 2023/06/30) |          |
      </Tab>
    </Tabs>

    <Tabs items={['Ruby', 'Rust', 'Haskell', 'PHP']}>
      <Tab value="Ruby">
        | Driver  | Supported? | Minimum version | Tutorial                                                                |
        | ------- | ---------- | --------------- | ----------------------------------------------------------------------- |
        | Rails 5 | Verified   | 5.2.4           |                                                                         |
        | Rails 6 | Verified   | 6.1.3.1         | [Rails with Readyset Cache](/cache/connect/ruby-on-rails-with-readyset) |
        | Rails 7 | Verified   | 7.0.8           | [Rails with Readyset Cache](/cache/connect/ruby-on-rails-with-readyset) |
      </Tab>

      <Tab value="Rust">
        | Driver | Supported?     | Minimum version | Tutorial |
        | ------ | -------------- | --------------- | -------- |
        | Diesel | In Development |                 |          |
        | sqlx   | Verified       | 0.6.2           |          |
      </Tab>

      <Tab value="Haskell">
        | Driver       | Supported? | Minimum version | Tutorial |
        | ------------ | ---------- | --------------- | -------- |
        | MySQL-simple | Verified   | >= 0.4          |          |
      </Tab>

      <Tab value="PHP">
        | Driver  | Supported?     | Minimum version | Tutorial |
        | ------- | -------------- | --------------- | -------- |
        | Laravel | In Development |                 |          |
        | Drupal  | In Development |                 |          |
        | Spiral  | In Development |                 |          |
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Connect to Readyset Cache (/cache/connect)
import { Cards, Card } from 'fumadocs-ui/components/card'

Readyset Cache sits between your application and your database. When you start Readyset Cache, it'll connect
to your database and, for deep caching, take an initial snapshot of your tables and replicate changes to
keep cached results up to date. (Shallow, TTL-based caches are served without this snapshot.) You'll need
to configure your application to connect to Readyset Cache so that Readyset Cache can see the various SQL
queries your application uses. By default, all queries are proxied to your database.

In order to make use of Readyset Cache, you'll need to configure it to cache specific queries.

You can connect to Readyset Cache directly using your database's shell, such as `psql` or the `mysql`
client. From there, you can see any queries that Readyset Cache has seen and which ones are cacheable.
Follow the guide for your database to configure it and connect:

<Cards>
  <Card title="PostgreSQL" href="/cache/connect/postgres" />

  <Card title="MySQL" href="/cache/connect/mysql" />
</Cards>

To point your application at Readyset Cache instead of your database, see
[Connect an application via an ORM](/cache/connect/connect-an-application-via-an-orm) or the
[Connect Readyset Cache with Ruby on Rails](/cache/connect/ruby-on-rails-with-readyset) walkthrough. If your
database is hosted on a managed service, see [Cloud Databases](/cache/connect/cloud-databases).

Once connected, you can view and cache queries:

<Cards>
  <Card title="Creating a cache" href="/cache/cache" />
</Cards>


# MySQL (/cache/connect/mysql)
import { Callout } from 'fumadocs-ui/components/callout'

This guide will walk you through the process of configuring a MySQL 8.0 database to work with Readyset Cache.
Please note that other versions are untested so you might run into issues.

## Instructions

<Callout type="info">
  The replication settings and privileges below are required for **deep caching**, where Readyset Cache snapshots your tables and follows the replication stream to keep cached results up to date. **Shallow (TTL-based) caching** does not require replication or the snapshot/replication privileges; it needs only standard read access (`SELECT`) to run your queries. See [Shallow Caching](/concepts/shallow-caching).
</Callout>

To ensure you have the correct permissions set, run the following commands as the database user you will use Readyset Cache with:

#### 1. Ensure MySQL version 8.0 is running.

```sql
mysql> SHOW VARIABLES LIKE 'version';
+---------------+--------+
| Variable_name | Value  |
+---------------+--------+
| version       | 8.0.33 |
+---------------+--------+
1 row in set (0.17 sec)
```

#### 2. Ensure replication is enabled and properly configured .

```sql
mysql> SHOW BINARY LOGS;
+---------------+-----------+-----------+
| Log_name      | File_size | Encrypted |
+---------------+-----------+-----------+
| binlog.000001 |   3040038 | No        |
| binlog.000002 |  34978315 | No        |
| binlog.000003 |  34978333 | No        |
+---------------+-----------+-----------+
3 rows in set (0.07 sec)
```

If any files are returned, binary logging is correctly enabled.

```sql
mysql> SELECT @@global.binlog_format, @@global.binlog_row_image, @@global.binlog_transaction_compression, @@global.binlog_encryption\G
*************************** 1. row ***************************
                 @@global.binlog_format: ROW
              @@global.binlog_row_image: FULL
@@global.binlog_transaction_compression: 0
             @@global.binlog_encryption: 0
1 row in set, 1 warning (0.00 sec)
```

Ensure `binlog_format` is set to `ROW`, `binlog_row_image` is set to `FULL`, `binlog_transaction_compression` is `0` and `binlog_encryption` is also set to `0`.

#### 3. Ensure Readyset Cache user has sufficient privileges.

Readyset Cache uses below list of privileges:

* [`BACKUP_ADMIN`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_backup-admin) - During initial snapshot, Readyset Cache executes the metadata lock [`LOCK INSTANCE FOR BACKUP`](https://dev.mysql.com/doc/refman/8.0/en/lock-instance-for-backup.html) to prevent unsafe statements such as DDL's from happening while snapshot is in progress.
* [`LOCK TABLES`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_lock-tables) - During initial snapshot, Readyset Cache takes a brief lock in the table in order to start a transaction and have a consistent view of the table data and correlate it with the binlog position taken from the output of `SHOW BINARY LOGS`.
* [`REPLICATION CLIENT`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_replication-client) - During initial snapshot, Readyset Cache executes [`SHOW MASTER STATUS`](https://dev.mysql.com/doc/refman/8.0/en/show-master-status.html) to get a consistent binlog file and position for each table.
* [`REPLICATION SLAVE`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_replication-slave) - Readyset Cache register itself as a replica for CDC (Change Data Capture). This enables Readyset Cache to automatically keep cache entries up to date when data changes in your database.
* [`SELECT`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_select) - Used to snapshot data within replicated tables.

<Callout type="info">
  Note: Readyset Cache proxies all traffic from application to database. You should also add the privileges your current application uses to function (eg. 

  [`INSERT`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_insert)

  , 

  [`DELETE`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_delete)

  , 

  [`UPDATE`](https://dev.mysql.com/doc/refman/8.0/en/privileges-provided.html#priv_update)

  )
</Callout>

Example:

```sql
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES ON YOUR_DATABASE.* TO USER@'HOST';
mysql> GRANT BACKUP_ADMIN, REPLICATION CLIENT, REPLICATION SLAVE ON *.* TO USER@'HOST';
```

## AWS RDS-only configuration

If you are using AWS RDS, you will also need to do the following:

**1. Make sure binlog retention is enabled.**

```sql
mysql> call mysql.rds_show_configuration;
+------------------------+-------+------------------------------------------------------------------------------------------------------+
| name                   | value | description                                                                                          |
+------------------------+-------+------------------------------------------------------------------------------------------------------+
| binlog retention hours |    1  | binlog retention hours specifies the duration in hours before binary logs are automatically deleted. |
+------------------------+-------+------------------------------------------------------------------------------------------------------+
1 row in set (0.06 sec)
```

If the `value` is set to `NULL`, you must [configure binlog retention](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/mysql-stored-proc-configuring.html#mysql_rds_set_configuration-usage-notes.binlog-retention-hours) to be at least long enough for snapshotting to complete.  A reasonable value here is one hour of retention for every 150 GB of database size.

## Connecting to Readyset Cache

Readyset Cache is wire-compatible with MySQL, so you can use the `mysql` client to connect to it in the same way you would an ordinary database.

Readyset Cache uses the same username, password and database name as your upstream database.  To connect, fill in those values and run:

```sh
mysql -h<READYSET HOST> -u<USER> -p<PASSWORD> -P<READYSET PORT> <DATABASE>
```

Once connected, you can see the status of tables in Readyset Cache by running:

```sql
mysql> SHOW READYSET STATUS;
```

For details on how clients authenticate to Readyset Cache, see [Authentication](/reference/authentication).


# PostgreSQL (/cache/connect/postgres)
import { Callout } from 'fumadocs-ui/components/callout'

This guide will walk you through the process of configuring a Postgres 13.0 or higher database to work with Readyset Cache.
Please note that other versions are untested so you might run into issues.

## Instructions

<Callout type="info">
  The logical replication and superuser settings below are required for **deep caching**, where Readyset Cache snapshots your tables and follows the replication stream to keep cached results up to date. **Shallow (TTL-based) caching** does not require them; it needs only standard read access to run your queries. See [Shallow Caching](/concepts/shallow-caching).
</Callout>

To ensure you have the correct permissions set, run the following commands as the database user you will use Readyset Cache with:

#### 1. Ensure Postgres version 13.0 or higher is running.

```sql
testdb=> SELECT version();
      version
-----------------------
 PostgreSQL 14.8
(1 row)

```

#### 2. Ensure that logical replication is enabled.

```sql
testdb=> SHOW WAL_LEVEL;
 wal_level
-----------
 logical
(1 row)
```

`LOGICAL` is required to ensure sufficient data is present in the replication stream.

#### 3. Ensure superuser permissions are enabled.

Readyset Cache uses superuser access to be notified of changes to table DDL.

```sql
testdb=> SELECT * FROM pg_user where usename = CURRENT_USER;
 usename  | usesysid | usecreatedb | usesuper | userepl | usebypassrls |  passwd  | valuntil | useconfig
----------+----------+-------------+----------+---------+--------------+----------+----------+-----------
 postgres |       10 | t           | t        | t       | t            | ******** |          |
(1 row)
```

Ensure the `usesuper` variable is `true`.

#### 4. Decide on how to deal with unsupported features.

Some Postgres features, like row-level security, are not yet supported by Readyset Cache. You can either skip replicating those tables
into Readyset Cache (in [Step 2 – Install Readyset Cache](/cache/install-rs)), or alternatively,
you can disable these features on tables replicated by Readyset Cache prior to proceeding.

For managed Postgres services such as AWS RDS and AWS Aurora, see [Cloud Databases](/cache/connect/cloud-databases).

## Connecting to Readyset Cache

Readyset Cache is wire-compatible with Postgres, so you can use `psql` to connect to it in the same way you would an ordinary database.

Readyset Cache uses the same username, password and database name as your upstream database, so to connect, fill in those values in your connection string and run:

```sh
psql 'postgresql://<username>:<password>@127.0.0.1:5433/<database name>'
```

Once connected, you can see the status of tables in Readyset Cache by running:

```sql
testdb=> SHOW READYSET STATUS;
```


# Connect Readyset Cache to Ruby on Rails (/cache/connect/ruby-on-rails-with-readyset)
This guide walks you through how to use Readyset Cache with your Ruby on Rails app.
To do this, you'll use the [built-in Rails multiple database support](https://guides.rubyonrails.org/active_record_multiple_databases.html#activating-automatic-role-switching) to get the performance of
caching with the simplicity of a single read replica.

## 0. Set up Readyset Cache

First, you'll set up Readyset Cache using Docker.

1. [Make sure your database is configured for Readyset Cache](/cache/connect)
2. [Install Readyset Cache](/cache/install-rs)

## 1. Configure Rails in three steps

Ruby On Rails allows you to configure Readyset Cache as a read replica and define a time window after writes
for when to switch read traffic over to Readyset Cache. This allows clients to observe recent writes if there is write
traffic ongoing while still taking advantage of Readyset Cache's caching for read-heavy workloads.

This will take three steps. You'll need to add Readyset Cache as a read replica, then configure ActiveRecord to
route traffic, and finally configure Rails' connection switching middleware with a few quick changes.

### a. Update database configuration

Taking advantage of Readyset Cache means defining a read replica of your primary database.
Rails makes this incredibly simple and in the case of Readyset Cache, <b>you'll configure the replica to point
to your Readyset Cache instance</b>. We recommend following Rails established patterns and name your primary
database as `primary` and then your read replica Readyset Cache instance as `primary_replica`.

For instance, your `database.yml` file will look something like this:

```yml
production:
  primary:
    database: my_primary_database
    username: root
    password: <%= ENV['ROOT_PASSWORD'] %>
    adapter: postgresql
  primary_replica:
    database: my_primary_database
    username: root
    password: <%= ENV['READYSET_PASSWORD'] %>
    host: <%= ENV['READYSET_HOST'] %>
    port: 5433
    adapter: postgresql
    replica: true
    database_tasks: false
```

It's important to note that the `primary_replica` definition points to Readyset Cache and that two
flags are set: `replica` is `true` and `database_tasks` is `false`. The `database_tasks` flag
will disable Rails database migrations running against Readyset Cache. This isn't needed as
Readyset Cache will see any changes to the primary database already.

### b. Update `ApplicationRecord` to use two connections

In your application's `app/models` directory, you'll find a base class for all of your model classes
often called `ApplicationRecord`. Open up that class and add the following line:

```ruby
connects_to database: { writing: :primary, reading: :primary_replica }
```

If you haven't made any changes to this base class, it should look like this:

```ruby
class ApplicationRecord < ActiveRecord::Base
  primary_abstract_class

  connects_to database: { writing: :primary, reading: :primary_replica }
end
```

Note how `connects_to database:` is pointing to the names of both the primary database and Readyset Cache
via the names you defined in your `database.yml` configuration.

If you aren't on Rails 7, you'll need to replace `primary_abstract_class` with `self.abstract_class = true`.
What's more, if for some reason you do not have access to an `ApplicationRecord` base class, you'll need to
[monkey patch](https://dev.to/ayushn21/applying-monkey-patches-in-rails-1bj1) one.

### c. Activate connection switching middleware

Finally, you'll need to activate Rails middleware that'll ensure writes go to the primary database and
reads through Readyset Cache. First run this command to generate a configuration file:

```sh
bin/rails generate active_record:multi_db
```

This command will create a new file: `config/initializers/multi_db.rb`. Open up that file and uncomment
the following lines:

```ruby
Rails.application.configure do
  config.active_record.database_selector = { delay: 2.seconds }
  config.active_record.database_resolver = ActiveRecord::Middleware::DatabaseSelector::Resolver
  config.active_record.database_resolver_context = ActiveRecord::Middleware::DatabaseSelector::Resolver::Session
end
```

It's important to note that a delay of 2 seconds is designed to ensure the read replica (in this case Readyset Cache)
is consistent with writes that are going directly to the primary database.

## You're off to the races!

At this point, if you start your Rails application, read requests will go directly to Readyset Cache and
writes will go to your primary Postgres database. You'll next need to configure which SQL select statements (i.e. reads) you'll
want to cache. Check out [our caching guide](/cache/cache#1-creating-a-cache) for more information.


# Readyset Cache (/cache)
Readyset Cache is a SQL caching layer that sits between your application and your primary database. It is wire-compatible with MySQL and Postgres, so you point your application at Readyset Cache by swapping your connection string. Readyset Cache caches the queries you choose and automatically keeps their results up to date as your data changes, while uncached queries are proxied straight through to your database.

We'll cover how to:

1. [Download and install Readyset Cache](/cache/install-rs)
2. [Connect to Readyset Cache](/cache/connect)
3. [Specify which queries to cache](/cache/cache)


# Binaries (/cache/install-rs/binaries)
Readyset Cache can be installed as a stand-alone `systemd` service using a Linux
distribution package.  We currently produce the following packages for both x86\_64/amd64 and arm64/aarch64 architectures:

* `deb` for Debian-based systems running OpenSSL 3 (i.e. Ubuntu 22.04, Debian 12).
* `rpm` for Fedora Core 39 (and compatible distros).
* `rpm` for Amazon Linux 2023.

To install the package:

1. [Download the `deb` or `rpm` package from `Assets` on our GitHub release page](https://github.com/readysettech/readyset/releases/latest).
2. Install `deb` packages using `sudo dpkg -i <PACKAGE_NAME>`.
3. Install `rpm` packages using `sudo rpm -ivh <PACKAGE_NAME>`.

## Configure Readyset Cache Service

The Readyset Cache service must be configured to connect to an upstream database
before it can be started. Edit the default `/etc/readyset/readyset.conf` file
installed by the package and update the `UPSTREAM_DB_URL` to point to the
database.  Additional configuration variables are documented in `readyset.conf`
as well as on [the CLI `options` page](/command-reference).

## Prepare the Database

For directions on how to check and alter these configurations, please see our
[database reference documentation](/cache/connect). The
steps to configure these settings vary by database type and hosting provider.

## Run Readyset Cache Service

Once `readyset.conf` has been updated, the service can be controlled with
[`systemctl`](https://www.linux.org/docs/man1/systemctl.html).  For example,
use:

* `sudo systemctl start readyset` to start the service
* `sudo systemctl stop readyset` to stop the service

The default `readyset.conf` file configures service logging to go to the
`/var/lib/readyset` directory, but that can be changed using the `LOG_PATH`
setting.  If logging to `journalctl` is desired instead, comment out `LOG_PATH`
in `readyset.conf`.

## Uninstalling Readyset Cache Service

**For Ubuntu/Debian:** To uninstall, use `sudo apt remove readyset`.  This will
uninstall the service and executable, but will leave the
`/etc/readyset/readyset.conf` configuration file.  To remove all `readyset`
files entirely, use `sudo apt purge readyset`.

**For Fedora, Amazon Linux, or rpm-based distros:** To uninstall, use `sudo rpm --erase readyset`.  This will uninstall the service and executable.  The
`/etc/readyset/readyset.conf` configuration file will be preserved.  To remove
all readyset files, delete the `/var/lib/readyset` and `/etc/readyset`
directories.


# Docker (/cache/install-rs/docker)
import { Cards, Card } from 'fumadocs-ui/components/card'

Readyset Cache can be installed and run via Docker. Monthly images are stored on [Docker Hub](https://hub.docker.com/r/readysettech/readyset).

<Cards>
  <Card title="Install Readyset Cache with Postgres" href="/cache/install-rs/docker/postgres" />

  <Card title="Install Readyset Cache with MySQL" href="/cache/install-rs/docker/mysql" />
</Cards>


# MySQL (/cache/install-rs/docker/mysql)
This guide walks you through how to run Readyset Cache using Docker, connecting to an existing primary database.

## 0. Make sure you can connect to your primary database.

Ensure your database and user are configured for Readyset Cache to operate by following the [database reference documentation](/cache/connect/mysql).

Readyset Cache needs to be installed on a machine that can communicate with your primary database. To check to make sure that it can,
you can run the following on that instance:

```sh
mysql -u <username> -p -h <database host>
```

If you are able to successfully make the connection, you are ready to move onto the next steps.

## 1. Ensure you have sufficient disk space and memory for Readyset Cache

Any tables referenced by queries that you would like to cache need to be pulled into Readyset Cache. Before installing Readyset Cache,
ensure that the machine that you are installing it on has sufficient disk space and memory to replicate the base tables and
cache queries.

<Callout type="info">
   Note that by default, Readyset Cache will pull in all tables from your database. If you only want to pull in specific
  tables, you will need to set the 

  `--replication-tables`

   flag in Step 3.  
</Callout>

## 2. Download the Readyset Cache Docker image

To download the Readyset Cache Docker image from DockerHub, run the following command in your terminal:

```sh
docker pull readysettech/readyset
```

## 3. Create a Docker volume for persistent cache storage

To persist Readyset Cache's cache data across container restarts, create a Docker volume for storage. This
volume will hold the cache files, preventing data loss when the container is recreated.

Run this command to create a volume named `readyset_cache`:

```sh
docker volume create readyset_cache
```

You will mount this volume into the Readyset Cache container in the next step to enable persistent cache storage.

## 4. Run Readyset Cache

First, find your primary database's connection string.

It should look something like this:

`mysql://<username>:<password>@<host>:<port>/<db_name>`

**By default, Readyset Cache will import all tables.** If you'd like to import all database tables,
you can skip defining a `REPLICATION_TABLES` environment variable. If, however, you'd only like
to import a a subset of your database, then you need to define the list of tables you want to pull
into Readyset Cache as a comma-separated list: `<schema>.<table>, <schema>.<table2>`.
Note, this is optional - you can import all tables too by ignoring this command line flag. If you'd
like to import all of the tables in a given schema, you can specify everything as follows: `<schema name>.*`.

Now, you're ready to start Readyset Cache. In your terminal, run the following command:

```sh
docker run -d -p 3307:3307 -p 6034:6034         \
--name readyset                                 \
-e UPSTREAM_DB_URL=<database connection string> \
-e REPLICATION_TABLES=<specific tables or omit> \
-e LISTEN_ADDRESS=0.0.0.0:3307                  \
-e STORAGE_DIR=/data/cache \
-v readyset_cache:/data/cache \
readysettech/readyset:latest
```

As you can see above, Readyset Cache is exposing two ports: 3307 and 6034. The Readyset Cache
process will listen for query traffic on port 3307 and emits telemetry on port 6034 via
a `/metrics` endpoint. The persistent cache storage volume is mounted at `/data/cache` using the `-v` argument, and the `-e STORAGE_DIR=/data/cache` argument tells Readyset Cache to write to it.
All `-e` environment variables can be
placed into a file and referenced via Docker's `--env-file` flag if you'd rather simply your command
line experience.

<Callout type="info">
   If your database is running locally, you'll need to
  use 

  `host.docker.internal`

   rather than 

  `localhost`

  . 
</Callout>

Readyset Cache will then connect to your database and replicate specified tables (i.e. all or the explictly defined ones).
Depending on how large these tables are and the network connection between Readyset Cache and your database,
this could take between seconds and hours.

To check whether the tables have been imported, run the following:

```sh
docker logs readyset
```

While the snapshot is ongoing, you will see many log messages related to snapshotting progress.

Once you see:

```
INFO replicators::noria_adapter: Streaming replication started
```

Readyset Cache is ready to start caching queries.

Alternatively, you can log into the Readyset Cache [shell](/cache/connect) and run

```sql
SHOW READYSET STATUS;
```

Look at the `Snapshot Status` column. If snapshotting successfully completed,
it'll report `Completed`.

Now Readyset Cache is ready to start caching queries.

## Next Steps

As a next step, you can [connect to Readyset Cache from a database shell ](/cache/connect) or [connect from your application](/cache/connect/connect-an-application-via-an-orm).


# PostgreSQL (/cache/install-rs/docker/postgres)
This guide walks you through how to run Readyset Cache using Docker, connecting to an existing primary database.

## 0. Make sure you can connect to your primary database.

Readyset Cache needs to be installed on a machine that can communicate with your primary database. To check to make sure that it can,
you can run the following on that instance:

```sh
psql -h <ip address> -p <port> -d <database name which you want to connect> -U <username of the database server>
```

If you are able to successfully make the connection, you should be all set.

## 1. Ensure you have sufficient disk space and memory for Readyset Cache

Any tables referenced by queries that you would like to cache need to be pulled into Readyset Cache. Before installing Readyset Cache,
ensure that the machine that you are installing it on has sufficient disk space and memory to replicate the base tables and
cache queries.

<Callout type="info">
   Note that by default, Readyset Cache will pull in all tables from your database. If you only want to pull in specific
  tables, you will need to set the 

  `--replication-tables`

   flag in Step 3.  
</Callout>

## 2. Download the Readyset Cache Docker image

To download the Readyset Cache Docker image from DockerHub, run the following command in your terminal:

```sh
docker pull readysettech/readyset
```

## 3. Create a Docker volume for persistent cache storage

To persist Readyset Cache's cache data across container restarts, create a Docker volume for storage. This
volume will hold the cache files, preventing data loss when the container is recreated.

Run this command to create a volume named `readyset_cache`:

```sh
docker volume create readyset_cache
```

You will mount this volume into the Readyset Cache container in the next step to enable persistent cache storage.

## 4.  Run Readyset Cache

First, find your primary database's connection string.

It should look something like this:

`postgres://<username>:<password>@<host>:<port>/<db_name>`

**By default, Readyset Cache will import all tables.** If you'd like to import all database tables,
you can skip defining a `REPLICATION_TABLES` environment variable. If, however, you'd only like
to import a a subset of your database, then you need to define the list of tables you want to pull
into Readyset Cache as a comma-separated list: `<schema>.<table>, <schema>.<table2>`.
Note, this is optional - you can import all tables too by ignoring this command line flag. If you'd
like to import all of the tables in a given schema, you can specify everything as follows: `<schema name>.*`.

Now, you're ready to start Readyset Cache. In your terminal, run the following command:

```sh
docker run -d -p 5433:5433 -p 6034:6034         \
--name readyset                                 \
-e UPSTREAM_DB_URL=<database connection string> \
-e REPLICATION_TABLES=<specific tables or omit> \
-e LISTEN_ADDRESS=0.0.0.0:5433                  \
-e STORAGE_DIR=/data/cache \
-v readyset_cache:/data/cache \
readysettech/readyset:latest
```

As you can see above, Readyset Cache is exposing two ports: 5433 and 6034. The Readyset Cache process will
listen for query traffic on port 5433 and emits telemetry on port 6034 via a `/metrics` endpoint.  The persistent cache storage volume is mounted at `/data/cache` using the `-v` argument, and the `-e STORAGE_DIR=/data/cache` argument tells Readyset Cache to write to it.
All `-e` environment variables can be placed into a file and referenced via Docker's `--env-file`
flag if you'd rather simplify your command line experience.

<Callout type="info">
   If your database is running locally, you'll need to
  use 

  `host.docker.internal`

   rather than 

  `localhost`

  . 
</Callout>

Connecting to a locally running docker Postgres and importing all tables
in the `locution` database, for instance, would look like this:

```sh
docker run -d -p 5433:5433 -p 6034:6034 --name readyset                            \
-e UPSTREAM_DB_URL=postgres://postgres:locution@host.docker.internal:5432/locution \
-e LISTEN_ADDRESS=0.0.0.0:5433                                                     \
-e STORAGE_DIR=/data/cache \
-v readyset_cache:/data/cache \
readysettech/readyset:latest
```

Readyset Cache will then connect to your database and replicate specified tables (i.e. all or the explictly defined ones).
Depending on how large these tables are and the network connection between Readyset Cache and your database,
this could take between seconds and hours.

To check whether the tables have been imported, run the following:

```sh
docker logs readyset
```

While the snapshot is ongoing, you will see many log messages related to snapshotting progress.

Once you see:

```
INFO replicators::noria_adapter: Streaming replication started
```

Readyset Cache is ready to start caching queries.

Alternatively, you can log into the Readyset Cache shell and run

```sql
SHOW READYSET STATUS;
```

Look at the `Snapshot Status` column. If snapshotting successfully completed,
it'll report `Completed`.

Now Readyset Cache is ready to start caching queries.

## Next Steps

As a next step, you can [connect to Readyset Cache from a database shell ](/cache/connect) or [connect from your application](/cache/connect/connect-an-application-via-an-orm).


# Install Readyset Cache (/cache/install-rs)
import { Cards, Card } from 'fumadocs-ui/components/card'

These guides walk you through the process for downloading, configuring, and running Readyset Cache using
[Docker](/cache/install-rs/docker) or using [Linux binary distribution packages](/cache/install-rs/binaries). For production workloads, we recommend using the Linux binary.

## Database Requirements

For **deep caching**, Readyset Cache snapshots and replicates your tables, which requires the
following database settings:

1. Logical replication must be turned on in your database
2. Readyset Cache must have superuser permissions

For directions on how to check and alter these configurations, please see our
[database reference documentation](/cache/connect). The steps to
configure these settings vary by database
type and hosting provider.

**Shallow caching** is TTL-based and served without snapshotting or replication, so it does not
require these settings. See [Shallow Caching](/concepts/shallow-caching) for details.

## Supported Database Versions

| Database Type | Versions | Support Level |
| ------------- | -------- | ------------- |
| PostgreSQL    | 13.0+    | GA            |
| MySQL         | 8.0+     | GA            |

**GA support** conveys that Readyset Cache has reached General Availability and is fully supported in those contexts.

## Supported Hosting Providers

| Hosting Provider   | Support Level |
| ------------------ | ------------- |
| Self-hosted        | GA            |
| AWS RDS            | GA            |
| AWS Aurora         | GA            |
| Azure SQL Database | Alpha         |
| GCP SQL            | Alpha         |
| Supabase           | Alpha         |
| Aiven for MySQL    | Alpha         |

**Beta support** conveys that Readyset Cache is routinely tested in those contexts.

**Alpha support** conveys that Readyset Cache has previously been validated to work in those contexts, but we don't actively check for regressions.

## Troubleshooting

If you experience any issues, please reach out to us in [Slack](https://join.slack.com/t/readysetcommunity/shared_invite/zt-2272gtiz4-0024xeRJUPGWlRETQrGkFw)
or open a [Github issue](https://github.com/readysettech/readyset/issues/new/choose). We will help you troubleshoot.

<Cards>
  <Card title="Install Readyset Cache with Docker" href="/cache/install-rs/docker" />

  <Card title="Install Readyset Cache on Linux with binary package" href="/cache/install-rs/binaries" />
</Cards>


# Command Reference (/command-reference)
import { Callout } from 'fumadocs-ui/components/callout'

This section provides a reference for the built-in SQL commands for Readyset.

## Cache Management

### `CREATE CACHE`

<div class="option-details" markdown="1">
  Create a new cache entry for a specific `SELECT` statement or `<query id>`.

  **Command** :

  ```sql
  CREATE [DEEP | SHALLOW] CACHE
    [<name>]
    [WITH (<option>[, <option>...])]
    FROM [<query> | <query id>]
  ```

  The optional `DEEP` or `SHALLOW` modifier selects the cache type:

  * `DEEP` builds a materialized view in the dataflow graph.
  * `SHALLOW` stores results in memory and serves them until a TTL expires, without building a materialized view. See [Shallow Caching](/concepts/shallow-caching) for the conceptual overview and [examples](#examples) for sample DDL.
  * With no modifier, the cache type follows the server's [`--cache-mode`](/reference/config-options#--cache-mode) setting, which defaults to `shallow`.

  The `WITH (...)` clause carries a comma-separated list of options. Available options:

  * [`ALWAYS`](#always) — serve from cache inside transactions.
  * [`UNTIL WRITE`](#until-write) — serve from cache for read-only-so-far transactions.
  * [`POLICY TTL`](#policy-ttl), [`REFRESH`](#refresh), [`REFRESH EVERY`](#refresh-every) — TTL and refresh behavior for shallow caches.
  * [`COALESCE`](#coalesce) — coalesce concurrent upstream fetches for shallow caches.
  * [`ADAPTIVE`](#adaptive) — adjust per-entry refresh intervals to observed data change rates.

  `ALWAYS` and `UNTIL WRITE` are mutually exclusive. They control how the cached query is served when the connection is inside a transaction (for example, when a client driver wraps every statement in `BEGIN`/`COMMIT`). With no keyword, the cached query is proxied upstream for the entire transaction.

  #### `UNTIL WRITE`

  Serves the cached query from Readyset for read-only-so-far transactions, and proxies upstream once the transaction observes a write. This is the right choice for client drivers that wrap every statement in an implicit transaction (for example, Python drivers running with `autocommit=False`, JDBC defaults, or ORMs that do not expose autocommit). Reads stay served from Readyset while the transaction is read-only; writes and reads-after-writes are routed upstream so they observe the write set.

  `UNTIL WRITE` is also the default policy for caches created automatically by [`--auto-cache`](/concepts/shallow-caching/auto-caching) and by hint-based auto-creation when no policy keyword is supplied.

  #### `ALWAYS`

  When specified, the cached query is served from Readyset even inside a transaction. Use this for queries that should never be proxied upstream once cached, including the bucket function which requires `ALWAYS`.

  For the broader picture, including read-your-writes outside of transactions, see [Read-your-writes](/concepts/read-your-writes).

  #### `POLICY TTL`

  **Shallow caches only.** The lifetime of each cache entry. Once an entry has not been accessed for this duration, it is considered stale and will be refreshed on the next access.

  If omitted, Readyset uses the server default configured by [`--default-ttl-ms`](/reference/config-options#--default-ttl-ms).

  #### `REFRESH`

  **Shallow caches only.** When a request hits a cache entry that is at least `n` old (in the specified unit), Readyset preemptively issues a background refresh against upstream. The current request receives the existing cached value immediately; the updated result is available for subsequent requests.

  If `REFRESH` is omitted entirely (no `REFRESH` or `REFRESH EVERY` clause), Readyset applies an implicit refresh interval equal to half the TTL.

  Must be less than the TTL.

  #### `REFRESH EVERY`

  **Shallow caches only.** Readyset proactively re-executes the query against upstream on a fixed schedule, regardless of whether any client has requested it. Automatic refreshes continue as long as the cache entry has not been evicted due to TTL expiration.

  <Callout type="warn">
    If the query takes longer to execute than the refresh interval, multiple refreshes for the same key can be in-flight concurrently. This produces consistently fresh results at the cost of higher database query volume. See [database load considerations](/concepts/shallow-caching#database-load-considerations) for guidance on tuning refresh settings.
  </Callout>

  Must be less than the TTL.

  Units can be mixed freely within a single statement (e.g., TTL in seconds and refresh in milliseconds).

  #### `COALESCE`

  **Shallow caches only.** The window during which concurrent requests for the same query and parameter values are coalesced on a cache miss. Only the first request is sent to upstream; the rest wait for its result. This prevents a thundering herd from hitting upstream simultaneously.

  If omitted, Readyset uses the server default configured by [`--default-coalesce-ms`](/reference/config-options#--default-coalesce-ms). Set to `0` to disable coalescing for this cache.

  #### `ADAPTIVE`

  **Shallow caches only.** Adjusts each cache entry's refresh interval to the rate at which its data is observed to change: entries whose results change between refreshes are refreshed more often, and entries whose results stay the same return to the configured interval. The extra upstream load from shortened intervals is capped by [`--shallow-adaptive-max-extra-load-percent`](/reference/config-options#--shallow-adaptive-max-extra-load-percent). See [Adaptive refresh](/concepts/shallow-caching#adaptive-refresh) for details.

  Caches created by [automatic shallow caching](/concepts/shallow-caching/auto-caching) have this option enabled implicitly.

  #### `<name>`

  An optional name for the cache. If omitted, Readyset assigns an identifier automatically. The name can be used with [`DROP CACHE`](#drop-cache) and [`SHOW CACHES`](#show-caches).

  **Result**: On success, returns a single row with the following columns:

  | Column       | Description                                                              |
  | ------------ | ------------------------------------------------------------------------ |
  | `query_id`   | Unique query identifier (e.g., `q_5986a67d37048328`)                     |
  | `name`       | Name of the cache (user-specified or auto-generated from the query hash) |
  | `query`      | The cached SQL query                                                     |
  | `cache_type` | Type of cache created: `deep` or `shallow`                               |

  For examples covering each combination of options, see [the examples below](#examples).
</div>

### `DROP CACHE`

<div class="option-details" markdown="1">
  Drop a cache entry based on a `<query id>` from [`SHOW CACHES`](#show-caches).

  **Command** : `DROP CACHE <query id>`
</div>

### `DROP ALL CACHES`

<div class="option-details" markdown="1">
  Drop all cache entries. The optional `DEEP` or `SHALLOW` modifier restricts the operation to caches of that type; with no modifier, all caches are dropped.

  **Command** : `DROP ALL [DEEP | SHALLOW] CACHES`
</div>

### `DROP ALL PROXIED QUERIES`

<div class="option-details" markdown="1">
  Clear the list of proxied queries shown by [`SHOW PROXIED QUERIES`](#show-proxied-queries).

  **Command** : `DROP ALL PROXIED QUERIES`
</div>

## Shallow Caches

Shallow caches store result sets in memory and serve them until a TTL expires, without building a materialized view. They are created with [`CREATE CACHE`](#create-cache) using the `SHALLOW` modifier and the `POLICY`, `REFRESH`, and `COALESCE` options documented above. For the conceptual overview, see [Shallow Caching](/concepts/shallow-caching).

### Examples

Cache with a 30-second TTL and default refresh behavior (implicit on-access refresh at half the TTL):

```sql
CREATE SHALLOW CACHE WITH (POLICY TTL 30 SECONDS) FROM
  SELECT * FROM products WHERE category_id = $1;
```

Cache with a 60-second TTL and a 10-second on-access refresh:

```sql
CREATE SHALLOW CACHE WITH (POLICY TTL 60 SECONDS REFRESH 10 SECONDS) FROM
  SELECT * FROM sessions WHERE user_id = $1;
```

Cache with a 60-second TTL and a proactive 15-second scheduled refresh:

```sql
CREATE SHALLOW CACHE WITH (POLICY TTL 60 SECONDS REFRESH EVERY 15 SECONDS) FROM
  SELECT count(*) FROM orders WHERE status = $1;
```

Cache with coalescing disabled and a name:

```sql
CREATE SHALLOW CACHE my_cache WITH (POLICY TTL 30 SECONDS, COALESCE 0 SECONDS) FROM
  SELECT * FROM inventory WHERE sku = $1;
```

Cache with sub-second TTL and mixed units:

```sql
CREATE SHALLOW CACHE WITH (POLICY TTL 5 SECONDS REFRESH 500 MILLISECONDS) FROM
  SELECT * FROM leaderboard WHERE game_id = $1;
```

Cache with a scheduled refresh whose per-entry intervals [adapt](/concepts/shallow-caching#adaptive-refresh) to observed data change rates:

```sql
CREATE SHALLOW CACHE WITH (POLICY TTL 60 SECONDS REFRESH EVERY 15 SECONDS, ADAPTIVE) FROM
  SELECT count(*) FROM orders WHERE status = $1;
```

Cache that serves read-only-so-far transactions but proxies upstream after the first write in a transaction:

```sql
CREATE SHALLOW CACHE WITH (UNTIL WRITE) FROM
  SELECT * FROM users WHERE id = $1;
```

### Metrics

The following Prometheus metrics are available for shallow caches. Each metric includes a `query_id` label identifying the cache.

| Metric                                                         | Type      | Description                                                                                                                                                      |
| -------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `readyset_shallow_shallow_result_hit{query_id=...}`            | Counter   | Number of requests served from the cache                                                                                                                         |
| `readyset_shallow_shallow_result_miss{query_id=...}`           | Counter   | Number of requests that missed the cache and went to upstream                                                                                                    |
| `readyset_shallow_shallow_result_refresh{query_id=...}`        | Counter   | Number of background refreshes dispatched for a cache entry                                                                                                      |
| `readyset_shallow_shallow_refresh_changed{query_id=...}`       | Counter   | Number of refreshes of an [adaptive](/concepts/shallow-caching#adaptive-refresh) cache that returned data different from the cached entry                        |
| `readyset_shallow_shallow_refresh_unchanged{query_id=...}`     | Counter   | Number of refreshes of an adaptive cache that returned the same data as the cached entry                                                                         |
| `readyset_shallow_shallow_refresh_queue_exceeded`              | Counter   | Number of refresh requests dropped because all refresh workers were busy; see [`--shallow-refresh-workers`](/reference/config-options#--shallow-refresh-workers) |
| `readyset_shallow_shallow_refresh_query_time_us{query_id=...}` | Histogram | Time in microseconds spent executing the upstream query during a refresh; only recorded for successful queries                                                   |
| `readyset_shallow_shallow_evict_memory`                        | Counter   | Number of cache entries evicted due to memory pressure                                                                                                           |

## `SHOW` Commands

### `SHOW CACHES`

<div class="option-details" markdown="1">
  Display a list of cached queries.

  **Command** : `SHOW [DEEP | SHALLOW] CACHES [WHERE query_id = <query id>]`
</div>

### `SHOW PROXIED QUERIES`

<div class="option-details" markdown="1">
  Display a list of proxied queries to upstream alongside with a status indicating if Readyset can cache the query. Optionally, users can filter only **SUPPORTED** queries.

  **Command** :

  ```sql
  SHOW PROXIED [SUPPORTED] [DEEP | SHALLOW] QUERIES
    [WHERE query_id = <query id>]
    [LIMIT <n>]
  ```

  The `DEEP` or `SHALLOW` modifier restricts the listing to queries Readyset would route to that cache type. `WHERE query_id = <query id>` returns just that one entry; `LIMIT <n>` caps the number of rows returned.
</div>

### `SHOW CONNECTIONS`

<div class="option-details" markdown="1">
  Display a list of client connections. Each row shows the client address, the authenticated username, and the upstream server (`host:port`) the session uses.

  **Command** : `SHOW CONNECTIONS`
</div>

### `SHOW READYSET STATUS`

<div class="option-details" markdown="1">
  Display current Readyset server status.

  **Command** : `SHOW READYSET STATUS`
</div>

### `SHOW READYSET STATUS ADAPTER`

<div class="option-details" markdown="1">
  Display current Readyset adapter status.

  **Command** : `SHOW READYSET STATUS ADAPTER`
</div>

### `SHOW READYSET MIGRATION STATUS`

<div class="option-details" markdown="1">
  Display the migration status for a specific migration id.

  **Command** : `SHOW READYSET MIGRATION STATUS <migration id>`
</div>

### `SHOW READYSET VERSION`

<div class="option-details" markdown="1">
  Display information about the current Readyset version.

  **Command** : `SHOW READYSET VERSION`
</div>

### `SHOW READYSET TABLES`

<div class="option-details" markdown="1">
  Display the list of replicated tables and their statuses. Optionally, the `ALL` keyword extends the listing to include non-replicated tables from the upstream.

  **Command** : `SHOW READYSET [ALL] TABLES`
</div>

### `SHOW READYSET RSA PUBLIC KEY`

<div class="option-details" markdown="1">
  Display the RSA public key used by Readyset for `caching_sha2_password` full-authentication exchanges. Clients that connect over a non-TLS channel need this key to encrypt their password before sending it to the server.

  The result is a single row with one column (`Caching_sha2_password_rsa_public_key`) containing the PEM-encoded public key.

  **Command** : `SHOW READYSET RSA PUBLIC KEY`

  See [Authentication](/reference/authentication) for more information on `caching_sha2_password`.
</div>

### `SHOW REPLAY PATHS`

<div class="option-details" markdown="1">
  List active replay paths in the dataflow graph.

  **Command** : `SHOW REPLAY PATHS`
</div>

## `EXPLAIN` Commands

### `EXPLAIN CACHES`

<div class="option-details" markdown="1">
  List all `CREATE CACHE` statements that have been executed, for the purpose of exporting them.

  **Command** : `EXPLAIN CACHES`
</div>

### `EXPLAIN CREATE CACHE`

<div class="option-details" markdown="1">
  Display information about how Readyset will interpret a specific query, including whether the query is supported or not.

  **Command** : `EXPLAIN CREATE [DEEP | SHALLOW] CACHE FROM <query>`
</div>

### `EXPLAIN DOMAINS`

<div class="option-details" markdown="1">
  List domains and the worker they're running on.

  **Command** : `EXPLAIN DOMAINS`
</div>

### `EXPLAIN GRAPHVIZ`

<div class="option-details" markdown="1">
  Print a graphviz representation of the current query graph to stdout. `SIMPLIFIED` produces a less detailed graph; `FOR CACHE <query id>` scopes the output to the subgraph supporting one cache.

  **Command** : `EXPLAIN [SIMPLIFIED] GRAPHVIZ [FOR CACHE <query id>]`
</div>

### `EXPLAIN MATERIALIZATIONS`

<div class="option-details" markdown="1">
  List and give information about all materializations in the graph.

  **Command** : `EXPLAIN MATERIALIZATIONS [FOR CACHE <query id>]`
</div>

### `EXPLAIN LAST STATEMENT`

<div class="option-details" markdown="1">
  Provides metadata about the last statement that was executed on this connection:

  * `Query_destination` — where the statement was answered (`readyset`, `readyset_shallow`, `upstream`, ...).
  * `Readyset_reason` — the Readyset-side error for the statement, or why it was routed to the upstream even though Readyset holds a cache for it: an open transaction's cache policy (`trx`, `trx_after_write`), a `/*rs+ ... */` skip hint (`hint`), a [read-your-writes window](/concepts/read-your-writes) (`opportunistic_ryw`), or [cache authorization](/reference/cache-authorization) (`cache_acl_denied`, `cache_acl_unknown`, `cache_acl_untrusted`). `ok` when the statement was served from a cache or no cache applies.

  **Command** : `EXPLAIN LAST STATEMENT`
</div>

## `ALTER READYSET` Commands

### `ALTER READYSET STOP REPLICATION`

<div class="option-details" markdown="1">
  Stop the replication stream from the upstream database. While stopped, Readyset continues to serve cached data but does not receive new changes. Use this as the first step in a [failover](/reference/failover) procedure.

  Returns an error if replication is already stopped.

  **Command** : `ALTER READYSET STOP REPLICATION`
</div>

### `ALTER READYSET START REPLICATION`

<div class="option-details" markdown="1">
  Resume the replication stream after it has been stopped with [`ALTER READYSET STOP REPLICATION`](#alter-readyset-stop-replication). Readyset reconnects to the upstream database (or the new upstream set via [`ALTER READYSET CHANGE CDC`](#alter-readyset-change-cdc)) and begins replicating from the stored replication position.

  Returns an error if replication is already running.

  **Command** : `ALTER READYSET START REPLICATION`
</div>

### `ALTER READYSET SET REPLICATION POSITION`

<div class="option-details" markdown="1">
  Set the replication position for all tables. Replication must be stopped before running this command. The position format depends on the database:

  * **MySQL binlog file and position:** `'binlog.000003:154'`
  * **MySQL GTID:** `'uuid:1-10'` or a comma-separated GTID set
  * **PostgreSQL LSN:** `'0/16B3748'`

  Switching between MySQL position types (binlog file/position and GTID) is allowed. Switching between MySQL and PostgreSQL is not.

  <Callout type="info">
    For PostgreSQL failover, this command is not needed. See [Failover](/reference/failover) for details.
  </Callout>

  **Command** : `ALTER READYSET SET REPLICATION POSITION '<position>'`
</div>

### `ALTER READYSET CHANGE CDC`

<div class="option-details" markdown="1">
  Replace the CDC (Change Data Capture) connection URL or [server list](/reference/config-options#--cdc-db-url) that Readyset uses for replication. Use it during [failover](/reference/failover) to point Readyset at a new upstream, or to keep the list of failover servers up to date.

  The `<url>` must be a connection URL for the same database type as the upstream (e.g. `mysql://<user>:<password>@host/db` or `postgresql://<user>:<password>@host/db`). For MySQL, it can also be a comma-separated list of URLs, each with an optional `|<weight>` suffix from 1 to 100 (default 50). Encode a `,` inside a password as `%2C`.

  If replication's current server is still in the new list, replication keeps running on it. Otherwise, it restarts on the new list.

  **Command** : `ALTER READYSET CHANGE CDC TO '<url>'`
</div>

### `ALTER READYSET CHANGE UPSTREAM`

<div class="option-details" markdown="1">
  Replace the upstream URL or [server list](/reference/config-options#--upstream-db-url) that Readyset sends client traffic to.

  The `<url>` takes the same form as in [`ALTER READYSET CHANGE CDC`](#alter-readyset-change-cdc). The statement returns one row per server with its result: `unchanged`, `verified`, `unreachable, marked down`, or `warning`. Warnings (such as a different server version) will not stop this operation from completing.

  Readyset closes any session whose upstream server left the list, and the client picks a server from the new list when it reconnects. Other sessions keep running.

  **Command** : `ALTER READYSET CHANGE UPSTREAM TO '<url>'`
</div>

### `ALTER READYSET ADD USER`

<div class="option-details" markdown="1">
  Add a user to the set of users allowed to authenticate with Readyset. Requires authentication to be enabled. The change is persisted, so it survives restarts and overrides the [`--allowed-users`](/reference/config-options#--allowed-users) bootstrap, and the new user can connect immediately. See [User Management](/reference/user-management) for the full lifecycle.

  <Callout type="info">
    The list of allowed users can be inspected by querying the `readyset.users` virtual relation, for example `SELECT user FROM readyset.users` (on PostgreSQL, quote the column: `SELECT "user" FROM readyset.users`). Only usernames are returned; passwords are never exposed.
  </Callout>

  **Command** : `ALTER READYSET ADD USER '<user>' PASSWORD '<password>'`
</div>

### `ALTER READYSET MODIFY USER`

<div class="option-details" markdown="1">
  Rotate the password of an existing allowed user. Requires authentication to be enabled. The user derived from [`--upstream-db-url`](/reference/config-options#--upstream-db-url) cannot be modified, since that identity backs Readyset's upstream connectivity.

  `RETAIN CURRENT PASSWORD` keeps the current password valid alongside the new one, and `DISCARD OLD PASSWORD` retires it once all clients have updated. See [password rotation](/reference/user-management#rotating-a-password-without-downtime). Both clauses require MySQL mode.

  **Command** : `ALTER READYSET MODIFY USER '<user>' PASSWORD '<password>' [RETAIN CURRENT PASSWORD]`

  **Command** : `ALTER READYSET MODIFY USER '<user>' DISCARD OLD PASSWORD`
</div>

### `ALTER READYSET DROP USER`

<div class="option-details" markdown="1">
  Remove a user from the set of users allowed to authenticate with Readyset. Requires authentication to be enabled. The user derived from [`--upstream-db-url`](/reference/config-options#--upstream-db-url) cannot be dropped.

  **Command** : `ALTER READYSET DROP USER '<user>'`
</div>

### `ALTER READYSET FLUSH PRIVILEGES`

<div class="option-details" markdown="1">
  Re-check every user's privileges against the upstream database immediately, instead of waiting for the next [cache authorization](/reference/cache-authorization) refresh interval. Run it right after a `GRANT` or `REVOKE` on the upstream to apply the change to cache serving at once. Requires authentication to be enabled.

  <Callout type="info">
    Any authenticated user may run this command: it can only trigger re-validation against the upstream, so the worst case is one pass of privilege checks.
  </Callout>

  **Command** : `ALTER READYSET FLUSH PRIVILEGES`
</div>

### `ALTER READYSET RESNAPSHOT TABLE`

<div class="option-details" markdown="1">
  Resnapshot one specific table.

  **Command** : `ALTER READYSET RESNAPSHOT TABLE [db.table]`
</div>

### `ALTER READYSET ADD TABLES`

<div class="option-details" markdown="1">
  Add new tables to Readyset that have either been excluded from [`--replication-tables-ignore`](/reference/config-options#--replication-tables-ignore) or omitted from [`--replication-tables`](/reference/config-options#--replication-tables). The command accepts a single table or a list of table comma-delimited.

  <Callout type="info">
    The same change should be adjusted in the `.cnf` in order to make it persistent across restarts.
  </Callout>

  The command also recovers a table that was dropped because its snapshot failed: it re-enables replication for the table and snapshots it. No `.cnf` change is needed in that case; see [Snapshotting](/reference/snapshots#when-a-table-snapshot-fails).

  **Command** : `ALTER READYSET ADD TABLES [db.table, db.table2]`
</div>

### `ALTER READYSET ENTER MAINTENANCE MODE`

<div class="option-details" markdown="1">
  Enter maintenance mode is meant to inform external tools like ProxySQL that Readyset is in maintenance mode and it should stop sending queries to Readyset.

  **Command** : `ALTER READYSET ENTER MAINTENANCE MODE`
</div>

### `ALTER READYSET EXIT MAINTENANCE MODE`

<div class="option-details" markdown="1">
  Exit maintenance mode is meant to inform external tools like ProxySQL that Readyset is no longer in maintenance mode and it should resume sending queries to Readyset.

  **Command** : `ALTER READYSET EXIT MAINTENANCE MODE`
</div>

### `ALTER READYSET SET LOG LEVEL`

<div class="option-details" markdown="1">
  Dynamically change the log level of a running Readyset process without restarting it. The new level applies immediately to the adapter or server connected to and is not persisted across restarts. To make the change permanent, also update [`--log-level`](/reference/config-options#--log-level) (or the `LOG_LEVEL` environment variable).

  The directive string accepts the same syntax as [`--log-level`](/reference/config-options#--log-level): a single severity (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`), or a comma-separated list of per-module directives such as `info,readyset_server=debug`. See the [tracing library docs](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) for the full directive syntax.

  <Callout type="info">
    `ALTER READYSET SET LOG LEVEL` only affects the process serving the connection. In a deployment with multiple adapters and a separate server, run the command against each process whose log level you want to change.
  </Callout>

  **Command** : `ALTER READYSET SET LOG LEVEL '<directives>'`

  Examples:

  ```sql
  ALTER READYSET SET LOG LEVEL 'debug';
  ALTER READYSET SET LOG LEVEL 'info,readyset_server=debug,replicators=trace';
  ```
</div>

## MCP Commands

Used to administer Bearer tokens for the embedded MCP HTTP endpoint. See the [MCP Server](/readyset-ai/mcp-server) page for the full user guide.

### `CREATE MCP TOKEN`

<div class="option-details" markdown="1">
  Create a new MCP Bearer token and return its raw value. The value is shown exactly once. Only the SHA-256 hash is stored.

  **Command** : `CREATE MCP TOKEN '<name>' [WITH SCOPE {read_only | cache_admin | full}] [EXPIRES '<rfc3339-datetime>']`

  Examples:

  ```sql
  CREATE MCP TOKEN 'claude-desktop';
  CREATE MCP TOKEN 'claude-desktop' WITH SCOPE cache_admin;
  CREATE MCP TOKEN 'claude-desktop' WITH SCOPE full EXPIRES '2027-01-01T00:00:00Z';
  ```
</div>

### `SHOW MCP TOKENS`

<div class="option-details" markdown="1">
  List all stored MCP tokens with their name, scope, creation timestamp, and expiration. Raw values and hashes are not returned.

  **Command** : `SHOW MCP TOKENS`
</div>

### `ALTER MCP TOKEN`

<div class="option-details" markdown="1">
  Change the expiration on an existing token without rotating its value. Use this to extend a soon-to-expire token or remove the expiration entirely.

  **Command** : `ALTER MCP TOKEN '<name>' SET {EXPIRES '<rfc3339-datetime>' | NEVER EXPIRES}`

  Examples:

  ```sql
  ALTER MCP TOKEN 'claude-desktop' SET EXPIRES '2028-01-01T00:00:00Z';
  ALTER MCP TOKEN 'claude-desktop' SET NEVER EXPIRES;
  ```
</div>

### `DROP MCP TOKEN`

<div class="option-details" markdown="1">
  Immediately revoke an MCP token. Requests using the dropped token receive HTTP 401 on the next call.

  **Command** : `DROP MCP TOKEN '<name>'`
</div>


# Deep Caching (/concepts/deep-caching)


















**Deep caching** is Readyset's dataflow-based caching engine. It turns even the most complex SQL reads into **lightning fast lookups** with **no extra code** by maintaining query results incrementally as your data changes, rather than recomputing them on each read.

Readyset slots between your application and database. It is wire-compatible with both MySQL and Postgres, so all you have to
do to start using Readyset is swap out your database connection string. Readyset gives you fine-grained control over which
queries are cached. Queries that aren't cached are proxied through Readyset.

<img alt="Deep Cache" src={__img0} />

## Research origins

Deep caching grew out of [Noria](https://pdos.csail.mit.edu/papers/noria:osdi18.pdf), a research project from MIT's Computer Science and Artificial Intelligence Laboratory (CSAIL). Noria introduced **partially-stateful dataflow**: a long-lived dataflow graph that incrementally maintains query results as the underlying data changes, while materializing only the subset of state that queries actually demand and evicting the rest under memory pressure. This is the partial materialization model that lets Readyset cache complex queries without holding entire result sets in memory.

Noria was published as ["Noria: dynamic, partially-stateful dataflow for high-performance web applications"](https://www.usenix.org/conference/osdi18/presentation/gjengset) at OSDI 2018. Readyset is the production system built on those ideas.

## How does deep caching work under the hood?

Imagine a basic online forum application with `posts`, `users`, and `upvotes`. A simple database schema for this application might look like:

<img alt="Example DB Schema" src={__img1} placeholder="blur" />

You can imagine a query like the one below, which returns all of the posts authored by a particular user:

```sql
    SELECT
      posts.title, posts.id, users.username
    FROM
        posts
    INNER JOIN
        users
    WHERE
        posts.author_id = users.id AND users.id = ?;
```

Under the hood, Readyset constructs a **dataflow graph** for the query. Each node of the graph is updated when writes occur, keeping the query results up to date.

The graph for the query would look something like this:

<img alt="Example Readyset Dataflow Graph" src={__img2} placeholder="blur" />

Once the graph is constructed, if a user queries all of the posts authored by user id 4, Readyset has the results ready so reads can be performed with **no additional compute**.
Results are therefore returned instantaneously, regardless of the size of your database.

## How does Readyset handle more complex queries?

One of the biggest advantages of this model is that latencies are not affected by query complexity. Let's take a look at a few more queries in this application:

Here's a point query for an article:

```sql
SELECT * FROM posts WHERE id = ?;
```

And here's a query for the total upvote count of an article:

```sql
SELECT
    id, author_id, title, vcount
FROM
    posts
JOIN
    (SELECT post, COUNT(*) AS vcount
                FROM upvotes GROUP BY post)
AS
    VoteCount
ON
    VoteCount.post = posts.id WHERE posts.id = ?;
```

In traditional database settings, as queries get more complex, performance can seriously suffer. To work around this, developers denormalize data or implement out-of-band caching solutions that require extra application logic to keep in sync with the database.
With Readyset, read performance is not impacted by the size of the base tables or query complexity.

## Streaming Dataflow

The basic premise of [streaming dataflow](https://en.wikipedia.org/wiki/Stream_processing) is that a [series of operations](#operations) is applied to each element of a [stream](#stream) (a given sequence of data).

### Stream

The stream that Readyset deals with is the sequence of **inserts of new records** to your database and **updates of existing records** in the database.

Databases typically refer to the stream as either the binary log or replication stream.

Readyset receives this stream as input by registering itself as a [read replica of your primary database](https://dev.mysql.com/doc/internals/en/replication.html).

### Operations

Operations transform the stream in some way.

Readyset applies SQL operations over this data change stream to compute the results of the SQL queries you want to cache. When Readyset receives a new SQL query, it first creates a query plan, which consists of the ordered sequence of transformations over the data in the base tables that needs to be applied to compute the correct query result. Readyset then instantiates a long-lived **dataflow graph** that actually executes these operations in the query plan over the incoming data stream.

The entry points of Readyset's dataflow graph are referred to as **base table nodes**, which represent the underlying database tables. Incoming data changes enter the graph via the base tables, before flowing through the rest of the operators in the graph.

Below the base table nodes are **internal nodes**. Each internal node computes a specific SQL operator (e.g., joins, aggregates, projections, and filters) over the incoming stream of data changes. Each node tracks the results of these operations, keeping them up to date in real-time in memory.

Whenever a new element in the stream is received by Readyset, it is first updated in the base table node. The change then "flows" downstream, through the internal nodes of the graph. Each internal node updates its in-memory state before passing the change downstream through the graph.

Leaf nodes in the graph have no downstream nodes. These nodes are called **reader nodes**, storing the result set associated with a given query.

<img alt="" src={__img3} placeholder="blur" />

## Things to consider

### Memory Overhead

There's no free lunch– Readyset trades off the cost of maintaining the dataflow graph in memory for excellent read performance. However, there are a few key ways we can mitigate this cost, such as
through **partial materialization**. You can think of partial materialization as a demand-driven cache-filling mechanism. With it, only a subset of the query results are stored in memory
based on common input parameters to the query. For example, if a query is parameterized on user IDs, then Readyset would only cache the results of
that query for the active subset of users, since they are the ones issuing requests. Once Readyset surpasses a developer-specified memory limit,
cache entries are evicted from memory based on a specified eviction strategy (e.g., LRU).

Readyset also makes it easy to cache only the subset of your queries that have the highest impact on read performance. You can use the Readyset
dashboard to profile your existing workload and make caching decisions based on query frequency and the current latencies.
If some of your queries don't need additional read performance boosts, you can continue proxying them to the customer database. As a result, they
won't take up any memory real estate in your Readyset deployment.

### No Strong Consistency

Readyset is **eventually consistent**. There will be a small delay between when the write is issued and the cached result is updated in Readyset to reflect that write. This might not be suitable for all applications, or all parts of an application.

## Example

To illustrate these concepts, we will walk through an example of using Readyset for a news forum application inspired by HackerNews.

### Schema

First we define two tables to keep track of HackerNews stories and votes.

`CREATE TABLE stories (id int, author text, title text, url text); `

`CREATE TABLE votes (user int, story_id int);`

### Query

Next, we'll write a query that computes the vote count for each story and joins the
vote counts with other story metadata such as the author, title, and ID.

```
SELECT id, author, title, url, vcount
FROM stories
JOIN (SELECT story_id, COUNT(*) AS vcount
            FROM votes GROUP BY story_id)
AS VoteCount
ON VoteCount.story_id = stories.id WHERE stories.id = ?;

```

### Caching with Readyset

Traditional databases would compute the results of this query from scratch every time it was issued. Readyset takes a
different approach and instead precomputes and incrementally maintains the results of this query for commonly read keys.
To accomplish this, Readyset creates a streaming dataflow graph, as described in the [Streaming Dataflow](#streaming-dataflow) section above. At a high level, the
dataflow graph would look as follows:

<img alt="Vote Count" src={__img4} placeholder="blur" />

Under the hood, here's what some of the internal state might look like for this graph.

<img alt="Vote Count Specific" src={__img5} placeholder="blur" />

Now, we'll take a look at what happens when the data changes. Let's say that we add a record to the Votes table to
reflect the fact that Justin voted for the story with ID `2`. This update would first be applied to the Votes base table at
the root of the graph, and then be propagated through the graph, updating all children nodes along that way.
The figure below shows the modified state at each node as the result of this write.

<img alt="Write Prop" src={__img6} />

When performing a read (i.e., executing the prepared statement), we're essentially just doing a key-value lookup for the parameter
value on the relevant column of the reader node.

<img alt="prepread" src={__img7} placeholder="blur" />
<img alt="prepread2" src={__img8} placeholder="blur" />

In this case, we're doing a lookup for key `2` on the `ID` column of the reader node. These lookups are blazingly fast, since reader
nodes are lock-free, in-memory data structures.


# Supported Queries (/concepts/deep-caching/queries)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

This page describes the specific query structures that are cacheable in Readyset.

<Callout>
   The easiest way to determine whether your queries are supported is to run them against Readyset and check the output of 

  [`SHOW PROXIED QUERIES`](/command-reference#show-proxied-queries)

  , or run 

  [`EXPLAIN CREATE CACHE FROM [YOUR_QUERY]`](/command-reference#explain-create-cache)

   command to see if the query is supported. 
</Callout>

## Query Structure

Readyset supports the following clauses in SQL SELECT queries:

* `SELECT` with a list of select expressions, all of which must be supported expressions (see “[Expressions](#expressions)”)
  * Readyset does not support scalar subqueries in the `SELECT` clause
* `DISTINCT`, modifying the select clause
* `OVER([PARTITION BY ..] [ORDER BY ..])` also known as Window Functions
* `FROM`, with a list of tables (which may be implicitly joined), and (uncorrelated) subqueries
* `JOIN` (see ["Joins"](#joins))
* `WHERE`
  * The `WHERE` clause must have a single condition [expression](#expressions)
* `GROUP BY`, with a list of **column references**
  * Readyset does not support expressions or field positions in the `GROUP BY` clause
* `HAVING`
* `ORDER BY`, with a list of [expression](#expressions), an optional ASC or DESC specifier, and an optional `NULLS FIRST` or `NULLS LAST`
* `LIMIT`
* `OFFSET`

There are specific top-level clauses and other query conditions that Readyset does not yet support.

Notably, Readyset does not support any of the following (this is not an exhaustive list):

* `UNION`, `INTERSECT`, or `EXCEPT` as operators to combine multiple `SELECT` statements

<Callout>
  Support for additional operators is always expanding! Reach out to us on 

  [Slack](https://join.slack.com/t/readysetcommunity/shared_invite/zt-2272gtiz4-0024xeRJUPGWlRETQrGkFw)

  , or 

  [open an issue](https://github.com/readysettech/readyset/issues/new/choose)

   in our GitHub repository if you need an unsupported feature and we'll look into it.
</Callout>

## Joins

Readyset supports the below forms of the SQL `JOIN` clause:

* `LEFT` and `INNER` joins are supported
* the right-hand side of a join may be a subquery, and if preceded with `LATERAL`, might be correlated with the preceding items.

The primary limitation is on the **condition** of a JOIN. If using the `ON` clause with a join condition expression, the condition may only be either a single equality comparison between a column on a table appearing outside the join (or a function call with such column as an argument) and the join table (or subquery), or multiple such expressions combined using AND. For example, the following queries are supported:

```sql
select * from t1
join t2 on t1.id = t2.t1_id
select * from t1
join t2 on lower(t1.id) = lower(t2.t1_id)
select * from t1
join t2 on t1.x = t2.x AND t1.y = t2.y
select * from t1
join t2 on t1.x = t2.x
join t3 on t1.y = t3.y
```

But the following queries are not supported:

```sql
-- This query doesn't compare a column in one table to a column in another table
select * from t1 join t2 on t1.x = t1.y
-- This query doesn't compare using equality
select * from t1 join t2 on t1.x > t2.x
-- This query doesn't combine its equality join keys with AND
select * from t1 join t2 on t1.x = t2.x OR t1.y = t2.y
```

In addition, multiple tables specified in the FROM clause can be **implicitly** joined, but only if there is a condition in the WHERE clause that follows the above requirements when expressed in conjunctive normal form. For example, the following query is supported:

```sql
select * from t1, t2 where t1.x = t2.x
```

but the following query is not:

```sql
select * from t1, t2 where t1.x = t1.y
```

## Expressions

Readyset supports most standard SQL expressions. We are continuously expanding coverage to ensure compatibility with the broadest range of MySQL and PostgreSQL workloads.

## Parameters

Readyset uses the **parameters** in a prepared statement, specified either positionally (using `?`) or numbered (using `$1`, `$2`, etc.), as the **key** that enables storing only certain result sets for each query. Readyset will automatically turn literal values in certain positions in queries into parameters, but only supports certain positions for **user-specified parameters** in queries:

* Parameters can only appear in the `WHERE` clause of the outermost `SELECT` statement in a query (e.g., not in any subqueries).
  * Parameters are only supported in the `WHERE` clause of a query if, when expressed in conjunctive normal form, all conjunctive subexpressions of the expression in the `WHERE` clause either contain no parameters, or can be expressed as a single equality comparison between a column and a parameter, **or** are an `IN` expression where the right-hand side consists of a list of **only** parameters (Readyset does not support mixing parameters and other types of expressions on the right-hand side of an `IN` expression).
  * Readyset contains experimental support for conditions that consist of an **inequality** comparison between a parameter and a column (`>`, `>=`, `<` and `<=`)
* Parameters can also appear as the value of the `LIMIT` or `OFFSET` clause of a query.

### Limitations of `IN`

When the IN clause is used with parameters, queries may not contain the following elements:

* Some aggregate functions (`AVG`, or `GROUP_CONCAT`)

These limitations do not apply when the right-hand side of the `IN` clause does not contain any query parameters.

## Schema

Check out the [Supported Data Types](/concepts/deep-caching/supported-data-types) page for more information on the data types that Readyset supports.

### Miscellaneous schema support

Readyset does not support [schemas](https://www.postgresql.org/docs/current/ddl-schemas.html) (namespaces for tables).

## Character sets & collations

Readyset stores all strings internally as UTF-8. We currently support the following list of collations:

<CollationList
  fallbackCollations={[
  'Failed to fetch collations'
]}
/>

<Callout>
  Contact us if you need to add a collation that is not listed here.
</Callout>


# Supported Data Types (/concepts/deep-caching/supported-data-types)
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Readyset takes an initial snapshot of tables from a primary database and uses the database's replication stream to keep the snapshot (and cached query results) up to date as the tables change.
To successfully snapshot and replicate a table, Readyset must support the data types of the columns, the character set in which the data is encoded, and any modifications to the table via writes and schema changes.

The scope of data types, character sets, and table changes supported by Readyset are described below.

<Tabs className="data-types-tables" items={['Postgres', 'MySQL']}>
  <Tab>
    **Numeric types**

    | Type                                                                                                            | Supported | Notes |
    | --------------------------------------------------------------------------------------------------------------- | --------- | ----- |
    | [`INT SMALLINT BIGINT`](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-INT)             | ✔️        |       |
    | [`DECIMAL NUMERIC`](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL)     | ✔️        |       |
    | [`FLOAT DOUBLE PRECISION REAL`](https://dev.mysql.com/doc/refman/8.0/en/floating-point-types.html)              | ✔️        |       |
    | [`SERIAL SMALLSERIAL BIGSERIAL`](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) | ✔️        |       |

    **Monetary types**

    | Type                                                                   | Supported | Notes |
    | ---------------------------------------------------------------------- | --------- | ----- |
    | [`MONEY`](https://www.postgresql.org/docs/current/datatype-money.html) | ✖️        |       |

    **Character types**

    | Type                                                                                                         | Supported | Notes |
    | ------------------------------------------------------------------------------------------------------------ | --------- | ----- |
    | [`CHAR VARCHAR TEXT`](https://www.postgresql.org/docs/current/datatype-character.html)                       | ✔️        |       |
    | [`"CHAR"`](https://www.postgresql.org/docs/current/datatype-character.html#DATATYPE-CHARACTER-SPECIAL-TABLE) | ✔️        |       |
    | [`CITEXT`](https://www.postgresql.org/docs/15/citext.html)                                                   | ✔️        |       |

    **Binary types**

    | Type                                                                    | Supported | Notes |
    | ----------------------------------------------------------------------- | --------- | ----- |
    | [`BYTEA`](https://www.postgresql.org/docs/current/datatype-binary.html) | ✔️        |       |

    **Date and time types**

    | Type                                                                                           | Supported | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
    | ---------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | [`DATE TIME TIMETZ TIMESTAMP`](https://www.postgresql.org/docs/current/datatype-datetime.html) | ✔️        |                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
    | [`TIMESTAMPTZ`](https://www.postgresql.org/docs/current/datatype-datetime.html)                | ✔️        | Rendered as a UTC wallclock; the session [`TimeZone`](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE) is not applied to query results. Session `TimeZone` must be `UTC` (or an equivalent like `+00:00`, `Etc/UTC`, `GMT`, `Universal`, or `Zulu`); `SET TIME ZONE` to any other value is treated as an unsupported `SET` and, by default, causes the connection to proxy to the upstream rather than serve from cache. |
    | [`INTERVAL`](https://www.postgresql.org/docs/current/datatype-datetime.html)                   | ✖️        |                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

    **Boolean typess**

    | Type                                                                       | Supported | Notes |
    | -------------------------------------------------------------------------- | --------- | ----- |
    | [`BOOLEAN`](https://www.postgresql.org/docs/current/datatype-boolean.html) | ✔️        |       |

    **Enumerated types**

    | Type                                                                 | Supported | Notes |
    | -------------------------------------------------------------------- | --------- | ----- |
    | [`ENUM`](https://www.postgresql.org/docs/current/datatype-enum.html) | ✔️        |       |

    **Geometric types**

    | Type                                                                                                         | Supported | Notes                                                                                                                                  |
    | ------------------------------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
    | [PostGIS `GEOMETRY(POINT)`](https://postgis.net/workshops/postgis-intro/geometries.html)                     | ✔️        | As of stable-250522. PostGIS `GEOMETRY` columns are replicated, but only `POINT` values can be used, and only `ST_AsWKT` is supported. |
    | [`POINT LINE LSEG BOX PATH POLYGON CIRCLE`](https://www.postgresql.org/docs/current/datatype-geometric.html) | ✖️        | Native Postgres spatial types are not supported.                                                                                       |

    **Network address typess**

    | Type                                                                                            | Supported | Notes |
    | ----------------------------------------------------------------------------------------------- | --------- | ----- |
    | [`INET`](https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-INET)         | ✖️        |       |
    | [`CIDR`](https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-CIDR)         | ✖️        |       |
    | [`MACADDR	`](https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-MACADDR)  | ✖️        |       |
    | [`MACADDR8`](https://www.postgresql.org/docs/current/datatype-net-types.html#DATATYPE-MACADDR8) | ✖️        |       |

    **Bit string types**

    | Type                                                                          | Supported | Notes                                       |
    | ----------------------------------------------------------------------------- | --------- | ------------------------------------------- |
    | [`BITBIT VARYING`](https://www.postgresql.org/docs/current/datatype-bit.html) | ✔️        | Readyset ignores the optional length field. |

    **Text search types**

    | Type                                                                                             | Supported | Notes |
    | ------------------------------------------------------------------------------------------------ | --------- | ----- |
    | [`tsvector`](https://www.postgresql.org/docs/current/datatype-textsearch.html#DATATYPE-TSVECTOR) | ✖️        |       |
    | [`tsquery`](https://www.postgresql.org/docs/current/datatype-textsearch.html#DATATYPE-TSQUERY)   | ✖️        |       |

    **UUID types**

    | Type                                                                 | Supported | Notes |
    | -------------------------------------------------------------------- | --------- | ----- |
    | [`UUID`](https://www.postgresql.org/docs/current/datatype-uuid.html) | ✔️        |       |

    **XML types**

    | Type                                                               | Supported | Notes |
    | ------------------------------------------------------------------ | --------- | ----- |
    | [`XML`](https://www.postgresql.org/docs/current/datatype-xml.html) | ✖️        |       |

    **JSON types**

    | Type                                                                       | Supported | Notes                                                                    |
    | -------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------ |
    | [`JSON JSONB`](https://www.postgresql.org/docs/current/datatype-json.html) | ✔️        | JSON/JSONB data is replicated. Users can read the JSON/JSONB data as is. |

    **Array types**

    | Type                                                            | Supported | Notes |
    | --------------------------------------------------------------- | --------- | ----- |
    | [`ARRAY	`](https://www.postgresql.org/docs/current/arrays.html) | ✔️        |       |

    **Composite data types**

    | Type                                                                             | Supported | Notes |
    | -------------------------------------------------------------------------------- | --------- | ----- |
    | [`CREATE TYPE <name> AS`](https://www.postgresql.org/docs/current/rowtypes.html) | ✖️        |       |

    **Range types**

    | Type                                                                                                                  | Supported | Notes |
    | --------------------------------------------------------------------------------------------------------------------- | --------- | ----- |
    | [`INT4RANGE INT8RANGE NUMRANGE TSRANGE TSTZRANGE DATERANGE`](https://www.postgresql.org/docs/current/rangetypes.html) | ✖️        |       |

    **Domain types**

    | Type                                                                                          | Supported | Notes |
    | --------------------------------------------------------------------------------------------- | --------- | ----- |
    | [`CREATE TABLE <table> (col <domain>)`](https://www.postgresql.org/docs/current/domains.html) | ✖️        |       |

    **Object identifier types**

    | Type                                                                                                                                                                                    | Supported | Notes |
    | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----- |
    | [`OID REGCLASS REGCOLLATION REGCONFIG REGDICTIONARY REGNAMESPACE REGOPER REGOPERATOR REGPROC REGPROCEDURE REGROLE REGTYPE	`](https://www.postgresql.org/docs/current/datatype-oid.html) | ✖️        |       |
  </Tab>

  <Tab>
    **Numeric types**

    | Type                                                                                                                                                                                            | Supported | Notes                                              |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------- |
    | [`INT INT UNSIGNED TINYINT TINYINT UNSIGNED SMALLINT SMALLINT UNSIGNED MEDIUMINT MEDIUMINT UNSIGNED BIGINT BIGINT UNSIGNED SERIAL`](https://dev.mysql.com/doc/refman/8.0/en/integer-types.html) | ✔️        | Readyset ignores the optional display width field. |
    | [`DECIMAL NUMERIC`](https://dev.mysql.com/doc/refman/8.0/en/fixed-point-types.html)                                                                                                             | ✔️        |                                                    |
    | [`FLOAT DOUBLE REAL`](https://dev.mysql.com/doc/refman/8.0/en/floating-point-types.html)                                                                                                        | ✔️        |                                                    |
    | [`BIT`](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL)                                                                                                          | ✔️        | Readyset ignores the optional length field.        |

    **Date and time types**

    | Type                                                                     | Supported | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
    | ------------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | [`DATE DATETIME`](https://dev.mysql.com/doc/refman/8.0/en/datetime.html) | ✔️        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
    | [`TIMESTAMP`](https://dev.mysql.com/doc/refman/8.0/en/datetime.html)     | ✔️        | Rendered as a UTC wallclock; the session [`@@time_zone`](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_time_zone) is not applied to query results. Session `@@time_zone` must be `UTC` (or an equivalent like `+00:00`, `Etc/UTC`, or `GMT`); `SET @@time_zone` to any other value, including `SYSTEM`, is treated as an unsupported `SET` and, by default, causes the connection to proxy to the upstream rather than serve from cache. |
    | [`TIME`](https://dev.mysql.com/doc/refman/8.0/en/time.html)              | ✔️        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
    | [`YEAR`](https://dev.mysql.com/doc/refman/8.0/en/year.html)              | ✖️        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

    **String types**

    | Type                                                                                     | Supported | Notes                                       |
    | ---------------------------------------------------------------------------------------- | --------- | ------------------------------------------- |
    | [`CHAR VARCHAR`](https://dev.mysql.com/doc/refman/8.0/en/char.html)                      | ✔️        | Readyset ignores the optional length field. |
    | [`BINARY VARBINARY`](https://dev.mysql.com/doc/refman/8.0/en/binary-varbinary.html)      | ✔️        | Readyset ignores the optional length field. |
    | [`BLOB TINYBLOG MEDIUMBLOB LONGBLOB`](https://dev.mysql.com/doc/refman/8.0/en/blob.html) | ✔️        |                                             |
    | [`TEXT TINYTEXT MEDIUMTEXT LONGTEXT`](https://dev.mysql.com/doc/refman/8.0/en/blob.html) | ✔️        |                                             |
    | [`ENUM`](https://dev.mysql.com/doc/refman/8.0/en/enum.html)                              | ✔️        |                                             |
    | [`SET`](https://dev.mysql.com/doc/refman/8.0/en/set.html)                                | ✖️        |                                             |

    **JSON types**

    | Type                                                        | Supported | Notes                                                        |
    | ----------------------------------------------------------- | --------- | ------------------------------------------------------------ |
    | [`JSON`](https://dev.mysql.com/doc/refman/8.0/en/json.html) | ✔️        | JSON data is replicated. Users can read the JSON data as is. |

    **Spatial types**

    | Type                                                                                                                                                           | Supported | Notes                                               |
    | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------- |
    | [`POINT`](https://dev.mysql.com/doc/refman/8.4/en/spatial-type-overview.html)                                                                                  | ✔️        | As of stable-250522. Only `ST_AsText` is supported. |
    | [`GEOMETRY LINESTRING POLYGON MULTIPOINT MULTILINESTRING MULTIPOLYGON GEOMETRYCOLLECTION`](https://dev.mysql.com/doc/refman/8.4/en/spatial-type-overview.html) | ✖️        |                                                     |
  </Tab>
</Tabs>


# Memory Efficiency (/concepts/efficiency)


In the first section, we discussed the **stateful, streaming dataflow** model and how to use it to
maintain cached state in real time. In this model, both reader and internal nodes of the graph store result sets.
Without care, this could lead to an impractical memory footprint.

Readyset solves this problem via **partial materialization**. You can think of partial materialization as a
demand-driven cache filling mechanism that enables Readyset to only store the subset of the overall result set that is
useful (i.e., the subset of the results that are commonly read).

What does this look like in practice? Let's come back to the query in the prior section:

```
SELECT id, author, title, url, vcount
FROM stories
JOIN (SELECT story_id, COUNT(*) AS vcount
            FROM votes GROUP BY story_id)
AS VoteCount
ON VoteCount.story_id = stories.id WHERE stories.id = ?;

```

Without partial materialization, Readyset would have to compute the results for this query for every possible
input parameter (i.e., for every possible story). This would be pretty unfortunate, because caching the info
for every story is not necessary to improve the performance of most applications. In the case of HackerNews,
only the first few pages worth of stories are commonly read. Most of the benefit from caching would therefore
come from storing this popular content, rather than caching every story ever posted.

With partial materialization, Readyset can compute the query results for specific input parameters when they are requested.
After this initial computation, Readyset will keep those results up-to-date based on writes to the primary database.
For example, after the info for story `42` has been cached, if any users upvote that story, then Readyset will
increment the cached vote count for story `42` by `1` to reflect this data change.

When Readyset is initially deployed, the cache starts off cold and the dataflow graph is entirely empty. During the initial cache warming phase,
most queries will be ones that Readyset has never seen before (i.e., cache misses) so Readyset will have to compute their
results from scratch.

Readyset computes missing values via **upqueries**: upon receiving a query for missing state, the reader recursively
traverses up the dataflow graph to request its parent nodes for the state required to be able to rederive the missing result set.
In the worst case, the upquery has to go all the way up to the base table nodes to retrieve this information.
Once it finds the missing state, this state is propagated down the graph.

<img alt="upqueries" src={__img0} />

Over time, the frequency with which Readyset sees new input parameters will decrease,
given that certain input parameters are much more popular than others. Therefore, the ratio of cache hits vs cache misses will
swing in favor of cache hits. Cache hits take less than a millisecond to resolve, so once the cache hit rate is high enough,
read performance will dramatically improve.

When you start up Readyset, you give it a memory budget. In most cases, as you continue to use Readyset, the size of the cached state eventually
surpasses the budget. From there, Readyset will start to evict cached state. If a query is later run that requests missing results,
they are again computed via upquerying.


# Query Support (/concepts/query-support)
{/* Generated from query-support test results for Readyset build dd98d6ce. Do not edit by hand. */}

import { Callout } from 'fumadocs-ui/components/callout'

This page lists the SQL that Readyset caches, grouped by query shape, function, column type and connection setting, for PostgreSQL and MySQL and for both cache types. Each entry was run against a live Readyset instance. It was last tested on 2026-10-05 with PostgreSQL 17 and MySQL 8.4.

* [Push based caches](/concepts/deep-caching) are kept up to date automatically as data changes in the upstream database.
* [Pull based caches](/concepts/shallow-caching) store results for a configurable time (TTL) and refresh them from the upstream database. They accept almost any read query.
* A query that is not cached still works: Readyset passes it to the upstream database unchanged.

<Callout>
  To check a specific query, run 

  [`EXPLAIN CREATE CACHE FROM [YOUR_QUERY]`](/command-reference#explain-create-cache)

  , or look at 

  [`SHOW PROXIED QUERIES`](/command-reference#show-proxied-queries)

  .
</Callout>

## How to read the tables

| Mark    | Meaning                                                                                   |
| ------- | ----------------------------------------------------------------------------------------- |
| ✔️      | Cached, both with bind parameters (`$1` or `?`) and with values written inline in the SQL |
| Inline  | Cached when values are written inline in the SQL, not with bind parameters                |
| Partial | Some variants are cached, others are not                                                  |
| ✖️      | Passed through to the upstream database                                                   |
| –       | Does not apply to this database                                                           |

## Query shapes

Each row is a query shape that was run against Readyset. Queries are `SELECT` statements over small test tables; the example shows the exact query that was tested. A `?` marks a bind parameter (written `$1` in PostgreSQL).

### Select lists and projections

| Query shape                                                                                                                                                                            | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Star<br />`SELECT * FROM authors WHERE id = ?`                                                                                                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Alias expr<br />`SELECT id, price * 2 AS dbl, title AS t FROM books WHERE id = ?`                                                                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Distinct multi<br />`SELECT DISTINCT author_id, year FROM books WHERE price > ?`                                                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Distinct in list<br />`SELECT DISTINCT author_id FROM books WHERE author_id IN (?, ?)`                                                                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| No table<br />`SELECT 1 AS one`                                                                                                                                                        | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Values only<br />PostgreSQL: `VALUES (1), (2)`<br />MySQL: `VALUES ROW(1), ROW(2)`                                                                                                     | ✖️                    | ✖️                    | ✖️               | ✖️               |
| Case placeholder<br />`SELECT id, CASE WHEN price > ? THEN 'hi' ELSE 'lo' END AS tier FROM books WHERE author_id = ?`                                                                  | Inline                | ✔️                    | Inline           | ✔️               |
| Const column<br />`SELECT id, 'x' AS k, 42 AS n FROM books WHERE id = ?`                                                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| No where<br />`SELECT id, title FROM books`                                                                                                                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Count no where<br />`SELECT COUNT(*) FROM books`                                                                                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Qualified table<br />PostgreSQL: `SELECT books.id, books.title FROM public.books WHERE books.id = ?`<br />MySQL: `SELECT books.id, books.title FROM qs_mysql.books WHERE books.id = ?` | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Quoted ident<br />PostgreSQL: `SELECT "id", "title" FROM "books" WHERE "id" = ?`<br />MySQL: ``SELECT `id`, `title` FROM `books` WHERE `id` = ?``                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Filters (WHERE)

| Query shape                                                                                                                                                | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Eq and range<br />`SELECT id FROM books WHERE author_id = ? AND year > ?`                                                                                  | Inline                | ✔️                    | Inline           | ✔️               |
| Range two cols<br />`SELECT id FROM books WHERE price > ? AND year < ?`                                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Lt le ge<br />`SELECT id FROM books WHERE price <= ? AND year >= ?`                                                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Neq<br />`SELECT id FROM books WHERE author_id <> ?`                                                                                                       | Inline                | ✔️                    | Inline           | ✔️               |
| In single<br />`SELECT id FROM books WHERE author_id IN (?)`                                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| In three<br />`SELECT id FROM books WHERE author_id IN (?, ?, ?)`                                                                                          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| In literal only<br />`SELECT id FROM books WHERE author_id IN (1, 3)`                                                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Not in list<br />`SELECT id FROM books WHERE author_id NOT IN (?, ?)`                                                                                      | Inline                | ✔️                    | Inline           | ✔️               |
| Not between<br />`SELECT id FROM books WHERE price NOT BETWEEN ? AND ?`                                                                                    | Inline                | ✔️                    | Inline           | ✔️               |
| Like literal only<br />`SELECT id FROM books WHERE title LIKE 'Alpha%'`                                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Not like<br />`SELECT id FROM books WHERE title NOT LIKE ?`                                                                                                | Inline                | ✔️                    | Inline           | ✔️               |
| Ilike<br />`SELECT id FROM books WHERE title ILIKE ?`                                                                                                      | Inline                | ✔️                    | –                | –                |
| Is null<br />`SELECT id FROM books WHERE author_id IS NULL`                                                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Is not null param<br />`SELECT id FROM books WHERE author_id IS NOT NULL AND year > ?`                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Is distinct from<br />PostgreSQL: `SELECT id FROM books WHERE author_id IS DISTINCT FROM ?`<br />MySQL: `SELECT id FROM books WHERE NOT (author_id <=> ?)` | Inline                | ✔️                    | ✖️               | ✔️               |
| Or diff cols<br />`SELECT id FROM books WHERE author_id = ? OR year = ?`                                                                                   | Inline                | ✔️                    | Inline           | ✔️               |
| And or mix<br />`SELECT id FROM books WHERE author_id = ? AND (year > ? OR price < ?)`                                                                     | Inline                | ✔️                    | Inline           | ✔️               |
| Not eq<br />`SELECT id FROM books WHERE NOT (author_id = ?)`                                                                                               | Inline                | ✔️                    | Inline           | ✔️               |
| Row eq<br />`SELECT id FROM books WHERE (author_id, year) = (?, ?)`                                                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Expr gt<br />`SELECT id FROM books WHERE price * 2 > ?`                                                                                                    | Inline                | ✔️                    | Inline           | ✔️               |
| Col expr eq<br />`SELECT id FROM books WHERE year + 1 = ?`                                                                                                 | Inline                | ✔️                    | Inline           | ✔️               |
| Upper func<br />`SELECT id FROM authors WHERE UPPER(name) = ?`                                                                                             | Inline                | ✔️                    | Inline           | ✔️               |
| Col eq col<br />`SELECT id FROM books WHERE id = author_id AND year > ?`                                                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Regex<br />PostgreSQL: `SELECT id FROM books WHERE title ~ ?`<br />MySQL: `SELECT id FROM books WHERE title REGEXP ?`                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Any array<br />`SELECT id FROM books WHERE author_id = ANY(ARRAY[1, 3])`                                                                                   | ✔️                    | ✔️                    | –                | –                |
| Null safe eq<br />`SELECT id FROM books WHERE author_id <=> ?`                                                                                             | –                     | –                     | ✖️               | ✔️               |
| String eq<br />`SELECT id FROM authors WHERE country = ?`                                                                                                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| In strings<br />`SELECT id FROM authors WHERE country IN (?, ?)`                                                                                           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Decimal eq<br />`SELECT id FROM books WHERE price = ?`                                                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Ordering

| Query shape                                                                                                                                                                                     | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Simple<br />`SELECT id, title FROM books WHERE author_id = ? ORDER BY price, id`                                                                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Desc multi<br />`SELECT id FROM books WHERE year > ? ORDER BY price DESC, id`                                                                                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Position<br />`SELECT id, price FROM books WHERE year > ? ORDER BY 2, 1`                                                                                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Expr<br />`SELECT id FROM books WHERE year > ? ORDER BY price * -1, id`                                                                                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Non selected<br />`SELECT title FROM books WHERE author_id = ? ORDER BY price, id`                                                                                                              | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Nulls last<br />PostgreSQL: `SELECT id FROM books WHERE year > ? ORDER BY author_id NULLS LAST, id`<br />MySQL: `SELECT id FROM books WHERE year > ? ORDER BY author_id IS NULL, author_id, id` | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Limits and paging

| Query shape                                                                                                                                  | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Limit 1<br />`SELECT id, title FROM books WHERE author_id = ? LIMIT 1`                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Limit param<br />`SELECT id FROM books ORDER BY id LIMIT ?`                                                                                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Offset literal<br />`SELECT id FROM books ORDER BY id LIMIT 2 OFFSET 1`                                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Where limit offset param<br />`SELECT id FROM books WHERE year > ? ORDER BY id LIMIT ? OFFSET ?`                                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Mysql limit comma<br />`SELECT id FROM books ORDER BY id LIMIT 1, 2`                                                                         | –                     | –                     | ✔️               | ✔️               |
| Fetch first<br />`SELECT id FROM books ORDER BY id FETCH FIRST 2 ROWS ONLY`                                                                  | ✖️                    | ✔️                    | –                | –                |
| Topk no where<br />`SELECT id FROM books ORDER BY price DESC, id LIMIT 3`                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Topk where join<br />`SELECT b.id FROM books b JOIN authors a ON b.author_id = a.id WHERE a.country = ? ORDER BY b.price DESC, b.id LIMIT 2` | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Aggregation and grouping

| Query shape                                                                                                                                                                                                                                                  | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | --------------------- | ---------------- | ---------------- |
| Count star<br />`SELECT COUNT(*) FROM books WHERE author_id = ?`                                                                                                                                                                                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Count col<br />`SELECT COUNT(author_id) FROM books WHERE year > ?`                                                                                                                                                                                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Count distinct<br />`SELECT COUNT(DISTINCT author_id) FROM books WHERE year > ?`                                                                                                                                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Min max<br />`SELECT MIN(price), MAX(price) FROM books WHERE author_id = ?`                                                                                                                                                                                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Sum int<br />`SELECT SUM(year) FROM books WHERE author_id = ?`                                                                                                                                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Group having<br />`SELECT author_id, COUNT(*) AS n FROM books WHERE year > ? GROUP BY author_id HAVING COUNT(*) > ?`                                                                                                                                         | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Group having sum<br />`SELECT author_id, SUM(price) AS s FROM books WHERE year > ? GROUP BY author_id HAVING SUM(price) > ?`                                                                                                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Group expr<br />`SELECT CASE WHEN year < 2010 THEN 'old' ELSE 'new' END AS era, COUNT(*) AS n FROM books WHERE price > ? GROUP BY CASE WHEN year < 2010 THEN 'old' ELSE 'new' END`                                                                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Group position<br />`SELECT author_id, COUNT(*) AS n FROM books WHERE year > ? GROUP BY 1`                                                                                                                                                                   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Group no agg<br />`SELECT author_id FROM books WHERE year > ? GROUP BY author_id`                                                                                                                                                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Group no agg extra key<br />`SELECT author_id FROM books WHERE price > ? GROUP BY author_id, year`                                                                                                                                                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Group multi col<br />`SELECT author_id, year, COUNT(*) AS n FROM books WHERE price > ? GROUP BY author_id, year`                                                                                                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Group by pk dependent<br />`SELECT a.id, a.name, COUNT(*) AS n FROM authors a JOIN books b ON b.author_id = a.id WHERE b.year > ? GROUP BY a.id`                                                                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Json agg<br />PostgreSQL: `SELECT author_id, JSON_AGG(id) AS ids FROM books WHERE author_id = ? GROUP BY author_id`<br />MySQL: `SELECT author_id, JSON_ARRAYAGG(id) AS ids FROM books WHERE author_id = ? GROUP BY author_id`                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Array agg<br />`SELECT author_id, ARRAY_AGG(id) AS ids FROM books WHERE author_id = ? GROUP BY author_id`                                                                                                                                                    | ✔️                    | ✔️                    | –                | –                |
| Stddev<br />`SELECT STDDEV(price) FROM books WHERE year > ?`                                                                                                                                                                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Variance<br />`SELECT VARIANCE(price) FROM books WHERE year > ?`                                                                                                                                                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Bool and<br />`SELECT BOOL_AND(price > 5) FROM books WHERE year > ?`                                                                                                                                                                                         | ✖️                    | ✔️                    | –                | –                |
| Bit and<br />`SELECT BIT_AND(id) FROM books WHERE year > ?`                                                                                                                                                                                                  | –                     | –                     | ✖️               | ✔️               |
| Filter<br />`SELECT COUNT(*) FILTER (WHERE price > ?) FROM books WHERE year > ?`                                                                                                                                                                             | ✖️                    | ✔️                    | –                | –                |
| Rollup<br />PostgreSQL: `SELECT author_id, COUNT(*) AS n FROM books WHERE year > ? GROUP BY ROLLUP (author_id)`<br />MySQL: `SELECT author_id, COUNT(*) AS n FROM books WHERE year > ? GROUP BY author_id WITH ROLLUP`                                       | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Grouping sets<br />`SELECT author_id, year, COUNT(*) AS n FROM books WHERE price > ? GROUP BY GROUPING SETS ((author_id), (year))`                                                                                                                           | ✖️                    | ✔️                    | –                | –                |
| Percentile<br />`SELECT PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY price) FROM books WHERE year > ?`                                                                                                                                                        | ✖️                    | ✔️                    | –                | –                |
| In list count<br />`SELECT COUNT(*) FROM books WHERE author_id IN (?, ?)`                                                                                                                                                                                    | ✖️                    | ✔️                    | ✖️               | ✔️               |
| In list count distinct<br />`SELECT COUNT(DISTINCT year) FROM books WHERE author_id IN (?, ?)`                                                                                                                                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Sum expr<br />`SELECT SUM(price * 2) FROM books WHERE author_id = ?`                                                                                                                                                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| String agg sep<br />PostgreSQL: `SELECT author_id, STRING_AGG(title, '; ') AS t FROM books WHERE author_id = ? GROUP BY author_id`<br />MySQL: `SELECT author_id, GROUP_CONCAT(title SEPARATOR '; ') AS t FROM books WHERE author_id = ? GROUP BY author_id` | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Sales group region<br />`SELECT region, SUM(amount) AS total, COUNT(*) AS n FROM sales WHERE qty > ? GROUP BY region`                                                                                                                                        | ✖️                    | ✔️                    | ✖️               | ✔️               |
| No where group<br />`SELECT region, COUNT(*) AS n FROM sales GROUP BY region`                                                                                                                                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Count col eq<br />`SELECT COUNT(author_id) FROM books WHERE author_id = ?`                                                                                                                                                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Count distinct eq<br />`SELECT COUNT(DISTINCT author_id) FROM books WHERE author_id = ?`                                                                                                                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Group having eq<br />`SELECT author_id, COUNT(*) AS n FROM books WHERE author_id = ? GROUP BY author_id HAVING COUNT(*) > ?`                                                                                                                                 | Inline                | ✔️                    | Inline           | ✔️               |
| Group having sum eq<br />`SELECT author_id, SUM(price) AS s FROM books WHERE author_id = ? GROUP BY author_id HAVING SUM(price) > ?`                                                                                                                         | Inline                | ✔️                    | Inline           | ✔️               |
| Group position eq<br />`SELECT author_id, COUNT(*) AS n FROM books WHERE author_id = ? GROUP BY 1`                                                                                                                                                           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Group no agg eq<br />`SELECT author_id FROM books WHERE author_id = ? GROUP BY author_id`                                                                                                                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Group by pk dependent eq<br />`SELECT a.id, a.name, COUNT(*) AS n FROM authors a JOIN books b ON b.author_id = a.id WHERE b.author_id = ? GROUP BY a.id`                                                                                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Stddev eq<br />`SELECT STDDEV(price) FROM books WHERE author_id = ?`                                                                                                                                                                                         | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Variance eq<br />`SELECT VARIANCE(price) FROM books WHERE author_id = ?`                                                                                                                                                                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Bool and eq<br />`SELECT BOOL_AND(price > 5) FROM books WHERE author_id = ?`                                                                                                                                                                                 | ✖️                    | ✔️                    | –                | –                |
| Bit and eq<br />`SELECT BIT_AND(id) FROM books WHERE author_id = ?`                                                                                                                                                                                          | –                     | –                     | ✖️               | ✔️               |
| Rollup eq<br />PostgreSQL: `SELECT author_id, COUNT(*) AS n FROM books WHERE author_id = ? GROUP BY ROLLUP (author_id)`<br />MySQL: `SELECT author_id, COUNT(*) AS n FROM books WHERE author_id = ? GROUP BY author_id WITH ROLLUP`                          | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Percentile eq<br />`SELECT PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY price) FROM books WHERE author_id = ?`                                                                                                                                                | ✖️                    | ✔️                    | –                | –                |

### Joins

| Query shape                                                                                                                                                                      | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Using<br />`SELECT e.id, d.floor FROM emp e JOIN dept d USING (dept) WHERE e.id = ?`                                                                                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Natural<br />`SELECT id, floor FROM emp NATURAL JOIN dept WHERE id = ?`                                                                                                          | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Comma<br />`SELECT b.id, a.name FROM books b, authors a WHERE b.author_id = a.id AND a.id = ?`                                                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Cross<br />`SELECT a.id, d.dept FROM authors a CROSS JOIN dept d WHERE a.id = ?`                                                                                                 | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Three way<br />`SELECT b.id, a.name, r.rating FROM books b JOIN authors a ON b.author_id = a.id JOIN reviews r ON r.book_id = b.id WHERE a.id = ?`                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Left where right<br />`SELECT a.id, b.title FROM authors a LEFT JOIN books b ON b.author_id = a.id WHERE b.year > ?`                                                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Left anti<br />`SELECT a.id FROM authors a LEFT JOIN books b ON b.author_id = a.id WHERE b.id IS NULL AND a.id > ?`                                                              | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Left on literal cond<br />`SELECT a.id, b.title FROM authors a LEFT JOIN books b ON b.author_id = a.id AND b.year > 2005 WHERE a.id = ?`                                         | ✔️                    | ✔️                    | Inline           | ✔️               |
| Left on param<br />`SELECT a.id, b.title FROM authors a LEFT JOIN books b ON b.author_id = a.id AND b.year > ? WHERE a.id = ?`                                                   | Inline                | ✔️                    | Inline           | ✔️               |
| Left on func<br />`SELECT a.id, b.title FROM authors a LEFT JOIN books b ON LOWER(b.title) = LOWER(a.name) WHERE a.id = ?`                                                       | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Left multi eq<br />`SELECT b.id, r.id AS rid FROM books b LEFT JOIN reviews r ON r.book_id = b.id AND r.id = b.id WHERE b.year > ?`                                              | ✔️                    | ✔️                    | Inline           | ✔️               |
| Right second<br />`SELECT b.id, r.id AS rid FROM authors a JOIN books b ON b.author_id = a.id RIGHT JOIN reviews r ON r.book_id = b.id WHERE r.id = ?`                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Non equi<br />`SELECT a.id, b.id AS bid FROM authors a JOIN books b ON a.id < b.author_id WHERE a.id = ?`                                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| On func<br />`SELECT e.id, d.floor FROM emp e JOIN dept d ON LOWER(e.dept) = LOWER(d.dept) WHERE e.id > ?`                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| On expr<br />`SELECT a.id, b.id AS bid FROM authors a JOIN books b ON b.author_id = a.id + 0 WHERE a.id = ?`                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| On or<br />`SELECT a.id, b.id AS bid FROM authors a JOIN books b ON b.author_id = a.id OR b.author_id = 0 WHERE a.id = ?`                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| On extra nonkey filter<br />`SELECT a.id, b.id AS bid FROM authors a JOIN books b ON b.author_id = a.id AND b.year > 2000 WHERE a.id = ?`                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Self mgr<br />`SELECT e.id, m.name AS mgr FROM emp e JOIN emp m ON e.mgr_id = m.id WHERE e.id = ?`                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Self left<br />`SELECT e.id, m.name AS mgr FROM emp e LEFT JOIN emp m ON e.mgr_id = m.id WHERE e.id = ?`                                                                         | ✔️                    | ✔️                    | Inline           | ✔️               |
| Keys both sides<br />`SELECT b.id, r.id AS rid FROM books b JOIN reviews r ON r.book_id = b.id WHERE b.author_id = ? AND r.rating = ?`                                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Lateral<br />`SELECT a.id, t.title FROM authors a, LATERAL (SELECT title FROM books b WHERE b.author_id = a.id) t WHERE a.id = ?`                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Straight<br />`SELECT STRAIGHT_JOIN b.id, a.name FROM books b JOIN authors a ON b.author_id = a.id WHERE a.id = ?`                                                               | –                     | –                     | ✔️               | ✔️               |
| Derived both<br />`SELECT x.id, y.n FROM (SELECT id FROM authors) x JOIN (SELECT author_id, COUNT(*) AS n FROM books GROUP BY author_id) y ON y.author_id = x.id WHERE x.id = ?` | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Agg join<br />`SELECT a.id, c.n FROM authors a JOIN (SELECT author_id, COUNT(*) AS n FROM books GROUP BY author_id) c ON c.author_id = a.id WHERE a.id = ?`                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Left agg<br />`SELECT a.id, COUNT(b.id) AS n FROM authors a LEFT JOIN books b ON b.author_id = a.id WHERE a.country = ? GROUP BY a.id`                                           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Join then order limit<br />`SELECT a.name, b.title FROM authors a JOIN books b ON b.author_id = a.id WHERE a.id = ? ORDER BY b.price DESC, b.id LIMIT 1`                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| No where<br />`SELECT a.name, b.title FROM authors a JOIN books b ON b.author_id = a.id`                                                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Subqueries

| Query shape                                                                                                                                   | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Not in notnull<br />`SELECT id FROM authors WHERE id NOT IN (SELECT book_id FROM reviews WHERE rating > ?)`                                   | Inline                | ✔️                    | Inline           | ✔️               |
| Not in nullable<br />`SELECT id FROM authors WHERE id NOT IN (SELECT author_id FROM books WHERE year > ?)`                                    | Inline                | ✔️                    | Inline           | ✔️               |
| Not in nullable null present<br />`SELECT id FROM authors WHERE id NOT IN (SELECT author_id FROM books WHERE year > ?)`                       | Inline                | Inline                | Inline           | ✔️               |
| Exists uncorrelated<br />`SELECT id FROM authors WHERE EXISTS (SELECT 1 FROM books WHERE price > ?)`                                          | Inline                | ✔️                    | Inline           | ✔️               |
| Not exists corr<br />`SELECT a.id FROM authors a WHERE NOT EXISTS (SELECT 1 FROM books b WHERE b.author_id = a.id AND b.year > ?)`            | Inline                | ✔️                    | Inline           | ✔️               |
| Corr nonequal<br />`SELECT a.id FROM authors a WHERE EXISTS (SELECT 1 FROM books b WHERE b.price > a.id AND b.year > ?)`                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Scalar select list<br />`SELECT a.id, (SELECT COUNT(*) FROM books b WHERE b.author_id = a.id) AS n FROM authors a WHERE a.country = ?`        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Exists select list<br />`SELECT a.id, EXISTS (SELECT 1 FROM books b WHERE b.author_id = a.id) AS has FROM authors a WHERE a.country = ?`      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Scalar pk<br />`SELECT id FROM books WHERE price > (SELECT price FROM books WHERE id = ?)`                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Any<br />`SELECT id FROM books WHERE price > ANY (SELECT price FROM books WHERE author_id = ?)`                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| All<br />`SELECT id FROM books WHERE price > ALL (SELECT price FROM books WHERE author_id = ?)`                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| In or pred<br />`SELECT id FROM books WHERE author_id IN (SELECT id FROM authors WHERE country = ?) OR year > ?`                              | Inline                | ✔️                    | Inline           | ✔️               |
| Derived<br />`SELECT t.author_id, t.n FROM (SELECT author_id, COUNT(*) AS n FROM books GROUP BY author_id) t WHERE t.author_id = ?`           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Derived limit<br />`SELECT t.id FROM (SELECT id, price FROM books ORDER BY price DESC, id LIMIT 3) t WHERE t.price > ?`                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Having scalar<br />`SELECT author_id FROM books GROUP BY author_id HAVING COUNT(*) >= (SELECT COUNT(*) FROM authors WHERE id = ?)`            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Nested in<br />`SELECT id FROM authors WHERE id IN (SELECT author_id FROM books WHERE year > ?)`                                              | Inline                | ✔️                    | Inline           | ✔️               |
| In two level<br />`SELECT id FROM books WHERE author_id IN (SELECT id FROM authors WHERE id IN (SELECT author_id FROM books WHERE year > ?))` | Inline                | ✔️                    | Inline           | ✔️               |
| In literal<br />`SELECT id FROM books WHERE author_id IN (SELECT id FROM authors WHERE country = 'US')`                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Group by subq<br />`SELECT COUNT(*) AS n FROM books GROUP BY (SELECT 1)`                                                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |

### Common table expressions (WITH)

| Query shape                                                                                                                                                                     | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Param in body<br />`WITH c AS (SELECT id, price FROM books WHERE author_id = ?) SELECT id, price FROM c WHERE price > 0`                                                        | Inline                | ✔️                    | Inline           | ✔️               |
| Agg<br />`WITH c AS (SELECT author_id, COUNT(*) AS n FROM books GROUP BY author_id) SELECT author_id, n FROM c WHERE author_id = ?`                                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Two joined<br />`WITH x AS (SELECT id, name FROM authors), y AS (SELECT author_id, price FROM books) SELECT x.name, y.price FROM x JOIN y ON y.author_id = x.id WHERE x.id = ?` | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Chain<br />`WITH a1 AS (SELECT id, price, author_id FROM books), a2 AS (SELECT id, price FROM a1 WHERE price > 10) SELECT id FROM a2 WHERE price > ?`                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Read twice<br />`WITH c AS (SELECT id, author_id FROM books) SELECT c1.id FROM c c1 JOIN c c2 ON c1.author_id = c2.author_id WHERE c1.id = ?`                                   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| In subquery<br />`WITH c AS (SELECT id FROM authors WHERE country = 'US') SELECT id FROM books WHERE author_id IN (SELECT id FROM c) AND year > ?`                              | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Column list<br />`WITH c (a, b) AS (SELECT id, price FROM books) SELECT a FROM c WHERE b > ?`                                                                                   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Recursive<br />`WITH RECURSIVE t AS (SELECT id, mgr_id FROM emp WHERE id = ? UNION ALL SELECT e.id, e.mgr_id FROM emp e JOIN t ON e.mgr_id = t.id) SELECT id FROM t`            | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Materialized<br />`WITH c AS MATERIALIZED (SELECT id, price FROM books WHERE price > 10) SELECT id FROM c WHERE price > ?`                                                      | ✔️                    | ✔️                    | –                | –                |
| Join table<br />`WITH c AS (SELECT id, author_id FROM books WHERE year > 2000) SELECT c.id, a.name FROM c JOIN authors a ON a.id = c.author_id WHERE a.id = ?`                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Window inside<br />`WITH c AS (SELECT id, author_id, ROW_NUMBER() OVER (PARTITION BY author_id ORDER BY price, id) AS rn FROM books) SELECT id FROM c WHERE author_id = ?`      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| In list outer<br />`WITH c AS (SELECT id, author_id FROM books) SELECT id FROM c WHERE author_id IN (?, ?)`                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Literal body only<br />`WITH c AS (SELECT id, price FROM books WHERE author_id = 1) SELECT id, price FROM c`                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Set operations

| Query shape                                                                                                                                             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Union<br />`SELECT id FROM books WHERE author_id = ? UNION SELECT id FROM authors WHERE id = ?`                                                         | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Intersect<br />`SELECT id FROM books WHERE author_id = ? INTERSECT SELECT id FROM authors WHERE id = ?`                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Except<br />`SELECT id FROM books WHERE year > ? EXCEPT SELECT id FROM authors WHERE id = ?`                                                            | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Union derived<br />`SELECT t.id FROM (SELECT id FROM books WHERE author_id = ? UNION ALL SELECT id FROM authors) t`                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Union three<br />`SELECT id FROM books WHERE author_id = ? UNION ALL SELECT id FROM authors WHERE id = ? UNION ALL SELECT id FROM reviews WHERE id = ?` | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Union order limit<br />`(SELECT id FROM books WHERE author_id = ?) UNION ALL (SELECT id FROM authors WHERE id = ?) ORDER BY id LIMIT 3`                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Union in cte<br />`WITH c AS (SELECT id FROM books UNION ALL SELECT id FROM authors) SELECT id FROM c WHERE id = ?`                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |

### Window functions

| Query shape                                                                                                                                                                                             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Rank<br />`SELECT id, RANK() OVER (PARTITION BY author_id ORDER BY price) AS r FROM books WHERE year > ?`                                                                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Dense rank<br />`SELECT id, DENSE_RANK() OVER (PARTITION BY author_id ORDER BY price) AS r FROM books WHERE year > ?`                                                                                   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Sum partition<br />`SELECT id, SUM(price) OVER (PARTITION BY author_id) AS s FROM books WHERE year > ?`                                                                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Running sum<br />`SELECT id, SUM(price) OVER (PARTITION BY author_id ORDER BY id) AS s FROM books WHERE year > ?`                                                                                       | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Two windows<br />`SELECT id, ROW_NUMBER() OVER (PARTITION BY author_id ORDER BY id) AS rn, SUM(price) OVER (PARTITION BY author_id) AS s FROM books WHERE year > ?`                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Lag<br />`SELECT id, LAG(price) OVER (PARTITION BY author_id ORDER BY id) AS prev FROM books WHERE year > ?`                                                                                            | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Lead<br />`SELECT id, LEAD(price) OVER (PARTITION BY author_id ORDER BY id) AS nxt FROM books WHERE year > ?`                                                                                           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Ntile<br />`SELECT id, NTILE(2) OVER (ORDER BY id) AS bucket FROM books WHERE year > ?`                                                                                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| First value<br />`SELECT id, FIRST_VALUE(price) OVER (PARTITION BY author_id ORDER BY id) AS f FROM books WHERE year > ?`                                                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Frame rows<br />`SELECT id, SUM(price) OVER (PARTITION BY author_id ORDER BY id ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS s FROM books WHERE year > ?`                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Named window<br />`SELECT id, ROW_NUMBER() OVER w AS rn FROM books WHERE year > ? WINDOW w AS (PARTITION BY author_id ORDER BY id)`                                                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| No partition<br />`SELECT id, ROW_NUMBER() OVER (ORDER BY id) AS rn FROM books WHERE year > ?`                                                                                                          | ✖️                    | ✔️                    | ✖️               | ✔️               |
| With in list<br />`SELECT id, ROW_NUMBER() OVER (PARTITION BY author_id ORDER BY id) AS rn FROM books WHERE author_id IN (?, ?)`                                                                        | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Top1 per group<br />`SELECT t.id, t.author_id FROM (SELECT id, author_id, ROW_NUMBER() OVER (PARTITION BY author_id ORDER BY price DESC, id) AS rn FROM books WHERE year > ?) t WHERE t.rn = 1`         | Inline                | ✔️                    | Inline           | ✔️               |
| Count over<br />`SELECT id, COUNT(*) OVER (PARTITION BY author_id) AS n FROM books WHERE year > ?`                                                                                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Avg over<br />`SELECT id, AVG(price) OVER (PARTITION BY author_id) AS a FROM books WHERE year > ?`                                                                                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Sales running<br />`SELECT id, SUM(amount) OVER (PARTITION BY region ORDER BY sold_on, id) AS run FROM sales WHERE qty > ?`                                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Rank eq<br />`SELECT id, RANK() OVER (PARTITION BY author_id ORDER BY price) AS r FROM books WHERE author_id = ?`                                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Dense rank eq<br />`SELECT id, DENSE_RANK() OVER (PARTITION BY author_id ORDER BY price) AS r FROM books WHERE author_id = ?`                                                                           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Sum partition eq<br />`SELECT id, SUM(price) OVER (PARTITION BY author_id) AS s FROM books WHERE author_id = ?`                                                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Running sum eq<br />`SELECT id, SUM(price) OVER (PARTITION BY author_id ORDER BY id) AS s FROM books WHERE author_id = ?`                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Two windows eq<br />`SELECT id, ROW_NUMBER() OVER (PARTITION BY author_id ORDER BY id) AS rn, SUM(price) OVER (PARTITION BY author_id) AS s FROM books WHERE author_id = ?`                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Lag eq<br />`SELECT id, LAG(price) OVER (PARTITION BY author_id ORDER BY id) AS prev FROM books WHERE author_id = ?`                                                                                    | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Lead eq<br />`SELECT id, LEAD(price) OVER (PARTITION BY author_id ORDER BY id) AS nxt FROM books WHERE author_id = ?`                                                                                   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Ntile eq<br />`SELECT id, NTILE(2) OVER (ORDER BY id) AS bucket FROM books WHERE author_id = ?`                                                                                                         | ✖️                    | ✔️                    | ✖️               | ✔️               |
| First value eq<br />`SELECT id, FIRST_VALUE(price) OVER (PARTITION BY author_id ORDER BY id) AS f FROM books WHERE author_id = ?`                                                                       | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Frame rows eq<br />`SELECT id, SUM(price) OVER (PARTITION BY author_id ORDER BY id ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS s FROM books WHERE author_id = ?`                                       | ✖️                    | ✔️                    | ✖️               | ✔️               |
| Named window eq<br />`SELECT id, ROW_NUMBER() OVER w AS rn FROM books WHERE author_id = ? WINDOW w AS (PARTITION BY author_id ORDER BY id)`                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| No partition eq<br />`SELECT id, ROW_NUMBER() OVER (ORDER BY id) AS rn FROM books WHERE author_id = ?`                                                                                                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Top1 per group eq<br />`SELECT t.id, t.author_id FROM (SELECT id, author_id, ROW_NUMBER() OVER (PARTITION BY author_id ORDER BY price DESC, id) AS rn FROM books WHERE author_id = ?) t WHERE t.rn = 1` | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Count over eq<br />`SELECT id, COUNT(*) OVER (PARTITION BY author_id) AS n FROM books WHERE author_id = ?`                                                                                              | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Avg over eq<br />`SELECT id, AVG(price) OVER (PARTITION BY author_id) AS a FROM books WHERE author_id = ?`                                                                                              | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Locking reads

| Query shape                                                                 | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| For update<br />`SELECT id FROM books WHERE id = ? FOR UPDATE`              | ✖️                    | ✖️                    | ✖️               | ✖️               |
| For share<br />`SELECT id FROM books WHERE id = ? FOR SHARE`                | ✖️                    | ✖️                    | ✖️               | ✖️               |
| Skip locked<br />`SELECT id FROM books WHERE id = ? FOR UPDATE SKIP LOCKED` | ✖️                    | ✖️                    | ✖️               | ✖️               |
| Lock in share<br />`SELECT id FROM books WHERE id = ? LOCK IN SHARE MODE`   | –                     | –                     | ✖️               | ✖️               |

### Other

| Query shape                                                                                                | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| Select into var<br />`SELECT id INTO @v FROM books WHERE id = ?`                                           | –                     | –                     | ✖️               | ✖️               |
| Sql calc found rows<br />`SELECT SQL_CALC_FOUND_ROWS id FROM books WHERE year > ? LIMIT 2`                 | –                     | –                     | ✔️               | ✔️               |
| Index hint<br />`SELECT id FROM books USE INDEX (books_author_idx) WHERE author_id = ?`                    | –                     | –                     | ✔️               | ✔️               |
| Distinct count star<br />`SELECT COUNT(*) FROM (SELECT DISTINCT author_id FROM books) t`                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Select star join<br />`SELECT * FROM books b JOIN authors a ON b.author_id = a.id WHERE a.id = ?`          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Dup column names<br />`SELECT b.id, a.id FROM books b JOIN authors a ON b.author_id = a.id WHERE a.id = ?` | ✔️                    | ✔️                    | ✔️               | ✔️               |
| In with null<br />`SELECT id FROM books WHERE author_id IN (?, NULL)`                                      | Inline                | ✔️                    | Inline           | ✔️               |

## Functions and operators

Each expression was tested in the select list and in a `WHERE` filter. A check mark means both uses are cached.

### Operators

| Expression                                             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------ | --------------------- | --------------------- | ---------------- | ---------------- |
| `n + 1`                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n - 1`                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n * 2`                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n / 2`                                                | ✔️                    | ✔️                    | Inline           | ✔️               |
| `n % 3`                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `s \|\| t`                                             | ✔️                    | ✔️                    | –                | –                |
| `s \|\| t`                                             | –                     | –                     | Inline           | ✔️               |
| `s LIKE 'He%'`                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `s NOT LIKE 'He%'`                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `s ILIKE 'he%'`                                        | ✔️                    | ✔️                    | –                | –                |
| `b IS TRUE`                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `b IS NOT FALSE`                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n IS NULL`                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n IS DISTINCT FROM 3`                                 | ✔️                    | ✔️                    | –                | –                |
| `n BETWEEN 1 AND 10`                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n IN (1, 7, 9)`                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `NOT (n > 5)`                                          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `(n > 5 AND d < 20) OR f > 100`                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CASE WHEN n > 5 THEN 'big' ELSE 'small' END`          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CASE n WHEN 7 THEN 'seven' ELSE 'other' END`          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `(n, d) = (7, 12.35)`                                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `s ~ 'Hel'` (PostgreSQL)<br />`s REGEXP 'Hel'` (MySQL) | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `s RLIKE 'Hel'`                                        | –                     | –                     | ✖️               | ✔️               |
| `s SIMILAR TO 'Hel%'`                                  | ✖️                    | ✔️                    | –                | –                |
| `n <=> 7`                                              | –                     | –                     | ✖️               | ✔️               |
| `n & 3`                                                | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `n \| 8`                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `n << 1`                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `n # 5` (PostgreSQL)<br />`n ^ 5` (MySQL)              | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `n XOR 1`                                              | –                     | –                     | ✖️               | ✔️               |
| `n DIV 2`                                              | –                     | –                     | ✖️               | ✔️               |
| `s LIKE 'H!%' ESCAPE '!'`                              | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `-n`                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CONCAT_WS(',', s, NULL, t)`                           | ✔️                    | ✔️                    | ✔️               | ✔️               |

### String functions

| Expression                                                                | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `CONCAT(s, t)`                                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CONCAT_WS('-', s, t)`                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `SUBSTRING(s, 2, 3)`                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `SUBSTRING(s FROM 2 FOR 3)`                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `SUBSTR(s, 2, 3)`                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `SPLIT_PART(s, ' ', 1)`                                                   | ✔️                    | ✔️                    | –                | –                |
| `SUBSTRING_INDEX(s, ' ', 1)`                                              | –                     | –                     | ✖️               | ✔️               |
| `LOWER(s)`                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `UPPER(s)`                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `LENGTH(s)`                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CHAR_LENGTH(s)`                                                          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `OCTET_LENGTH(s)`                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `ASCII(s)`                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `ENCODE(CONVERT_TO(s, 'UTF8'), 'hex')` (PostgreSQL)<br />`HEX(s)` (MySQL) | ✖️                    | ✔️                    | ✔️               | ✔️               |
| `TRIM(s)`                                                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LTRIM(s)`                                                                | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `RTRIM(s)`                                                                | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `TRIM(BOTH ' ' FROM s)`                                                   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `BTRIM(s)`                                                                | ✖️                    | ✔️                    | –                | –                |
| `POSITION('o' IN s)`                                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `REPLACE(s, 'o', '0')`                                                    | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LPAD(s, 15, '*')`                                                        | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `RPAD(s, 15, '*')`                                                        | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LEFT(s, 3)`                                                              | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `RIGHT(s, 3)`                                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LOCATE('o', s)`                                                          | –                     | –                     | ✖️               | ✔️               |
| `INSTR(s, 'o')`                                                           | –                     | –                     | ✖️               | ✔️               |
| `STRPOS(s, 'o')`                                                          | ✖️                    | ✔️                    | –                | –                |
| `REVERSE(s)`                                                              | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `MD5(s)`                                                                  | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `REPEAT(s, 2)`                                                            | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `INITCAP(t)`                                                              | ✖️                    | ✔️                    | –                | –                |
| `TRANSLATE(s, 'lo', 'xy')`                                                | ✖️                    | ✔️                    | –                | –                |
| `OVERLAY(s PLACING 'xx' FROM 2 FOR 2)`                                    | ✖️                    | ✔️                    | –                | –                |
| `REGEXP_REPLACE(s, 'o', '0')`                                             | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `REGEXP_LIKE(s, 'Hel')`                                                   | –                     | –                     | ✖️               | ✔️               |
| `REGEXP_MATCH(s, 'H(el)')`                                                | ✖️                    | ✔️                    | –                | –                |
| `TO_CHAR(d, '999.99')`                                                    | ✖️                    | ✔️                    | –                | –                |
| `FORMAT(d, 1)`                                                            | –                     | –                     | ✖️               | ✔️               |
| `STRCMP(s, 'abc')`                                                        | –                     | –                     | ✖️               | ✔️               |
| `QUOTE(s)`                                                                | –                     | –                     | ✖️               | ✔️               |
| `CONCAT(n, s)`                                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CHR(65)`                                                                 | ✖️                    | ✔️                    | –                | –                |
| `CHAR(65)`                                                                | –                     | –                     | ✖️               | ✔️               |
| `SPACE(3)`                                                                | –                     | –                     | ✖️               | ✔️               |
| `STARTS_WITH(s, 'He')`                                                    | ✖️                    | ✔️                    | –                | –                |

### Math functions

| Expression                                    | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `ROUND(d)`                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `ROUND(d, 1)`                                 | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `GREATEST(n, 3, 10)`                          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `LEAST(n, 3, 10)`                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `MOD(n, 3)`                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `ABS(n)`                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `CEIL(d)`                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `CEILING(d)`                                  | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `FLOOR(d)`                                    | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `SIGN(n)`                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `POWER(n, 2)`                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `SQRT(f)`                                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LN(f)`                                       | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LOG10(f)`                                    | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `EXP(f)`                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `TRUNC(d, 1)`                                 | ✖️                    | ✔️                    | –                | –                |
| `TRUNCATE(d, 1)`                              | –                     | –                     | ✖️               | ✔️               |
| `PI()`                                        | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `DEGREES(f)`                                  | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `SIN(f)`                                      | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `RANDOM()` (PostgreSQL)<br />`RAND()` (MySQL) | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `DIV(n, 2)`                                   | ✖️                    | ✔️                    | –                | –                |
| `f / 3.0`                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Date and time

| Expression                              | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `EXTRACT(YEAR FROM dt)`                 | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `EXTRACT(MONTH FROM ts)`                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `EXTRACT(EPOCH FROM ts)`                | ✔️                    | ✔️                    | –                | –                |
| `DATE_TRUNC('month', ts)`               | ✔️                    | ✔️                    | –                | –                |
| `DATE(ts)`                              | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `MONTH(dt)`                             | –                     | –                     | ✔️               | ✔️               |
| `DAYOFWEEK(dt)`                         | –                     | –                     | ✔️               | ✔️               |
| `DATE_FORMAT(ts, '%Y-%m')`              | –                     | –                     | ✔️               | ✔️               |
| `ADDTIME(ts, '01:00:00')`               | –                     | –                     | ✔️               | ✔️               |
| `TIMEDIFF(ts, '2024-03-15 08:00:00')`   | –                     | –                     | ✔️               | ✔️               |
| `CONVERT_TZ(ts, '+00:00', '+02:00')`    | –                     | –                     | ✔️               | ✔️               |
| `tstz AT TIME ZONE 'America/New_York'`  | ✔️                    | ✔️                    | –                | –                |
| `NOW()`                                 | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `CURRENT_TIMESTAMP`                     | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `CURRENT_DATE`                          | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `CURDATE()`                             | –                     | –                     | ✖️               | ✔️               |
| `ts + INTERVAL '1 day'`                 | ✖️                    | ✔️                    | –                | –                |
| `ts + INTERVAL 1 DAY`                   | –                     | –                     | ✖️               | ✔️               |
| `DATE_ADD(dt, INTERVAL 1 DAY)`          | –                     | –                     | ✖️               | ✔️               |
| `DATE_SUB(dt, INTERVAL 1 DAY)`          | –                     | –                     | ✖️               | ✔️               |
| `DATEDIFF(dt, '2024-01-01')`            | –                     | –                     | ✖️               | ✔️               |
| `TIMESTAMPDIFF(DAY, '2024-01-01', dt)`  | –                     | –                     | ✖️               | ✔️               |
| `dt - DATE '2024-01-01'`                | ✖️                    | ✔️                    | –                | –                |
| `YEAR(dt)`                              | –                     | –                     | ✖️               | ✔️               |
| `DAY(dt)`                               | –                     | –                     | ✖️               | ✔️               |
| `UNIX_TIMESTAMP(ts)`                    | –                     | –                     | ✖️               | ✔️               |
| `STR_TO_DATE('2024-01-05', '%Y-%m-%d')` | –                     | –                     | ✖️               | ✔️               |
| `TO_DATE('2024-01-05', 'YYYY-MM-DD')`   | ✖️                    | ✔️                    | –                | –                |
| `TO_TIMESTAMP(86400)`                   | ✖️                    | ✔️                    | –                | –                |
| `TO_CHAR(ts, 'YYYY-MM')`                | ✖️                    | ✔️                    | –                | –                |
| `AGE(ts, TIMESTAMP '2024-01-01')`       | ✖️                    | Inline                | –                | –                |
| `dt > DATE '2024-01-01'`                | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `ts > TIMESTAMP '2024-01-01 00:00:00'`  | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `DATE_PART('year', ts)`                 | ✖️                    | ✔️                    | –                | –                |
| `LAST_DAY(dt)`                          | –                     | –                     | ✖️               | ✔️               |
| `DAYNAME(dt)`                           | –                     | –                     | ✖️               | ✔️               |
| `MAKEDATE(2024, 60)`                    | –                     | –                     | ✖️               | ✔️               |
| `HOUR(ts)`                              | –                     | –                     | ✖️               | ✔️               |
| `WEEKDAY(dt)`                           | –                     | –                     | ✖️               | ✔️               |
| `CAST(ts AS DATE)`                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `ts + 0`                                | –                     | –                     | Inline           | ✔️               |
| `CLOCK_TIMESTAMP()`                     | ✖️                    | ✔️                    | –                | –                |
| `CURRENT_TIME`                          | ✖️                    | Inline                | ✖️               | ✔️               |
| `UTC_TIMESTAMP()`                       | –                     | –                     | ✖️               | ✔️               |

### Conditional expressions

| Expression                                   | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| -------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `COALESCE(n, 0)`                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `IFNULL(n, 0)`                               | –                     | –                     | ✔️               | ✔️               |
| `NULLIF(n, 8)`                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `IF(n > 5, 'a', 'b')`                        | –                     | –                     | ✖️               | ✔️               |
| `ISNULL(n)`                                  | –                     | –                     | ✖️               | ✔️               |
| `COALESCE(NULL, n, 0)`                       | Partial               | ✔️                    | Inline           | ✔️               |
| `CASE WHEN s IS NULL THEN 'none' ELSE s END` | ✔️                    | ✔️                    | ✔️               | ✔️               |

### Type casts

| Expression                                                                          | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `CAST(n AS text)` (PostgreSQL)<br />`CAST(n AS CHAR)` (MySQL)                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n::text`                                                                           | ✔️                    | ✔️                    | –                | –                |
| `CAST(d AS integer)` (PostgreSQL)<br />`CAST(d AS SIGNED)` (MySQL)                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `d::int`                                                                            | ✔️                    | ✔️                    | –                | –                |
| `CAST(n AS double precision)` (PostgreSQL)<br />`CAST(n AS DOUBLE)` (MySQL)         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `n::float8`                                                                         | ✖️                    | ✔️                    | –                | –                |
| `CAST(n AS DECIMAL(10,2))`                                                          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CAST('42' AS integer)` (PostgreSQL)<br />`CAST('42' AS SIGNED)` (MySQL)            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CAST(dt::text AS date)` (PostgreSQL)<br />`CAST(CAST(dt AS CHAR) AS DATE)` (MySQL) | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CAST('1 day' AS interval)`                                                         | ✖️                    | Inline                | –                | –                |
| `CONVERT(n, CHAR)`                                                                  | –                     | –                     | ✔️               | ✔️               |
| `CAST(d AS CHAR)`                                                                   | –                     | –                     | ✔️               | ✔️               |
| `CAST('10.0.0.1' AS inet)`                                                          | ✖️                    | ✔️                    | –                | –                |
| `CAST('{"a":1}' AS json)` (PostgreSQL)<br />`CAST('{"a":1}' AS JSON)` (MySQL)       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `CAST(n AS UNSIGNED)`                                                               | –                     | –                     | ✔️               | ✔️               |
| `CAST(n AS bigint)`                                                                 | ✔️                    | ✔️                    | –                | –                |

### JSON

| Expression                                        | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `jb -> 'a'`                                       | ✔️                    | ✔️                    | –                | –                |
| `jb ->> 'a'`                                      | ✔️                    | ✔️                    | –                | –                |
| `jb #> '{c,d}'`                                   | ✔️                    | ✔️                    | –                | –                |
| `jb #>> '{c,d}'`                                  | ✔️                    | ✔️                    | –                | –                |
| `js -> 'a'`                                       | ✔️                    | ✔️                    | –                | –                |
| `js ->> 'a'`                                      | ✔️                    | ✔️                    | –                | –                |
| `jb @> '{"a":1}'`                                 | ✔️                    | ✔️                    | –                | –                |
| `jb <@ '{"a":1,"b":[1,2,3],"c":{"d":"x"},"e":2}'` | ✔️                    | ✔️                    | –                | –                |
| `jb \? 'a'`                                       | ✔️                    | ✔️                    | –                | –                |
| `jb \?\| array['a','z']`                          | ✔️                    | ✔️                    | –                | –                |
| `jb \?& array['a','b']`                           | ✔️                    | ✔️                    | –                | –                |
| `jb \|\| '{"z":1}'`                               | ✔️                    | ✔️                    | –                | –                |
| `jb - 'a'`                                        | ✔️                    | ✔️                    | –                | –                |
| `jb #- '{c,d}'`                                   | ✔️                    | ✔️                    | –                | –                |
| `jsonb_build_object('k', n)`                      | ✔️                    | ✔️                    | –                | –                |
| `json_build_object('k', n)`                       | ✔️                    | ✔️                    | –                | –                |
| `jsonb_build_array(n, s)`                         | ✔️                    | ✔️                    | –                | –                |
| `json_build_array(n, s)`                          | ✔️                    | ✔️                    | –                | –                |
| `jsonb_set(jb, '{a}', '2')`                       | ✔️                    | ✔️                    | –                | –                |
| `jsonb_insert(jb, '{z}', '1')`                    | ✔️                    | ✔️                    | –                | –                |
| `jsonb_extract_path(jb, 'c', 'd')`                | ✔️                    | ✔️                    | –                | –                |
| `jsonb_extract_path_text(jb, 'c', 'd')`           | ✔️                    | ✔️                    | –                | –                |
| `jsonb_typeof(jb)`                                | ✔️                    | ✔️                    | –                | –                |
| `jsonb_array_length(jb -> 'b')`                   | ✔️                    | ✔️                    | –                | –                |
| `jsonb_strip_nulls(jb)`                           | ✔️                    | ✔️                    | –                | –                |
| `to_json(s)`                                      | ✖️                    | ✔️                    | –                | –                |
| `to_jsonb(s)`                                     | ✖️                    | ✔️                    | –                | –                |
| `row_to_json(fx)`                                 | ✖️                    | ✔️                    | –                | –                |
| `jsonb_each(jb)`                                  | ✖️                    | Inline                | –                | –                |
| `jsonb_array_elements(jb -> 'b')`                 | ✖️                    | ✔️                    | –                | –                |
| `jb @\? '$.a'`                                    | ✖️                    | ✔️                    | –                | –                |
| `jb @@ '$.a == 1'`                                | ✖️                    | ✔️                    | –                | –                |
| `jsonb_path_query_first(jb, '$.a')`               | ✖️                    | ✔️                    | –                | –                |
| `jsonb_pretty(jb)`                                | ✔️                    | ✔️                    | –                | –                |
| `JSON_OBJECT('k', n)`                             | –                     | –                     | ✔️               | ✔️               |
| `JSON_OVERLAPS(JSON_EXTRACT(j, '$.b'), '[1, 9]')` | –                     | –                     | ✖️               | ✔️               |
| `JSON_DEPTH(j)`                                   | –                     | –                     | ✔️               | ✔️               |
| `JSON_VALID(s)`                                   | –                     | –                     | ✔️               | ✔️               |
| `JSON_QUOTE(s)`                                   | –                     | –                     | ✔️               | ✔️               |
| `j -> '$.a'`                                      | –                     | –                     | ✖️               | ✔️               |
| `j ->> '$.a'`                                     | –                     | –                     | ✖️               | ✔️               |
| `JSON_EXTRACT(j, '$.a')`                          | –                     | –                     | ✖️               | ✔️               |
| `JSON_UNQUOTE(JSON_EXTRACT(j, '$.c.d'))`          | –                     | –                     | ✖️               | ✔️               |
| `JSON_CONTAINS(j, '1', '$.a')`                    | –                     | –                     | ✖️               | ✔️               |
| `JSON_LENGTH(j)`                                  | –                     | –                     | ✖️               | ✔️               |
| `JSON_KEYS(j)`                                    | –                     | –                     | ✖️               | ✔️               |
| `JSON_ARRAY(n, s)`                                | –                     | –                     | ✖️               | ✔️               |
| `7 MEMBER OF (JSON_EXTRACT(j, '$.b'))`            | –                     | –                     | ✖️               | ✔️               |
| `JSON_SET(j, '$.a', 2)`                           | –                     | –                     | ✖️               | ✔️               |
| `JSON_TYPE(j)`                                    | –                     | –                     | ✖️               | ✔️               |
| `JSON_SEARCH(j, 'one', 'x')`                      | –                     | –                     | ✖️               | ✔️               |
| `JSON_MERGE_PATCH(j, '{"z":1}')`                  | –                     | –                     | ✖️               | ✔️               |
| `j`                                               | –                     | –                     | ✔️               | ✔️               |

### Arrays (PostgreSQL)

| Expression                              | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `ARRAY[n, 1]`                           | ✔️                    | ✔️                    | –                | –                |
| `ARRAY(SELECT id FROM fx WHERE id < 3)` | Partial               | ✔️                    | –                | –                |
| `n = ANY(arr)`                          | ✔️                    | ✔️                    | –                | –                |
| `arr @> ARRAY[1]`                       | ✔️                    | ✔️                    | –                | –                |
| `arr <@ ARRAY[1,2,3,4]`                 | ✔️                    | ✔️                    | –                | –                |
| `arr && ARRAY[3,9]`                     | ✔️                    | ✔️                    | –                | –                |
| `arr \|\| ARRAY[9]`                     | ✔️                    | ✔️                    | –                | –                |
| `array_to_string(arr, ',')`             | ✔️                    | ✔️                    | –                | –                |
| `arr[1]`                                | ✖️                    | ✔️                    | –                | –                |
| `arr[1:2]`                              | ✖️                    | ✔️                    | –                | –                |
| `UNNEST(arr)`                           | ✖️                    | ✔️                    | –                | –                |
| `array_length(arr, 1)`                  | ✖️                    | ✔️                    | –                | –                |
| `cardinality(arr)`                      | ✖️                    | ✔️                    | –                | –                |
| `array_append(arr, 9)`                  | ✖️                    | ✔️                    | –                | –                |
| `array_position(arr, 2)`                | ✖️                    | ✔️                    | –                | –                |
| `array_remove(arr, 2)`                  | ✖️                    | ✔️                    | –                | –                |
| `string_to_array(s, ' ')`               | ✖️                    | ✔️                    | –                | –                |
| `arr`                                   | ✔️                    | ✔️                    | –                | –                |
| `tarr`                                  | ✔️                    | ✔️                    | –                | –                |
| `ARRAY['a','b']`                        | ✔️                    | ✔️                    | –                | –                |

### Other functions

| Expression                                                  | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `RAND()`                                                    | –                     | –                     | ✖️               | ✔️               |
| `UUID()`                                                    | –                     | –                     | ✖️               | ✔️               |
| `gen_random_uuid()`                                         | ✖️                    | ✔️                    | –                | –                |
| `MATCH(t) AGAINST('lorem')`                                 | –                     | –                     | ✖️               | ✔️               |
| `to_tsvector('english', t) @@ to_tsquery('lorem')`          | ✖️                    | ✔️                    | –                | –                |
| `f_double(n)`                                               | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `LAST_INSERT_ID()`                                          | –                     | –                     | ✖️               | ✔️               |
| `version()` (PostgreSQL)<br />`VERSION()` (MySQL)           | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `current_database()` (PostgreSQL)<br />`DATABASE()` (MySQL) | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `current_user` (PostgreSQL)<br />`CURRENT_USER()` (MySQL)   | ✖️                    | ✔️                    | ✖️               | ✔️               |
| `CONNECTION_ID()`                                           | –                     | –                     | ✖️               | ✔️               |
| `pg_backend_pid()`                                          | ✖️                    | ✔️                    | –                | –                |
| `@@sql_mode`                                                | –                     | –                     | ✖️               | ✔️               |
| `@x`                                                        | –                     | –                     | ✖️               | ✔️               |
| `current_setting('TimeZone')`                               | ✖️                    | ✔️                    | –                | –                |
| `pg_typeof(n)`                                              | ✖️                    | ✔️                    | –                | –                |
| `ROW(n, s)`                                                 | Partial               | Inline                | –                | –                |
| `INTERVAL '1 hour'`                                         | ✖️                    | Inline                | –                | –                |
| `'const'`                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `42`                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `COALESCE(NULL, 1)`                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |

## Column types

A column type is cached when queries that read it are cached. A column of a type Readyset cannot replicate keeps its whole table out of push based caching. For replication details see [Supported Data Types](/concepts/deep-caching/supported-data-types).

### Integers

| Type             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| int2             | ✔️                    | ✔️                    | –                | –                |
| int4             | ✔️                    | ✔️                    | –                | –                |
| int8             | ✔️                    | ✔️                    | –                | –                |
| serial           | ✔️                    | ✔️                    | –                | –                |
| tinyint          | –                     | –                     | ✔️               | ✔️               |
| smallint         | –                     | –                     | ✔️               | ✔️               |
| mediumint        | –                     | –                     | ✔️               | ✔️               |
| int              | –                     | –                     | ✔️               | ✔️               |
| bigint           | –                     | –                     | ✔️               | ✔️               |
| tinyint unsigned | –                     | –                     | ✔️               | ✔️               |
| int unsigned     | –                     | –                     | ✔️               | ✔️               |
| bigint unsigned  | –                     | –                     | ✔️               | ✔️               |

### Numbers

| Type              | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| numeric           | ✔️                    | ✔️                    | –                | –                |
| numeric unbounded | ✔️                    | ✔️                    | –                | –                |
| real              | ✔️                    | ✔️                    | –                | –                |
| double            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| money             | ✖️                    | Inline                | –                | –                |
| decimal           | –                     | –                     | ✔️               | ✔️               |
| float             | –                     | –                     | ✔️               | ✔️               |

### Text

| Type       | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------- | --------------------- | --------------------- | ---------------- | ---------------- |
| text       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| varchar    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| char       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| citext     | ✔️                    | ✔️                    | –                | –                |
| tinytext   | –                     | –                     | ✔️               | ✔️               |
| mediumtext | –                     | –                     | ✔️               | ✔️               |
| longtext   | –                     | –                     | ✔️               | ✔️               |

### Binary

| Type       | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------- | --------------------- | --------------------- | ---------------- | ---------------- |
| bytea      | ✔️                    | ✔️                    | –                | –                |
| binary     | –                     | –                     | ✔️               | ✔️               |
| varbinary  | –                     | –                     | ✔️               | ✔️               |
| tinyblob   | –                     | –                     | ✔️               | ✔️               |
| blob       | –                     | –                     | ✔️               | ✔️               |
| mediumblob | –                     | –                     | ✔️               | ✔️               |
| longblob   | –                     | –                     | ✔️               | ✔️               |

### Boolean

| Type    | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------- | --------------------- | --------------------- | ---------------- | ---------------- |
| boolean | ✔️                    | ✔️                    | –                | –                |
| bool    | –                     | –                     | ✔️               | ✔️               |

### Dates and times

| Type        | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----------- | --------------------- | --------------------- | ---------------- | ---------------- |
| date        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| time        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| timetz      | ✖️                    | Inline                | –                | –                |
| timestamp   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| timestamptz | ✔️                    | ✔️                    | –                | –                |
| interval    | ✖️                    | Inline                | –                | –                |
| datetime    | –                     | –                     | ✔️               | ✔️               |
| datetime6   | –                     | –                     | ✔️               | ✔️               |
| time6       | –                     | –                     | ✔️               | ✔️               |
| year        | –                     | –                     | ✖️               | ✔️               |

### Other types

| Type      | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------- | --------------------- | --------------------- | ---------------- | ---------------- |
| uuid      | ✔️                    | ✔️                    | –                | –                |
| xml       | ✖️                    | Inline                | –                | –                |
| domain    | ✖️                    | ✔️                    | –                | –                |
| composite | ✖️                    | Inline                | –                | –                |

### JSON

| Type  | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----- | --------------------- | --------------------- | ---------------- | ---------------- |
| json  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| jsonb | ✔️                    | ✔️                    | –                | –                |

### Bit strings

| Type   | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------ | --------------------- | --------------------- | ---------------- | ---------------- |
| bit    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| varbit | ✔️                    | ✔️                    | –                | –                |

### Enumerations and sets

| Type | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---- | --------------------- | --------------------- | ---------------- | ---------------- |
| enum | ✔️                    | ✔️                    | ✔️               | ✔️               |
| set  | –                     | –                     | ✖️               | ✔️               |

### Arrays

| Type         | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------ | --------------------- | --------------------- | ---------------- | ---------------- |
| int array    | ✔️                    | ✔️                    | –                | –                |
| text array   | ✔️                    | ✔️                    | –                | –                |
| int array 2d | ✔️                    | ✔️                    | –                | –                |

### Network addresses

| Type    | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------- | --------------------- | --------------------- | ---------------- | ---------------- |
| inet    | ✖️                    | ✔️                    | –                | –                |
| cidr    | ✖️                    | ✔️                    | –                | –                |
| macaddr | ✖️                    | ✔️                    | –                | –                |

### Text search

| Type     | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| -------- | --------------------- | --------------------- | ---------------- | ---------------- |
| tsvector | ✔️                    | ✔️                    | –                | –                |
| tsquery  | ✖️                    | Inline                | –                | –                |

### Ranges

| Type      | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------- | --------------------- | --------------------- | ---------------- | ---------------- |
| int4range | ✖️                    | Inline                | –                | –                |
| tsrange   | ✖️                    | Inline                | –                | –                |

### Geometric

| Type               | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------ | --------------------- | --------------------- | ---------------- | ---------------- |
| point              | ✖️                    | Inline                | ✔️               | ✔️               |
| polygon            | ✖️                    | Inline                | ✖️               | ✔️               |
| geometry           | –                     | –                     | ✖️               | ✔️               |
| linestring         | –                     | –                     | ✖️               | ✔️               |
| multipoint         | –                     | –                     | ✖️               | ✔️               |
| geometrycollection | –                     | –                     | ✖️               | ✔️               |

### PostGIS

| Type             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| geometry point   | ✔️                    | Inline                | –                | –                |
| geometry polygon | ✔️                    | Inline                | –                | –                |
| geography point  | ✖️                    | Inline                | –                | –                |

### Table kinds

| Type               | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------ | --------------------- | --------------------- | ---------------- | ---------------- |
| generated          | ✖️                    | ✔️                    | –                | –                |
| partitioned        | ✖️                    | ✔️                    | –                | –                |
| generated\_stored  | –                     | –                     | ✔️               | ✔️               |
| generated\_virtual | –                     | –                     | ✔️               | ✔️               |

## Schema and session conditions

How Readyset behaves with different table layouts and connection settings. ✖️ means Readyset passes the query to the upstream database instead of caching it.

### Table and schema shapes

| Setting or table shape                                                                                                                                                                                                                                                                               | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| No primary key · eq<br />`SELECT a, b FROM sc_nopk WHERE a = ?`                                                                                                                                                                                                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| No primary key · count<br />`SELECT COUNT(*) AS n FROM sc_nopk WHERE b = ?`                                                                                                                                                                                                                          | ✔️                    | ✔️                    | ✔️               | ✔️               |
| No primary key · all<br />`SELECT a, b FROM sc_nopk`                                                                                                                                                                                                                                                 | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Composite primary key · full<br />`SELECT v FROM sc_compkey WHERE a = ? AND b = ?`                                                                                                                                                                                                                   | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Composite primary key · prefix<br />`SELECT b, v FROM sc_compkey WHERE a = ?`                                                                                                                                                                                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Composite primary key · suffix<br />`SELECT a, v FROM sc_compkey WHERE b = ?`                                                                                                                                                                                                                        | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Unique index, no primary key · eq<br />`SELECT id, v FROM sc_uniq WHERE id = ?`                                                                                                                                                                                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Nullable indexed column · eq<br />`SELECT id, v FROM sc_nullkey WHERE k = ?`                                                                                                                                                                                                                         | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Nullable indexed column · is null<br />`SELECT id, v FROM sc_nullkey WHERE k IS NULL`                                                                                                                                                                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Nullable indexed column · eq and null check<br />`SELECT id FROM sc_nullkey WHERE k = ? AND v IS NOT NULL`                                                                                                                                                                                           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Unindexed column lookup · eq<br />`SELECT id, v FROM sc_noidx WHERE k = ?`                                                                                                                                                                                                                           | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Text primary key · eq<br />`SELECT code, v FROM sc_vpk WHERE code = ?`                                                                                                                                                                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| UUID primary key · eq<br />`SELECT id, v FROM sc_uuidpk WHERE id = ?`                                                                                                                                                                                                                                | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Bigint primary key · eq<br />`SELECT id, v FROM sc_bigpk WHERE id = ?`                                                                                                                                                                                                                               | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Bigint primary key · max<br />`SELECT id, v FROM sc_bigpk WHERE id = ?`                                                                                                                                                                                                                              | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Wide table (60 columns) · star<br />`SELECT * FROM sc_wide WHERE id = ?`                                                                                                                                                                                                                             | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Wide table (60 columns) · few columns<br />`SELECT id, c1, c30, c60 FROM sc_wide WHERE id = ?`                                                                                                                                                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Empty table · eq<br />`SELECT id, v FROM sc_empty WHERE id = ?`                                                                                                                                                                                                                                      | ✔️                    | Inline                | ✔️               | ✔️               |
| Empty table · count<br />`SELECT COUNT(*) AS n FROM sc_empty WHERE v = ?`                                                                                                                                                                                                                            | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Reserved words as identifiers<br />PostgreSQL: `SELECT "select", "from" FROM "order" WHERE "group" = ?`<br />MySQL: ``SELECT `select`, `from` FROM `order` WHERE `group` = ?``                                                                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Mixed-case identifiers<br />PostgreSQL: `SELECT "Id", "FirstName" FROM "MixedCase" WHERE "Id" = ?`<br />MySQL: `SELECT Id, FirstName FROM MixedCase WHERE Id = ?`                                                                                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Mixed-case identifiers · lower reference<br />`SELECT Id, FirstName FROM mixedcase WHERE Id = ?`                                                                                                                                                                                                     | –                     | –                     | ✖️               | ✔️               |
| Schema-qualified names · unqualified<br />`SELECT id, v FROM sc_dup WHERE id = ?`                                                                                                                                                                                                                    | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Schema-qualified names · primary<br />PostgreSQL: `SELECT id, v FROM public.sc_dup WHERE id = ?`<br />MySQL: `SELECT id, v FROM qs_mysql_sc.sc_dup WHERE id = ?`                                                                                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Schema-qualified names · other<br />PostgreSQL: `SELECT id, v FROM other.sc_dup WHERE id = ?`<br />MySQL: `SELECT id, v FROM qs_mysql_sc_other.sc_dup WHERE id = ?`                                                                                                                                  | ✔️                    | ✔️                    | ✖️               | ✔️               |
| Schema-qualified names · other only table<br />`SELECT id, v FROM other.sc_only WHERE id = ?`                                                                                                                                                                                                        | ✔️                    | ✔️                    | –                | –                |
| Schema-qualified names · join across schemas<br />PostgreSQL: `SELECT a.v AS av, b.v AS bv FROM public.sc_dup a JOIN other.sc_dup b ON a.id = b.id WHERE a.id = ?`<br />MySQL: `SELECT a.v AS av, b.v AS bv FROM qs_mysql_sc.sc_dup a JOIN qs_mysql_sc_other.sc_dup b ON a.id = b.id WHERE a.id = ?` | ✔️                    | ✔️                    | ✖️               | ✔️               |
| View · select<br />`SELECT id, name FROM sc_view WHERE id = ?`                                                                                                                                                                                                                                       | ✔️                    | ✔️                    | ✔️               | ✔️               |
| View · join<br />`SELECT v.name, s.amt FROM sc_view v JOIN sess s ON s.id = v.id WHERE v.id = ?`                                                                                                                                                                                                     | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Materialized view · select<br />`SELECT id, name FROM sc_matview WHERE id = ?`                                                                                                                                                                                                                       | ✖️                    | ✔️                    | –                | –                |
| Unlogged table · select<br />`SELECT id, v FROM sc_unlogged WHERE id = ?`                                                                                                                                                                                                                            | ✔️                    | ✔️                    | –                | –                |
| Foreign keys · join<br />`SELECT p.name, c.v FROM sc_parent p JOIN sc_child c ON c.parent_id = p.id WHERE p.id = ?`                                                                                                                                                                                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Foreign keys · child only<br />`SELECT id, v FROM sc_child WHERE parent_id = ?`                                                                                                                                                                                                                      | ✔️                    | ✔️                    | ✔️               | ✔️               |
| Storage engine · myisam<br />`SELECT id, v FROM sc_myisam WHERE id = ?`                                                                                                                                                                                                                              | –                     | –                     | ✖️               | ✔️               |
| Storage engine · memory<br />`SELECT id, v FROM sc_memory WHERE id = ?`                                                                                                                                                                                                                              | –                     | –                     | ✖️               | ✔️               |
| Table character set · latin1 table<br />`SELECT id, v FROM sc_latin1 WHERE id = ?`                                                                                                                                                                                                                   | –                     | –                     | ✔️               | ✔️               |
| Table collation · bin table eq<br />`SELECT id FROM sc_bincoll WHERE v = ?`                                                                                                                                                                                                                          | –                     | –                     | ✔️               | ✔️               |
| Partitioned table · hash<br />`SELECT id, v FROM sc_part WHERE id = ?`                                                                                                                                                                                                                               | –                     | –                     | ✖️               | ✔️               |

### Session time zone

| Setting or table shape             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `Default session`                  | ✔️                    | ✔️                    | ✔️               | ✔️               |
| `SET TIME ZONE 'UTC'`              | ✔️                    | ✔️                    | –                | –                |
| `SET TIME ZONE 'America/New_York'` | ✔️                    | ✔️                    | –                | –                |
| `SET TIME ZONE 'Asia/Kolkata'`     | ✔️                    | ✔️                    | –                | –                |
| `SET TIME ZONE 'Asia/Tokyo'`       | ✔️                    | ✔️                    | –                | –                |
| `SET time_zone = '+00:00'`         | –                     | –                     | ✔️               | ✔️               |
| `SET time_zone = '+05:30'`         | –                     | –                     | ✖️               | ✖️               |
| `SET time_zone = '-08:00'`         | –                     | –                     | ✖️               | ✖️               |
| `SET time_zone = 'SYSTEM'`         | –                     | –                     | ✖️               | ✖️               |

### Connection character set and encoding

| Setting or table shape                  | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| --------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `SET client_encoding = 'UTF8'`          | ✔️                    | ✔️                    | –                | –                |
| `SET client_encoding = 'LATIN1'`        | ✖️                    | ✖️                    | –                | –                |
| `SET client_encoding = 'WIN1252'`       | ✖️                    | ✖️                    | –                | –                |
| `SET client_encoding = 'SQL_ASCII'`     | ✖️                    | ✖️                    | –                | –                |
| `SET NAMES utf8mb4`                     | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES utf8mb3`                     | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES latin1`                      | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES gbk`                         | –                     | –                     | ✖️               | ✖️               |
| `SET NAMES sjis`                        | –                     | –                     | ✖️               | ✖️               |
| `SET NAMES ascii`                       | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES binary`                      | –                     | –                     | Partial          | ✖️               |
| `SET NAMES big5`                        | –                     | –                     | ✖️               | ✖️               |
| `SET character_set_results = NULL`      | –                     | –                     | ✖️               | ✖️               |
| `SET character_set_results = latin1`    | –                     | –                     | ✔️               | ✔️               |
| `SET character_set_client = latin1`     | –                     | –                     | ✔️               | ✔️               |
| `SET character_set_connection = latin1` | –                     | –                     | ✔️               | ✔️               |

### Output formatting settings (PostgreSQL)

| Setting or table shape                   | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `SET DateStyle = 'ISO, DMY'`             | ✖️                    | ✖️                    | –                | –                |
| `SET DateStyle = 'SQL, MDY'`             | ✖️                    | ✖️                    | –                | –                |
| `SET DateStyle = 'SQL, DMY'`             | ✖️                    | ✖️                    | –                | –                |
| `SET DateStyle = 'German'`               | ✖️                    | ✖️                    | –                | –                |
| `SET DateStyle = 'Postgres, MDY'`        | ✖️                    | ✖️                    | –                | –                |
| `SET IntervalStyle = 'sql_standard'`     | ✖️                    | ✔️                    | –                | –                |
| `SET IntervalStyle = 'postgres_verbose'` | ✖️                    | ✔️                    | –                | –                |
| `SET IntervalStyle = 'iso_8601'`         | ✖️                    | ✔️                    | –                | –                |
| `SET extra_float_digits = 3`             | ✖️                    | ✔️                    | –                | –                |
| `SET extra_float_digits = 0`             | ✖️                    | ✖️                    | –                | –                |
| `SET extra_float_digits = -3`            | ✖️                    | ✖️                    | –                | –                |
| `SET bytea_output = 'escape'`            | ✖️                    | ✖️                    | –                | –                |
| `SET bytea_output = 'hex'`               | ✖️                    | ✔️                    | –                | –                |

### `search_path` (PostgreSQL)

| Setting or table shape             | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `SET search_path TO public`        | ✔️                    | ✔️                    | –                | –                |
| `SET search_path TO other, public` | ✔️                    | ✔️                    | –                | –                |
| `SET search_path TO other`         | ✔️                    | ✔️                    | –                | –                |

### Other session settings

| Setting or table shape                                                    | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `SET transform_null_equals = on`                                          | ✖️                    | ✖️                    | –                | –                |
| `SET standard_conforming_strings = off`                                   | ✖️                    | ✖️                    | –                | –                |
| `SET row_security = off`                                                  | ✔️                    | ✔️                    | –                | –                |
| `SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE` | ✔️                    | ✔️                    | –                | –                |
| `SET default_transaction_read_only = on`                                  | ✔️                    | ✔️                    | –                | –                |
| `SET statement_timeout = '5s'`                                            | ✔️                    | ✔️                    | –                | –                |
| `SET application_name = 'qs_probe'`                                       | ✔️                    | ✔️                    | –                | –                |
| `SET lock_timeout = '2s'`                                                 | ✔️                    | ✔️                    | –                | –                |
| `SET work_mem = '8MB'`                                                    | ✔️                    | ✔️                    | –                | –                |
| `SET synchronous_commit = off`                                            | ✔️                    | ✔️                    | –                | –                |
| `SET plan_cache_mode = force_custom_plan`                                 | ✖️                    | ✖️                    | –                | –                |
| `SET default_text_search_config = 'pg_catalog.simple'`                    | ✔️                    | ✔️                    | –                | –                |
| `SET xmloption = document`                                                | ✔️                    | ✔️                    | –                | –                |
| `SET lc_messages = 'C'`                                                   | ✖️                    | ✖️                    | –                | –                |
| `SET enable_seqscan = off`                                                | ✔️                    | ✔️                    | –                | –                |
| `SET idle_in_transaction_session_timeout = '60s'`                         | ✔️                    | ✔️                    | –                | –                |
| `SET group_concat_max_len = 5`                                            | –                     | –                     | ✖️               | ✔️               |
| `SET div_precision_increment = 2`                                         | –                     | –                     | ✔️               | ✔️               |
| `SET sql_select_limit = 2`                                                | –                     | –                     | ✔️               | ✔️               |
| `SET sql_auto_is_null = 1`                                                | –                     | –                     | ✔️               | ✔️               |
| `SET lc_time_names = 'de_DE'`                                             | –                     | –                     | ✔️               | ✔️               |
| `SET lc_time_names = 'fr_FR'`                                             | –                     | –                     | ✔️               | ✔️               |
| `SET max_execution_time = 1000`                                           | –                     | –                     | ✔️               | ✔️               |
| `SET @x = 1`                                                              | –                     | –                     | ✖️               | ✖️               |
| `SET foreign_key_checks = 0`                                              | –                     | –                     | ✔️               | ✔️               |
| `SET unique_checks = 0`                                                   | –                     | –                     | ✔️               | ✔️               |
| `SET sql_safe_updates = 1`                                                | –                     | –                     | ✔️               | ✔️               |
| `SET default_week_format = 3`                                             | –                     | –                     | ✔️               | ✔️               |
| `SET sql_big_selects = 0`                                                 | –                     | –                     | ✔️               | ✔️               |
| `SET net_read_timeout = 60`                                               | –                     | –                     | ✔️               | ✔️               |
| `SET optimizer_switch = 'index_merge=off'`                                | –                     | –                     | ✔️               | ✔️               |
| `SET sort_buffer_size = 524288`                                           | –                     | –                     | ✔️               | ✔️               |
| `SET session_track_schema = ON`                                           | –                     | –                     | ✔️               | ✔️               |
| `SET explicit_defaults_for_timestamp = ON`                                | –                     | –                     | ✔️               | ✔️               |

### Transactions

| Setting or table shape                                     | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `BEGIN`                                                    | ✖️                    | ✖️                    | –                | –                |
| `BEGIN READ ONLY`                                          | ✖️                    | ✖️                    | –                | –                |
| `BEGIN ISOLATION LEVEL REPEATABLE READ`                    | ✖️                    | ✖️                    | –                | –                |
| `BEGIN ISOLATION LEVEL SERIALIZABLE`                       | ✖️                    | ✖️                    | –                | –                |
| `SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED`   | –                     | –                     | ✔️               | ✔️               |
| `SET SESSION TRANSACTION ISOLATION LEVEL SERIALIZABLE`     | –                     | –                     | ✔️               | ✔️               |
| `SET SESSION TRANSACTION ISOLATION LEVEL READ UNCOMMITTED` | –                     | –                     | ✔️               | ✔️               |
| `SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ`  | –                     | –                     | ✔️               | ✔️               |
| `SET SESSION TRANSACTION READ ONLY`                        | –                     | –                     | ✔️               | ✔️               |
| `SET autocommit = 0`                                       | –                     | –                     | ✖️               | ✖️               |
| `SET autocommit = 1`                                       | –                     | –                     | ✔️               | ✔️               |
| `START TRANSACTION`                                        | –                     | –                     | ✖️               | ✖️               |
| `START TRANSACTION READ ONLY`                              | –                     | –                     | ✖️               | ✖️               |
| `START TRANSACTION WITH CONSISTENT SNAPSHOT`               | –                     | –                     | ✔️               | ✔️               |

### Temporary tables

| Setting or table shape                                                                                   | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| -------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `CREATE TEMPORARY TABLE tmp_s (id int PRIMARY KEY, v varchar(10)); INSERT INTO tmp_s VALUES (1, 'mine')` | ✖️                    | ✖️                    | ✖️               | ✔️               |

### Connection collation

| Setting or table shape                         | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ---------------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `SET NAMES utf8mb4 COLLATE utf8mb4_bin`        | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci` | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES utf8mb4 COLLATE utf8mb4_0900_as_cs` | –                     | –                     | ✔️               | ✔️               |
| `SET NAMES utf8mb4 COLLATE utf8mb4_general_ci` | –                     | –                     | ✔️               | ✔️               |

### `sql_mode` (MySQL)

| Setting or table shape                    | PostgreSQL push based | PostgreSQL pull based | MySQL push based | MySQL pull based |
| ----------------------------------------- | --------------------- | --------------------- | ---------------- | ---------------- |
| `SET sql_mode = ''`                       | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'ANSI'`                   | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'PIPES_AS_CONCAT'`        | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'ANSI_QUOTES'`            | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'NO_BACKSLASH_ESCAPES'`   | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'TRADITIONAL'`            | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'STRICT_ALL_TABLES'`      | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'NO_ZERO_DATE'`           | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'REAL_AS_FLOAT'`          | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'HIGH_NOT_PRECEDENCE'`    | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'NO_ENGINE_SUBSTITUTION'` | –                     | –                     | ✖️               | ✖️               |
| `SET sql_mode = 'STRICT_TRANS_TABLES'`    | –                     | –                     | ✖️               | ✖️               |


# Read-your-writes (/concepts/read-your-writes)
import { Callout } from 'fumadocs-ui/components/callout'

# Read-your-writes

Replication from your upstream database to Readyset is asynchronous. A session that writes a row and immediately reads it back can therefore see the *pre-write* value if the read is served from a Readyset cache before the cache has caught up to the write. Readyset gives you two separate controls for this, and they cover different code paths:

* **Inside a transaction:** the cache's per-cache **transaction policy** (set on `CREATE CACHE` / `CREATE SHALLOW CACHE`).
* **Outside any transaction:** an optional **opportunistic read-your-writes window** configured at the adapter level via [`--opportunistic-ryw-ms`](/reference/config-options#--opportunistic-ryw-ms).

The two controls do not overlap. Opportunistic read-your-writes is dormant inside transactions; the per-cache transaction policy is what governs in-transaction routing. Pick the right control for the place the read happens.

## Inside a transaction: the cache's transaction policy

When a session is inside an explicit `BEGIN ... COMMIT` block (or an implicit transaction under `autocommit=0`), routing is decided entirely by the cache's transaction policy, declared on the cache:

```sql
CREATE CACHE [<name>] WITH (ALWAYS | UNTIL WRITE) FROM <query>;
CREATE SHALLOW CACHE [<name>] WITH (POLICY ..., ALWAYS | UNTIL WRITE) FROM <query>;
```

There are three possible policies. They differ in how reads are routed once the session is inside a transaction:

### `NEVER` (default, no keyword)

When no keyword is supplied on `CREATE CACHE` / `CREATE SHALLOW CACHE`, the cached query is *always* proxied upstream while the session is inside a transaction. The cache is consulted only once the transaction commits. This is the safest default: every read inside the transaction observes the same snapshot the upstream would, including the session's own pending writes.

Use this when an unconditional read-your-writes guarantee inside the transaction is required and cache hits inside transactions are not important.

### `ALWAYS`

Documented at [`ALWAYS`](/command-reference#always). The cached query is served from Readyset regardless of transaction state. Reads inside the transaction can therefore observe a pre-write value of the session's own writes (the cache has not yet absorbed them).

Use this when occasional stale reads inside transactions are acceptable in exchange for cache hits on every statement, even inside a `BEGIN`/`COMMIT` block. Common case: drivers that wrap every statement in a transaction yet only ever issue reads.

### `UNTIL WRITE`

Documented at [`UNTIL WRITE`](/command-reference#until-write). Reads are served from the cache as long as the transaction has not yet observed an `INSERT`, `UPDATE`, or `DELETE`. The first write flips the session into a "had write in txn" state, and *every* subsequent read in that transaction is proxied upstream, including reads from caches whose tables have nothing to do with the write. The flip is session-wide, not per-table. The cache becomes available again at the next transaction boundary.

This is the right default for client drivers that wrap every statement in an implicit transaction (Python with `autocommit=False`, JDBC defaults, ORMs that do not expose autocommit). Read-only-so-far statements get cache hits; once the transaction has written, the rest of the transaction reads its own writes through the upstream.

`UNTIL WRITE` is also the default policy for caches created automatically by [`--auto-cache`](/concepts/shallow-caching/auto-caching) and by [hint-based auto-creation](/concepts/shallow-caching/hint-based-caches).

### Picking a policy

| Need                                                                                  | Policy            |
| ------------------------------------------------------------------------------------- | ----------------- |
| Strictest read-your-writes inside transactions; do not care about in-txn cache hits   | `NEVER` (default) |
| In-transaction cache hits are required and stale-reads-of-own-writes are acceptable   | `ALWAYS`          |
| Cache hits while the transaction is read-only; read-your-writes after the first write | `UNTIL WRITE`     |

## Outside any transaction: the opportunistic window

Outside of a transaction (autocommit-on, no `BEGIN`), Readyset has no transaction boundary on which to flip routing. A session that does:

```
INSERT INTO t (id) VALUES (1);   -- write goes to upstream
SELECT * FROM t WHERE id = 1;    -- next statement is autocommitted
```

may be served the second statement from a Readyset cache before the cache has observed the insert. This is where [`--opportunistic-ryw-ms`](/reference/config-options#--opportunistic-ryw-ms) comes in. When set, every write on the session arms a deadline `now + N ms`. Until that deadline elapses, *every* read on the same session bypasses the cache and is proxied to the upstream, regardless of the cache's transaction policy, and regardless of whether the read touches the same table as the write. A write to one table arms the window for *all* caches that session subsequently reads from.

```text
INSERT (autocommit on)  ──▶ window armed for N ms
SELECT during window     ──▶ proxied upstream (sees the write)
... time passes (> N ms) ...
SELECT after window      ──▶ served from cache (may be pre-write)
```

The window also applies on the canonical `BEGIN; INSERT; COMMIT; SELECT` pattern: `BEGIN` clears the window (the per-cache policy takes over while inside the transaction), and `COMMIT` re-arms it if the transaction wrote, so the post-`COMMIT` `SELECT` reads the session's own writes through the upstream. `ROLLBACK` clears it (rolled-back writes never landed).

### This is opportunistic, not a guarantee

<Callout type="warning">
  `--opportunistic-ryw-ms` is *not* a consistency guarantee. It only suppresses the cache for the configured window. Once the window elapses, reads resume from the cache, and the cache may still hold a pre-write value. Two common ways this happens:

  * **TTL not yet expired.** A shallow cache with a 60-second TTL caches a row at `t=0`. A write lands at `t=10`. Even with `--opportunistic-ryw-ms 5000`, reads at `t > 15s` resume from the cache and continue to serve the pre-write value until the TTL expires at `t=60`.
  * **Refresh has not caught up.** Even if the cache has a short TTL or a refresh schedule, the post-window read can race the refresh and pick up the stale entry.

  In both cases, after the configured window the session can flip from "reading upstream and seeing my write" back to "reading cache and seeing the old value." The window narrows the race; it does not close it.
</Callout>

### When to enable it

Enable `--opportunistic-ryw-ms` only when:

* Sessions issue writes outside transactions and immediately read back, *and*
* Occasional stale reads after the window are acceptable for your workload, *and*
* You have measured replication lag and picked a window that is long enough to cover the typical gap (too short and the freshly-written row may still be served stale; too long and reads that could safely hit the cache go upstream instead).

If you need stricter guarantees, do the writes and reads inside a transaction and pick the appropriate transaction policy above.

The window is **disabled by default**. The default is conservative because the right value depends on your replication lag and your tolerance for stale reads after the window.

## See also

* [`--opportunistic-ryw-ms`](/reference/config-options#--opportunistic-ryw-ms): flag reference.
* [`ALWAYS`](/command-reference#always), [`UNTIL WRITE`](/command-reference#until-write): per-cache transaction policy keywords.
* [`CREATE CACHE`](/command-reference#create-cache): full DDL syntax, including the `[DEEP | SHALLOW]` modifier.
* [Auto-caching](/concepts/shallow-caching/auto-caching): default policy for auto-created caches.
* [Hint-based caches](/concepts/shallow-caching/hint-based-caches): default policy for hint-created caches.


# Automatic Shallow Caching (/concepts/shallow-caching/auto-caching)
import { Callout } from 'fumadocs-ui/components/callout'

Automatic shallow caching lets Readyset create a [shallow cache](/concepts/shallow-caching) for every previously-unseen `SELECT` it sees, with no `CREATE CACHE` statement and no `/*rs+ ... */` hint required. The first time a query reaches Readyset it is proxied to the upstream database and a cache is created in the background; subsequent executions are served from that cache.

This is the lowest-friction way to onboard an existing application: point your client at Readyset, run your normal traffic, and caches accumulate as your queries arrive.

## Enabling auto-caching

Pass [`--auto-cache`](/reference/config-options#--auto-cache) when starting Readyset:

```bash
readyset --upstream-db-url=... --auto-cache ...
```

`--auto-cache` is shorthand for [`--cache-mode=shallow`](/reference/config-options#--cache-mode) plus [`--query-caching=inrequestpath`](/reference/config-options#--query-caching). It is mutually exclusive with both of those flags. Use it unless you specifically need a non-shallow cache mode or a different migration style.

## How it works

1. **First execution** — Readyset receives a `SELECT` it has not seen before. It checks the query against the [eligibility filter](#eligibility-filter). If the query passes, Readyset proxies it to the upstream database, returns the result, and creates a shallow cache for the query.
2. **Subsequent executions** — Matching queries are served from the shallow cache, subject to the cache's TTL and refresh settings. See [Shallow Caching](/concepts/shallow-caching) for cache semantics.
3. **Ineligible queries** — Queries that fail the eligibility filter are proxied to upstream every time. No cache is created and no automatic retry is attempted.

The default cache parameters (TTL, coalescing, refresh) come from [`--default-ttl-ms`](/reference/config-options#--default-ttl-ms) and [`--default-coalesce-ms`](/reference/config-options#--default-coalesce-ms). Auto-created caches also use [adaptive refresh](/concepts/shallow-caching#adaptive-refresh), so per-entry refresh intervals track observed data change rates. To override these parameters per query, use a [`/*rs+ CREATE SHALLOW CACHE ... */` hint](/concepts/shallow-caching/hint-based-caches) instead; hint-created caches are adaptive only when the hint includes [`ADAPTIVE`](/command-reference#adaptive). Explicit hints take precedence over the auto-cache trigger and bypass the eligibility filter.

## Transaction handling

Auto-created caches default to the [`UNTIL WRITE`](/command-reference#until-write) transaction policy. Inside a transaction, the cache is consulted as long as the transaction has not yet observed a write. After the first `INSERT`, `UPDATE`, or `DELETE`, subsequent reads in that transaction are proxied upstream. The cache becomes available again at the next transaction boundary.

This default makes auto-caching compatible with client drivers that wrap every statement in an implicit transaction (for example, Python drivers running with `autocommit=False`, JDBC defaults, or ORMs that do not expose autocommit). Without `UNTIL WRITE`, those clients would never see cache hits because every query would be inside a transaction.

To override the default for a specific query, use a [`/*rs+ CREATE SHALLOW CACHE WITH (ALWAYS) */`](/concepts/shallow-caching/hint-based-caches#with-always-transaction-support) hint (always serve from cache regardless of transaction state) or an explicit `CREATE SHALLOW CACHE` DDL statement with the keyword you want.

For read-your-writes outside of transactions, see the [Read-your-writes](/concepts/read-your-writes) concept page and [`--opportunistic-ryw-ms`](/reference/config-options#--opportunistic-ryw-ms): when set, reads on a session bypass every cache for a configurable window after any write on that same session. The window is opportunistic, not a consistency guarantee, so review the concept page before enabling it.

## Eligibility filter

Auto-caching is deliberately aggressive: every previously-unseen `SELECT` is a candidate. That is too aggressive for client and driver bootstrap traffic, which is structurally `SELECT` but should never be cached. The eligibility filter rejects three classes of query before a cache can be created. Ineligible queries are simply proxied to upstream; they do not produce errors.

The filter applies only to the implicit auto-cache trigger. Explicit `CREATE CACHE` statements and `/*rs+ CREATE SHALLOW CACHE */` hints are user-initiated and bypass it.

### System-schema references

A query is rejected if any table reference (including inside a CTE or subquery) targets a database system schema.

| Dialect    | Schemas                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| MySQL      | `mysql`, `information_schema`, `performance_schema`, `sys`                                                     |
| PostgreSQL | `pg_catalog`, `information_schema`, `readyset`, plus any schema whose name begins with `pg_toast` or `pg_temp` |

Examples that are filtered out:

```sql
SELECT * FROM information_schema.tables WHERE table_schema = 'app';
SELECT * FROM mysql.user;
SELECT * FROM pg_catalog.pg_class;
WITH t AS (SELECT * FROM pg_catalog.pg_class) SELECT * FROM t;
```

### User and session variables

A query is rejected if it references a session variable, user variable, or any compound expression rooted in one. The most common case is MySQL clients probing server state on connect.

```sql
SELECT @@version;
SELECT @@global.max_connections;
SELECT @my_user_var;
SELECT id FROM users WHERE id = @target_id;
```

The check matches identifiers and compound identifiers whose first component starts with `@`, so both `@var` and `@@scope.name` forms are caught.

### Non-deterministic functions

A query is rejected if it calls a function whose result depends on time, randomness, session state, server state, or external resources. Matching is case-insensitive and checks the last component of the function name, so both `now()` and `pg_catalog.now()` are caught.

| Category                            | Functions                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time and clock                      | `now`, `current_timestamp`, `current_date`, `current_time`, `localtime`, `localtimestamp`, `sysdate`, `clock_timestamp`, `statement_timestamp`, `transaction_timestamp`, `timeofday`, `unix_timestamp`, `curdate`, `curtime`, `utc_date`, `utc_time`, `utc_timestamp`                                                                                                                                      |
| Identity and session                | `user`, `current_user`, `session_user`, `system_user`, `current_role`, `current_database`, `current_schema`, `current_schemas`, `current_catalog`, `database`, `schema`, `version`, `connection_id`, `pg_backend_pid`, `ps_current_thread_id`, `ps_thread_id`, `inet_client_addr`, `inet_client_port`, `inet_server_addr`, `inet_server_port`, `txid_current`, `last_insert_id`, `found_rows`, `row_count` |
| Sequence state (PostgreSQL)         | `lastval`, `nextval`, `currval`                                                                                                                                                                                                                                                                                                                                                                            |
| Randomness                          | `rand`, `random`, `random_bytes`, `uuid`, `uuid_short`, `gen_random_uuid`                                                                                                                                                                                                                                                                                                                                  |
| Side-effecting and blocking (MySQL) | `sleep`, `load_file`                                                                                                                                                                                                                                                                                                                                                                                       |
| Advisory locks (MySQL)              | `get_lock`, `release_lock`, `release_all_locks`, `is_free_lock`, `is_used_lock`                                                                                                                                                                                                                                                                                                                            |
| Replication waits (MySQL)           | `master_pos_wait`, `source_pos_wait`, `wait_for_executed_gtid_set`                                                                                                                                                                                                                                                                                                                                         |
| Misc                                | `benchmark`                                                                                                                                                                                                                                                                                                                                                                                                |

#### Bare session keywords

A subset of the names above also reject the query when used as a bare identifier without parentheses. PostgreSQL accepts `SELECT current_user` (no `()`) as a session-state reference, and the filter treats it the same way:

`current_user`, `current_role`, `session_user`, `system_user`, `current_database`, `current_schema`, `current_catalog`, `current_date`, `current_time`, `current_timestamp`, `localtime`, `localtimestamp`.

```sql
SELECT current_user;
SELECT current_timestamp;
```

## Skipping the cache for a single query

To prevent a specific query from being auto-cached even though it would pass the eligibility filter, annotate it with the [`/*rs+ SKIP CACHE */` hint](/concepts/shallow-caching/hint-based-caches#skip-cache-syntax):

```sql
SELECT /*rs+ SKIP CACHE */ id, name FROM users WHERE id = ?;
```

`SKIP CACHE` routes the query directly to upstream and never creates a cache for it.

## See also

* [`--auto-cache`](/reference/config-options#--auto-cache) — the convenience flag that turns this mode on.
* [Shallow Caching concept](/concepts/shallow-caching) — what shallow caches are and how they refresh.
* [Hint-based caches](/concepts/shallow-caching/hint-based-caches) — per-query control with `/*rs+ ... */` hints, including how to bypass auto-caching.


# Hint-Based Caches (/concepts/shallow-caching/hint-based-caches)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Hint-based caches let you create [shallow caches](/concepts/shallow-caching) inline, directly within your application's SQL queries. Instead of managing caches out-of-band through a Readyset shell or admin connection, you embed a special comment (a **hint**) in a `SELECT` statement and Readyset automatically creates the cache on first execution.

You can also use hints to **bypass** caching entirely for individual queries with `SKIP CACHE`, routing them straight to the upstream database.

## Why use hints?

With DDL-based cache creation (`CREATE SHALLOW CACHE ... FROM ...`), a DBA or operations engineer creates caches ahead of time through the Readyset shell. This works well for a known, stable set of queries but can be cumbersome when:

* **Application teams own query performance.** Developers know which queries are latency-sensitive and can annotate them at the source, right next to the query itself, without requiring a separate operational step.
* **Caches should be created on demand.** New queries or code paths are deployed frequently, and you want caching to follow the code rather than requiring manual DDL after each deploy.
* **Different queries need different policies.** Each hint can carry its own TTL, refresh, and coalesce settings, so the application can express per-query caching requirements directly in the SQL text.

Hints give your application declarative control over what gets cached and how, making cache management part of your code review and deployment workflow rather than an external operational concern.

## Syntax

Place a hint comment immediately after the `SELECT` keyword:

```sql
SELECT /*rs+ CREATE SHALLOW CACHE [options] */ columns FROM ...
SELECT /*rs+ SKIP CACHE */ columns FROM ...
```

The hint uses the optimizer-hint comment format `/*rs+ ... */`. The `rs` prefix identifies it as a Readyset directive and is case-insensitive (`/*rs+`, `/*RS+`, and `/*Rs+` are all equivalent).

### CREATE SHALLOW CACHE syntax

```sql
SELECT /*rs+ CREATE SHALLOW CACHE
    [<name>]
    [WITH (<option>[, <option>...])]
*/ ...
```

The options accepted inside `WITH (...)` are identical to those of the [`CREATE CACHE`](/command-reference#create-cache) DDL statement. See the command reference for the full option list and descriptions.

When no policy keyword is supplied, hint-created caches default to [`UNTIL WRITE`](/command-reference#until-write) so that read-only-so-far transactions can still serve from cache. Hints with an explicit `ALWAYS` or `UNTIL WRITE` always win.

### SKIP CACHE syntax

```sql
SELECT /*rs+ SKIP CACHE */ ...
```

`SKIP CACHE` takes no options. See [Skipping the cache](#skipping-the-cache) for details and use cases.

## How it works

1. **First execution** — Readyset parses the hint, strips it from the query, and creates a shallow cache for the underlying `SELECT`. The result is returned from the upstream database (cache miss).

2. **Subsequent executions** — The same query (with or without the hint) matches the existing shallow cache and is served directly from it (cache hit).

3. **Stable query identity** — The hint is stripped before computing the query ID hash. This means a hinted query and the same query without the hint produce the **same** query ID and share the same cache entry. For example:

   ```sql
   -- These two queries share the same cache:
   SELECT /*rs+ CREATE SHALLOW CACHE */ id FROM users WHERE id = 1;
   SELECT id FROM users WHERE id = 1;
   ```

4. **Persistence** — Hint-created caches are persisted exactly like DDL-created caches. If Readyset restarts, they are automatically restored with their original policy settings.

## Examples

### Basic cache creation

```sql
-- First execution: creates the cache, returns from upstream
SELECT /*rs+ CREATE SHALLOW CACHE */ id, name
FROM users
WHERE id = 1;

-- Second execution: served from the shallow cache
SELECT id, name
FROM users
WHERE id = 1;
```

### With Explicit TTL eviction

```sql
SELECT /*rs+ CREATE SHALLOW CACHE WITH (POLICY TTL 300 SECONDS) */ *
FROM products
WHERE category = 'electronics';
```

Cached entries expire after 300 seconds. See [TTL expiration](/concepts/shallow-caching#ttl-expiration) for details on how TTL works.

### With TTL and scheduled refresh

```sql
SELECT /*rs+ CREATE SHALLOW CACHE WITH (POLICY TTL 300 SECONDS REFRESH EVERY 60 SECONDS) */ *
FROM products
WHERE category = 'electronics';
```

Entries are proactively refreshed every 60 seconds. See [Refresh behavior](/concepts/shallow-caching#refresh-behavior) for the difference between on-access and scheduled refresh.

### With adaptive refresh

```sql
SELECT /*rs+ CREATE SHALLOW CACHE WITH (POLICY TTL 300 SECONDS REFRESH EVERY 60 SECONDS, ADAPTIVE) */ *
FROM products
WHERE category = 'electronics';
```

Per-entry refresh intervals [adapt](/concepts/shallow-caching#adaptive-refresh) to observed data change rates: entries whose results change between refreshes are refreshed more often than the configured 60 seconds, and entries whose results stay the same return to the configured interval.

### With coalesce window

```sql
SELECT /*rs+ CREATE SHALLOW CACHE WITH (COALESCE 10 SECONDS) */ *
FROM dashboard_stats
WHERE tenant_id = 42;
```

Multiple cache misses arriving within a 10-second window are [coalesced](/concepts/shallow-caching#coalescing) into a single upstream query.

### With ALWAYS (transaction support)

```sql
SELECT /*rs+ CREATE SHALLOW CACHE WITH (ALWAYS) */ balance
FROM accounts
WHERE account_id = 100;
```

The cache is consulted even when the query is executed inside a transaction (e.g., by an ORM that wraps reads in `BEGIN`/`COMMIT`). See [`ALWAYS`](/command-reference#always).

### With UNTIL WRITE (read-only-so-far transactions)

```sql
SELECT /*rs+ CREATE SHALLOW CACHE WITH (UNTIL WRITE) */ id, name
FROM users
WHERE id = 1;
```

Reads inside a transaction are served from the cache while the transaction has not yet observed a write. After the first `INSERT`, `UPDATE`, or `DELETE`, the query is proxied upstream for the rest of that transaction. The cache becomes available again on the next transaction. This is the right choice for client drivers that wrap every statement in an implicit transaction (for example, Python drivers running with `autocommit=False`, JDBC defaults, or ORMs that do not expose autocommit). See [`UNTIL WRITE`](/command-reference#until-write).

`UNTIL WRITE` is also the default policy for hint-created caches when no policy keyword is supplied, so the bare `/*rs+ CREATE SHALLOW CACHE */` example above is equivalent to `/*rs+ CREATE SHALLOW CACHE WITH (UNTIL WRITE) */`.

### Prepared statements

Hints work with prepared statements via the binary protocol. The cache is created during the first prepare + execute cycle. Place the hint in the query string passed to the driver's prepare method:

<Tabs items={['MySQL', 'PostgreSQL']}>
  <Tab>
    ```python
    import mysql.connector

    conn = mysql.connector.connect(host="127.0.0.1", port=3307, database="mydb")
    cursor = conn.cursor(prepared=True)

    # The hint is embedded in the prepared query string.
    # On first execute, Readyset creates the shallow cache.
    cursor.execute(
        "SELECT /*rs+ CREATE SHALLOW CACHE */ id, val FROM t WHERE id = %s",
        (1,),
    )
    row = cursor.fetchone()
    ```
  </Tab>

  <Tab>
    ```python
    import psycopg2

    conn = psycopg2.connect(host="127.0.0.1", port=5433, dbname="mydb")
    cursor = conn.cursor()

    # psycopg2 uses server-side prepared statements automatically.
    cursor.execute(
        "SELECT /*rs+ CREATE SHALLOW CACHE */ id, val FROM t WHERE id = %s",
        (1,),
    )
    row = cursor.fetchone()
    ```
  </Tab>
</Tabs>

## Supported query shapes

Hints work with a variety of query structures:

* **Simple SELECTs** — `SELECT /*rs+ CREATE SHALLOW CACHE */ ... FROM t`
* **UNION queries** — `SELECT /*rs+ CREATE SHALLOW CACHE */ ... UNION SELECT ...`
* **CTEs** — `WITH cte AS (...) SELECT /*rs+ CREATE SHALLOW CACHE */ * FROM cte`
* **Window functions** — `SELECT /*rs+ CREATE SHALLOW CACHE */ ROW_NUMBER() OVER (...), ...`
* **Derived tables** — `SELECT /*rs+ CREATE SHALLOW CACHE */ * FROM (SELECT ...) AS sub`

The hint can appear in any `SELECT` within the query (e.g., on the left or right branch of a `UNION`), though placing it on the outermost `SELECT` is the recommended convention, because the entire query is cached, regardless of where the hint appears.

## Skipping the cache

The `SKIP CACHE` hint forces a query to bypass Readyset entirely and execute directly against the upstream database, even when a matching cache exists.

```sql
SELECT /*rs+ SKIP CACHE */ columns FROM ...
```

### When to use SKIP CACHE

* **Reading your own writes.** After an `INSERT` or `UPDATE`, the next read may need the freshest possible data before the cache has been refreshed. `SKIP CACHE` guarantees you read from the source of truth.
* **Consistency-sensitive operations.** Financial transactions, inventory checks, or any workflow where serving a stale value could cause incorrect behavior.
* **Debugging and validation.** Compare cached results against upstream to verify cache correctness during development or incident triage.
* **Selective opt-out.** Most queries in a code path can benefit from caching, but one or two need to hit upstream. `SKIP CACHE` lets you opt out per-query without changing routing rules or cache configuration.

### How it works

1. Readyset parses the `SKIP CACHE` hint and strips it from the query.
2. The query is routed directly to the upstream database, bypassing both shallow and deep caches.
3. If a matching cache exists, Readyset still computes the query ID so that the skip is visible in metrics, but the cache is never consulted.

### Example

```sql
-- This query always goes to upstream, even if a cache exists
SELECT /*rs+ SKIP CACHE */ balance
FROM accounts
WHERE account_id = 100;

-- The same query without the hint still uses the cache
SELECT balance
FROM accounts
WHERE account_id = 100;
```

### Combining with CREATE CACHE hints

`SKIP CACHE` and `CREATE CACHE` are independent directives. A query can have a cache created via a `CREATE SHALLOW CACHE` hint on one code path, while a different code path uses `SKIP CACHE` to bypass it:

```sql
-- Code path A: creates and uses the cache
SELECT /*rs+ CREATE SHALLOW CACHE WITH (POLICY TTL 60 SECONDS) */ balance
FROM accounts WHERE account_id = ?;

-- Code path B: bypasses the cache for a fresh read
SELECT /*rs+ SKIP CACHE */ balance
FROM accounts WHERE account_id = ?;
```

## Behavior details

### Malformed hints

If the hint text is syntactically invalid (e.g., `POLICY TT` instead of `POLICY TTL`), Readyset logs a warning and ignores the directive. The query still executes normally and if a matching cache already exists, it is used.

### Multiple hints

If a query contains multiple optimizer hints (e.g., `/*rs+ CREATE SHALLOW CACHE */ /*mysql+ SET_VAR(...) */`), all hints are stripped from the query before computing the query ID. Only the first `rs`-prefixed hint is interpreted as a directive. This ensures the query ID remains stable regardless of how many hints are present.

### Cache DDL disabled

If the Readyset server is running with a dedicated [`--cache-ddl-address`](/reference/config-options#--cache-ddl-address), hints arriving on the main listener are silently ignored and no cache is created. The query executes normally against upstream.

### Managing hint-created caches

Caches created via hints are identical to caches created via DDL. You can inspect them with [`SHOW CACHES`](/command-reference#show-caches) and remove them with [`DROP CACHE`](/command-reference#drop-cache):

```sql
SHOW CACHES;
DROP CACHE <query_id>;
```


# Shallow Caching (/concepts/shallow-caching)
import { Callout } from 'fumadocs-ui/components/callout'

# Shallow Caching

Shallow caching is a TTL-based query result caching mode in Readyset. When a query is registered as a shallow cache using [`CREATE SHALLOW CACHE`](/command-reference#create-cache), Readyset stores the result set in memory and serves it directly to clients until the TTL expires, without building or maintaining a materialized view in the dataflow graph.

Because shallow caching does not require a materialized view, it supports a broader range of queries than [deep caching](/concepts/deep-caching)-based caches, including queries with constructs that the dataflow engine does not currently handle.

<Callout type="warning">
  Cache entries are keyed on the query and its parameters, not on the connecting user, so any client that authenticates to Readyset can read any shallow cache regardless of its upstream database permissions. Cache only queries whose results are safe for every permitted user. Per-user access control is in active development. See the release notes for updates.

  The exception is Postgres [row-level security](/concepts/shallow-caching/row-level-security): a cache over an RLS-protected table is automatically keyed on the session state its policies read, so it cannot return rows across tenants.
</Callout>

## How it works

### Query parameterization

When Readyset registers a shallow cache, it automatically replaces literal values in the query with placeholders. For example:

```sql
SELECT * FROM products WHERE id = 42
```

is normalized to:

```sql
SELECT * FROM products WHERE id = $1
```

This means queries that differ only in their literal values (`WHERE id = 1`, `WHERE id = 2`, and so on) share a single cache entry template. Each unique combination of parameter values gets its own cached result, but the cache infrastructure is shared across all parameterizations of the same query shape.

Parameterization also applies to `IN` lists. The entire set is treated as a single parameter, so `WHERE id IN (1, 2, 3)`, `WHERE id IN (4, 5, 6)`, and `WHERE id IN (7, 8)` all share the same cache template regardless of how many elements the list contains.

### TTL expiration

Each cache entry has a lifetime configured by the `POLICY TTL` clause (or the server default [`--default-ttl-ms`](/reference/config-options#--default-ttl-ms) if omitted). TTL is calculated based on last access time: an entry is considered stale when it has not been accessed within the TTL window. When a stale entry is accessed, Readyset fetches a fresh result from upstream and replaces the entry.

TTLs need not be manually configured unless desired. If omitted, Readyset falls back to server defaults. Caches created with the `ADAPTIVE` option also adjust each entry's refresh rate based on how often its data is observed to change; see [Adaptive refresh](#adaptive-refresh).

### Refresh behavior

A *refresh* is a Readyset-generated query sent to your upstream database solely to update a stale shallow cache entry. Refreshes happen on a per-key basis: each unique set of parameter values is refreshed independently. The right refresh interval balances cache freshness against the query load each refresh places on your database.

Readyset supports two refresh strategies:

**On-access refresh** (`REFRESH <n> {SECONDS | MILLISECONDS | MS}`): When a request hits a shallow cache and the cached value is at least `n` old (in the specified unit), Readyset preemptively issues a background refresh. The current request receives the existing cached value immediately; the refreshed result is available for subsequent requests. If `REFRESH` is omitted, Readyset applies an implicit default refresh interval equal to half the TTL.

**Scheduled refresh** (`REFRESH EVERY <n> {SECONDS | MILLISECONDS | MS}`): Readyset unconditionally re-executes the query against upstream on a fixed schedule, regardless of whether any client has requested it. Automatic refreshes continue as long as the cache entry has not been evicted due to TTL expiration. Note that if the query takes longer to execute than the refresh interval, multiple refreshes for the same key can be in-flight concurrently, producing consistently fresh results at the cost of higher database query volume.

In both cases, the refresh interval must be less than the TTL.

### Adaptive refresh

A cache created with the `ADAPTIVE` option tunes each entry's refresh interval to the rate at which its data is observed to change. When a refresh returns changed data, the entry's interval shrinks so future changes are picked up sooner; when refreshes keep returning the same data, the interval grows back toward the configured interval, which acts as the ceiling.

Adaptive refresh works with both on-access and scheduled refresh. To keep shortened intervals from overloading the upstream database, the extra refresh load they generate is capped by the [`--shallow-adaptive-max-extra-load-percent`](/reference/config-options#--shallow-adaptive-max-extra-load-percent) server option. At the cap, intervals stop shrinking until aggregate load decreases.

Caches created by [automatic shallow caching](/concepts/shallow-caching/auto-caching) are always adaptive. The current per-entry refresh interval is visible in the `refresh_period_ms` column of `SHOW SHALLOW CACHE ENTRIES`.

### Database load considerations

A primary goal of shallow caching is to reduce database load. However, it is possible to configure shallow caches in a way that *increases* load. For example, setting an aggressive `REFRESH EVERY` interval on a high-cardinality cache with many distinct parameter values can generate more upstream queries than the cache saves.

To bound the total number of concurrent background refreshes across all shallow caches, use the [`--shallow-refresh-workers`](/reference/config-options#--shallow-refresh-workers) option (env: `SHALLOW_REFRESH_WORKERS`). This defaults to 40 concurrent refreshes. For [adaptive](#adaptive-refresh) caches, the extra load from shortened refresh intervals is additionally capped by [`--shallow-adaptive-max-extra-load-percent`](/reference/config-options#--shallow-adaptive-max-extra-load-percent). When choosing refresh intervals for individual caches, consider both the per-query cost and the aggregate load across all caches.

### Memory and eviction

All shallow caches share a single in-memory store. Its capacity is a share of the server's [`--memory-limit`](/reference/config-options#--memory-limit--m), configured with [`--shallow-memory-percent`](/reference/config-options#--shallow-memory-percent).

When the store is full, admission and eviction are cost-aware. Each cached result records how long its query took to execute upstream, and Readyset weighs that against how often the result is requested when deciding what to keep. A result that is requested less often but is slow to recompute can be kept ahead of one that is requested more often but is cheap to recompute, so memory is spent where caching saves the most database time.

As a backstop against single entries crowding out the rest of the store, result sets larger than [`--shallow-max-entry-bytes`](/reference/config-options#--shallow-max-entry-bytes) are served from upstream without being cached.

### Coalescing

When multiple client requests for the same query (same parameter values) arrive simultaneously and all miss the cache, Readyset can coalesce them: only the first request goes to upstream, and the rest wait for that result to be populated before responding. This prevents a thundering herd from overwhelming upstream on a cache miss.

The coalescing window is configured with the optional `COALESCE` clause (or the server default [`--default-coalesce-ms`](/reference/config-options#--default-coalesce-ms) if omitted). During this window, concurrent identical requests wait for the first to complete rather than each issuing an independent upstream query.


# Row-Level Security (/concepts/shallow-caching/row-level-security)
import { Callout } from 'fumadocs-ui/components/callout'

# Row-Level Security

Under Postgres [row-level security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html) (RLS), the same query with the same parameters returns different rows to different sessions. A cache that ignored the session would serve one tenant's rows to another.

Readyset reads your RLS policies from `pg_catalog` and, for a shallow cache over an RLS-protected table, folds the session state those policies actually read into the cache key. Each session gets its own entries, so a cache hit can only ever return rows that session was already entitled to see. Policies Readyset cannot analyze safely are refused, and the query is served from the upstream database instead.

This is on by default on a Postgres upstream and needs no per-cache configuration. It applies to [shallow caches](/concepts/shallow-caching) only; RLS-protected tables are not supported by [deep caching](/concepts/deep-caching).

<Callout type="warning">
  RLS awareness partitions caches by the session state the *policies* read. It is not a general per-user authorization layer: a table with no RLS policy is cached with a shared, session-independent key, so any client authenticated to Readyset can read it regardless of its upstream `GRANT`s. See the caveat in [Shallow Caching](/concepts/shallow-caching).
</Callout>

## How it works

### Cache partitioning

At `CREATE CACHE` time, Readyset resolves the relations the query references and checks whether any of them has RLS enabled.

* **No RLS-protected table:** the cache is *plain*. Its key is the query and its parameters, exactly as without RLS, and there is no added lookup cost.
* **An RLS-protected table:** the cache is *scoped*. Readyset analyzes the table's policy expressions and records the minimal set of session inputs they read. That set is folded into the key alongside the parameters, so the cache holds one independent entry per distinct combination of parameters and session values.

The inputs that can be folded into a scoped key are:

1. The session's current role and session user
2. `request.jwt.claims` claims read via `auth.uid()`, `auth.jwt()`, or `auth.role()`
3. Allowlisted GUCs read via `current_setting()`
4. Whether the role holds `BYPASSRLS`
5. The catalog generation (see [Policy changes](#policy-changes))

Only the inputs a policy actually reads are keyed. A policy reading `auth.uid()` partitions on the `sub` claim and nothing else; adding an unrelated GUC to the session does not fragment the cache.

Readyset tracks the session state it needs by observing `SET`, `SET ROLE`, `set_config()`, and `DISCARD ALL` / `RESET ALL` on the connection. Transaction-local writes (`SET LOCAL ROLE`, `set_config(..., true)`) revert to the session baseline at `COMMIT` or `ROLLBACK`. If Readyset cannot mirror the session's state confidently, it serves the query from upstream rather than guessing — see [Off-cache routing](#off-cache-routing).

### Supported policies

Policy expressions must fit a deliberately narrow grammar, shaped around the Supabase and PostgREST idiom. A policy that steps outside it is not cached, rather than cached approximately.

Allowlisted functions:

| Function                              | Session input read                |
| ------------------------------------- | --------------------------------- |
| `auth.uid()`                          | `request.jwt.claims` → `sub`      |
| `auth.jwt()`                          | `request.jwt.claims` (whole blob) |
| `auth.role()`                         | `request.jwt.claims` → `role`     |
| `current_user`, `session_user`        | the session's role identity       |
| `current_setting(name[, missing_ok])` | `name`, if allowlisted below      |

Allowlisted `current_setting()` GUCs: `request.jwt.claims`, `request.jwt.claim.sub`, `request.jwt.claim.role`, `request.jwt.claim.email`, `request.method`, `request.path`.

The allowlist is matched by name. A function is never accepted on the basis of its declared volatility, so a `STABLE` function of your own in a policy expression refuses the cache.

Views are analyzed against their underlying base tables when the view is declared `security_invoker = true`. A non-invoker view over an RLS-protected table is refused, because its rows are filtered as the view's owner rather than the caller.

### Refused caches

When a policy or query falls outside the supported grammar, `CREATE CACHE` fails and the query keeps being served from the upstream database. Run `EXPLAIN CACHE SUPPORT <query>` to see the reason. Each reason carries a stable code in the form `rls_uncacheable[code=<code>, ...]`, so tooling can switch on the code rather than parse the message:

| Code                            | Meaning                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `policy_too_dynamic`            | The policy expression uses constructs outside the supported grammar.                                    |
| `non_stable_function_in_policy` | The policy calls a function that is not on the allowlist.                                               |
| `policy_reads_other_table`      | The policy expression references a second table, so the rows it admits depend on that table's contents. |
| `view_without_security_invoker` | The query reads a view over an RLS-protected table and the view is not `security_invoker = true`.       |
| `security_definer_function`     | The query calls a `SECURITY DEFINER` function.                                                          |
| `partitioned_table`             | The RLS-protected table is partitioned.                                                                 |
| `unknown_relation`              | Readyset has not observed one of the referenced relations yet. Retry after the next catalog poll.       |

`unknown_relation` is the one transient entry in this table. It means the table exists but the catalog poller has not picked it up, which is expected for a few seconds after the table's `CREATE`. Retry the `CREATE CACHE` after the next poll; see [`--rls-poll-interval-secs`](/reference/config-options#--rls-poll-interval-secs).

### Policy changes

Readyset polls `pg_catalog` for policy, RLS-enablement, and role-attribute changes every [`--rls-poll-interval-secs`](/reference/config-options#--rls-poll-interval-secs) (60 seconds by default). This gives you two independent staleness bounds:

* Cached **rows** are fresh to within the cache's TTL.
* Cached **policies** are fresh to within the poll interval.

When a poll detects a change, Readyset reacts before serving anything under the new catalog state:

| Change                                           | Effect                                                                                                                                                                  |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A policy's expression is edited                  | Affected caches are re-analyzed. Still in grammar: the cache is re-keyed on the new input set. Out of grammar: the cache is dropped and the query serves from upstream. |
| `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`      | Plain caches over the table are dropped. They come back scoped through the normal create path if still cacheable.                                                       |
| `ALTER TABLE ... DISABLE ROW LEVEL SECURITY`     | Scoped caches over the table are invalidated.                                                                                                                           |
| A role attribute changes (including `BYPASSRLS`) | Every scoped cache is invalidated. Any scoped cache is reachable by any role, so the affected set cannot be narrowed.                                                   |

Any of these bumps a global catalog generation that is part of every scoped cache key, which makes entries written under the previous policies unreachable immediately. They are reclaimed lazily by TTL and eviction.

Shortening the poll interval tightens the policy-staleness window at the cost of more catalog queries against your upstream. Lengthening it does the reverse.

### Off-cache routing

Some conditions make a *single lookup* unsafe without making the cache itself invalid. Readyset then serves that lookup from upstream and caches nothing, while the cache stays in place for other sessions. This happens when:

* The session's state could not be mirrored confidently — for example a malformed `set_config()` call left Readyset unsure of the live value.
* A keyed GUC is unset in the session and Readyset cannot rule out a role-level default for it, because it lacks `SELECT` on `pg_db_role_setting`.

Off-cache lookups increment `readyset_shallow.shallow_result_uncacheable`. This is distinct from a miss: nothing is stored, so it never warms. A session stuck in this state routes all of its traffic upstream while the overall hit rate can still look healthy, which makes this metric worth alerting on.

Scoped caches are also excluded from background refresh and refresh lazily in-session on a miss. Background refresh workers run on their own connections with no session state, so a background refill would execute under the wrong RLS context.

## Required privileges

The connection in [`--upstream-db-url`](/reference/config-options#--upstream-db-url) reads the catalog. It needs `EXECUTE` on `pg_get_expr` plus `SELECT` on:

| Relation                  | Required    | Purpose                                |
| ------------------------- | ----------- | -------------------------------------- |
| `pg_policy`               | Yes         | Policy expressions                     |
| `pg_class`                | Yes         | RLS-enabled flags, relation OIDs       |
| `pg_namespace`            | Yes         | Schema resolution                      |
| `pg_roles`                | Yes         | Role attributes, including `BYPASSRLS` |
| `pg_rewrite`, `pg_depend` | Yes         | View-to-base-table expansion           |
| `pg_db_role_setting`      | Recommended | Role-level GUC defaults                |

If a required relation is unreadable, Readyset **refuses to start**, rather than come up and cache RLS-protected tables with a shared key. The error names the relations it could not read.

If only `pg_db_role_setting` is unreadable, Readyset starts and degrades: it cannot see role-level GUC defaults, so any lookup whose keyed GUC the session left unset is served [off-cache](#off-cache-routing). Sessions that set their GUCs explicitly are unaffected.

## Monitoring

| Metric                                        | Type    | Meaning                                                                                                                                            |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `readyset.rls.poll_age_seconds`               | Gauge   | Seconds since the last successful catalog poll. Alert when it exceeds your poll interval; the cache is serving under a stale view of the policies. |
| `readyset.rls.poll_initialised`               | Gauge   | `1` once the first poll has succeeded. Gate `poll_age_seconds` alerts on this to avoid firing during startup.                                      |
| `readyset.rls.poll_errors_total`              | Counter | Failed poll attempts. A rising count next to a rising `poll_age_seconds` means the registry has fallen behind.                                     |
| `readyset.rls.policy_reloads_total`           | Counter | Reloads, labelled `kind = relation \| role \| rls_flag`.                                                                                           |
| `readyset.rls.bootstrap_attempts_total`       | Counter | Catalog bootstrap attempts at startup, including retries.                                                                                          |
| `readyset_shallow.shallow_result_uncacheable` | Counter | Lookups served [off-cache](#off-cache-routing).                                                                                                    |

Polling is fail-open: a failed poll leaves the previous catalog snapshot in place and retries on the next tick, so a transient upstream blip does not drop your caches. The tradeoff is that a *sustained* poll failure lets policies go stale without bound, which is what `poll_age_seconds` is for.

## Configuration

| Option                                                                           | Default | Purpose                                                                                      |
| -------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| [`--rls-poll-interval-secs`](/reference/config-options#--rls-poll-interval-secs) | `60`    | How often the catalog is polled for policy changes.                                          |
| [`--enable-rls`](/reference/config-options#--enable-rls)                         | `true`  | Set to `false` to skip the catalog entirely. Unsafe unless no table has, or ever gains, RLS. |

## Limitations

1. Policy expressions must fit the grammar described in [Supported policies](#supported-policies). Anything else is served from upstream.
2. Partitioned tables with RLS are not cached.
3. RLS-protected tables are not supported by [deep caching](/concepts/deep-caching).
4. Scoped caches do not participate in background refresh; they refresh in-session on a miss.
5. A policy change takes effect within one poll interval, not instantly. Postgres event triggers are not used, because they are unavailable on hosted Supabase without superuser.


# Caching Slow IMDB Queries (/demos/caching-slow-queries-imdb)


import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
import { Callout } from 'fumadocs-ui/components/callout'

This demo walks through caching a slow query against a sample IMDB dataset and comparing latencies in Grafana. First, we'll spin up a local Readyset instance, sample database, and Grafana dashboard using Docker.

## Prerequisites

* Docker Engine version >= 19.03.0 and Docker Compose V2 OR Docker Desktop >= 4.1.0
* A [MySQL](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) or [Postgres](https://www.postgresql.org/docs/current/app-psql.html) client, depending on the primary database

## Set up Readyset

This sets up a Readyset instance, a primary database, and a Grafana dashboard on your local machine using Docker.

<Callout>
  If you want to connect Readyset to your own database instead, please follow the directions in
  the 

  [install Readyset](/cache/install-rs)

   documentation.
</Callout>

Download and run the Readyset Docker compose file:

<Tabs items={['Postgres', 'MySQL']}>
  <Tab value="Postgres">
    ```sh
    curl -L -o compose.yml                                  \
      "https://readyset.io/quickstart/compose.postgres.yml" \
      && docker compose pull                                \
      && docker compose up -d
    ```
  </Tab>

  <Tab value="MySQL">
    ```sh
    curl -L -o compose.yml                                  \
      "https://readyset.io/quickstart/compose.mysql.yml"    \
      && docker compose pull                                \
      && docker compose up -d
    ```
  </Tab>
</Tabs>

## Steps

### 1. Download the IMDB dataset & load it into your database

<Tabs items={['MySQL','Postgres']}>
  <Tab value="MySQL">
    First, download the IMDB dataset for MySQL:

    ```sh
    curl -L -O "https://readyset.io/quickstart/imdb-mysql.sql"
    ```

    Then, connect to your Readyset instance and import the dataset. With the Docker setup above, you can use the following command to connect and import:

    ```sh
    mysql -h127.0.0.1 -uroot -P3307 testdb -preadyset <  imdb-mysql.sql
    ```
  </Tab>

  <Tab value="Postgres">
    First, download the IMDB dataset for Postgres:

    ```sh
    curl -L -O "https://readyset.io/quickstart/imdb-postgres.sql"
    ```

    Then, connect to your Readyset instance and import the dataset. With the Docker setup above, you can use the following command to connect and import:

    ```sh
    PGPASSWORD=readyset psql -h127.0.0.1 -Upostgres -p5433 testdb < imdb-postgres.sql
    ```
  </Tab>
</Tabs>

### 2. Connect to Readyset & make sure the tables have been imported

It could take a few seconds for Readyset to import the tables. You can check whether they've been successfully imported by connecting to Readyset through your database client and running:

```sql
SHOW READYSET TABLES;
```

Once the table is imported, you will see that the status of that table is 'snapshotted'.

### 3. Run a query against your primary database

Once the tables have been imported into Readyset, we can start running queries.

Let's try this one, which counts how many titles released in 2000 had an average rating that was higher than 5:

```sql
SELECT count(*) FROM title_ratings
JOIN title_basics ON title_ratings.tconst = title_basics.tconst
WHERE title_basics.startyear = 2000 AND title_ratings.averagerating > 5;
```

By default, this query is proxied to the primary database.

### 4. Cache the query in Readyset

We can cache it in Readyset by running the following:

```sql
CREATE CACHE FROM SELECT count(*) FROM title_ratings
JOIN title_basics ON title_ratings.tconst = title_basics.tconst
WHERE title_basics.startyear = 2000 AND title_ratings.averagerating > 5;
```

We can check the Grafana dashboard to see that the query was successfully cached, and compare latencies. With the Docker setup above, you can open Grafana by going to `localhost:4000` in your browser.

<img alt="" src={__img0} placeholder="blur" />

Here, we can see that the 99th percentile latencies for this query fell from over 80ms against Postgres to \< 1ms against Readyset.

<Callout type="info">
  The first time you execute a cached query, it'll be a cache miss, which is slower than the average cache hit. To get a sense for cache hit latencies, issue the query a handful of times to see the cache hit latency reflected in the query latency percentiles in Grafana.
</Callout>

### 5. Update the underlying data

The query you've run a few times returns the count of titles released in 2000 that had a rating greater than 5 (i.e. 2,418 titles). "Battlefield Earth" was a movie released in 2000 that received poor ratings. For instance, run this query:

```sql
SELECT title_basics.tconst, title_basics.primarytitle, title_ratings.averagerating, title_ratings.numvotes
FROM title_basics
INNER JOIN title_ratings on title_ratings.tconst = title_basics.tconst
WHERE title_basics.primarytitle = 'Battlefield Earth';
```

You'll see it scored an average rating of 2.5:

```sql
  tconst   |   primarytitle    | averagerating | numvotes
-----------+-------------------+---------------+----------
 tt0185183 | Battlefield Earth |           2.5 |    80451
(1 row)
```

It was, indeed, an awful movie. Nevertheless, historical revisionism is fun when you have full control of the data. You can grab the id for "Battlefield Earth" (`tt0185183`) and update its average rating accordingly:

```sql
UPDATE title_ratings
SET averagerating = 5.1
WHERE tconst = 'tt0185183';
```

### 6. The cache is auto-updated!

Rerun the previously cached query that returns the count of titles:

```sql
SELECT count(*) FROM title_ratings
JOIN title_basics ON title_ratings.tconst = title_basics.tconst
WHERE title_basics.startyear = 2000 AND title_ratings.averagerating > 5;
```

The count has been increased by one (i.e. 2,419 vs 2,418), without you ever invalidating or refreshing the cache yourself.

```sql
 count
-------
  2419
(1 row)
```


# Tutorial: Caching with the Accelerator (/demos/querypilot/accelerator-caching)
import { Steps, Step } from 'fumadocs-ui/components/steps';

The Accelerator is QueryPilot's caching plugin. Running in-process inside the Router (binary `querypilot`), it ranks your hottest query shapes from the Router's own statistics, creates caches for them on a Readyset deployment, and installs the routing rules that steer matching traffic to those caches. This tutorial enables it, walks through one discovery cycle, and shows the operational controls: dry run, warmup, the denylist, and the kill switch.

Prerequisites:

* A Router deployment (see [Getting Started](/querypilot/getting-started)).
* A running Readyset deployment reachable from the Router, with credentials that can run `SHOW READYSET STATUS`, `SHOW CACHES`, and `CREATE CACHE`. Readyset is a separate product; if you do not have a deployment, contact [hello@readyset.io](mailto:hello@readyset.io).
* The Accelerator is the one QueryPilot component that requires Readyset. Everything else works without it.

<Steps>
  <Step>
    **Add a Readyset pool and the plugin block.**

    The Accelerator only installs rules that target pools you explicitly grant it. Add both to `querypilot.toml`:

    ```toml
    [pools.readyset]
    username = "app"
    password = "<your-password>"
    backends = [{ host = "readyset.internal", port = 5433 }]

    [plugins.accelerator]
    enabled = true
    interval_s = 10                  # discovery cycle cadence, seconds
    dry_run = true                   # log decisions, mutate nothing (first rollout step)
    database = "postgresql"
    readyset_servers = [{ host = "readyset.internal", port = 5433 }]
    readyset_user = "app"
    readyset_password = "<your-password>"
    min_execution = 5                # executions before a shape is a candidate
    warmup_time_s = 60               # new rules stay disabled for this window
    api_key = "<your-api-key>"

    [plugins.accelerator.grants]
    pools = ["readyset"]
    max_owned_rules = 100
    ```

    Restart the Router. The plugin runs its cycle every `interval_s` seconds on its own thread: health-check Readyset, drop denylisted caches, reconcile rules against existing caches, then discover new candidates from the Router's per-query-shape statistics (the same data served at `GET /api/stats/digests`). Configuration errors fail startup; runtime errors never affect query traffic. Key-by-key detail is in the [configuration reference](/querypilot/reference/router-configuration).
  </Step>

  <Step>
    **Generate load and watch candidates appear.**

    Run a query through the Router repeatedly, at least `min_execution` times:

    ```bash
    for i in $(seq 1 20); do
      psql -h localhost -p 5433 -U app -d mydb \
        -c "SELECT * FROM orders WHERE customer_id = $((RANDOM % 100))" > /dev/null
    done
    ```

    Literal values do not matter: the Router normalizes queries to a fingerprint, so all twenty executions count toward one shape. Watch the plugin's view of the world on the [admin API](/querypilot/reference/admin-api) (metrics port + 1):

    ```bash
    curl -s http://localhost:9091/api/v1/plugins/accelerator/candidates
    curl -s http://localhost:9091/api/v1/plugins/accelerator/status
    ```

    `/candidates` lists each shape with its threshold evaluation; `/status` reports loop health (last cycle time, result, consecutive errors). In `dry_run` mode the log shows what the plugin would cache. When the candidate list looks right, set `dry_run = false` and restart.
  </Step>

  <Step>
    **Watch a cache get created and promoted.**

    With `dry_run` off, the next cycle checks candidate support with `EXPLAIN CREATE CACHE FROM <sql>`, runs `CREATE CACHE` on Readyset, and installs a routing rule for the fingerprint:

    ```bash
    curl -s http://localhost:9091/api/v1/plugins/accelerator/rules
    ```

    New rules are installed disabled while Readyset warms the cache, then enabled once `warmup_time_s` elapses. You see the rule appear in `/rules` with its enabled flag false, then flip to true one warmup window later. Once enabled, confirm routing changed:

    ```bash
    curl -s "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20orders%20WHERE%20customer_id%20=%207"
    # ... "target_pool": "readyset" ...
    ```

    On the metrics side, `sqp_qp_caches_created_total` and `sqp_qp_rules_added_total` increment, and `sqp_qp_last_success_timestamp_seconds` advances every cycle; alert on the latter going stale (see [metrics](/querypilot/reference/metrics)).

    The plugin also fails safe: if Readyset becomes unhealthy (snapshot in progress, unreachable), the Accelerator disables the rules it owns so traffic flows to the source database, and re-enables them on recovery. It never touches rules it did not create.
  </Step>

  <Step>
    **Denylist a query.**

    Some queries must never be cached, whatever the statistics say. The denylist file (path set by `denylist_path`, one rule per line) gates discovery and retroactively removes caches and rules for newly denied shapes:

    ```text
    # deny one specific query shape
    digest=0x9A3C0F12B44D21AA

    # deny everything in a schema
    db=internal
    ```

    Use the hex digest as the Accelerator's REST endpoints (`/candidates`, `/rules`) report it. The file is re-read at each cycle start, so edits take effect without a restart.
  </Step>

  <Step>
    **Know the operational controls.**

    Mutating endpoints require the configured `api_key` in the `X-QueryPilot-Api-Key` header:

    ```bash
    # Kill switch: stop all mutations, keep observing
    curl -s -X POST -H "X-QueryPilot-Api-Key: change-me" \
      http://localhost:9091/api/v1/plugins/accelerator/actions/pause

    # Resume
    curl -s -X POST -H "X-QueryPilot-Api-Key: change-me" \
      http://localhost:9091/api/v1/plugins/accelerator/actions/resume

    # Cache a specific fingerprint immediately, skipping the ranking queue.
    # fingerprint_hash is the numeric hash from /api/routing/test or /candidates.
    curl -s -X POST -H "X-QueryPilot-Api-Key: change-me" \
      -H "Content-Type: application/json" \
      -d '{"fingerprint_hash": 11114457943247356330}' \
      http://localhost:9091/api/v1/plugins/accelerator/actions/force-cache

    # Drop one owned rule, by the same numeric hash
    curl -s -X DELETE -H "X-QueryPilot-Api-Key: change-me" \
      http://localhost:9091/api/v1/plugins/accelerator/rules/11114457943247356330
    ```

    Force-cache is gated: the fingerprint must exist in the current statistics, be SELECT-shaped, and not be denylisted.

    `GET /decisions` keeps a ring buffer of recent cycle outcomes, and `GET /audit` records operator mutations made through this API. The full endpoint table is in the [Accelerator guide](/querypilot/accelerator).
  </Step>
</Steps>

## The standalone binary

The same engine also ships as `querypilot-accelerator`, a standalone binary with its own TOML-syntax `.cnf` config. It runs one full cycle per invocation under an external scheduler and manages either a ProxySQL deployment or a Router deployment from the outside, through the Router's admin API. Use it when the deployment being managed is not the Router process you control, or when you already schedule ProxySQL maintenance jobs. The in-process form above is the default path; see the [Accelerator guide](/querypilot/accelerator) for the standalone configuration, discovery ranking modes, and per-user targets.

{/* source: verified against code @ 2026-07-18 */}


# Tutorial: Guard Policies (/demos/querypilot/guard-policies)
import { Steps, Step } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';

<Callout type="warning">
  **Upcoming feature.** This tutorial exercises Guard, which is not part of QueryPilot GA v1. It is documented here ahead of availability; details may change before release.
</Callout>

Guard is QueryPilot's policy-enforcement plugin. It runs inside the Router (binary `querypilot`), inspects every query before it reaches a backend, and can allow, amend, reroute, or block it, writing an audit record for every decision. It is built for traffic you do not fully trust: AI agents, third-party integrations, ad hoc tooling.

This tutorial enables the plugin in shadow mode, writes two policies, watches decisions accumulate, and then tightens to enforcement. The available actions are the shipped set: block, warn-level application via enforcement mode, and the amendments `add_limit`, `add_timeout`, and `force_read_only`, plus rerouting to another pool.

You need a Router deployment fronting PostgreSQL (see [Getting Started](/querypilot/getting-started)).

<Steps>
  <Step>
    **Write the policies.**

    Policies are YAML files in a directory, loaded in alphabetical order (use filename prefixes like `10-`, `20-` for precedence within a severity). Create `policies/`:

    `policies/10-block-unbounded-delete.yaml` blocks `DELETE` without a `WHERE` clause:

    ```yaml
    name: block-unbounded-delete
    description: A DELETE with no WHERE clause wipes the table. Block it.
    enabled: true
    severity: critical
    match:
      query_type: ["delete"]
      has_where: false
    action:
      type: block
    message: "DELETE without WHERE is blocked by policy. Add a WHERE clause."
    ```

    `policies/20-limit-unbounded-select.yaml` caps unbounded scans instead of blocking them:

    ```yaml
    name: limit-unbounded-select
    description: Cap SELECTs that carry neither WHERE nor LIMIT.
    enabled: true
    severity: high
    match:
      query_type: ["select"]
      has_where: false
      has_limit: false
    action:
      type: amend
      amendments:
        - type: add_limit
          value: 10000
    notify: true
    ```

    The pieces:

    * `match` conditions are AND-combined; omitted conditions match anything. Available conditions include `query_type`, `tables` (globs), `has_where`, `has_limit`, `trust_level` (comparison string like `"< 2"`), `estimated_cost`, `risk_factors`, `time_of_day`, and `database`.
    * `action.type` is one of `allow`, `block`, `amend`, or `reroute` (with `target_pool`). For `block`, the top-level `message` is returned to the client.
    * Amendments compose in order; `add_limit` appends `LIMIT n` to a SELECT that has none, `add_timeout` caps per-query execution time, `force_read_only` runs the statement read-only. An amendment that cannot apply to a statement is skipped.
    * `severity` interacts with session trust: `critical` policies always evaluate; lower tiers are skipped for sufficiently trusted sessions. With the default trust level (`verified`), `critical` and `high` policies fire and `low` policies do not.
    * `notify: true` sends the client a notice describing an applied amendment.

    The full condition and trust-model reference is in the [Guard guide](/querypilot/guard).
  </Step>

  <Step>
    **Enable the plugin in shadow mode.**

    Add to `querypilot.toml` and mount the policy directory into the container:

    ```toml
    [plugins.guard]
    enabled = true
    enforcement_mode = "shadow"
    policy_dir = "/etc/querypilot/guard-policies"
    default_trust_level = "verified"
    api_key = "<your-api-key>"
    audit_sink = { type = "stdout" }
    ```

    ```bash
    docker run -d --name querypilot --network host \
      -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
      -v "$(pwd)/policies:/etc/querypilot/guard-policies:ro" \
      public.ecr.aws/readyset/querypilot:latest
    ```

    In `shadow` mode Guard evaluates every query and audits the decision it would have made, but never applies it. Traffic is unaffected while you observe. Invalid policy files are logged and skipped, never fatal; confirm both loaded:

    ```bash
    curl -s http://localhost:9091/api/v1/plugins/guard/policies
    ```

    For sessions with different trust, add `[[plugins.guard.trust_rules]]` entries matching `username`, `role` (glob), or `origin`; for example, pin a known agent account to `untrusted`, which is blocked by default when no policy or registry entry explicitly allows the query.
  </Step>

  <Step>
    **Test policies without traffic.**

    `POST /test` dry-runs any SQL against the current configuration and returns the decision:

    ```bash
    curl -s -X POST http://localhost:9091/api/v1/plugins/guard/test \
      -H "Content-Type: application/json" \
      -d '{"sql": "DELETE FROM orders"}'
    # {"decision":"block","policy":"block-unbounded-delete","message":"DELETE without WHERE is blocked by policy. Add a WHERE clause.", ...}

    curl -s -X POST http://localhost:9091/api/v1/plugins/guard/test \
      -H "Content-Type: application/json" \
      -d '{"sql": "SELECT * FROM orders"}'
    # {"decision":"amend","policy":"limit-unbounded-select", ...}
    ```

    The body also accepts optional `username` and `trust_level` fields to simulate a specific session. After editing a policy file, reload without a restart:

    ```bash
    curl -s -X POST -H "X-Guard-Api-Key: change-me" \
      http://localhost:9091/api/v1/plugins/guard/policies/reload
    ```
  </Step>

  <Step>
    **Watch real decisions in shadow.**

    Run normal application traffic through the Router, then read the decision buffer and the audit sink:

    ```bash
    curl -s "http://localhost:9091/api/v1/plugins/guard/decisions?limit=20"
    docker logs querypilot | tail        # stdout sink: one JSON record per decision
    ```

    Each audit record carries the timestamp, session, username, trust level, query fingerprint, statement type, tables, action, matching policy, amendments, and decision latency. For a persistent on-disk log, switch the sink to `audit_sink = { type = "file", path = "/var/log/querypilot/guard.jsonl" }`.

    Let shadow mode run until the would-be blocks and amendments match your expectations: every `block` decision in the buffer is a query that will start failing when you enforce. Prometheus series to watch: `sqp_guard_decisions_total` (by action, policy, trust level), `sqp_guard_decision_duration_seconds`, and `sqp_guard_audit_dropped_total` (see [metrics](/querypilot/reference/metrics)).
  </Step>

  <Step>
    **Roll out: shadow, then warn, then enforce.**

    `enforcement_mode` controls whether decisions bite:

    | Mode      | Behavior                                                |
    | --------- | ------------------------------------------------------- |
    | `shadow`  | decisions computed and audited, never applied           |
    | `warn`    | decisions applied, each application logged as a warning |
    | `enforce` | decisions applied silently                              |

    Move one step at a time: set `enforcement_mode = "warn"` in `querypilot.toml`, restart the Router, and confirm applications behave with amendments actually applied (the warning log makes each application visible). Then set `enforce`. In `enforce`, the blocked DELETE now fails at the client:

    ```bash
    psql -h localhost -p 5433 -U app -d mydb -c "DELETE FROM orders"
    # ERROR:  DELETE without WHERE is blocked by policy. Add a WHERE clause.
    ```
  </Step>

  <Step>
    **Fail closed on unanalyzable queries.**

    Statements Guard cannot analyze (parse failures, statements over 64 KiB, pathological nesting) are governed by `unanalyzable_action`, which applies to non-read statements from sessions below `privileged`:

    ```toml
    [plugins.guard]
    unanalyzable_action = "block"
    ```

    The default is `log`: pass the statement, log a warning, and increment `sqp_guard_unanalyzable_total`. Run on `log` first and watch that metric; once you have confirmed no legitimate traffic trips it, set `block` for the fail-closed posture. Plain reads and privileged sessions always flow regardless.
  </Step>
</Steps>

## Where to go next

* [Guard guide](/querypilot/guard) for the trust model, severity gating, the trusted-query registry (the O(1) allowlist fast path), and the full REST surface.
* [Security](/querypilot/security) for how Guard fits the wider deployment posture.
* [Operations](/querypilot/operations) for audit sink rotation and alerting.

{/* source: verified against code @ 2026-07-18 */}


# Tutorial: Read/Write Splitting (/demos/querypilot/read-write-split)
import { Steps, Step } from 'fumadocs-ui/components/steps';

This tutorial configures the Router (binary `querypilot`) to classify each statement and send reads to a replica pool while writes, DDL, and anything ambiguous go to the primary. No application changes: clients connect to one endpoint and the Router decides per statement.

You need Docker, access to the `querypilot` image (see [Getting Started](/querypilot/getting-started)), and a PostgreSQL primary with at least one streaming replica.

<Steps>
  <Step>
    **Write `querypilot.toml` with a pool per role.**

    ```toml
    [general]
    pool_mode = "transaction"

    [[listeners]]
    protocol = "postgres"
    bind = "0.0.0.0:5433"

    [pools.primary]
    role = "primary"
    username = "app"
    password = "<your-password>"
    database = "mydb"
    min_connections = 2
    max_connections = 50
    backends = [{ host = "primary.db.local", port = 5432 }]

    [pools.replica]
    role = "replica"
    username = "app"
    password = "<your-password>"
    database = "mydb"
    min_connections = 2
    max_connections = 25
    backends = [
        { host = "replica1.db.local", port = 5432, weight = 2 },
        { host = "replica2.db.local", port = 5432, weight = 1, max_replica_lag = "10s" },
    ]

    [routing]
    read_write_split = true
    read_pool = "replica"
    write_pool = "primary"
    default_pool = "primary"

    [metrics]
    enabled = true
    bind = "0.0.0.0:9090"
    ```

    The three keys that matter: [`read_write_split`](/querypilot/reference/router-configuration#read_write_split) turns classification on, [`read_pool`](/querypilot/reference/router-configuration#read_pool) receives reads, and [`write_pool`](/querypilot/reference/router-configuration#write_pool) receives everything else.

    Two backend-level knobs:

    * `max_replica_lag` marks a backend unhealthy whenever its measured replication lag exceeds the threshold; the Router skips it when opening connections and brings it back automatically once lag recovers.
    * `weight` is accepted and validated (must be non-zero), but the current release opens new connections round-robin across healthy backends; weights do not yet bias selection.
  </Step>

  <Step>
    **Run the Router.**

    ```bash
    docker run -d --name querypilot --network host \
      -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
      readysettech/querypilot:latest
    ```

    Wait for `docker ps --filter name=querypilot` to report healthy. Clients authenticate with the pool credentials (`app`/`app-password` above).
  </Step>

  <Step>
    **Verify decisions without sending traffic.**

    `GET /api/routing/test` on the admin API (metrics port + 1) dry-runs the routing decision for any SQL:

    ```bash
    curl -s "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20users%20WHERE%20id%20=%201"
    # ... "target_pool": "replica" ...

    curl -s "http://localhost:9091/api/routing/test?sql=UPDATE%20users%20SET%20name%20=%20%27x%27%20WHERE%20id%20=%201"
    # ... "target_pool": "primary" ...

    curl -s "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20users%20WHERE%20id%20=%201%20FOR%20UPDATE"
    # ... "target_pool": "primary" ...
    ```

    That last one is intentional: `SELECT ... FOR UPDATE` and `SELECT ... FOR SHARE` take row locks, so the Router classifies them as writes and routes them to `write_pool`. A lock taken on a replica would be useless to a later write on the primary.

    The full classification table:

    | Statement                                              | Routed to                                                            |
    | ------------------------------------------------------ | -------------------------------------------------------------------- |
    | `SELECT`                                               | `read_pool`, unless it contains `FOR UPDATE` / `FOR SHARE`           |
    | `WITH ...`                                             | `read_pool`, unless the CTE body contains `INSERT`/`UPDATE`/`DELETE` |
    | `SHOW`, `EXPLAIN`, `DESCRIBE`, `COPY ... TO`           | `read_pool`                                                          |
    | `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `COPY ... FROM` | `write_pool`                                                         |
    | DDL, `GRANT`/`REVOKE`, `VACUUM`, anything unrecognized | `write_pool`                                                         |

    When in doubt, the Router routes to the primary rather than risk a write on a replica.
  </Step>

  <Step>
    **Confirm under real traffic.**

    Run a mixed workload through port 5433, then check the routing counter. Split decisions are recorded with `decision_type="default"` and the pool they landed on:

    ```bash
    curl -s http://localhost:9090/metrics | grep sqp_routing_decisions_total
    # sqp_routing_decisions_total{decision_type="default",target_pool="replica"} 812
    # sqp_routing_decisions_total{decision_type="default",target_pool="primary"} 147
    ```

    `sqp_queries_total{pool="replica"}` climbing alongside confirms the queries actually executed there. See the [metrics reference](/querypilot/reference/metrics).
  </Step>

  <Step>
    **Understand transaction pinning.**

    Transaction pinning runs before any routing rule: once a session is inside an explicit transaction, every statement reuses the backend connection the transaction started on. A `SELECT` between `BEGIN` and `COMMIT` therefore stays on the write connection rather than hopping to a replica:

    ```sql
    BEGIN;
    INSERT INTO orders (id, total) VALUES (1, 9.99);  -- primary
    SELECT * FROM orders WHERE id = 1;                -- primary (pinned, sees the uncommitted row)
    COMMIT;
    ```

    Pinned statements show up as `decision_type="pinned"` in `sqp_routing_decisions_total`. This is what makes read-your-own-writes correct inside transactions. Outside a transaction, an autocommit `SELECT` immediately after a write may route to a replica and race replication lag; keep read-after-write sequences inside a transaction, or tighten `max_replica_lag`.
  </Step>
</Steps>

## Where to go next

* [Router guide](/querypilot/router) for the full routing decision order, pattern rules, and pooling modes.
* [Performance](/querypilot/performance) for what classification and routing cost per statement.

{/* source: verified against code @ 2026-07-18 */}


# QueryPilot (/faq/querypilot)
import { Callout } from 'fumadocs-ui/components/callout';

<Callout type="info">
  **MySQL support is in preview.** MySQL proxying and MySQL CDC are functional and documented, but they are not part of the GA v1 support surface. PostgreSQL is the fully supported GA v1 path.
</Callout>

## General

### Do I need to change my application?

No code changes. Applications keep their drivers, SQL, and query patterns, and change only the host and port they connect to. One authentication detail: when a pool carries `username`/`password` (required for any network-facing listener), clients authenticate to the Router with those pool credentials. See [Getting Started](/querypilot/getting-started) and [Security](/querypilot/security).

### How is QueryPilot licensed and distributed?

QueryPilot is a commercial product from Readyset, distributed as Docker images: `querypilot` (the Router) and `querypilot-accelerator`. Pre-release builds are published to `public.ecr.aws/readyset`; production releases go to Docker Hub. For access and licensing, contact [hello@readyset.io](mailto:hello@readyset.io). See [Getting Started](/querypilot/getting-started).

### Do I need Readyset to use QueryPilot?

Only for the Accelerator, whose job is creating and managing caches on a Readyset deployment. The Router and Guard have no Readyset dependency. See the [Accelerator guide](/querypilot/accelerator).

### Which components do I have to run?

Only the Router (binary `querypilot`). The Accelerator and Guard are each opt-in and independent of one another. See [What is QueryPilot?](/querypilot/what-is-querypilot).

### Does the Router store my data?

No. The Router is a stateless proxy; it holds connections and in-memory statistics, not data.

## Compatibility

### Which databases and versions are supported?

PostgreSQL is the GA v1 path, tested against PostgreSQL 15 and 16. MySQL proxying is in preview, tested against MySQL 8.0. See the compatibility table in [What is QueryPilot?](/querypilot/what-is-querypilot).

### Does the Router terminate TLS?

No. In the current release the Router handles client and backend connections in plaintext. Run it on a trusted network segment, bind listeners to loopback or private addresses, and terminate TLS in front of it (load balancer, mTLS sidecar, VPN) when clients connect over untrusted networks. See [Security](/querypilot/security).

### Can MySQL clients query PostgreSQL backends?

Yes. Setting `protocol` on a pool forces the backend wire protocol regardless of what the client speaks; the Router decodes result rows from the backend protocol and re-encodes them for the client. See the [Router guide](/querypilot/router).

### How do prepared statements work through the Router?

Prepared statements are supported on both protocols, including the PostgreSQL extended protocol with binary encoding, and are exercised continuously by client-framework tests (pgx, psycopg3, PyMySQL, and others). For vanilla PostgreSQL-to-PostgreSQL pools, [`raw_passthrough`](/querypilot/reference/router-configuration#raw_passthrough) streams prepared-statement results to the client without re-encoding; leave it off for cross-protocol pools. See the [Router guide](/querypilot/router).

## Operations

### How do I see where a query routes?

`GET /api/routing/test?sql=...` on the [admin API](/querypilot/reference/admin-api) dry-runs the routing decision without sending traffic and returns the target pool, the matched rule, and the query's fingerprint hash. Under load, `sqp_routing_decisions_total` counts decisions by type and target pool. See the [read/write splitting tutorial](/demos/querypilot/read-write-split).

### What happens when a backend goes down?

Health checks mark the backend unavailable and new connections skip it; backends within a pool are opened round-robin across the healthy set. A replica whose measured lag exceeds its `max_replica_lag` is treated the same way. Recovered backends rejoin automatically. Sessions that cannot get a connection within `acquire_timeout` receive an error rather than queueing forever. See [Operations](/querypilot/operations).

### Does enabling plugins slow queries down?

Not until you enable one. With no plugin blocks configured, the plugin chain is empty and adds zero per-query overhead. Guard, when enabled, evaluates under a per-decision latency budget (default 50 ms cap, fail-open for reads); the Accelerator does its work on a background thread, not in the query path. See [Performance](/querypilot/performance).

### How do I monitor QueryPilot?

Enable `[metrics]` and the Router serves Prometheus metrics under the `sqp_` prefix (metrics on 9090, admin API always on metrics port + 1). Start with `sqp_query_duration_seconds`, `sqp_pool_acquire_duration_seconds`, and `sqp_routing_decisions_total`. See the [metrics reference](/querypilot/reference/metrics) and [Operations](/querypilot/operations).

### How do I change configuration safely?

Validate first: `querypilot --check -c querypilot.toml` (the Router's schema is strict and rejects unknown keys), then `POST /api/config/reload` on the admin API applies routing and translation changes without a restart. See the [router configuration reference](/querypilot/reference/router-configuration).

## Components

### What can Guard actually do to a query?

The shipped decision set: allow it, block it with a structured error, amend it (`add_limit`, `add_timeout`, `force_read_only`), or reroute it to a different pool. Enforcement can be staged through shadow and warn modes before anything bites, and every decision is audited. See the [Guard tutorial](/demos/querypilot/guard-policies).

### What does the Accelerator do if Readyset goes down?

It fails safe. The health-check stage detects the outage, disables the routing rules the plugin owns so traffic flows to the source database, and re-enables them when Readyset recovers. Runtime errors in the plugin never affect query traffic. See the [Accelerator guide](/querypilot/accelerator).

{/* source: verified against code @ 2026-07-18 */}


# Readyset Platform (/)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Readyset Platform is a self-tuning query acceleration layer for Postgres and MySQL, along with a
set of tools for understanding and optimizing your query workloads. Point your application at
Readyset by swapping your connection string: Readyset caches the queries you choose and keeps
their results up to date as your data changes, while everything else is proxied straight through
to your database.

The platform includes:

* **Readyset QueryPilot** — automatic query caching for AI-generated workloads.
* **Readyset Cache** — the SQL caching engine, with deep (dataflow-based) and shallow (TTL-based) caches.
* **rdst** — a command-line tool that analyzes and optimizes your queries.

The best way to test Readyset Platform is with **rdst**. It's now available as a native app, and can also be run directly from the command line.

## Download rdst

`rdst` is available as a native app for macOS, Windows, and Linux.

[Download rdst](https://readyset.io/downloads) picks the right build for your
platform, and lists the macOS DMG, Windows `.exe`, and Linux AppImage, `.deb`,
and `.rpm` packages.

## Install the rdst CLI

Install the CLI, then start the web UI with `rdst web`.

<Tabs items={['Installer', 'Package managers']}>
  <Tab value="Installer">
    ```bash
    curl -fsSL https://downloads.readyset.io/packages/rdst-cli/install.sh | sh
    ```

    The installer uses user-owned directories and needs no sudo, no pip, and no
    preinstalled Python. Open a new shell afterwards.
  </Tab>

  <Tab value="Package managers">
    ```bash
    uv tool install rdst
    # or: pipx install rdst
    ```

    RDST leaves these installations under the control of their package manager.
  </Tab>
</Tabs>

```bash
rdst web
```

## Run Readyset with Docker

To run Readyset in a Docker container, run:

```bash
bash -c "$(curl -sSL https://launch.readyset.io)"
```

<Callout type="info">
  Running Readyset in Docker — and running the `rdst` demo — requires Docker to be installed. [Download Docker](https://www.docker.com/get-started/) if you don't already have it.
</Callout>


# Accelerator (/querypilot/accelerator)
import { Callout } from 'fumadocs-ui/components/callout'
import { Steps, Step } from 'fumadocs-ui/components/steps'

## What the Accelerator does

The Accelerator (config block `[plugins.accelerator]`) is QueryPilot's caching component. It watches query traffic through the Router, ranks the hottest query shapes, creates caches for them on a Readyset deployment, and installs the routing rules that steer matching queries to those caches. It then keeps caches and rules reconciled as traffic and health change.

<Callout type="info">
  MySQL support is in preview. The Accelerator can manage MySQL-protocol Readyset endpoints and ProxySQL deployments, but PostgreSQL is the fully supported GA v1 path.
</Callout>

It ships in two forms:

* **In-process**, running inside the Router (binary `querypilot`), enabled by a `[plugins.accelerator]` block in `querypilot.toml`, with a REST surface at `/api/v1/plugins/accelerator` on the Router's admin API. This is the primary deployment form.
* **Standalone**, as the `querypilot-accelerator` binary with its own TOML-syntax `.cnf` config file, managing either a Router deployment or a ProxySQL deployment from the outside.

## The cycle

Each cycle walks the same pipeline regardless of deployment form:

<Steps>
  <Step>
    **Health check.** Ask each Readyset instance `SHOW READYSET STATUS`: snapshot completed means online; snapshot in progress or unreachable means traffic should fall back to the source database. When the Readyset pool is unhealthy, the Accelerator disables the routing rules it owns so queries flow to the primary, and re-enables them on recovery.
  </Step>

  <Step>
    **Drop denied.** Remove caches and rules for queries that appear on the denylist.
  </Step>

  <Step>
    **Reconcile rules from caches.** Enumerate existing caches (`SHOW CACHES`) and install routing rules for any cache that lacks one, so caches created by hand also get traffic.
  </Step>

  <Step>
    **Drop rogue rules.** Remove owned rules whose backing cache no longer exists. If the cache catalog cannot be fetched (Readyset down), no rules are dropped; an outage never causes rule churn.
  </Step>

  <Step>
    **Discovery.** Rank query shapes from execution statistics, check candidate support with `EXPLAIN CREATE CACHE FROM <sql>`, create caches with `CREATE CACHE <name> FROM <sql>`, and install a routing rule per new cache.
  </Step>
</Steps>

New rules can be installed disabled and enabled only after a warmup window (`warmup_time_s`), giving Readyset time to warm the cache by mirroring before traffic promotes to it.

## Rule ownership

The Accelerator only ever manages rules it owns. Ownership is recorded in the rule's comment metadata (a `readyset-meta:` JSON blob carrying the rule type, creation time, and cache name), and for the in-process form ownership is additionally limited to the pools named in `[plugins.accelerator.grants]`. Rules created by operators are never touched.

## Running in-process

You need a Router pool whose backends are Readyset instances, plus the plugin block:

```toml
[pools.readyset]
backends = [{ host = "readyset.internal", port = 5433 }]

[plugins.accelerator]
enabled = true
interval_s = 10          # discovery cycle cadence, seconds
database = "postgresql"
readyset_servers = [{ host = "readyset.internal", port = 5433 }]
readyset_user = "app"
readyset_password = "<your-password>"
min_execution = 1        # executions before a query shape is a candidate
warmup_time_s = 60       # new rules stay disabled for this window
api_key = "<your-api-key>"

[plugins.accelerator.grants]
pools = ["readyset"]
max_owned_rules = 100
```

The plugin runs the cycle every `interval_s` seconds on its own thread inside the Router process. It reads the Router's built-in per-query-shape statistics directly (the same data served at `GET /api/stats/digests`), so there is no external stats collection to set up. Discovery in this form ranks candidates by execution count; the standalone form exposes the ranking mode and top-N as config keys. `min_execution` sets the execution-count floor and `wait_s` requires a shape to have been observable for that many seconds before it is a candidate.

Operationally, the plugin is fail-open by design: configuration errors fail Router startup, but no runtime error, whether a Readyset outage, a failed cycle, or a panic inside the cycle, ever affects query traffic. Failed cycles retry on the next tick; repeated panics stop the loop and surface through the liveness metric rather than crashing the Router.

Two knobs shape rollout:

* `dry_run = true` logs every caching decision without creating caches or rules. Run this first to see what the plugin would do to your workload.
* `warmup_time_s` delays traffic promotion for new rules, as above.

Verify it is working through the admin port:

```bash
curl http://localhost:9091/api/v1/plugins/accelerator/status      # loop health
curl http://localhost:9091/api/v1/plugins/accelerator/candidates  # what discovery sees
curl http://localhost:9091/api/v1/plugins/accelerator/rules       # rules it installed
curl "http://localhost:9091/api/routing/test?sql=<your query>"    # target_pool: "readyset"
```

A step-by-step walkthrough is in the [Accelerator caching tutorial](/demos/querypilot/accelerator-caching).

### REST API

Mounted under `/api/v1/plugins/accelerator` on the Router's admin API. Mutating endpoints require the configured `api_key`, sent as the `X-QueryPilot-Api-Key` header; when no key is set and the admin API binds a non-loopback address, the mutating surface refuses to serve.

| Method | Path                   | Purpose                                                                                           | Auth |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------- | ---- |
| GET    | `/status`              | Loop health: last cycle time, duration, result, consecutive errors, paused flag                   | no   |
| GET    | `/decisions`           | Ring buffer of recent cycle outcomes                                                              | no   |
| GET    | `/candidates`          | Current discovery candidates with threshold evaluation (query text redacted unless authenticated) | no   |
| GET    | `/rules`               | Rules the plugin owns, with state and enabled flag                                                | no   |
| GET    | `/denylist`            | Denylist rule count                                                                               | no   |
| GET    | `/audit`               | Trail of operator mutations through this API                                                      | yes  |
| POST   | `/actions/force-cache` | Queue a specific fingerprint for immediate caching                                                | yes  |
| POST   | `/actions/pause`       | Kill switch: stop all mutations, keep observing                                                   | yes  |
| POST   | `/actions/resume`      | Resume mutations                                                                                  | yes  |
| DELETE | `/rules/:hash`         | Drop an owned rule                                                                                | yes  |

`POST /actions/pause` is the operational kill switch: the plugin keeps running and reporting but creates and drops nothing until resumed. `force-cache` requires the fingerprint to exist in stats, be SELECT-shaped, and not be denylisted.

## Standalone binary

`querypilot-accelerator --config <path>` runs one full cycle and exits; an external scheduler (cron, or ProxySQL's scheduler table) invokes it repeatedly. A lock file (`lock_file`, default `/tmp/readyset_query_pilot.lock`) guarantees a single running instance. `--health-check` runs only the health-check operation under its own lock, and `--dry-run` plans without mutating. The `.cnf` file contains credentials; keep it `chmod 600`.

The binary manages one of two backends, selected by `backend_type`.

### Managing a Router deployment (`backend_type = "sqp"`)

The Accelerator drives the Router through its admin API: it reads statistics from `GET /api/stats/digests`, installs and removes dynamic pattern rules through `POST /api/pattern-rules` and `DELETE /api/pattern-rules/:hash`, disables rules during warmup with `PUT /api/pattern-rules/:hash/disable`, and drives pool health through `PUT /api/pools/:name/status`. It only owns pattern rules targeting the pool named by `sqp_readyset_pool`.

```toml
backend_type = 'sqp'
database_type = 'postgresql'      # wire protocol of the readyset pool; required for this backend
sqp_api_url = 'http://127.0.0.1:9091'
sqp_readyset_pool = 'readyset'
sqp_readyset_servers = [
    { host = '127.0.0.1', port = 5433 },
]
warmup_time_s = 60
number_of_queries = 10
query_discovery_mode = 'sum_time'

[[user]]
readyset_user = 'rs_user'
readyset_password = 'rs_pass'
readyset_database = 'rs_db'
```

Pointing it at a non-loopback Router requires `https` in `sqp_api_url` plus an `sqp_api_token`, sent as a bearer token; startup validation enforces both. ProxySQL-only operations are neutralized in this mode: `operation_proxysql_cache` is forced off with a warning, and `cache_mode = "cloud"` is rejected at startup.

### Managing ProxySQL (`backend_type = "proxysql"`)

For deployments fronted by ProxySQL instead of the Router, the Accelerator connects to ProxySQL's admin interface, reads query statistics from `stats_mysql_query_digest` (or the PostgreSQL equivalent), and manages digest-match routing rules in `mysql_query_rules` (destination `readyset_hostgroup`, source traffic in `source_hostgroup`, ownership in the rule `comment`), per-host server status for the Readyset hostgroup driven by the health check, and optionally ProxySQL's own TTL-based query cache for hot queries Readyset cannot cache (`operation_proxysql_cache`, `proxysql_cache_ttl_ms`, `proxysql_cache_size_mb`).

### Per-user targets

At least one `[[user]]` section is required; each defines a Readyset login (`readyset_user`, `readyset_password`, optional `readyset_database`) and gets its own independent discovery pass per invocation. Most tuning keys (`number_of_queries`, `query_discovery_mode`, `warmup_time_s`, and others) can be overridden per user.

## Query discovery modes

The standalone form ranks candidates by `query_discovery_mode`; each mode sorts descending on one metric and takes the top `number_of_queries` per user. Supported modes:

| Mode                   | Ranks by                              |
| ---------------------- | ------------------------------------- |
| `count_star` (default) | total executions                      |
| `sum_time`             | total execution time                  |
| `sum_rows_sent`        | total rows returned                   |
| `mean_time`            | average execution time                |
| `query_throughput`     | executions per unit of execution time |

Any other value fails at config validation.

The in-process plugin (`[plugins.accelerator]`) has no `query_discovery_mode` key: it always ranks by total executions (`count_star`), with `min_execution` and `wait_s` as its threshold filters.

Threshold filters run before ranking: `query_discovery_min_execution`, `query_discovery_min_rows_sent`, and `query_discovery_wait_s` (minimum time a query must have been observed). Statements whose results stream through without decoding can report zero rows sent, so prefer count- and time-based thresholds over `min_rows_sent` when in doubt.

## The denylist

The denylist file (`denylist_path`, default `/etc/readyset_query_pilot_denylist`) lists queries the Accelerator must never cache. Each non-empty line is a rule of space-separated `key=value` tokens; all tokens on a line must match (omitted tokens match anything), and a query is denied if any line matches:

```text
# deny one specific query shape everywhere
digest=0x9A3C0F12B44D21AA

# deny everything in the internal schema, Readyset caches only
db=internal type=readyset
```

Tokens: `db=<schema>`, `digest=0x<hash>` (fingerprint hashes as reported in statistics and the REST API), and `type=` (`readyset` or `proxysql`, legacy aliases `deep`/`shallow`, or `all`). The denylist gates discovery and `force-cache`, and the drop-denied cycle stage retroactively removes caches and rules for newly denylisted queries. The file is read at each cycle start; a missing file logs a warning and denies nothing.

## Observability

The in-process plugin exports `sqp_qp_*` Prometheus series through the Router's metrics endpoint: `sqp_qp_cycles_total` (by result: success/degraded/error), `sqp_qp_cycle_duration_seconds`, `sqp_qp_caches_created_total`, `sqp_qp_rules_added_total` / `sqp_qp_rules_disabled_total` / `sqp_qp_rules_dropped_total`, `sqp_qp_support_checks_total` (by outcome), `sqp_qp_errors_total` (by stage), and `sqp_qp_last_success_timestamp_seconds`. Alert on the last of these going stale to catch a stuck loop. `GET /status` and `GET /decisions` give the same picture ad hoc. See the [metrics reference](/querypilot/reference/metrics).

{/* source: verified against code @ 2026-07-18 */}


# Deployment (/querypilot/deployment)
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

QueryPilot ships as Docker images. Every deployment path on this page produces the same shape: the Router (binary `querypilot`) proxying client traffic between your applications and your database. Applications connect to the Router instead of the database directly. The database itself is external; none of these deployments run it for you.

<Callout type="info">
  MySQL support is in preview. MySQL proxying is functional, but PostgreSQL is the fully supported GA path. Where a deployment option below takes a MySQL backend, treat it as preview.
</Callout>

## Images and registries

| Image                    | Component              | Binary                   |
| ------------------------ | ---------------------- | ------------------------ |
| `querypilot`             | Router                 | `querypilot`             |
| `querypilot-accelerator` | Standalone Accelerator | `querypilot-accelerator` |

Pre-release builds are published to `public.ecr.aws/readyset` with tags of the form `X.Y.Z-<sha>` (for example `0.1.0-72807f4e`). Production releases are published to Docker Hub with `X.Y.Z` tags plus a moving `latest`. Published bits are the same images that passed the release gates; a pre-release tag is a build you can pull ahead of the corresponding production release.

The images are runtime-only: a non-root `sqp` user (UID/GID 999), the binary, `curl` for healthchecks, and nothing else. The Router image reads its config from `QUERYPILOT_CONFIG=/etc/sqp/querypilot.toml`, exposes 5433/9090/9091, and healthchecks itself with `curl -sf http://localhost:9091/api/config/status` (10s interval, 5s start period).

## Port conventions

| Service                 | Port | Protocol          | Notes                                                |
| ----------------------- | ---- | ----------------- | ---------------------------------------------------- |
| Router, PostgreSQL wire | 5433 | PostgreSQL        | Applications connect here                            |
| Router, metrics         | 9090 | HTTP (Prometheus) | `sqp_*` series                                       |
| Router, admin API       | 9091 | HTTP              | Always metrics port + 1; not separately configurable |

The Router's admin API port is derived, not configured: it binds on the metrics IP at the metrics port + 1. The shipped healthchecks and validation tooling assume the 9090/9091 pair.

## Single node with docker run

For a single-host deployment, run the image with a config mounted at `/etc/sqp/querypilot.toml`:

```bash
docker run -d --name querypilot --network host \
  -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
  readysettech/querypilot:latest
```

[Getting Started](/querypilot/getting-started) walks through this path end to end, including a minimal config and first proxied query.

## Docker Compose

For a Compose-managed deployment against an external PostgreSQL reachable on `localhost`, use host networking so the config's `127.0.0.1` backend addresses work as-is. Treat the Compose file and config below as starting points you adapt, not turnkey production artifacts.

<Steps>
  <Step>
    **Write the Router config.**

    Save this as `querypilot-router.toml` next to your Compose file: one PostgreSQL listener on `0.0.0.0:5433` and a pool per role. Set each pool's `username`/`password`/`database` to your credentials; these also serve as the client-auth credentials (see [Security](/querypilot/security)).

    ```toml
    [general]
    pool_mode = "transaction"

    [[listeners]]
    protocol = "postgres"
    bind = "0.0.0.0:5433"

    [pools.primary]
    role = "primary"
    username = "<your_pg_user>"
    password = "<your_pg_password>"
    database = "<your_database>"
    min_connections = 2
    max_connections = 20

    backends = [
        { host = "127.0.0.1", port = 5432 }
    ]

    [pools.replica]
    role = "replica"
    username = "<your_pg_user>"
    password = "<your_pg_password>"
    database = "<your_database>"
    min_connections = 2
    max_connections = 50

    backends = [
        { host = "<replica-host>", port = 5432 }
    ]

    [routing]
    read_write_split = true
    read_pool = "replica"
    write_pool = "primary"
    default_pool = "primary"

    # Pattern rules take priority over the read/write split; lower priority
    # numbers win. Example: keep a hot query shape on the primary.
    #[[routing.pattern_rules]]
    #name = "orders_lookup_on_primary"
    #type = "regex"
    #pattern = "(?i)FROM orders WHERE order_id ="
    #pool = "primary"
    #priority = 10

    [metrics]
    enabled = true
    bind = "0.0.0.0:9090"
    ```

    Single-backend deployments can drop the `replica` pool and the `[routing]` split; `default_pool` is all that is required. Every key is documented in the [Router configuration reference](/querypilot/reference/router-configuration).
  </Step>

  <Step>
    **Start the stack.**

    ```yaml
    services:
      querypilot:
        image: ${QUERYPILOT_IMAGE:-readysettech/querypilot:latest}
        network_mode: host
        volumes:
          - ./querypilot-router.toml:/etc/sqp/querypilot.toml:ro
        restart: unless-stopped
    ```

    ```bash
    QUERYPILOT_IMAGE=readysettech/querypilot:latest docker compose up -d
    ```
  </Step>

  <Step>
    **Connect.**

    ```bash
    psql -h localhost -p 5433 -U <pool-user> -d <database>
    ```
  </Step>

  <Step>
    **Stop.**

    ```bash
    docker compose down
    ```
  </Step>
</Steps>

## Post-deploy validation

Work through this checklist after any deployment.

1. **Router is healthy.** `curl -sf http://localhost:9091/api/config/status` returns 200 with the live config path.
2. **Traffic flows.** Run a query through port 5433, then confirm `sqp_queries_total` appears and increments in `curl http://localhost:9090/metrics`. See the [metrics reference](/querypilot/reference/metrics).
3. **Routing is what you intended.** `curl "http://localhost:9091/api/routing/test?sql=SELECT%20count(*)%20FROM%20your_table"` returns the expected `target_pool`.

Day-2 concerns (reload, shutdown, monitoring) are covered in [Operations](/querypilot/operations); the shipped Grafana dashboard and alert rules are in [QueryPilot Optional Configurations](/reference/querypilot-optional-configurations).

{/* source: verified against code @ 2026-07-18 */}


# Getting Started (/querypilot/getting-started)
import { Callout } from 'fumadocs-ui/components/callout';
import { Steps, Step } from 'fumadocs-ui/components/steps';

This guide takes you from pulling the Router image to your first proxied query. You need Docker, a PostgreSQL server you can already reach with `psql`, and about ten minutes. The Router proxies to your database; it does not replace it.

<Callout type="info">
  QueryPilot is distributed as Docker images: `querypilot` (the Router) and `querypilot-accelerator`. Pre-release builds are published to `public.ecr.aws/readyset`; production releases are published to Docker Hub. If you do not yet have access, contact [hello@readyset.io](mailto:hello@readyset.io).
</Callout>

<Steps>
  <Step>
    **Pull the Router image.**

    ```bash
    docker pull readysettech/querypilot:latest
    ```
  </Step>

  <Step>
    **Write a minimal `querypilot.toml`.**

    The image reads its configuration from `/etc/sqp/querypilot.toml` (set via the `QUERYPILOT_CONFIG` environment variable baked into the image). Create `querypilot.toml` in your working directory:

    ```toml
    [general]
    pool_mode = "transaction"

    [[listeners]]
    protocol = "postgres"
    bind = "0.0.0.0:5433"

    [pools.primary]
    role = "primary"
    username = "<your_pg_user>"
    password = "<your_pg_password>"
    database = "<your_database>"
    min_connections = 2
    max_connections = 50

    backends = [
        { host = "127.0.0.1", port = 5432 }
    ]

    [routing]
    default_pool = "primary"

    [metrics]
    enabled = true
    bind = "0.0.0.0:9090"
    ```

    Adjust `host`/`port` under `backends` to point at your PostgreSQL server.

    Two things this config does deliberately:

    * **The pool carries credentials.** Inside a container the listener binds `0.0.0.0`, and the Router refuses to start a non-loopback listener without authentication (see [Security](/querypilot/security)). Clients authenticate to the Router with this same `username`/`password`.
    * **Metrics are on.** This also starts the [admin API](/querypilot/reference/admin-api) on the metrics IP at the metrics port + 1, in this case `9091`. You use it to verify the deployment below.
  </Step>

  <Step>
    **Validate the config.**

    ```bash
    docker run --rm -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
      readysettech/querypilot:latest --check
    ```

    This prints `Configuration is valid` and exits. The Router's schema is strict: a typo in any key name fails here instead of being silently ignored.
  </Step>

  <Step>
    **Run the Router.**

    Run with host networking so `127.0.0.1` in the config reaches PostgreSQL on the host:

    ```bash
    docker run -d --name querypilot --network host \
      -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
      readysettech/querypilot:latest
    ```

    The image exposes 5433 (PostgreSQL wire), 9090 (metrics), and 9091 (admin API) and health-checks itself against `http://localhost:9091/api/config/status`. Wait for the container to report healthy:

    ```bash
    docker ps --filter name=querypilot
    ```

    To turn up logging without touching the config, pass `--log-level debug` or set `QUERYPILOT_LOG_LEVEL=debug` (see [environment variables](/querypilot/reference/environment-variables)).
  </Step>

  <Step>
    **Connect and run a query.**

    Authenticate with the pool credentials from your config:

    ```bash
    psql -h 127.0.0.1 -p 5433 -U <your_pg_user> -d <your_database> -c "SELECT 1"
    ```

    ```text
     ?column?
    ----------
            1
    (1 row)
    ```

    That query went client, Router, pooled backend connection, PostgreSQL, and back.
  </Step>

  <Step>
    **Verify through the metrics and admin ports.**

    ```bash
    # Prometheus metrics: the counter increments with each proxied query
    curl -s http://127.0.0.1:9090/metrics | grep sqp_queries_total

    # Admin API (metrics port + 1): config status
    curl -s http://127.0.0.1:9091/api/config/status

    # Ask the Router where it would route a query
    curl -s "http://127.0.0.1:9091/api/routing/test?sql=SELECT+1"
    ```

    If `sqp_queries_total` is greater than zero, you have proxied a query.
  </Step>
</Steps>

## Where to go next

* [What is QueryPilot?](/querypilot/what-is-querypilot) explains the Router, Accelerator, and Guard and how they compose.
* [Deployment](/querypilot/deployment) covers Docker Compose deployment and post-deploy validation.
* [Tutorials](/demos/querypilot/read-write-split) walk through read/write splitting, caching, and policy enforcement end to end.
* The [configuration reference](/querypilot/reference/router-configuration) documents every key in `querypilot.toml`.

{/* source: verified against code @ 2026-07-18 */}


# Guard (/querypilot/guard)
import { Callout } from 'fumadocs-ui/components/callout'

## What Guard does

<Callout type="warning">
  **Upcoming feature.** Guard is not part of QueryPilot GA v1. It is documented here ahead of availability; details may change before release.
</Callout>

Guard (config block `[plugins.guard]`) is QueryPilot's policy-enforcement component. It runs inside the Router (binary `querypilot`) and inspects every query before it reaches a backend: it assigns the session a trust level, checks a trusted-query registry and a set of YAML policies, and then allows, amends, reroutes, or blocks the query, writing an audit record for every decision. It is built for environments where not all SQL is written by humans you trust: AI agents, third-party integrations, and generated queries from application frameworks.

Treat Guard's block policies as protection against accidents and misbehaving tools, an unbounded `DELETE` from an agent, a runaway full-table scan from a dashboard, DDL from a service account that should never issue it. It is not a hard security boundary against a determined adversary; enforce database-level privileges and network controls independently. See [Security](/querypilot/security).

## How a decision is made

For each query, Guard runs this pipeline under a per-decision time budget (`max_decision_latency_ms`, default 50 ms):

1. **Trust resolution.** The session's trust level is computed once, from trust rules or else `default_trust_level`, and cached for the session.
2. **Registry fast path.** The query's literal-agnostic fingerprint is looked up in the trusted-query registry. A hit applies the entry's action immediately; this is the O(1) path for pre-approved query shapes.
3. **Query analysis.** The SQL is parsed and classified: statement type, tables touched, structural risk factors, and a heuristic cost estimate.
4. **Policy evaluation.** Policies are evaluated in severity order (critical first), then alphabetically by name; the first matching policy decides. Higher session trust skips lower-severity policies entirely.
5. **Default action.** If nothing matched, sessions at `verified` trust or above are allowed; `untrusted` sessions are blocked. An untrusted client can therefore only run queries something has explicitly approved.

Privileged sessions short-circuit to allow (with audit) before policy evaluation; critical-severity policies are the only ones that can still affect them.

## Trust model

Four ordered trust levels:

| Level | Name          | Typical use                                | Policy exposure                                          |
| ----- | ------------- | ------------------------------------------ | -------------------------------------------------------- |
| 0     | `untrusted`   | unknown clients, AI agents, external tools | full evaluation; blocked by default when nothing matches |
| 1     | `verified`    | known application identity                 | full evaluation                                          |
| 2     | `established` | services with a clean track record         | skips `low`-severity policies                            |
| 3     | `privileged`  | DBAs, migration jobs, CI/CD                | audit-only except `critical` policies                    |

Severity gating: a policy of severity `low` is skipped for sessions at `verified` and above, `medium` is skipped at `established` and above, `high` is skipped at `privileged`, and `critical` is never skipped. Per-query cost stays proportional to how much you distrust the session.

Sessions get their level from `[[plugins.guard.trust_rules]]`, evaluated in declaration order with last match winning; sessions no rule matches fall back to `default_trust_level` (default `verified`):

```toml
[[plugins.guard.trust_rules]]
match = { role = "service-*" }        # role is a glob
set_level = "established"
reason = "internal service accounts"

[[plugins.guard.trust_rules]]
match = { username = "ai_agent" }     # username is an exact match
set_level = "untrusted"
reason = "LLM-generated SQL"
```

Two matchers are supported: `username` (exact match against the authenticated client username) and `role` (glob pattern). All fields present in a `match` must hold for the rule to apply; a rule with no fields matches every session. Identify agent and tool traffic by giving each its own database credentials, then pin those usernames to `untrusted`.

## Query analysis

The analyzer parses each statement and extracts what policies match on: the statement type (`select`, `insert`, `update`, `delete`, `drop`, and so on), the tables it touches, presence of `WHERE` and `LIMIT`, a heuristic cost estimate, and structural risk factors including missing `WHERE` on `UPDATE`/`DELETE`, unbounded `SELECT`, cartesian products, DDL, privilege changes, side-effecting functions, deep nesting, and multi-statement input.

Statements Guard cannot analyze, whether from parse failures, statements over 64 KiB, or pathological nesting, are handled by `unanalyzable_action`. It applies only to non-read statements from sessions below `privileged`; plain reads and privileged sessions always flow:

* `allow`: pass silently.
* `log` (default): pass, log a warning, increment `sqp_guard_unanalyzable_total`.
* `block`: reject.

<Callout type="warning">
  The default `unanalyzable_action = "log"` fails open: a write Guard cannot parse still reaches the backend. To fail closed, set `unanalyzable_action = "block"` in `[plugins.guard]`. Start on `log`, watch `sqp_guard_unanalyzable_total`, and tighten to `block` once you have confirmed no legitimate traffic trips it.
</Callout>

If a single decision exceeds `max_decision_latency_ms`, Guard fails open for reads and privileged sessions (allow, `sqp_guard_timeouts_total` incremented) and applies the `unanalyzable_action` handling for low-trust writes. Sustained timeout counts mean the policy set is too expensive; reduce policy count or matcher complexity.

## Policies

Policies are YAML files in `policy_dir`, loaded at startup in alphabetical order (filename prefixes like `00-`, `10-` make a natural precedence convention) and reloadable at runtime via `POST /api/v1/plugins/guard/policies/reload`. Invalid files are logged and skipped, never fatal.

```yaml
name: limit-untrusted-scans
description: Cap unbounded selects from low-trust sessions
severity: high            # critical | high | medium | low
enabled: true
match:
  query_type: [select]
  has_limit: false
  trust_level: "< 2"
action: amend
amendments:
  - type: add_limit
    value: 10000
notify: true              # send the client a notice when amended
```

All `match` conditions are AND-combined; omitted conditions match anything:

| Condition                | Matches on                                                                                     |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `query_type`             | statement type list (`select`, `insert`, `update`, `delete`, `drop`, ...)                      |
| `tables`                 | table name globs (`orders`, `user_*`), case-insensitive                                        |
| `has_where`, `has_limit` | presence of WHERE / LIMIT                                                                      |
| `trust_level`            | comparison against session trust (`"< 2"`, `">= 1"`)                                           |
| `estimated_cost`         | comparison against the heuristic cost score (`"> 100000"`)                                     |
| `risk_factors`           | any of the analyzer's risk factors (`NoWhereClause`, `CartesianProduct`, `FullTableScan`, ...) |
| `time_of_day`            | UTC window, wraps midnight (`"22:00-06:00"`)                                                   |
| `database`               | session database list                                                                          |

Four actions ship:

* **`allow`**: pass through; useful as a high-priority exemption above a broader policy.
* **`block`**: reject with a structured error; `message` is returned to the client.
* **`amend`**: rewrite the query before execution. Three amendment types ship: `add_limit` (append `LIMIT n` to a SELECT that has none), `add_timeout` (per-query statement timeout in seconds), and `force_read_only` (read-only transaction mode). An amendment that cannot apply to the statement is skipped; with `notify_on_amend = true` (the default) the client receives a notice describing the change.
* **`reroute`**: send the query to a different pool (`target_pool`), for example steering expensive queries to a replica pool.

Worked policy sets are in the [Guard policies tutorial](/demos/querypilot/guard-policies).

## Trusted-query registry

The registry is the allowlist fast path: a YAML file (`registry_file`) of approved query fingerprints, loaded at startup and manageable at runtime over REST. Matching is by normalized fingerprint, so one entry covers a query shape for all literal values; entries record the normalized pattern SQL as well, defeating hash collisions.

```yaml
entries:
  - fingerprint: "0xabcd1234deadbeef"
    name: "inventory lookup"
    action: allow
    approved_by: "jane@example.com"
    approved_at: 1709289600
    pattern_sql: "SELECT item.* FROM item WHERE store_uuid = $1"
    conditions:
      - type: trust_level_at_least
        value: verified
```

Entries can carry trust-level conditions (all must hold) and an optional `expires_at`; expired entries are evicted automatically. The registry is capped at `max_registry_size` (default 100000) and swapped atomically on reload. Use `POST /api/v1/plugins/guard/test` on a candidate query to obtain its fingerprint and see what the current configuration would decide.

## Enforcement modes and rollout

`enforcement_mode` in `[plugins.guard]` controls whether decisions bite:

| Mode                | Behavior                                                |
| ------------------- | ------------------------------------------------------- |
| `off`               | plugin inactive                                         |
| `shadow`            | decisions computed and audited, never applied           |
| `warn`              | decisions applied, each application logged as a warning |
| `enforce` (default) | decisions applied silently                              |

Guard itself always evaluates and always audits; the mode governs whether the Router applies the outcome. `shadow` therefore gives you a complete preview of production behavior. The recommended rollout:

1. Deploy in `shadow`; watch `GET /api/v1/plugins/guard/decisions` and the audit log until the would-be blocks and amendments look right.
2. Move to `warn` and confirm applications behave under real amendments.
3. Move to `enforce`.

Switching modes is a config change plus reload; there is no runtime API for it.

## Audit trail

Every decision produces a JSON record: timestamp, session id, username, trust level, query fingerprint, statement type, tables, action, matching policy (if any), reason, amendments applied, and decision latency in microseconds. Records flow through a bounded channel (`audit_channel_size`) to the configured sink, and the most recent ones (`audit_buffer_size`) stay readable in memory at `GET /api/v1/plugins/guard/decisions?limit=N`.

Two sinks ship: `audit_sink = { type = "stdout" }` (one JSON line per record, the default, suited to container deployments shipping logs via a sidecar) and `audit_sink = { type = "file", path = "/var/log/querypilot/guard.jsonl" }` (JSONL appended; new files are created mode `0640` on Unix).

Operational notes for the file sink:

* Rotation by rename (logrotate's default) silently detaches the sink from the visible file. Use `copytruncate`, or rotate by pointing new processes at time-stamped paths; the file descriptor is held for the sink's lifetime and there is no SIGHUP reopen.
* If audit throughput exceeds the channel, records are dropped rather than blocking queries. Alert on `sqp_guard_audit_dropped_total` and on `sqp_guard_audit_file_write_errors_total` (disk full, permissions).

## REST API

Mounted at `/api/v1/plugins/guard` on the Router's admin API. Mutating endpoints require the configured `api_key` in the `X-Guard-Api-Key` header (or a bearer token); with no key configured, everything is open, acceptable only for loopback development. The surface covers listing and reloading policies, reading and mutating the registry, dry-running a query (`POST /test` with `{ sql, username?, trust_level? }`), reading recent decisions, and stats. The full endpoint list is in the [admin API reference](/querypilot/reference/admin-api).

## Monitoring

Key Prometheus series: `sqp_guard_decisions_total` (by action, policy, trust level), `sqp_guard_decision_duration_seconds`, `sqp_guard_registry_hits_total` / `sqp_guard_registry_misses_total`, `sqp_guard_amendments_total` (by type), `sqp_guard_timeouts_total`, `sqp_guard_unanalyzable_total`, and the audit-sink counters above. The most common "policy never fires" causes are severity gating (a `low` policy is invisible to `verified`-and-above sessions) and a `match` condition that does not hold on real traffic; check `GET /decisions` for what was actually evaluated, and `POST /test` to reproduce. See the [metrics reference](/querypilot/reference/metrics).

{/* source: verified against code @ 2026-07-18 */}


# Readyset QueryPilot (/querypilot)
import { Cards, Card } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';

QueryPilot is a SQL proxy built for modern workloads. It accelerates query processing with automatic caching and enforces policies on agentic traffic with Guard, keeping your database focused on serving your application. Applications keep their existing drivers, SQL, and credentials; they change only the host and port they connect to.

<Callout type="info">
  **GA v1 ships the Router and the Accelerator.** Guard is an upcoming feature; its documentation is included here ahead of availability.
</Callout>

<Cards>
  <Card title="What is QueryPilot?" href="/querypilot/what-is-querypilot" description="The four components, how they compose, and what is supported in GA v1." />

  <Card title="Getting started" href="/querypilot/getting-started" description="Run the Router from the Docker image and proxy your first query." />

  <Card title="Deployment" href="/querypilot/deployment" description="Docker Compose, Kubernetes, and Helm deployments." />

  <Card title="Tutorials" href="/demos/querypilot/read-write-split" description="Step-by-step guides for read/write splitting, caching, and policy enforcement." />
</Cards>

## Components

<Cards>
  <Card title="Router" href="/querypilot/router" description="The SQL proxy: wire protocols, connection pooling, query routing and translation, plugin host." />

  <Card title="Accelerator" href="/querypilot/accelerator" description="Discovers hot queries and manages Readyset caches and the rules that route traffic to them." />

  <Card title="Guard" href="/querypilot/guard" description="Upcoming. Policy enforcement for every query: trust levels, YAML policies, and a full audit trail." />
</Cards>

## Reference

<Cards>
  <Card title="Configuration" href="/querypilot/reference/router-configuration" description="Every key in querypilot.toml." />

  <Card title="APIs" href="/querypilot/reference/admin-api" description="The admin REST API and plugin APIs." />

  <Card title="Metrics" href="/querypilot/reference/metrics" description="All Prometheus series exported by the platform." />

  <Card title="Operations" href="/querypilot/operations" description="Config reload, graceful shutdown, monitoring, and runbook entries." />
</Cards>


# Operations (/querypilot/operations)
import { Callout } from 'fumadocs-ui/components/callout';

This page covers running QueryPilot after deployment. The Router is the SQL proxy (binary `querypilot`). Everything here assumes the metrics endpoint is enabled (`[metrics] enabled = true`), which serves Prometheus metrics on port 9090 and the Router's admin API on 9091 by default.

## Config validation

Both binaries take `--check`: load the config, validate it, print the result, and exit without serving traffic.

```bash
querypilot --check -c /etc/sqp/querypilot.toml
```

The Router prints `Configuration is valid` on success and a parse or validation error otherwise. Its schema is strict: unknown keys fail. Run `--check` in CI or a deploy hook before rolling a config change; a config that passes `--check` will not fail startup on schema grounds.

## Online config reload

### Router

When the metrics endpoint is enabled, the Router serves a reload API on the admin port:

```bash
curl -X POST http://localhost:9091/api/config/reload
curl http://localhost:9091/api/config/status
```

Reloadable without a restart:

* `routing.rules` and `routing.pattern_rules`
* `routing.read_write_split`, `routing.read_pool`, `routing.write_pool`, `routing.default_pool`, `routing.mysql_default_pool`
* `routing.cache.enabled`, `routing.cache.max_size`
* `[[translation.rules]]` (translations are cleared and re-registered from config; translations registered at runtime via the API are ephemeral and do not survive a reload)
* `logging.level`

Not reloadable: `listeners`, `pools`, `tls`, and the rest of `general`. Those require a restart, and reloaded rules can only reference pools that existed at startup.

Reload validates before applying: the TOML must parse, regexes must compile, and pool references must exist. On failure it returns 400 identifying the offending rule and field, and the old config stays active. On success the change set is applied atomically and the routing-decision cache is cleared. The response reports what changed (rule counts, whether the read/write split, cache config, or log level moved).

## Graceful shutdown and connection draining

The Router shuts down on SIGTERM or Ctrl+C (`docker stop` and Kubernetes pod termination both send SIGTERM):

1. Listeners stop accepting new connections.
2. The Router waits for active client connections to drain, up to a fixed 5-second window.
3. Connections still open when the window expires are force-closed, with a warning log that includes the remaining count.
4. Plugins shut down last, after traffic has stopped.

Plan rolling restarts around the 5-second drain: with transaction pooling, in-flight transactions shorter than the window complete; long-running queries are cut off. Drain the pod from your load balancer before sending SIGTERM if you need zero interruption. The `shutdown_timeout` key under `[general]` parses but the drain window is fixed at 5 seconds in this release.

## Logging

Both servers configure logging from the `[logging]` section: `level`, and `format = "pretty"` (human-readable, for terminals) or `"json"` (one JSON object per line, for log pipelines). The provided deployment configs use `json`.

Override the level at launch without editing the config:

```bash
QUERYPILOT_LOG_LEVEL=debug querypilot
```

Precedence is CLI flag (`--log-level`) over environment variable over config file. The Router's config `level` is a closed list (`trace`/`debug`/`info`/`warn`/`error`); the env/CLI override accepts full tracing filter directives such as per-module levels.

`RUST_LOG` is not read by either binary; exporting it does nothing. Both servers reload `logging.level` via `POST /api/config/reload` as described above. See [environment variables](/querypilot/reference/environment-variables).

## Monitoring

Both components serve Prometheus metrics on `GET /metrics` at their `[metrics] bind` address. The full catalog is in the [metrics reference](/querypilot/reference/metrics); ready-made Grafana dashboards and alert rules are in [Extras](/reference/querypilot-optional-configurations). Start by alerting on these:

| Metric                       | Alert when                                | Meaning                                                               |
| ---------------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
| `sqp_backend_health`         | `== 0` for any `pool`/`backend`           | A backend failed health checks and is out of rotation                 |
| `sqp_pool_utilization_ratio` | Sustained near 1.0                        | Pool at its `max_connections` cap; requests will queue                |
| `sqp_pool_timeouts_total`    | Increasing                                | Sessions gave up waiting for a connection (`acquire_timeout` expired) |
| `sqp_query_errors_total`     | Rate above your baseline, by `error_type` | Query failures (deadlocks, syntax, connection loss, timeouts)         |

Useful companions: `sqp_pool_queue_depth` and `sqp_pool_wait_duration_seconds` (leading indicators of exhaustion), `sqp_queries_total` and `sqp_query_duration_seconds` (traffic and latency baselines), `sqp_routing_decisions_total` by `pool` (verifies traffic splits the way you configured), and `sqp_auth_failures_total`.

## Pool status management

Take a pool out of rotation without a restart, for example ahead of backend maintenance:

```bash
curl http://localhost:9091/api/pools                       # list pools and statuses
curl -X PUT http://localhost:9091/api/pools/replica/status \
  -H "Content-Type: application/json" -d '{"status": "offline_soft"}'
```

Statuses are `online`, `offline_soft`, and `shunned`. Both non-online statuses cause acquire attempts against the pool to fail immediately as if no healthy backends exist, so make sure routing has somewhere else to send that traffic before you flip a pool offline. Set `{"status": "online"}` to restore it. Status overrides live in memory and reset to `online` on restart. See the [admin API reference](/querypilot/reference/admin-api).

{/* source: verified against code @ 2026-07-18 */}


# Performance (/querypilot/performance)
import { Callout } from 'fumadocs-ui/components/callout';

This page collects the performance measurements recorded during QueryPilot development, with the date and test conditions stated next to every number.

<Callout type="warning">
  All numbers on this page depend on hardware, network, data shape, and workload, and were measured on the specific dates and setups stated with each table. Treat them as reference points for what to expect and verify against your own deployment before making capacity decisions. See [Measuring your own deployment](#measuring-your-own-deployment).
</Callout>

<Callout type="info">
  **MySQL support is in preview.** Measurements involving MySQL are not part of the GA v1 support surface. PostgreSQL is the fully supported GA v1 path.
</Callout>

## Proxy overhead

Design targets for the Router (binary `querypilot`): under 25% overhead at p50 and under 50% at p99 for simple queries versus a direct connection, under 10% throughput loss on large results, and more than 5x speedup from connection pooling versus unpooled clients.

Measured comparison against direct PostgreSQL and PgBouncer (recorded 2026-02-22; 10 iterations per query via `psql`, local PostgreSQL 16, transaction pooling mode on both proxies):

| Query      | Direct PostgreSQL | Router           | PgBouncer       |
| ---------- | ----------------- | ---------------- | --------------- |
| `SELECT 1` | 0.55 ms           | 0.40 ms (-27%)   | 0.37 ms (-33%)  |
| 1K rows    | 2.58 ms           | 1.50 ms (-42%)   | 1.49 ms (-42%)  |
| 10K rows   | 17.48 ms          | 12.66 ms (-28%)  | 14.98 ms (-14%) |
| 100K rows  | 48.24 ms          | 50.82 ms (+5.3%) | 46.75 ms (-3%)  |

Readings from this run:

* The Router tracks PgBouncer across all query sizes. On the 100K-row result, where per-connection savings stop dominating, the Router measured +5.3% over direct versus PgBouncer's -3%.
* The Router was faster than PgBouncer on the 10K-row case (-28% versus -14%) in this run.

### Why pooled results beat direct connections

The negative overhead on small and medium queries is not a measurement error. In this test each `psql` iteration opens a fresh connection, so the direct-PostgreSQL column pays connection establishment on every query. Both proxies hold pooled backend connections, so a client "connection" costs a pool checkout instead of a PostgreSQL backend fork and handshake. Any workload that opens connections frequently (serverless functions, short-lived scripts, per-request connections) sees the same effect; a long-lived application connection pool sees the proxy's true per-statement overhead instead, which is where the internal latency budget below matters.

## Internal latency budget

Per-statement costs inside the Router, from the internal microbenchmark baseline recorded 2026-01-18 on local development hardware:

| Operation                                 | Measured   |
| ----------------------------------------- | ---------- |
| Query classification, simple statement    | 30-50 ns   |
| Query classification, complex statement   | 150-220 ns |
| Routing decision, in-transaction (pinned) | 2-5 ns     |
| Routing decision, single default pool     | 10-20 ns   |
| Routing decision, read/write split        | 40-180 ns  |

Everything is nanoseconds against query times measured in hundreds of microseconds or milliseconds; the routing engine is not where your latency goes. One asymmetry worth knowing: under read/write splitting, read routing (\~177 ns) costs more than write routing (\~38 ns) because a `SELECT` must be scanned for `FOR UPDATE`/`FOR SHARE` before it can be declared a read. That is by design; see the [read/write splitting tutorial](/demos/querypilot/read-write-split).

Plugins add cost only when enabled: with no plugin blocks configured, the plugin chain is empty and adds zero per-query overhead. Guard evaluates under an explicit per-decision budget (`max_decision_latency_ms`, default 50 ms) and fails open for reads when it is exceeded; see the [Guard guide](/querypilot/guard).

## Large results and streaming

Result-set handling scales linearly with rows and columns. Internal streaming benchmarks (recorded 2026-01-18; mock backend, measuring result construction without network I/O) put the proxy-side cost at:

| Shape  | Rows    | Columns | Measured |
| ------ | ------- | ------- | -------- |
| Narrow | 1,000   | 5       | \~65 µs  |
| Narrow | 10,000  | 5       | \~920 µs |
| Narrow | 100,000 | 5       | \~21 ms  |
| Wide   | 1,000   | 20      | \~190 µs |

No superlinear pathologies: 100x the rows costs roughly 100x the time, and 4x the columns costs roughly 3x. End to end, the 100K-row case in the 2026-02-22 comparison above measured +5.3% over a direct connection.

For pools fronting a vanilla PostgreSQL backend, [`raw_passthrough`](/querypilot/reference/router-configuration#raw_passthrough) removes the decode and re-encode step for prepared-statement results entirely, streaming backend bytes to the client unchanged. It must stay off for cross-protocol pools, where rows genuinely need re-encoding. See the [Router guide](/querypilot/router).

## Measuring your own deployment

Reproduce the overhead comparison against your own database in a few minutes:

```bash
# Direct to PostgreSQL
psql "host=db.internal port=5432 dbname=mydb" \
  -c '\timing on' -c "SELECT * FROM orders LIMIT 10000" | tail -1

# Through the Router
psql "host=proxy.internal port=5433 dbname=mydb" \
  -c '\timing on' -c "SELECT * FROM orders LIMIT 10000" | tail -1
```

Run each query several times and compare medians, not single samples; first runs pay cache warming on both paths. Test the query shapes and result sizes your application actually produces, and test with your application's real connection behavior (pooled versus per-request) since that decides whether pooling savings apply to you.

Under sustained load, the Prometheus metrics separate proxy cost from backend cost:

* `sqp_query_duration_seconds` is end-to-end query latency through the Router, labelled by pool.
* `sqp_pool_acquire_duration_seconds` is time spent waiting for a backend connection; if this grows, raise pool limits before blaming query paths (see [Operations](/querypilot/operations)).
* `sqp_routing_decisions_total` and `sqp_routing_cache_operations_total` confirm where statements went and whether decision caching is hitting.
* `GET /api/stats/digests` on the admin API gives per-query-shape latency statistics without external tooling.

The full series list is in the [metrics reference](/querypilot/reference/metrics).

{/* source: verified against code @ 2026-07-18 */}


# Getting Started (/querypilot/proxysql/getting-started)
This page details the configuration of QueryPilot for ProxySQL when running in a self-hosted environment.

If you are curious about QueryPilot for ProxySQL, and would like to try it out in your own environment, please contact us at [hello@readyset.io](mailto:hello@readyset.io)!

# Workflow

QueryPilot for ProxySQL automatically executes the following steps:

1. Lock a file on disk (configured by `lock_file`) to prevent multiple instances of QueryPilot for ProxySQL from executing concurrently.
2. If `operation_health_check = true`, query `mysql_servers` and check all servers that have `comment LIKE '%Readyset%'` (case insensitive) and `hostgroup = <id of readyset_hostgroup>` in the ProxySQL configuration. For each Readyset instance, fetch its current status and update its ProxySQL status accordingly:
   * `Online` - Adjust the server status to `ONLINE` in ProxySQL.
   * `Maintenance Mode` -  Adjust the server status to `OFFLINE_SOFT` in ProxySQL.
   * `Snapshot In Progress` - Adjust the server status to `SHUNNED` in ProxySQL.
3. If `operation_query_discovery = true`, query the table `stats_mysql_query_digest` and find queries executed at `source_hostgroup` by `readyset_user`. Check if each query is supported by Readyset. The queries are considered in order of priority specified by the [Query Discovery](#query-discovery) configurations.
4. If the query is supported, cache it in Readyset by executing `CREATE CACHE FROM <query>`.
5. If `warmup_time_s` is NOT configured, a new query rule will be added, redirecting this query to Readyset.
6. If `warmup_time_s` is configured, a new query rule will be added to mirror this query to Readyset. The query will still be proxied to the original hostgroup.
7. Once `warmup_time_s` seconds have elapsed since the query was mirrored, the query rule will be updated to redirect the query to Readyset instead of mirroring.

# Configuration

Assuming you have your [ProxySQL](https://proxysql.com/documentation/installing-proxysql/) already configured with MySQL you will need to create a new hostgroup and add Readyset to this hostgroup:

```
INSERT INTO mysql_servers (hostgroup_id, hostname, port, comment) VALUES (99, '127.0.0.1', 3307, 'Readyset');
LOAD MYSQL SERVERS TO RUNTIME;
SAVE MYSQL SERVERS TO DISK;
```

**NOTE**: It's required to add `Readyset` as a comment to the server to be able to identify it in QueryPilot for ProxySQL.

To configure QueryPilot for ProxySQL to run, execute the following on the ProxySQL admin interface:

```
INSERT INTO scheduler (active, interval_ms, filename, arg1) VALUES (1, 10000, '/usr/bin/readyset_query_pilot', '--config=/etc/readyset_query_pilot.cnf');
LOAD SCHEDULER TO RUNTIME;
SAVE SCHEDULER TO DISK;
```

Configure `/etc/readyset_query_pilot.cnf` as follow:

* `proxysql_user` - (Required) - ProxySQL admin user
* `proxysql_password` - (Required) - ProxySQL admin password
* `proxysql_host` - (Required) - ProxySQL admin host
* `proxysql_port` - (Required) - ProxySQL admin port
* `readyset_user` - (Required) - Readyset application user
* `readyset_password` - (Required) - Readyset application password
* `readyset_database` - (Optional) - Readyset application database
* `source_hostgroup` - (Required) - Hostgroup running your Read workload
* `readyset_hostgroup` - (Required) - Hostgroup where Readyset is configure
* `warmup_time_s` - (Optional) - Time in seconds to mirror a query supported before redirecting the query to Readyset (Default `0` - no mirror)
* `lock_file` - (Optional) - Lock file to prevent two instances of QueryPilot for ProxySQL from running at the same time (Default `"/tmp/readyset_query_pilot.lock"`)
* `operation_health_check` - (Optional) - Whether to perform health checks on Readyset instances, shunning them if they become unhealthy (Default `true`)
* `operation_query_discovery` - (Optional) - Whether to automatic query discovery, caching, and routing to Readyset (Default `true`)
* `operation_rules_from_caches` - (Optional) - Whether to bring the ProxySQL deep cache rules into alignment with whatever deep caches (previously created by QueryPilot for ProxySQL) currently exist on Readyset, adding or dropping them as necessary (Default `true`)
* `operation_shallow_cache` - (Optional) - Whether to fallback to creating shallow caches if deep caching via Readyset is not supported (Default `true`)
* `number_of_queries` - (Optional) - Number of queries to cache when `operation_query_discovery` is enabled (Default `10`)
* `query_discovery_mode` / `query_discovery_min_execution` / `query_discovery_min_row_sent` / `query_discovery_wait_s` - (Optional) - Query Discovery configurations. The options are described in [Query Discovery](#query-discovery) (Default `"count_star"` / `0` / `0` / `0`)
* `shallow_cache_ttl_ms` - (Optional) - The desired TTL in milliseconds when using shallow caching (Default `10000`)
* `shallow_cache_size_mb` - (Optional) - The memory capacity to use for shallow caching (Default `256`)
* `denylist_path` - (Optional) - Path to the denylist file that QueryPilot for ProxySQL will use to deny queries from being cached (Default `/etc/readyset_query_pilot_denylist`)

# Query Discovery

Below are a set of configuration options related to finding queries that are cacheable:

* `query_discovery_mode`: (Optional) - Mode to discover queries to automatically cache in Readyset. The options are described in [Query Discovery Mode](#query-discovery-mode) (Default `"count_star"`)
* `query_discovery_min_execution`: (Optional) - Minimum number of executions of a query to be considered a candidate to be cached (Default `1`)
* `query_discovery_min_row_sent`: (Optional) - Minimum number of rows sent by a query to be considered a candidate to be cached (Default `0`)
* `query_discovery_wait_s` - (Optional) - Only discover queries after ProxySQL has proxied queries for at least this long (Default `0`)

# Query Discovery Mode

The `query_discovery_mode` setting can be customized to instruct QueryPilot for ProxySQL how it should prioritize the queries it considers when automatically making caching decisions.

The options are:

1. `"count_star"` - Total Number of Query Executions
   * **Formula**: `count_star = total_executions`
   * **Description**: This metric gives the total number of times the query has been executed. It is valuable for understanding how frequently the query runs. A high `count_star` value suggests that the query is executed often.

2. `"sum_time"` - Total Time Spent Executing the Query
   * **Formula**: `sum_time = total_execution_time`
   * **Description**: This metric represents the total cumulative time spent (measured in microseconds) executing the query across all its executions. It provides a clear understanding of how much processing time the query is consuming over time. A high total execution time can indicate that the query is either frequently executed or is time-intensive to process.

3. `"sum_rows_sent"` - Total Number of Rows Sent by the Query
   * **Formula**: `sum_rows_sent = total_rows_sent`
   * **Description**: This metric provides the total number of rows sent to the client across all executions of the query. It helps you understand the query's output volume and the amount of data being transmitted.

4. `"mean_time"` - Average Query Execution Time
   * **Formula**: `mean_time = sum_time / count_star`
   * **Description**: The mean time gives you an idea of the typical performance (measured in microseconds) of the query over all executions. It provides a central tendency of how long the query generally takes to execute.

5. `"execution_time_distance"` - Time Distance Between Query Executions
   * **Formula**: `execution_time_distance = max_time - min_time`
   * **Description**: This shows the spread between the fastest and slowest executions of the query (measured in microseconds). A large range might indicate variability in system load, input sizes, or external factors affecting performance.

6. `"query_throughput"` - Query Throughput
   * **Formula**: `query_throughput = count_star / sum_time`
   * **Description**: This shows how many queries are processed per unit of time (measured in microseconds). It's useful for understanding system capacity and how efficiently the database is handling the queries.

7. `"worst_best_case"` - Worst Best-Case Query Performance
   * **Formula**: `worst_best_case = max(min_time)`
   * **Description**: The `min_time` metric gives the fastest time the query was ever executed (measured in microseconds). It reflects the best-case performance scenario, which could indicate the query's performance under optimal conditions.

8. `"worst_worst_case"` - Worst Worst-Case Query Performance
   * **Formula**: `worst_worst_case = max(max_time)`
   * **Description**: The `max_time` shows the slowest time the query was executed (measured in microseconds). This can indicate potential bottlenecks or edge cases where the query underperforms, which could be due to larger data sets, locks, or high server load.

9. `"distance_mean_max"` - Distance Between Mean Time and Max Time (mean\_time vs max\_time)
   * **Formula**: `distance_mean_max = max_time - mean_time`
   * **Description**: The distance between the mean execution time and the maximum execution time provides insight into how much slower the worst-case execution is compared to the average (measured in microseconds). A large gap indicates significant variability in query performance, which could be caused by certain executions encountering performance bottlenecks, such as large datasets, locking, or high system load.

# Denylist

QueryPilot for ProxySQL supports a denylist mechanism to deny specific queries from being automatically cached.  The default denylist file path is `/etc/readyset_query_pilot_denylist`, but this can be changed with the `denylist_path` configuration setting.

Each line specifies a new denylist rule.  Queries can be denied based on database, their ProxySQL digest, and whether or not eligible for deep or shallow caching.

An example denylist file is below:

```
# Each line in the denylist defines one deny rule for QueryPilot for ProxySQL.
# Comments can be specified with the # character.
#
# A single rule can deny a specific database, digest, cache type, or any
# combination thereof.
#
# To compose a deny rule, write one or more space-delimited key=value pairs.
# These pairs are then AND'd together to define a single deny rule.  The pairs
# can be introduced in any order.
#
# The following keys are valid:
#
# - db        # Specifies a database
# - digest    # Specifies a ProxySQL digest
# - type      # Specifies the cache type (deep or shallow)
#
# Some examples are below:

# Deny all caches in database db1
db=db1

# Deny shallow caches in database db2
db=db2 type=shallow

# Deny this digest everywhere
digest=0x2153C80B94EC555E

# Deny deep caches for this digest in database db4
db=db4 digest=0x2153C80B94EC555E type=deep
```


# QueryPilot for ProxySQL (/querypilot/proxysql)
QueryPilot for ProxySQL automatically identifies your highest-impact queries and caches them, keeping results fresh without code changes or manual tuning.

* [What is QueryPilot for ProxySQL?](/querypilot/proxysql/what-is-querypilot) — how it works and what it's for
* [Getting Started](/querypilot/proxysql/getting-started) — install and configure QueryPilot for ProxySQL


# What is QueryPilot for ProxySQL (/querypilot/proxysql/what-is-querypilot)
QueryPilot for ProxySQL is an intelligent database optimization layer that automatically identifies and caches your highest-impact queries. It sits transparently between your application and your database, so your queries get cached automatically with no code changes.

It is built for unpredictable workloads, including AI-generated queries, where query patterns shift over time and manual caching and tuning can't keep up.

## How it works

* **Intelligent query identification.** QueryPilot for ProxySQL analyzes live workload patterns to find the queries driving latency, focusing on high-impact patterns rather than raw frequency.
* **Automatic optimization.** It routes each query to its optimal execution path (cache, replica, or primary) without code changes or manual tuning.
* **Data freshness.** Cached results stay in sync with the underlying database as it changes, with no manual TTLs or invalidation to manage.
* **Continuous learning.** Caching and routing decisions adapt as workload patterns evolve, improving over time.

## Benefits

* Sub-millisecond latency on cached queries
* Reduced database load without adding replicas
* Lower infrastructure costs
* No operational burden for query optimization

Ready to try it? See [Getting Started](/querypilot/proxysql/getting-started).


# Router Admin API (/querypilot/reference/admin-api)
import { Callout } from 'fumadocs-ui/components/callout';

## Overview

The Router (binary `querypilot`) serves a REST admin API for translations, routing, configuration reload, statistics, pattern rules, and pool control, plus the Accelerator and Guard plugin endpoints.

The admin API has no bind address of its own. It listens on the [`[metrics]` bind](/querypilot/reference/router-configuration#metrics) IP at the metrics port plus one: with the default `127.0.0.1:9090`, the admin API is `127.0.0.1:9091`. If the metrics port is 65535, startup fails with a port-overflow error.

The server starts when `[metrics] enabled = true` (full admin surface) or when an enabled plugin contributes REST routes. When only a plugin is enabled, only the plugin routes are served; enabling Guard alone does not expose the admin control plane.

<Callout type="warn">
  The core admin routes are unauthenticated. Keep the metrics bind on loopback or a private network, and firewall both the metrics port and the derived admin port. The plugin routes support an `api_key`; set one whenever the bind is not loopback. See [Security](/querypilot/security).
</Callout>

Errors return JSON with an `error` field. All examples below assume the default `127.0.0.1:9091`.

## Translations

Query translations rewrite matching queries and pin them to a pool. Translations registered through this API are ephemeral: a config reload replaces the registry with the `[[translation.rules]]` from the file.

### POST /api/translations

Register a translation. Send concrete SQL for both the original and translated query; the Router parameterizes both and builds the index mapping. The target pool must exist in the current config.

```bash
curl -X POST http://127.0.0.1:9091/api/translations \
  -H 'Content-Type: application/json' \
  -d '{
    "original_sql": "SELECT name FROM users WHERE id = 42",
    "translated_sql": "SELECT name FROM analytics.users WHERE id = 42",
    "target_pool": "analytics"
  }'
```

```json
{
  "hash": 1234567890123456789,
  "normalized": "SELECT name FROM users WHERE id = $1",
  "original_values": 1,
  "translated_values": 1
}
```

### GET /api/translations

List all registered translations.

```bash
curl http://127.0.0.1:9091/api/translations
```

```json
{
  "translations": [
    {
      "hash": 1234567890123456789,
      "original_sql": "SELECT name FROM users WHERE id = $1",
      "translated_pattern": "SELECT name FROM analytics.users WHERE id = $1",
      "target_pool": "analytics",
      "enabled": true
    }
  ],
  "total": 1,
  "enabled": 1
}
```

### DELETE /api/translations/:hash

Delete a translation by fingerprint hash. Returns `204 No Content` on success, `400` with an error body if the hash is unknown.

```bash
curl -X DELETE http://127.0.0.1:9091/api/translations/1234567890123456789
```

### PUT /api/translations/:hash/enable

Enable a translation. Returns `204 No Content`.

```bash
curl -X PUT http://127.0.0.1:9091/api/translations/1234567890123456789/enable
```

### PUT /api/translations/:hash/disable

Disable a translation without deleting it. Returns `204 No Content`.

```bash
curl -X PUT http://127.0.0.1:9091/api/translations/1234567890123456789/disable
```

## Routing

### GET /api/routing/test

Dry-run the routing decision for a SQL query without executing it. Query parameters: `sql` (required) and `in_transaction` (optional bool, default `false`). The response includes the query's fingerprint hash, which you can use in `type = "hash"` [pattern rules](/querypilot/reference/router-configuration#type) and in the pattern-rules API below.

```bash
curl 'http://127.0.0.1:9091/api/routing/test?sql=SELECT%20*%20FROM%20orders%20WHERE%20id%20%3D%201'
```

```json
{
  "decision": "pool",
  "target_pool": "primary",
  "rewritten_sql": null,
  "fingerprint_hash": 9876543210987654321,
  "normalized_sql": "SELECT * FROM orders WHERE id = $1",
  "cached": false,
  "duration_ns": 12345
}
```

`decision` is one of `pool`, `translation` (with `rewritten_sql` set), `reject` (with the rejection message in `rewritten_sql`), or `pinned` (the session is pinned mid-transaction).

## Configuration

### POST /api/config/reload

Re-read the config file from disk and apply the reloadable parts: routing rules, pattern rules, translation rules, read/write split settings, routing cache settings, and log level. Validation failures (bad regex, unknown pool) return `400` and leave the running config untouched.

```bash
curl -X POST http://127.0.0.1:9091/api/config/reload
```

```json
{
  "success": true,
  "reloaded_at": "2026-07-18T12:00:00Z",
  "changes": {
    "routing_rules": 2,
    "pattern_rules": 1,
    "translation_rules": 3,
    "read_write_split_changed": false,
    "cache_config_changed": false,
    "log_level_changed": false
  }
}
```

### GET /api/config/status

Report the config file path, load time, last reload attempt, and a summary of the active configuration. The shipped container healthcheck probes this endpoint.

```bash
curl http://127.0.0.1:9091/api/config/status
```

```json
{
  "config_file": "/etc/sqp/querypilot.toml",
  "loaded_at": "2026-07-18T11:00:00Z",
  "current": {
    "read_write_split": true,
    "read_pool": "replica",
    "write_pool": "primary",
    "routing_rules_count": 2,
    "pattern_rules_count": 1,
    "translation_rules_count": 3,
    "cache_enabled": true,
    "log_level": "info"
  }
}
```

## Query statistics

### GET /api/stats/digests

List per-query digest statistics, ranked and filtered. Query parameters:

* `limit`: maximum entries returned (default `100`)
* `order_by`: one of `count_star`, `sum_rows_sent`, `last_seen`, `mean_time`, `query_throughput`, `sum_time` (default `sum_time`); an unrecognized value returns an error
* `min_count`: minimum execution count (default `0`)
* `min_rows_sent`: minimum total rows sent (default `0`)
* `schema`: exact schema filter

```bash
curl 'http://127.0.0.1:9091/api/stats/digests?order_by=count_star&limit=10'
```

```json
{
  "digests": [
    {
      "digest_text": "SELECT * FROM orders WHERE id = $1",
      "fingerprint_hash": 9876543210987654321,
      "schema": "public",
      "username": "app",
      "count_star": 15230,
      "sum_time_us": 4820000,
      "sum_rows_sent": 15230,
      "first_seen": 1752830000,
      "last_seen": 1752840000
    }
  ],
  "total_unique_digests": 42,
  "overflow_count": 0
}
```

## Pattern rules

Runtime pattern rules route by fingerprint hash. Rules created here are hash-matched, unowned by any plugin, and separate from the `[[routing.pattern_rules]]` in the config file.

### POST /api/pattern-rules

Create a rule routing a fingerprint to a pool. Body fields: `fingerprint_hash` (required), `target_pool` (required), `comment` (optional). Returns `201 Created`.

```bash
curl -X POST http://127.0.0.1:9091/api/pattern-rules \
  -H 'Content-Type: application/json' \
  -d '{"fingerprint_hash": 9876543210987654321, "target_pool": "replica", "comment": "hot lookup"}'
```

```json
{
  "fingerprint_hash": 9876543210987654321,
  "status": "created"
}
```

### GET /api/pattern-rules

List runtime pattern rules.

```bash
curl http://127.0.0.1:9091/api/pattern-rules
```

```json
{
  "rules": [
    {
      "fingerprint_hash": 9876543210987654321,
      "target_pool": "replica",
      "enabled": true,
      "comment": "hot lookup",
      "created_at": 1752840000
    }
  ],
  "total": 1
}
```

### DELETE /api/pattern-rules/:hash

Remove a rule. Returns `204 No Content`, or `404` if the hash is unknown.

```bash
curl -X DELETE http://127.0.0.1:9091/api/pattern-rules/9876543210987654321
```

### PUT /api/pattern-rules/:hash/disable

Disable a rule in place. Returns `200 OK`, or `404` if the hash is unknown. There is no enable endpoint: to re-enable a disabled rule, delete it and create it again.

```bash
curl -X PUT http://127.0.0.1:9091/api/pattern-rules/9876543210987654321/disable
```

## Pools

### GET /api/pools

List pools and their health status.

```bash
curl http://127.0.0.1:9091/api/pools
```

```json
{
  "pools": [
    { "name": "primary", "status": "online" },
    { "name": "replica", "status": "online" }
  ],
  "total": 2
}
```

### PUT /api/pools/:name/status

Override a pool's status. Body: `{"status": "..."}` where the value is `online`, `offline_soft` (drain: no new assignments), or `shunned` (excluded). Returns `200 OK`, or `503` if pool management is unavailable.

```bash
curl -X PUT http://127.0.0.1:9091/api/pools/replica/status \
  -H 'Content-Type: application/json' \
  -d '{"status": "offline_soft"}'
```

## Accelerator plugin API

Mounted at `/api/v1/plugins/accelerator` when [`[plugins.accelerator]`](/querypilot/reference/router-configuration#pluginsaccelerator) is enabled. Mutating endpoints require the `X-QueryPilot-Api-Key` header when an `api_key` is configured, compared in constant time. When the admin API binds a non-loopback address and no `api_key` is set, the mutating endpoints refuse to serve entirely (`403`). Every mutation is recorded in the audit trail.

### GET /api/v1/plugins/accelerator/candidates

List caching candidates from the query digest, with per-candidate threshold flags. The literal-bearing `digest_text` is redacted unless the request presents a valid key.

```bash
curl -H 'X-QueryPilot-Api-Key: change-me' \
  http://127.0.0.1:9091/api/v1/plugins/accelerator/candidates
```

```json
[
  {
    "fingerprint_hash": "0x89ABCDEF01234567",
    "schema": "public",
    "username": "app",
    "count": 15230,
    "sum_time_us": 4820000,
    "first_seen": 1752830000,
    "last_seen": 1752840000,
    "past_execution_threshold": true,
    "past_warmup_window": true,
    "digest_text": "SELECT * FROM orders WHERE id = 1"
  }
]
```

### GET /api/v1/plugins/accelerator/rules

List routing rules owned by the Accelerator.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/accelerator/rules
```

```json
[
  {
    "fingerprint_hash": "0x89ABCDEF01234567",
    "target_pool": "readyset",
    "state": "active",
    "enabled": true,
    "created_at": 1752840000
  }
]
```

`state` is `active`, `warmup:until=<unix>`, `health_disabled`, or `operator_disabled`.

### GET /api/v1/plugins/accelerator/status

Report discovery-loop health: last tick, duration, result, last success, consecutive errors, and pause state.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/accelerator/status
```

```json
{
  "last_tick_unix": 1752840000,
  "last_duration_ms": 120,
  "last_result": "ok",
  "last_success_unix": 1752840000,
  "consecutive_errors": 0,
  "paused": false
}
```

### GET /api/v1/plugins/accelerator/decisions

List recent discovery-cycle outcomes (tick time, result, duration).

```bash
curl http://127.0.0.1:9091/api/v1/plugins/accelerator/decisions
```

### GET /api/v1/plugins/accelerator/denylist

Report how many denylist rules are loaded. Entry text is not returned; it can contain literal-bearing SQL.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/accelerator/denylist
```

```json
{ "rule_count": 3 }
```

### GET /api/v1/plugins/accelerator/audit

Read the bounded audit trail of mutations performed through this API. Requires a valid key when one is configured.

```bash
curl -H 'X-QueryPilot-Api-Key: change-me' \
  http://127.0.0.1:9091/api/v1/plugins/accelerator/audit
```

### DELETE /api/v1/plugins/accelerator/rules/:hash

Drop an Accelerator-owned rule by fingerprint hash (decimal). Returns `204 No Content`; `403` if the rule exists but is not owned by the Accelerator. Mutating: key required when configured.

```bash
curl -X DELETE -H 'X-QueryPilot-Api-Key: change-me' \
  http://127.0.0.1:9091/api/v1/plugins/accelerator/rules/9920397370294392167
```

### POST /api/v1/plugins/accelerator/actions/force-cache

Queue a fingerprint for caching, bypassing the execution-count and warmup thresholds. The fingerprint must exist in the current digest, be SELECT-shaped, and pass the denylist; the Readyset support check still applies when the loop processes it. Returns `202 Accepted`. Mutating: key required when configured.

```bash
curl -X POST -H 'X-QueryPilot-Api-Key: change-me' \
  -H 'Content-Type: application/json' \
  -d '{"fingerprint_hash": 9920397370294392167}' \
  http://127.0.0.1:9091/api/v1/plugins/accelerator/actions/force-cache
```

```json
{
  "fingerprint_hash": "0x89ABCDEF01234567",
  "status": "queued"
}
```

### POST /api/v1/plugins/accelerator/actions/pause

Pause the discovery loop. Mutating: key required when configured.

```bash
curl -X POST -H 'X-QueryPilot-Api-Key: change-me' \
  http://127.0.0.1:9091/api/v1/plugins/accelerator/actions/pause
```

```json
{ "paused": true }
```

### POST /api/v1/plugins/accelerator/actions/resume

Resume a paused discovery loop. Mutating: key required when configured.

```bash
curl -X POST -H 'X-QueryPilot-Api-Key: change-me' \
  http://127.0.0.1:9091/api/v1/plugins/accelerator/actions/resume
```

## Guard plugin API

Mounted at `/api/v1/plugins/guard` when [`[plugins.guard]`](/querypilot/reference/router-configuration#pluginsguard) is enabled. Read endpoints are open; mutating endpoints (`POST /policies/reload`, `POST /registry`, `DELETE /registry/:fingerprint`) require the `X-Guard-Api-Key` header (or `Authorization` header) to match the configured `api_key`. When no `api_key` is set, all endpoints are open; that is a development posture only.

### GET /api/v1/plugins/guard/policies

List loaded policies.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/guard/policies
```

```json
[
  {
    "name": "no-unbounded-deletes",
    "severity": "high",
    "enabled": true,
    "description": "Block DELETE without a WHERE clause"
  }
]
```

### POST /api/v1/plugins/guard/policies/reload

Reload policies from a directory. Body: `{"dir": "..."}`, or an empty object `{}` to reload from the configured `policy_dir`. Mutating: key required when configured.

```bash
curl -X POST -H 'X-Guard-Api-Key: change-me' \
  -H 'Content-Type: application/json' -d '{}' \
  http://127.0.0.1:9091/api/v1/plugins/guard/policies/reload
```

```json
{ "loaded": 4 }
```

### GET /api/v1/plugins/guard/registry

List trusted-query registry entries.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/guard/registry
```

### POST /api/v1/plugins/guard/registry

Add a registry entry. The body is a registry entry object; on success returns `{"ok": true}`. Mutating: key required when configured.

```bash
curl -X POST -H 'X-Guard-Api-Key: change-me' \
  -H 'Content-Type: application/json' \
  -d @entry.json \
  http://127.0.0.1:9091/api/v1/plugins/guard/registry
```

### GET /api/v1/plugins/guard/registry/:fingerprint

Fetch one registry entry by fingerprint (hex like `0xABC...` or decimal). Returns `404` if absent.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/guard/registry/0x89ABCDEF01234567
```

### DELETE /api/v1/plugins/guard/registry/:fingerprint

Remove a registry entry. Returns `{"removed": true}`, or `404` if absent. Mutating: key required when configured.

```bash
curl -X DELETE -H 'X-Guard-Api-Key: change-me' \
  http://127.0.0.1:9091/api/v1/plugins/guard/registry/0x89ABCDEF01234567
```

### POST /api/v1/plugins/guard/test

Dry-run a decision against the live policy set without executing the query. Body: `sql` (required), `username` (optional), `trust_level` (optional).

```bash
curl -X POST -H 'Content-Type: application/json' \
  -d '{"sql": "DELETE FROM orders", "trust_level": "verified"}' \
  http://127.0.0.1:9091/api/v1/plugins/guard/test
```

```json
{
  "decision": "block",
  "policy": "no-unbounded-deletes",
  "message": "DELETE without WHERE is not allowed",
  "reason": "policy matched",
  "latency_us": 180
}
```

`decision` is one of `allow`, `block`, `amend`, or `reroute`.

### GET /api/v1/plugins/guard/decisions

Read recent audit records from the in-memory ring buffer. Query parameter `limit` (default `100`, capped at the buffer capacity).

```bash
curl 'http://127.0.0.1:9091/api/v1/plugins/guard/decisions?limit=20'
```

### GET /api/v1/plugins/guard/stats

Report registry size, policy counts, and audit health.

```bash
curl http://127.0.0.1:9091/api/v1/plugins/guard/stats
```

```json
{
  "registry_size": 12,
  "policies_loaded": 4,
  "policies_invalid": 0,
  "policies_compile_warnings": 0,
  "audit_dropped": 0
}
```

{/* source: verified against code @ 2026-07-18 */}


# Environment Variables (/querypilot/reference/environment-variables)
import { Callout } from 'fumadocs-ui/components/callout';

## Overview

This page lists every environment variable read by the QueryPilot binaries: the Router (binary `querypilot`) and the standalone Accelerator (binary `querypilot-accelerator`).

For variables that mirror a CLI flag, precedence is:

**CLI flag, then environment variable, then config file or built-in default.**

The environment variable applies only when the corresponding flag is absent from the command line.

## Router

#### `QUERYPILOT_CONFIG`

Path to the Router config file. Mirrors `-c, --config`. When unset, the Router reads `querypilot.toml` from the current directory. See [Router configuration](/querypilot/reference/router-configuration).

#### `QUERYPILOT_LOG_LEVEL`

Override the Router log level. Mirrors `-l, --log-level` and overrides `logging.level` from the config file. Unlike the config key, it accepts full tracing filter directives, so both `debug` and `sqp_core=debug,info` are valid.

```bash
QUERYPILOT_LOG_LEVEL=debug querypilot
```

## Accelerator (standalone)

#### `QUERYPILOT_ACCELERATOR_ALLOW_INSECURE_HTTP`

When set to `1`, waives the requirement that a non-loopback `sqp_api_url` use `https` plus an API token. Read by the standalone `querypilot-accelerator` binary only.

<Callout type="warn">
  This variable exists for test and development fixtures only, so containerized end-to-end tests can reach the Router admin API over plain HTTP across a Docker network. Setting it in production sends the Accelerator's API token and cache-management traffic unencrypted to a non-loopback host. Use `https` and an API token instead.
</Callout>

## All binaries

#### `NO_COLOR`

When set to any value, disables ANSI color in log output.

## RUST\_LOG is not read

`querypilot` does not read `RUST_LOG`. It builds its log filter exclusively from the configured level: the config file's `logging.level`, the `--log-level` flag, or the `QUERYPILOT_LOG_LEVEL` variable above. Exporting `RUST_LOG=debug` has no effect.

The standalone `querypilot-accelerator` binary reads no logging environment variable at all; its verbosity is the `log_verbosity` key in its config file.

## Values preset by the shipped containers

The Docker images and deployment manifests preset three of the variables above; see [Deployment](/querypilot/deployment) for the full container conventions.

| Variable            | Value in shipped containers |
| ------------------- | --------------------------- |
| `QUERYPILOT_CONFIG` | `/etc/sqp/querypilot.toml`  |

{/* source: verified against code @ 2026-07-18 */}


# Metrics (/querypilot/reference/metrics)
import { Callout } from 'fumadocs-ui/components/callout';

## Overview

The Router (binary `querypilot`) serves Prometheus metrics at its [`[metrics]` bind](/querypilot/reference/router-configuration#metrics), default `127.0.0.1:9090`, when `[metrics] enabled = true`. All series names keep the `sqp_` prefix.

The endpoint exports the core `sqp_*` series plus the plugin-chain, Guard (`sqp_guard_*`), and Accelerator (`sqp_qp_*`) series for whichever plugins are enabled.

Series appear on first emission, so a metric is absent until the code path that records it has run at least once. See [Operations](/querypilot/operations) for alerting guidance.

<Callout type="info">
  The `protocol` label takes the values `postgres` and `mysql`. MySQL support is in preview; PostgreSQL is the supported GA v1 path.
</Callout>

## Router metrics

Query execution:

| Name                         | Type      | Measures                                                            | Labels                                     |
| ---------------------------- | --------- | ------------------------------------------------------------------- | ------------------------------------------ |
| `sqp_queries_total`          | counter   | Completed queries                                                   | `pool`, `query_type`, `protocol`, `status` |
| `sqp_query_duration_seconds` | histogram | Query execution latency                                             | `pool`, `query_type`, `protocol`           |
| `sqp_query_rows_returned`    | histogram | Rows returned per query                                             | `pool`, `query_type`                       |
| `sqp_query_errors_total`     | counter   | Query errors by classified type                                     | `pool`, `error_type`                       |
| `sqp_query_timeout_total`    | counter   | Queries that hit a per-query or pool deadline                       | `pool`                                     |
| `sqp_errors_retryable_total` | counter   | Errors classified as transient (deadlock, timeout, lost connection) | `pool`, `error_type`                       |
| `sqp_errors_fatal_total`     | counter   | Errors classified as permanent (syntax, constraint, permission)     | `pool`, `error_type`                       |
| `sqp_result_bytes_total`     | counter   | Bytes returned in query results                                     | `pool`, `query_type`                       |

`query_type` is one of `read`, `write`, `txn`, `ddl`, `admin`, `session`, `unknown`. `status` is `success` or `error`.

Routing:

| Name                                 | Type      | Measures                         | Labels                         |
| ------------------------------------ | --------- | -------------------------------- | ------------------------------ |
| `sqp_routing_decisions_total`        | counter   | Routing decisions by kind        | `decision_type`, `target_pool` |
| `sqp_routing_duration_seconds`       | histogram | Time to make a routing decision  | `decision_type`                |
| `sqp_routing_cache_entries`          | gauge     | Routing-cache size               | none                           |
| `sqp_routing_cache_operations_total` | counter   | Cache hits, misses, evictions    | `operation`                    |
| `sqp_routing_rejects_total`          | counter   | Queries rejected by a rule       | `pool`                         |
| `sqp_translations_registered`        | gauge     | Registered translations          | none                           |
| `sqp_translation_matches_total`      | counter   | Queries matched by a translation | `target_pool`                  |

`decision_type` is one of `translation`, `pattern`, `regex`, `default`, `pinned`.

Connection pools and backends:

| Name                                   | Type      | Measures                                                                      | Labels                          |
| -------------------------------------- | --------- | ----------------------------------------------------------------------------- | ------------------------------- |
| `sqp_pool_connections`                 | gauge     | Pooled connections by state (`available`, `in_use`)                           | `pool`, `state`                 |
| `sqp_pool_connections_max`             | gauge     | Configured connection ceiling                                                 | `pool`                          |
| `sqp_pool_acquire_total`               | counter   | Connection acquisitions by outcome (`reused`, `created`, `waited`, `timeout`) | `pool`, `outcome`               |
| `sqp_pool_acquire_duration_seconds`    | histogram | Acquire latency                                                               | `pool`, `outcome`               |
| `sqp_pool_errors_total`                | counter   | Pool errors                                                                   | `pool`, `error_type`            |
| `sqp_pool_queue_depth`                 | gauge     | Requests waiting for a connection                                             | `pool`                          |
| `sqp_pool_wait_duration_seconds`       | histogram | Time from request to acquisition                                              | `pool`                          |
| `sqp_pool_timeouts_total`              | counter   | Acquire timeouts                                                              | `pool`                          |
| `sqp_pool_utilization_ratio`           | gauge     | In-use over max connections                                                   | `pool`                          |
| `sqp_pool_connection_lifetime_seconds` | histogram | Connection lifetime at release                                                | `pool`                          |
| `sqp_backend_health`                   | gauge     | Backend health (1 healthy, 0 unhealthy)                                       | `pool`, `backend`               |
| `sqp_backend_connect_duration_seconds` | histogram | Backend connect time                                                          | `pool`, `backend`               |
| `sqp_backend_errors_total`             | counter   | Backend errors                                                                | `pool`, `backend`, `error_type` |

Sessions and transactions:

| Name                                     | Type      | Measures                                       | Labels               |
| ---------------------------------------- | --------- | ---------------------------------------------- | -------------------- |
| `sqp_sessions_active`                    | gauge     | Active client sessions                         | `protocol`           |
| `sqp_transactions_active`                | gauge     | Open transactions                              | `pool`               |
| `sqp_transaction_duration_seconds`       | histogram | Transaction duration at completion             | `pool`               |
| `sqp_transaction_idle_seconds`           | histogram | Idle time between queries inside a transaction | `pool`               |
| `sqp_transaction_abandoned_total`        | counter   | Clients that disconnected mid-transaction      | `pool`               |
| `sqp_session_replay_failures_total`      | counter   | Session-variable replay failures               | `pool`               |
| `sqp_session_auto_rollback_total`        | counter   | Automatic ROLLBACKs on session close           | `pool`               |
| `sqp_session_auto_rollback_failed_total` | counter   | Auto-ROLLBACKs that failed on the backend      | `pool`               |
| `sqp_auth_failures_total`                | counter   | Client authentication failures                 | `protocol`, `reason` |

Protocol layer:

| Name                                      | Type    | Measures                                       |
| ----------------------------------------- | ------- | ---------------------------------------------- |
| `sqp_postgres_connections_created_total`  | counter | PostgreSQL backend connections opened          |
| `sqp_postgres_connections_closed_total`   | counter | PostgreSQL backend connections closed          |
| `sqp_postgres_connections_reset_total`    | counter | PostgreSQL backend connections reset for reuse |
| `sqp_postgres_statements_prepared_total`  | counter | Statements prepared on PostgreSQL backends     |
| `sqp_postgres_execute_passthrough_total`  | counter | Executes forwarded via raw passthrough         |
| `sqp_mysql_connections_created_total`     | counter | MySQL backend connections opened               |
| `sqp_mysql_connections_closed_total`      | counter | MySQL backend connections closed               |
| `sqp_mysql_connections_reset_total`       | counter | MySQL backend connections reset for reuse      |
| `sqp_mysql_connections_recovered_total`   | counter | MySQL connections recovered after streaming    |
| `sqp_mysql_statements_prepared_total`     | counter | Statements prepared on MySQL backends          |
| `sqp_mysql_streaming_task_panics_total`   | counter | MySQL streaming tasks that panicked            |
| `sqp_mysql_streaming_tasks_aborted_total` | counter | MySQL streaming tasks aborted                  |

## Plugin chain metrics

Emitted by the Router's plugin chain for any registered plugin.

| Name                       | Type    | Measures                                                                        | Labels   |
| -------------------------- | ------- | ------------------------------------------------------------------------------- | -------- |
| `sqp_plugin_panic_total`   | counter | Plugin hooks that panicked (contained; the query proceeds per enforcement mode) | `plugin` |
| `sqp_plugin_timeout_total` | counter | Plugin hooks that exceeded their time budget                                    | `plugin` |

## Guard metrics

Emitted when [`[plugins.guard]`](/querypilot/reference/router-configuration#pluginsguard) is enabled.

| Name                                      | Type      | Measures                                                                                  | Labels                            |
| ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------- | --------------------------------- |
| `sqp_guard_decisions_total`               | counter   | Decisions by action (`allow`, `block`, `amend`, `reroute`)                                | `action`, `policy`, `trust_level` |
| `sqp_guard_decision_duration_seconds`     | histogram | Decision-pipeline latency                                                                 | `action`                          |
| `sqp_guard_amendments_total`              | counter   | Query amendments applied (`add_limit`, `add_timeout`, `force_read_only`)                  | `type`                            |
| `sqp_guard_unanalyzable_total`            | counter   | Statements Guard could not analyze; the alerting signal for `unanalyzable_action = "log"` | `source`                          |
| `sqp_guard_timeouts_total`                | counter   | Decisions that blew the latency cap and failed open                                       | none                              |
| `sqp_guard_panics_total`                  | counter   | Decision-pipeline panics (contained)                                                      | none                              |
| `sqp_guard_registry_hits_total`           | counter   | Trusted-query registry hits                                                               | none                              |
| `sqp_guard_registry_misses_total`         | counter   | Trusted-query registry misses                                                             | none                              |
| `sqp_guard_audit_dropped_total`           | counter   | Audit records dropped because the channel was full or closed                              | none                              |
| `sqp_guard_audit_file_writes_total`       | counter   | Audit records written by the file sink                                                    | none                              |
| `sqp_guard_audit_file_write_errors_total` | counter   | File-sink write failures (disk full, read-only mount)                                     | none                              |
| `sqp_guard_audit_file_flush_errors_total` | counter   | File-sink flush failures                                                                  | none                              |
| `sqp_guard_audit_serialize_errors_total`  | counter   | Audit records that failed to serialize                                                    | none                              |
| `sqp_guard_audit_sink_panics_total`       | counter   | Audit-sink panics (record dropped)                                                        | none                              |

## Accelerator metrics

Emitted when [`[plugins.accelerator]`](/querypilot/reference/router-configuration#pluginsaccelerator) is enabled. The stalest-gauge alert pattern: watch `time() - sqp_qp_last_success_timestamp_seconds`; a stalled or repeatedly failing discovery loop stops advancing it while the proxy keeps serving.

| Name                                    | Type      | Measures                                                                                                 | Labels   |
| --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------- | -------- |
| `sqp_qp_cycles_total`                   | counter   | Completed discovery cycles by result                                                                     | `result` |
| `sqp_qp_cycle_duration_seconds`         | histogram | Discovery-cycle wall-clock duration                                                                      | none     |
| `sqp_qp_errors_total`                   | counter   | Cycle-stage errors (fail-open), including `panic`                                                        | `stage`  |
| `sqp_qp_last_success_timestamp_seconds` | gauge     | Unix time of the last fully successful cycle                                                             | none     |
| `sqp_qp_candidates_total`               | counter   | Caching candidates surfaced by discovery                                                                 | none     |
| `sqp_qp_rules_added_total`              | counter   | Routing rules installed by the Accelerator                                                               | none     |
| `sqp_qp_rules_enabled_total`            | counter   | Rules enabled (for example after warmup)                                                                 | none     |
| `sqp_qp_rules_disabled_total`           | counter   | Rules disabled (for example on health failure)                                                           | none     |
| `sqp_qp_rules_dropped_total`            | counter   | Rules removed                                                                                            | none     |
| `sqp_qp_support_checks_total`           | counter   | Readyset support checks by outcome (`supported`, `unsupported`, `pending`, `cached`, `skipped`, `error`) | `status` |
| `sqp_qp_caches_created_total`           | counter   | Readyset caches created successfully                                                                     | none     |


# Router Configuration (/querypilot/reference/router-configuration)
import { Callout } from 'fumadocs-ui/components/callout';

## Overview

The Router (binary `querypilot`) is configured by a single TOML file, `querypilot.toml`. The Router locates it from, in order of precedence: the `--config` / `-c` flag, the `QUERYPILOT_CONFIG` environment variable, or `querypilot.toml` in the current working directory.

The schema is strict: unknown keys anywhere in the file are rejected at startup with a parse error, so typos fail loudly instead of being silently ignored. Duration values are humantime strings such as `"30s"`, `"10m"`, or `"750ms"`. Run `querypilot --check -c <path>` to validate a file without serving traffic.

Client authentication comes from pool credentials: clients authenticate with the `username` and `password` of a pool that defines them. If no pool defines credentials and [`allow_anonymous`](#allow_anonymous) is `false`, the Router refuses to start.

<Callout type="info">
  MySQL support is in preview. MySQL listeners, MySQL pools, and the MySQL-specific keys on this page are functional, but PostgreSQL is the supported GA v1 path.
</Callout>

## \[general]

Global proxy settings.

#### `worker_threads`

Number of Tokio worker threads. `0` means one thread per CPU core.

**Type:** integer
**Default:** `0`

#### `pool_mode`

When a backend connection is returned to the pool: at session end (`"session"`), at transaction end (`"transaction"`), or after each statement (`"statement"`). Individual pools can override this with [`mode`](#mode).

**Type:** string, one of `"session"`, `"transaction"`, `"statement"`
**Default:** `"transaction"`

#### `shutdown_timeout`

How long graceful shutdown waits for in-flight sessions before exiting.

**Type:** duration
**Default:** `"30s"`

#### `allow_anonymous`

Permit the Router to start with no client authentication on a non-loopback listener. Without configured pool credentials the Router accepts any client, so this is off by default and the Router refuses to boot in that situation. Leave `false` in production.

**Type:** bool
**Default:** `false`

```toml
[general]
pool_mode = "transaction"
shutdown_timeout = "30s"
worker_threads = 0
```

## \[\[listeners]]

Client-facing listeners. At least one is required.

#### `protocol`

Wire protocol served on this listener.

**Type:** string, one of `"postgres"`, `"mysql"`
**Default:** required, no default

#### `bind`

Address and port to listen on. The port must not be `0`, and no two listeners may share a bind address.

**Type:** socket address, for example `"0.0.0.0:6432"`
**Default:** required, no default

#### `tls_mode`

TLS posture for this listener. Any value other than `"disable"` requires a [`[tls]`](#tls) section to be present. The value is parsed and validated but not enforced in GA v1; see the [TLS section](#tls) below.

**Type:** string, one of `"disable"`, `"prefer"`, `"require"`
**Default:** `"disable"`

```toml
[[listeners]]
protocol = "postgres"
bind = "0.0.0.0:6432"

[[listeners]]
protocol = "mysql"
bind = "0.0.0.0:6433"
```

## \[pools.\<name>]

Named backend pools. Routing must resolve to an existing pool, so you need at least one.

#### `backends`

Backend servers in this pool. Non-empty array of inline tables; see [backend entries](#host) below.

**Type:** array of tables
**Default:** required, no default

#### `mode`

Per-pool override of [`general.pool_mode`](#pool_mode). Unset means inherit.

**Type:** string, one of `"session"`, `"transaction"`, `"statement"`
**Default:** unset

#### `protocol`

Force the backend wire protocol for this pool regardless of the client session's protocol. Useful for routing MySQL clients to a PostgreSQL-speaking backend. Incompatible with [`raw_passthrough`](#raw_passthrough).

**Type:** string, one of `"postgres"`, `"mysql"`
**Default:** unset (use the client session's protocol)

#### `username`

Backend login user. This also serves as the client-authentication credential: clients authenticate against the Router with pool credentials. Unset means pass through the client's credentials.

**Type:** string
**Default:** unset

#### `password`

Backend login password.

**Type:** string
**Default:** unset

#### `database`

Backend database override. Unset means use the client's database.

**Type:** string
**Default:** unset

#### `raw_passthrough`

Forward prepared-statement result rows from the backend to the client without decoding. Enable only when the backend is vanilla PostgreSQL whose wire encoding matches the client exactly. Leave off for any cross-protocol pool, where rows must be decoded and re-encoded. Rejected if a [`protocol`](#protocol-1) override is set on the same pool.

**Type:** bool
**Default:** `false`

#### `min_connections`

Connections kept open per backend. Must be less than or equal to `max_connections`.

**Type:** integer
**Default:** `1`

#### `max_connections`

Upper bound on pooled connections. At most `10000`.

**Type:** integer
**Default:** `10`

#### `acquire_timeout`

How long a session waits for a free backend connection before failing.

**Type:** duration, non-zero
**Default:** `"30s"`

#### `idle_timeout`

Idle backend connections above `min_connections` are closed after this.

**Type:** duration, non-zero
**Default:** `"600s"`

#### `connect_timeout`

TCP and startup timeout when dialing a backend.

**Type:** duration, non-zero
**Default:** `"10s"`

#### `query_timeout`

Per-query deadline for this pool. Unset means no deadline: a query only fails when the backend itself returns an error. Sessions may install a tighter per-query override (for example from an Guard `add_timeout` amendment).

**Type:** duration
**Default:** unset

#### `role`

Role used by read/write splitting.

**Type:** string, one of `"primary"`, `"replica"`
**Default:** `"primary"`

### Backend entries

Each element of `backends` is an inline table with these keys.

#### `host`

Backend hostname or IP. Required, non-empty.

**Type:** string
**Default:** required, no default

#### `port`

Backend port. Must not be `0`.

**Type:** integer
**Default:** `5432`

#### `weight`

Load-balancing weight. Parsed and validated, but not applied in GA v1: backend selection is round-robin.

**Type:** integer, non-zero
**Default:** `1`

#### `max_replica_lag`

Skip this backend when its measured replication lag exceeds the threshold. Unset disables the lag check.

**Type:** duration
**Default:** unset

```toml
[pools.primary]
role = "primary"
min_connections = 2
max_connections = 50
backends = [
    { host = "primary.db.local", port = 5432 }
]

[pools.replica]
role = "replica"
max_connections = 25
backends = [
    { host = "replica1.db.local", port = 5432 },
    { host = "replica2.db.local", port = 5432, max_replica_lag = "10s" }
]
```

## \[routing]

How the Router picks a pool for each query. See the [read/write split tutorial](/demos/querypilot/read-write-split) for a worked example.

#### `read_write_split`

Route reads and writes to different pools automatically. When `true`, `read_pool` and `write_pool` must exist in `[pools]`; when `false`, `default_pool` must exist.

**Type:** bool
**Default:** `false`

#### `read_pool`

Pool for read queries when splitting is enabled.

**Type:** string
**Default:** `"replica"`

#### `write_pool`

Pool for write queries when splitting is enabled.

**Type:** string
**Default:** `"primary"`

#### `default_pool`

Pool used when splitting is off and no rule matches.

**Type:** string
**Default:** `"primary"`

#### `mysql_default_pool`

Default pool for connections that arrived on a MySQL listener. When set, queries on a MySQL listener that match no content rules fall back to this pool instead of `default_pool`. This lets you route by listener identity without writing a content rule for every plain MySQL query. MySQL support is in preview.

**Type:** string
**Default:** unset

```toml
[routing]
read_write_split = true
read_pool = "replica"
write_pool = "primary"
default_pool = "primary"
```

### \[\[routing.rules]]

Regex-based routing rules. Each rule needs exactly one action: `pool` or `reject`.

#### `name`

Rule name for logs and metrics. Required, non-empty.

**Type:** string
**Default:** required, no default

#### `match_user`

Regex matched against the session user. Must compile.

**Type:** string (regex)
**Default:** unset

#### `match_database`

Regex matched against the session database. Must compile.

**Type:** string (regex)
**Default:** unset

#### `match_query`

Regex matched against the query text. Must compile.

**Type:** string (regex)
**Default:** unset

#### `match_listener_protocol`

Restrict the rule to connections that arrived on a listener speaking this protocol. Omit to apply the rule on all listeners.

**Type:** string, one of `"postgres"`, `"mysql"`
**Default:** unset

#### `pool`

Route matching queries to this pool. The pool must exist. Exactly one of `pool` or `reject` is required.

**Type:** string
**Default:** unset

#### `reject`

Reject matching queries with this error message. Exactly one of `pool` or `reject` is required.

**Type:** string
**Default:** unset

#### `priority`

Evaluation order; lower numbers run first.

**Type:** integer
**Default:** `0`

```toml
[[routing.rules]]
name = "admin_to_primary"
match_user = "^admin$"
pool = "primary"
priority = 0

[[routing.rules]]
name = "block_dangerous"
match_query = "(?i)DROP|TRUNCATE"
reject = "Dangerous query blocked by proxy"
priority = -1
```

### \[\[routing.pattern\_rules]]

Pattern rules match on normalized query shape rather than raw text. They are evaluated after translation rules and before regex rules.

#### `type`

How `pattern` is interpreted: `"template"` treats it as a normalized example query, `"regex"` as a regular expression over the query text, and `"hash"` as a query fingerprint hash written as a decimal 64-bit integer. Fingerprint hashes can be obtained from `GET /api/routing/test` on the [admin API](/querypilot/reference/admin-api#get-apiroutingtest).

**Type:** string, one of `"template"`, `"regex"`, `"hash"`
**Default:** required, no default

#### `pattern`

The pattern to match. For `type = "regex"`, must compile.

**Type:** string
**Default:** required, no default

Pattern rules also take `name` (required), `pool` or `reject` (exactly one required), and `priority` (default `0`) with the same semantics as regex rules above.

```toml
[[routing.pattern_rules]]
name = "analytics_to_olap"
type = "regex"
pattern = "(?i)FROM analytics_"
pool = "analytics"
priority = 0

[[routing.pattern_rules]]
name = "user_lookup"
type = "template"
pattern = "SELECT * FROM users WHERE id = 123"
pool = "replica"
priority = 10
```

### \[routing.cache]

Routing-decision cache settings.

#### `enabled`

Cache routing decisions per normalized query.

**Type:** bool
**Default:** `true`

#### `max_size`

Maximum cached entries.

**Type:** integer
**Default:** `10000`

#### `normalization_strategy`

How queries are normalized into cache keys: `"string"` is faster, `"ast"` is more accurate, `"auto"` chooses per query.

**Type:** string, one of `"auto"`, `"ast"`, `"string"`
**Default:** `"string"`

## \[translation]

Translation rules rewrite a query to different SQL text and pin it to a pool, typically to redirect specific queries to an analytics backend with a different schema layout. Literal values are parameterized on both sides and substituted at query time. On config reload, all translations are cleared and re-registered from the file; translations registered at runtime via the [admin API](/querypilot/reference/admin-api#translations) are ephemeral.

### \[\[translation.rules]]

#### `original_sql`

Concrete example of the incoming query, with literal values. Required, non-empty.

**Type:** string
**Default:** required, no default

#### `translated_sql`

Concrete rewritten query to execute instead. Required, non-empty.

**Type:** string
**Default:** required, no default

#### `target_pool`

Pool the translated query runs on. Must exist in `[pools]`.

**Type:** string
**Default:** required, no default

```toml
[[translation.rules]]
original_sql = "SELECT name, email FROM customers WHERE customer_id = 123"
translated_sql = "SELECT name, email FROM analytics.customers WHERE customer_id = 123"
target_pool = "analytics"
```

## \[tls]

Required if any listener sets `tls_mode` to `"prefer"` or `"require"`.

<Callout type="warn">
  The `[tls]` schema parses and is validated at startup, but the Router does not terminate TLS in GA v1. Client connections are accepted in cleartext regardless of `tls_mode`, and backend connections are dialed without TLS. Terminate TLS in front of the Router with a load balancer or sidecar. See [Security](/querypilot/security).
</Callout>

#### `cert_file`

Server certificate in PEM format. The file must exist at startup.

**Type:** string (path)
**Default:** required if the section is present

#### `key_file`

Private key in PEM format. The file must exist at startup.

**Type:** string (path)
**Default:** required if the section is present

#### `ca_file`

CA bundle for client-certificate verification. If set, the file must exist.

**Type:** string (path)
**Default:** unset

## \[metrics]

#### `enabled`

Serve Prometheus metrics (the `sqp_*` series; see the [metrics reference](/querypilot/reference/metrics)). Enabling metrics also starts the [admin API](/querypilot/reference/admin-api).

**Type:** bool
**Default:** `false`

#### `bind`

Metrics listen address. The default is loopback by design to keep the management surface off public networks.

**Type:** socket address
**Default:** `"127.0.0.1:9090"`

```toml
[metrics]
enabled = true
bind = "127.0.0.1:9090"
```

<Callout type="warn">
  The admin API address is derived from this section, not configured separately: it listens on the `bind` IP at the `bind` port plus one (9090 gives 9091). Binding metrics to `0.0.0.0` therefore also exposes the mutating admin surface on all interfaces. Set `api_key` on the plugin blocks where available, and firewall both ports. If the metrics port is 65535, startup fails with a port-overflow error.
</Callout>

## \[logging]

#### `level`

Log verbosity. This key accepts only the five listed levels. The `--log-level` flag and `QUERYPILOT_LOG_LEVEL` environment variable override it at launch and accept richer tracing filter directives; see [environment variables](/querypilot/reference/environment-variables#querypilot_log_level).

**Type:** string, one of `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`
**Default:** `"info"`

#### `format`

Human-readable or structured JSON output.

**Type:** string, one of `"pretty"`, `"json"`
**Default:** `"pretty"`

## \[stats]

Per-query digest statistics, the data source for `GET /api/stats/digests` and Accelerator discovery.

#### `max_entries`

Maximum retained per-query statistics entries (distinct query fingerprints). New fingerprints arriving after the cap are dropped and counted into an overflow metric. Must be less than `65535` when `[plugins.accelerator]` is present and enabled.

**Type:** integer
**Default:** `10000`

## \[plugins.guard]

Configuration for Guard, the query-governance plugin. Guard has no standalone config file; this block is its entire operator surface. It additionally reads runtime artifacts pointed to by config: YAML policy files (`policy_dir`) and a YAML trusted-query registry (`registry_file`). See [Guard](/querypilot/guard) and the [policies tutorial](/demos/querypilot/guard-policies).

#### `enabled`

Turn Guard on. When `false`, nothing is registered and the section is inert.

**Type:** bool
**Default:** `false`

#### `default_trust_level`

Trust level assigned to sessions no trust rule matches.

**Type:** string, one of `"untrusted"`, `"verified"`, `"established"`, `"privileged"`
**Default:** unset (falls back to `"verified"`)

#### `policy_dir`

Directory of YAML policy files. Paths containing `..` are rejected.

**Type:** string (path)
**Default:** unset (no policies loaded)

#### `registry_file`

Trusted-query registry file, YAML. Paths containing `..` are rejected.

**Type:** string (path)
**Default:** unset

#### `notify_on_amend`

Emit a client notice when Guard amends a query.

**Type:** bool
**Default:** `true`

#### `unanalyzable_action`

What to do with a statement Guard cannot structurally analyze (parse failure, size or nesting cap, decision timeout) whose coarse type is not a plain read, for sessions below `privileged`. `"log"` allows the query but logs a warning and increments `sqp_guard_unanalyzable_total`; `"block"` is the strict posture; `"allow"` silences the signal.

**Type:** string, one of `"allow"`, `"log"`, `"block"`
**Default:** `"log"`

#### `enforcement_mode`

Whether decisions are applied (`"enforce"`), surfaced as warnings without blocking (`"warn"`), evaluated but discarded (`"shadow"`, useful for canarying a policy), or skipped entirely (`"off"`).

**Type:** string, one of `"off"`, `"shadow"`, `"warn"`, `"enforce"`
**Default:** `"enforce"`

#### `audit_sink`

Where audit records go, as a tagged inline table. `type = "stdout"` writes one JSON line per record to stdout (suited to container deployments shipping logs via a sidecar). `type = "file"` requires a `path` and appends JSONL to it; the file is created with mode `0640` on Unix, and OS log rotation handles size. These are the only two supported sink types.

**Type:** inline table, `{ type = "stdout" }` or `{ type = "file", path = "..." }`
**Default:** `{ type = "stdout" }`

#### `max_decision_latency_ms`

Per-decision time budget in milliseconds. Beyond this, Guard fails open with Allow and increments `sqp_guard_timeouts_total`.

**Type:** integer
**Default:** unset (falls back to `50`)

#### `max_registry_size`

Maximum trusted-query registry entries.

**Type:** integer
**Default:** unset (falls back to `100000`)

#### `audit_buffer_size`

In-memory audit ring-buffer capacity, in records.

**Type:** integer
**Default:** unset (falls back to `10000`)

#### `audit_channel_size`

Audit channel depth between the producer and the drain task.

**Type:** integer
**Default:** unset (falls back to `4096`)

#### `api_key`

Key required by Guard's mutating REST endpoints (sent as the `X-Guard-Api-Key` header). Unset leaves them open, which is acceptable only for loopback development. See the [admin API](/querypilot/reference/admin-api#guard-plugin-api).

**Type:** string
**Default:** unset

#### `trust_rules`

Per-session trust assignment rules, as `[[plugins.guard.trust_rules]]` tables. Rules are applied in declaration order; the last matching rule wins.

**Type:** array of tables
**Default:** `[]`

Each trust rule takes:

#### `match`

Inline table of conditions; all present fields must match. `match.role` is a glob against the session role (for example `"service-*"`), `match.username` is an exact username, `match.origin` is an exact client IP. An empty table matches every session.

**Type:** inline table
**Default:** `{}`

#### `set_level`

Trust level to assign on match. Same values as [`default_trust_level`](#default_trust_level). Required.

**Type:** string
**Default:** required, no default

#### `reason`

Free-form note recorded in the audit log.

**Type:** string
**Default:** unset

```toml
[plugins.guard]
enabled = true
policy_dir = "/etc/querypilot/guard-policies"
registry_file = "/var/lib/querypilot/guard-registry.yaml"
enforcement_mode = "enforce"
audit_sink = { type = "file", path = "/var/log/querypilot/guard-audit.jsonl" }
api_key = "<your-api-key>"

[[plugins.guard.trust_rules]]
match = { role = "service-*" }
set_level = "established"
reason = "internal service accounts"
```

## \[plugins.accelerator]

Configuration for the Accelerator, the caching plugin that discovers hot queries and manages Readyset caches. `[plugins.accelerator]` is the Accelerator's config block. The block is validated at boot only when `enabled = true`. See [Accelerator](/querypilot/accelerator) and the [caching tutorial](/demos/querypilot/accelerator-caching).

#### `enabled`

Turn the Accelerator on. When `false`, nothing is registered and the plugin incurs no per-query or background cost.

**Type:** bool
**Default:** `false`

#### `interval_s`

Seconds between Accelerator discovery cycles. Must be at least `1`.

**Type:** integer
**Default:** `10`

#### `dry_run`

Log caching decisions without creating caches or mutating rules.

**Type:** bool
**Default:** `false`

#### `database`

Wire protocol of the Readyset endpoints. MySQL support is in preview.

**Type:** string, one of `"postgresql"`, `"mysql"`
**Default:** `"postgresql"`

#### `denylist_path`

File listing queries never to cache.

**Type:** string (path)
**Default:** unset (falls back to `/etc/readyset_query_pilot_denylist`)

#### `readyset_servers`

Readyset SQL endpoints the Accelerator connects to for support checks and `CREATE CACHE`, as an array of `{ host, port }` tables. The plugin needs at least one to do useful work.

**Type:** array of `{ host, port }`
**Default:** `[]`

#### `readyset_user`

User for connecting to Readyset.

**Type:** string
**Default:** `""`

#### `readyset_password`

Password for Readyset.

**Type:** string
**Default:** `""`

#### `readyset_database`

Database or schema on the Readyset side, when applicable.

**Type:** string
**Default:** unset

#### `min_execution`

Minimum execution count before a query shape is a caching candidate.

**Type:** integer
**Default:** `1`

#### `wait_s`

Discovery warmup: a query shape must have been observable for at least this many seconds before it is a candidate.

**Type:** integer
**Default:** `0`

#### `warmup_time_s`

Rule warmup window in seconds. When greater than `0`, a new rule is installed disabled and enabled after the window (mirror first, then serve). `0` enables rules immediately.

**Type:** integer
**Default:** `0`

#### `api_key`

Key required by the Accelerator's mutating REST endpoints (sent as the `X-QueryPilot-Api-Key` header). When unset and the admin API binds a non-loopback address, the mutating surface refuses to serve. See the [admin API](/querypilot/reference/admin-api#accelerator-plugin-api).

**Type:** string
**Default:** unset

### \[plugins.accelerator.grants]

The operator's least-privilege contract for the plugin: what the Accelerator is allowed to touch.

#### `pools`

Pools the Accelerator may write routing rules for. Must list at least one pool when the plugin is enabled; an empty grant is rejected at boot.

**Type:** array of strings
**Default:** `[]`

#### `max_owned_rules`

Cap on routing rules the plugin may own at once. Must be at least `1` when set; `0` is rejected at boot because it would refuse every rule.

**Type:** integer
**Default:** unset (unlimited)

```toml
[plugins.accelerator]
enabled = true
interval_s = 10
database = "postgresql"
readyset_servers = [{ host = "readyset.internal", port = 5433 }]
readyset_user = "rs_user"
readyset_password = "<your-password>"
warmup_time_s = 60
api_key = "<your-api-key>"

[plugins.accelerator.grants]
pools = ["readyset"]
max_owned_rules = 100
```

{/* source: verified against code @ 2026-07-18 */}


# Router (/querypilot/router)
import { Callout } from 'fumadocs-ui/components/callout'

## What the Router does

The Router (binary `querypilot`) is QueryPilot's SQL proxy and the only mandatory component of the platform. It terminates PostgreSQL and MySQL wire-protocol connections, pools connections to backend databases, and decides per query which pool a statement runs on, optionally rewriting it on the way. This page covers pooling, routing, translation, prepared statements, and shutdown behavior. The key-by-key schema of `querypilot.toml` lives in the [Router configuration reference](/querypilot/reference/router-configuration).

<Callout type="info">
  MySQL support is in preview. MySQL proxying works and is documented here, but PostgreSQL is the fully supported GA v1 path.
</Callout>

The Router loads its configuration from `--config` / `-c`, the `QUERYPILOT_CONFIG` environment variable, or `querypilot.toml` in the current directory, in that order. Validate a file without starting the proxy:

```bash
querypilot --check -c querypilot.toml
```

Unknown keys anywhere in the file are rejected at startup, so typos fail loudly instead of silently using a default.

## Listeners and wire protocols

Each `[[listeners]]` entry binds one address and speaks one protocol:

```toml
[[listeners]]
protocol = "postgres"
bind = "0.0.0.0:6432"

[[listeners]]
protocol = "mysql"
bind = "0.0.0.0:6433"
```

Clients connect with unmodified drivers; no application changes are required. The Router authenticates clients against pool credentials, so avoid exposing a listener without credentials configured (startup refuses this combination on non-loopback binds unless you explicitly opt in with [`allow_anonymous`](/querypilot/reference/router-configuration#allow_anonymous)).

The Router does not terminate TLS. Terminate TLS in front of the Router (load balancer, mTLS sidecar, or tunnel) and keep listeners on trusted network segments. See [Security](/querypilot/security).

## Connection pooling

Backend connections live in named `[pools.<name>]` sections. Each pool has its own backends, credentials, protocol, sizing, and timeouts; a client session borrows a connection from whichever pool the routing decision selects.

### Pooling modes

[`general.pool_mode`](/querypilot/reference/router-configuration#pool_mode) sets the default; [`pools.<name>.mode`](/querypilot/reference/router-configuration#mode) overrides it per pool. The mode controls when a borrowed backend connection returns to the pool:

| Mode                    | Connection returned         | Trade-off                                                                                                                             |
| ----------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `session`               | when the client disconnects | Backend session state (temp tables, `SET` variables) survives the whole client session; lowest sharing.                               |
| `transaction` (default) | at `COMMIT` / `ROLLBACK`    | Statements inside a transaction stay on one backend connection; different transactions from one client may run on different backends. |
| `statement`             | after every statement       | Maximum sharing; no cross-statement backend state.                                                                                    |

In every mode, statements inside an open transaction are pinned: the routing engine reuses the connection the transaction started on before any rule is evaluated.

### Per-pool overrides

A pool can override what the client session would otherwise supply:

```toml
[pools.analytics]
mode = "transaction"
protocol = "postgres"        # backend wire protocol, regardless of client protocol
username = "analytics_user"  # backend credentials, regardless of client credentials
password = "<your-password>"
database = "analytics"
backends = [
    { host = "replica1.db.local", port = 5432, weight = 2 },
    { host = "replica2.db.local", port = 5432, weight = 1, max_replica_lag = "10s" },
]
```

* [`protocol`](/querypilot/reference/router-configuration#protocol) forces the backend wire protocol. See [Cross-protocol pools](#cross-protocol-pools-and-raw_passthrough).
* [`username`](/querypilot/reference/router-configuration#username), [`password`](/querypilot/reference/router-configuration#password), and [`database`](/querypilot/reference/router-configuration#database) replace the client's credentials on backend connections.
* Each backend entry accepts a [`weight`](/querypilot/reference/router-configuration#weight) key (validated to be non-zero), but the current release opens new connections round-robin across healthy backends; weights do not yet bias the selection.
* A backend with [`max_replica_lag`](/querypilot/reference/router-configuration#max_replica_lag) set is marked unhealthy, and skipped, whenever its measured replication lag exceeds the threshold. It returns automatically when the lag recovers.

### Sizing and timeouts

Per pool: [`min_connections`](/querypilot/reference/router-configuration#min_connections) (default 1), [`max_connections`](/querypilot/reference/router-configuration#max_connections) (default 10), [`acquire_timeout`](/querypilot/reference/router-configuration#acquire_timeout) (default 30s), [`idle_timeout`](/querypilot/reference/router-configuration#idle_timeout) (default 600s), [`connect_timeout`](/querypilot/reference/router-configuration#connect_timeout) (default 10s), and optional [`query_timeout`](/querypilot/reference/router-configuration#query_timeout) (unset by default; no per-query deadline).

Sessions that cannot get a connection within `acquire_timeout` receive an error rather than queueing forever. Under load, watch `sqp_pool_queue_depth`, `sqp_pool_wait_duration_seconds`, and `sqp_pool_timeouts_total`: sustained queue depth with utilization near 1.0 means the cap is too low or the backend is the real limit. In `transaction` mode, size `max_connections` against concurrent transactions, not client count. See the [metrics reference](/querypilot/reference/metrics).

## Cross-protocol pools and raw\_passthrough

Setting `protocol` on a pool lets a client on one protocol be served from a backend speaking another, for example a MySQL client reading from a PostgreSQL backend. The Router decodes result rows from the backend protocol and re-encodes them for the client.

[`raw_passthrough = true`](/querypilot/reference/router-configuration#raw_passthrough) skips that decode/re-encode step for prepared-statement results and streams the backend's bytes to the client unchanged. It is only correct when both sides speak identical encodings, meaning a vanilla PostgreSQL client talking to a vanilla PostgreSQL backend, and is therefore rejected in combination with a `protocol` override. When a statement cannot be passed through (DDL, session commands), the Router falls back to the decoded path for that statement. Leave it off for any cross-protocol pool.

## The routing decision

For every statement, the routing engine walks these steps in order and stops at the first one that produces a decision:

1. **Transaction pinning.** Inside a transaction, reuse the pinned backend connection. Nothing else is evaluated.
2. **Translation rules.** The query is parameterized (literals lifted out) and its pattern hash is looked up in the translation registry. On a hit, the stored rewritten SQL is filled in with the incoming literal values and sent to the translation's `target_pool`.
3. **Dynamic pattern rules.** Rules registered at runtime, through `POST /api/pattern-rules` or by the Accelerator, matched against the query's normalized fingerprint.
4. **Routing-decision cache.** If an identical query shape was routed before and [`routing.cache`](/querypilot/reference/router-configuration#routingcache) is enabled (it is by default), the cached decision is reused.
5. **Pattern rules** (`[[routing.pattern_rules]]`), in ascending `priority` order, first match wins.
6. **Regex rules** (`[[routing.rules]]`), in ascending `priority` order, first match wins. These can also match on session user, database, and listener protocol.
7. **Read/write split or default pool.** With [`read_write_split = true`](/querypilot/reference/router-configuration#read_write_split), reads go to [`read_pool`](/querypilot/reference/router-configuration#read_pool) and everything else to [`write_pool`](/querypilot/reference/router-configuration#write_pool). Otherwise the query goes to [`default_pool`](/querypilot/reference/router-configuration#default_pool). Connections that arrived on a MySQL listener fall back to [`mysql_default_pool`](/querypilot/reference/router-configuration#mysql_default_pool) when it is set.

Rule-based and default decisions are cached per query fingerprint (translation and dynamic-rule hits are not); the cache is invalidated on config reload and rule changes. A matched rule either names a `pool` or names a `reject` message returned to the client as an error.

Dry-run any query without sending traffic:

```bash
curl "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20users%20WHERE%20id%20=%201"
```

The response includes the decision, target pool, fingerprint hash, and matched rule.

### Read/write classification

Classification looks at the first keyword after leading comments, with refinements:

| Statement                                             | Class                                                                       |
| ----------------------------------------------------- | --------------------------------------------------------------------------- |
| `SELECT`                                              | read, unless it contains `FOR UPDATE` / `FOR SHARE`, which makes it a write |
| `WITH ...`                                            | read, unless the CTE body contains `INSERT` / `UPDATE` / `DELETE`           |
| `SHOW`, `EXPLAIN`, `DESCRIBE`                         | read                                                                        |
| `COPY ... TO`                                         | read; `COPY ... FROM` is a write                                            |
| `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `UPSERT`       | write                                                                       |
| DDL (`CREATE`, `DROP`, `ALTER`, `TRUNCATE`, `RENAME`) | DDL                                                                         |
| `GRANT`, `REVOKE`, `VACUUM`, `ANALYZE`                | admin                                                                       |
| anything unrecognized                                 | unknown                                                                     |

Under read/write splitting, only reads go to `read_pool`. Writes, DDL, admin, and unknown statements all go to `write_pool`: when in doubt, the Router routes to the primary rather than risk a write on a replica. A worked setup is in the [read/write split tutorial](/demos/querypilot/read-write-split).

## Pattern rules and query normalization

Pattern rules match a query by shape rather than raw text. Three types exist:

* **`template`**: you write a concrete example query; the Router normalizes it into a fingerprint and matches any query with the same shape, regardless of literal values. The recommended type for routing specific query shapes.
* **`regex`**: a regular expression evaluated against the raw query text. Most flexible, slowest; good for keyword- or table-based routing.
* **`hash`**: a precomputed fingerprint hash (decimal u64), matched by equality. Fastest; obtain the hash from `GET /api/routing/test?sql=...`.

```toml
[[routing.pattern_rules]]
name = "order_lookups_to_replica"
type = "template"
pattern = "SELECT * FROM orders WHERE user_id = 42"
pool = "replica"
priority = 10

[[routing.pattern_rules]]
name = "analytics_tables"
type = "regex"
pattern = "(?i)FROM analytics_"
pool = "analytics"
priority = 20
```

Any literal value matches a `template` rule: the example is normalized, so `user_id = 7` hits the rule created from the `= 42` example. Rules added at runtime via `POST /api/pattern-rules` are ephemeral and cleared on config reload; put durable rules in the file.

Normalization replaces literals (numbers, strings, booleans, `NULL`) with placeholders and hashes the result. [`routing.cache.normalization_strategy`](/querypilot/reference/router-configuration#normalization_strategy) selects how:

* `string` (default): regex-based literal replacement; fast and dialect-agnostic.
* `ast`: parses the SQL and rewrites literals in the syntax tree; more precise, several times slower, and currently applied to `SELECT` statements only.
* `auto`: tries AST, silently falls back to string when parsing fails.

Statements the AST strategy does not cover (including all non-`SELECT` statements) always use string normalization.

## Query translation

Translation rules go one step further than routing: they replace the query's SQL and pin it to a pool. The canonical use is redirecting specific hot queries to a backend whose SQL dialect differs from the source, rewriting a function call the target does not support into its equivalent.

A rule is three strings: a concrete `original_sql` example, the `translated_sql` to run instead, and the `target_pool`:

```toml
[[translation.rules]]
original_sql = "SELECT id FROM tags WHERE JSON_OVERLAPS(labels, '[1,2]')"
translated_sql = "SELECT id FROM tags WHERE list_has_any(labels, [1,2])"
target_pool = "analytics"
```

At registration time both sides are parameterized and the literal positions are matched up. At query time, any incoming query with the same shape as `original_sql`, with any literal values including `IN` lists of any length, is rewritten by substituting its actual literals into the translated pattern and sent to the target pool.

Translations come from two places with different lifetimes: `[[translation.rules]]` in `querypilot.toml` is re-registered from the file on every config reload; `POST /api/translations` at runtime is ephemeral, and a config reload clears it.

## Prepared statements

The Router supports the PostgreSQL extended protocol and MySQL prepared statements end to end, including binary result formats. Prepared statements are tracked per client session under their original SQL, so execute-time routing (including translation rules) still applies. Because pooling means the backend connection under a session can change between executes, the Router transparently re-prepares a statement on the backend it acquires when needed; clients never see the difference. When a translation rule matches a prepared statement, the rewritten SQL is what gets prepared on the target pool's backend.

## Graceful shutdown

On `SIGTERM` or `SIGINT`, the Router stops accepting new connections, keeps serving active sessions while they drain, and then force-closes any connections still open after a bounded drain window. In-flight statements on drained sessions complete normally; plan rolling restarts so long-running transactions finish first or accept that stragglers are cut at the deadline. See [Operations](/querypilot/operations) for deployment patterns.

## Metrics and the admin API

With `[metrics] enabled = true`, the Router serves Prometheus metrics on [`metrics.bind`](/querypilot/reference/router-configuration#bind) (default port 9090) and a REST admin API on the same IP at the metrics port plus one (9090 gives 9091). The admin API manages translations, dynamic pattern rules, pool status, config reload, and per-query-shape execution statistics (`GET /api/stats/digests`); the full surface is in the [admin API reference](/querypilot/reference/admin-api).

Plugin REST surfaces mount on the same listener: `/api/v1/plugins/accelerator` for the [Accelerator](/querypilot/accelerator) and `/api/v1/plugins/guard` for [Guard](/querypilot/guard).

Routing and pooling export Prometheus series under the `sqp_` prefix, notably `sqp_routing_decisions_total` (labeled by decision type and target pool), `sqp_routing_cache_operations_total`, `sqp_pool_connections`, `sqp_pool_acquire_total`, `sqp_pool_queue_depth`, and `sqp_pool_timeouts_total`. `GET /api/routing/test` is the fastest way to answer "where would this query go and why" without sending traffic. See the [metrics reference](/querypilot/reference/metrics).

{/* source: verified against code @ 2026-07-18 */}


# Security (/querypilot/security)
import { Callout } from 'fumadocs-ui/components/callout';

This page describes how to deploy QueryPilot components safely, and equally what the current release does not protect against. The Router is the SQL proxy (binary `querypilot`), the Accelerator is the caching plugin, and Guard is the policy plugin.

**QueryPilot is designed to run on trusted networks.** Management surfaces default to loopback, non-loopback exposure requires explicit opt-ins, and wire encryption is not available in this release. Treat the network between clients, the Router, and backends as part of your security boundary.

## Client authentication

**Pool credentials double as client credentials.** There is no dedicated client-auth section and no per-user credential passthrough in GA v1. Clients must authenticate with the `username`/`password` of the first pool that defines them, and the Router then uses those same credentials to log into the backend. One secret, two jobs: anyone who can authenticate to the Router acts as that backend user, and rotating the backend password simultaneously rotates what every client must present.

Mechanisms per protocol:

* PostgreSQL listeners authenticate clients with SCRAM-SHA-256, so the password itself does not cross the wire during authentication. Without TLS, the queries and results after authentication do.
* MySQL listeners authenticate clients with `mysql_native_password`.

<Callout type="info">
  MySQL support, including the MySQL listener path, is in preview. PostgreSQL is the fully supported GA path.
</Callout>

Client auth failures are observable via `sqp_auth_failures_total` (labeled by `protocol` and `reason`).

## The open-proxy guard

If no pool defines credentials, the Router accepts any client credentials. In that state, a listener on a non-loopback address would be an open proxy: any client that can reach the port gets a connection to your backend with the pool's identity. The Router therefore refuses to start when an unauthenticated listener binds a non-loopback address, unless you explicitly set [`allow_anonymous = true`](/querypilot/reference/router-configuration#allow_anonymous) under `[general]`.

`allow_anonymous = true` exists for loopback development and for deployments where the network layer itself is the access control (a dedicated compose network, Kubernetes NetworkPolicy, security groups). The tradeoff is exactly what the name says: authentication is off, and reachability equals access. Leave it `false` in production and put credentials on your pools instead.

## TLS status

<Callout type="warning">
  **The Router does not terminate TLS in GA v1.** The `[tls]` config section (`cert_file`, `key_file`, `ca_file`) and the per-listener `tls_mode` parse and validate, but they are not wired to the listeners: client sessions run over plaintext TCP regardless of `tls_mode`. Backend connections to PostgreSQL and MySQL are also cleartext; there is no backend TLS configuration. Run QueryPilot on trusted network segments only.
</Callout>

Until wire TLS ships, put the Router in the same trust domain as its clients and backends: the same host (loopback), a private network segment, a VPN or service mesh that encrypts at the network layer, or SSH tunnels. One caution when reaching for a fronting proxy or load balancer to terminate TLS: PostgreSQL and MySQL negotiate TLS inside their own protocols rather than as a raw TLS socket, so a generic TLS terminator does not work for database clients that expect in-protocol negotiation. Network-layer encryption (mesh, VPN, tunnel) is the reliable pattern.

On the client-facing PostgreSQL path, wire-protocol input parsing is hardened against malformed frames: message length is capped at 256 MiB and attacker-controlled length prefixes are bounds-checked rather than trusted.

## Admin API and management surfaces

The Router's core admin API (`/api/translations`, `/api/config/*`, `/api/pattern-rules`, `/api/pools`, `/api/routing/test`, `/api/stats/digests`) is **unauthenticated**. It is safe only because it defaults to loopback: the admin API always binds the metrics IP at the metrics port + 1 (`127.0.0.1:9091` by default). Treat "admin API reachable" as equivalent to "control over the proxy's routing". Two consequences:

* **Widening `metrics.bind` to `0.0.0.0` for Prometheus also exposes the mutating admin API.** There is no way to expose one without the other. Firewall both ports and set the plugin `api_key`s before doing this.
* Bind metrics to loopback or a private management network, never a client-reachable interface.

Plugin routes on the same port carry their own bearer keys:

* **Accelerator** (`/api/v1/plugins/accelerator/*`): mutating endpoints require the `X-QueryPilot-Api-Key` header, compared in constant time. When the admin API binds a non-loopback address and no `plugins.accelerator.api_key` is set, the mutating endpoints refuse to serve (403), and unauthenticated reads redact query text.
* **Guard** (`/api/v1/plugins/guard/*`): mutating endpoints require `X-Guard-Api-Key` when `plugins.guard.api_key` is set. Plan around two caveats: with no `api_key` set the mutating endpoints are open (acceptable only on loopback), and `POST /test`, which runs the policy engine against arbitrary SQL, does not require the key even when one is set. The key comparison is also a plain string compare rather than constant-time. Keep the guard surface loopback-only or behind an authenticating reverse proxy.

Set both `api_key`s whenever the metrics/admin bind is anything other than `127.0.0.1`. See the [admin API reference](/querypilot/reference/admin-api).

## Guard: what it protects against

Frame Guard as protection against accidents and misbehaving tools (an agent issuing a `DELETE` without a `WHERE`, a migration script touching the wrong table), not as a hard boundary against a motivated adversary.

The default is fail-open on unanalyzable statements: `unanalyzable_action = "log"` allows statements the analyzer cannot classify, emitting a throttled warning and incrementing `sqp_guard_unanalyzable_total`. A determined client below the `privileged` trust level can construct statements that are unanalyzable on purpose. If you need enforcement rather than observability, fail closed: set `unanalyzable_action = "block"`, or deploy a policy matching the `Unanalyzable` risk factor. Whichever you choose, alert on `sqp_guard_unanalyzable_total`; it is the observability control for the fail-open path.

Two further limitations to plan around in this release: trust rules matching on `origin` never fire (the client's network address is not threaded into the session context; match on `username` or `role` instead), and the guard API caveats described above. In enforce mode, Guard fails closed on analyzer panics.

Every Guard decision is written to the configured `audit_sink`: `{ type = "stdout" }` (default) or `{ type = "file", path = "..." }`, one JSON record per line. Audit files are created with mode `0640`, and records are fingerprint-only: they carry the query fingerprint, username, trust level, coarse query type, tables, action, policy name, reason, amendments, and decision latency, never raw SQL text or literal values, so the audit log cannot leak query contents. The pipeline is observable; `sqp_guard_audit_dropped_total` counts records lost to backpressure. See [Guard](/querypilot/guard) and the [policies tutorial](/demos/querypilot/guard-policies).

## Secrets in configuration files

QueryPilot configs contain live credentials in plaintext TOML: pool `username`/`password` in `querypilot.toml` and plugin `api_key`s. There is no built-in secret-manager integration, so protect the files themselves:

* `chmod 600` every config file and have the service user own it.
* In Kubernetes, mount configs from `Secret` objects rather than ConfigMaps when they carry passwords. The provided manifests template credentials in from a Secret at pod start.
* Keep configs out of world-readable images and repositories; template credentials in at deploy time.
* `GET /api/config/status` reports the config path, not its contents, but anyone with admin-API access can trigger a reload of whatever is on disk.

The standalone Accelerator additionally requires `https` plus an API token for any non-loopback `sqp_api_url`. The `QUERYPILOT_ACCELERATOR_ALLOW_INSECURE_HTTP=1` escape hatch exists for disposable test environments only; in production it would send the token and cache-management traffic unencrypted. Never set it outside tests.

{/* source: verified against code @ 2026-07-18 */}


# What is QueryPilot? (/querypilot/what-is-querypilot)
import { Callout } from 'fumadocs-ui/components/callout';

QueryPilot is a SQL proxy built for modern workloads. It speaks the PostgreSQL and MySQL wire protocols on the front; behind them it accelerates query processing with automatic caching and enforces policies on agentic traffic with Guard, keeping your database focused on serving your application. Applications keep their existing drivers, SQL, and credentials; they change only the host and port they connect to.

<Callout type="info">
  **MySQL support is in preview.** MySQL proxying is functional and documented, but they are not part of the GA v1 support surface. PostgreSQL is the fully supported GA v1 path; full MySQL support is a fast-follow.
</Callout>

The platform is three components:

| Component       | What it is                                                                                                            | Ships as                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Router**      | The SQL proxy: wire protocols, connection pooling, query routing and translation, plugin host, metrics and admin API  | binary `querypilot`                                                                  |
| **Accelerator** | Caching plugin: discovers hot queries and manages Readyset caches plus the routing rules that send traffic to them    | in-process plugin inside `querypilot`, or standalone binary `querypilot-accelerator` |
| **Guard**       | Policy-enforcement plugin: trust levels, YAML policies, a trusted-query registry, and an audit log for every decision | in-process plugin inside `querypilot`                                                |

Only the Router is mandatory. Each of the other two is opt-in and independent of the other.

<Callout type="info">
  **GA v1 ships the Router and the Accelerator.** Guard is an upcoming feature; it is documented here ahead of availability and details may change before release.
</Callout>

## Architecture

<svg id="qp-arch" viewBox="0 0 1200 762" style={{maxWidth: '100%', height: 'auto'}} xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" role="img" aria-label="QueryPilot architecture diagram">
  <style>
    {`  #qp-arch {
        --bg: transparent;
        --text: #1e293b;
        --muted: #64748b;
        --faint: #94a3b8;
        --stroke: #cbd5e1;
        --card: #f8fafc;
        --row: #ffffff;
        --router-stroke: #3b82f6;
        --router-fill: #eff6ff;
        --pg: #3b82f6;  --pg-fill: #eff3fa;
        --my: #0d9488;  --my-fill: #ecf7f5;
        --an: #16a34a;  --an-fill: #eef8f0;
        --ac: #7c3aed;  --ac-fill: #f3effb;
      }
      .dark #qp-arch {
          --bg: transparent;
          --text: #e2e8f0;
          --muted: #94a3b8;
          --faint: #64748b;
          --stroke: #334155;
          --card: #1e293b;
          --row: #16213a;
          --router-stroke: #60a5fa;
          --router-fill: #142035;
          --pg: #60a5fa;  --pg-fill: #172136;
          --my: #2dd4be;  --my-fill: #12262b;
          --an: #4ade80;  --an-fill: #132619;
          --ac: #a78bfa;  --ac-fill: #1e1a33;
      }
      #qp-arch .bg      { fill: var(--bg); }
      #qp-arch .title   { fill: var(--muted); font-size: 20px; font-weight: 700; }
      #qp-arch .h1      { fill: var(--text); font-size: 20px; font-weight: 700; }
      #qp-arch .h2      { fill: var(--text); font-size: 17px; font-weight: 700; }
      #qp-arch .h3      { fill: var(--text); font-size: 15px; font-weight: 700; }
      #qp-arch .sub     { fill: var(--muted); font-size: 12.5px; }
      #qp-arch .label   { fill: var(--muted); font-size: 11px; font-weight: 700; letter-spacing: 1.1px; }
      #qp-arch .mono    { fill: var(--faint); font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12.5px; }
      #qp-arch .mono-lg { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 14px; font-weight: 600; }
      #qp-arch .line    { stroke: var(--muted); stroke-width: 1.6; fill: none; }
      #qp-arch .line-f  { stroke: var(--faint); stroke-width: 1.4; fill: none; }
      #qp-arch .dashed  { stroke: var(--faint); stroke-width: 1.4; stroke-dasharray: 5 5; fill: none; }
      #qp-arch .card    { fill: var(--card); stroke: var(--stroke); stroke-width: 1.2; }
      #qp-arch .band    { fill: var(--card); stroke: var(--stroke); stroke-width: 1.2; }
      #qp-arch .row     { fill: var(--row); stroke: var(--stroke); stroke-width: 1; }
      #qp-arch .plugin  { fill: var(--row); stroke: var(--stroke); stroke-width: 1.2; stroke-dasharray: 6 4; }
      #qp-arch .router  { fill: var(--router-fill); stroke: var(--router-stroke); stroke-width: 1.8; }
      #qp-arch .arrow   { fill: var(--muted); }
      #qp-arch .arrow-f { fill: var(--faint); }
      #qp-arch .pg-box  { fill: var(--pg-fill); stroke: var(--pg); stroke-width: 1.4; }
      #qp-arch .my-box  { fill: var(--my-fill); stroke: var(--my); stroke-width: 1.4; }
      #qp-arch .an-box  { fill: var(--an-fill); stroke: var(--an); stroke-width: 1.4; }
      #qp-arch .ac-box  { fill: var(--ac-fill); stroke: var(--ac); stroke-width: 1.4; }
      #qp-arch .pg-t    { fill: var(--pg); }
      #qp-arch .my-t    { fill: var(--my); }
      #qp-arch .an-t    { fill: var(--an); }
      #qp-arch .ac-t    { fill: var(--ac); }
      `}
  </style>

  <defs>
    <marker id="head" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 z" class="arrow" />
    </marker>

    <marker id="head-faint" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 z" class="arrow-f" />
    </marker>
  </defs>

  <rect class="bg" x="0" y="0" width="1200" height="762" />

  <text class="title" x="40" y="48">
    QueryPilot architecture
  </text>

  <rect class="card" x="400" y="22" width="400" height="72" rx="12" />

  <text class="h1" x="600" y="52" text-anchor="middle">
    Applications
  </text>

  <text class="sub" x="600" y="76" text-anchor="middle">
    any PostgreSQL or MySQL driver, no code changes
  </text>

  <line class="line" x1="520" y1="94" x2="520" y2="142" marker-end="url(#head)" />

  <line class="line" x1="680" y1="94" x2="680" y2="142" marker-end="url(#head)" />

  <text class="sub" x="508" y="124" text-anchor="end">
    PostgreSQL wire
  </text>

  <text class="sub" x="692" y="124">
    MySQL wire
  </text>

  <rect class="router" x="80" y="150" width="1040" height="406" rx="16" />

  <text class="h1" x="104" y="186">
    Router
  </text>

  <text class="mono" x="186" y="185">
    binary querypilot
  </text>

  <text class="sub" x="1096" y="185" text-anchor="end">
    metrics :9090  /  admin API :9091
  </text>

  {/* Band A: Plugin chain */}

  <rect class="band" x="104" y="204" width="992" height="100" rx="12" />

  <text class="label" x="120" y="226">
    PLUGIN CHAIN (OPT-IN)
  </text>

  <rect class="plugin" x="120" y="236" width="458" height="52" rx="9" />

  <text class="h3" x="349" y="260" text-anchor="middle">
    Guard*
  </text>

  <text class="sub" x="349" y="278" text-anchor="middle">
    allow / amend / block / audit
  </text>

  <rect class="plugin" x="622" y="236" width="458" height="52" rx="9" />

  <text class="h3" x="851" y="260" text-anchor="middle">
    Accelerator
  </text>

  <text class="sub" x="851" y="278" text-anchor="middle">
    cache discovery, rule management
  </text>

  <line class="line" x1="600" y1="304" x2="600" y2="322" marker-end="url(#head)" />

  {/* Band B: Query routing */}

  <rect class="band" x="104" y="322" width="992" height="100" rx="12" />

  <text class="label" x="120" y="344">
    QUERY ROUTING
  </text>

  <rect class="row" x="120" y="354" width="290" height="52" rx="9" />

  <text class="h3" x="265" y="378" text-anchor="middle">
    Transaction pinning
  </text>

  <text class="sub" x="265" y="396" text-anchor="middle">
    in-flight transactions stay put
  </text>

  <line class="line-f" x1="410" y1="380" x2="455" y2="380" marker-end="url(#head-faint)" />

  <rect class="row" x="455" y="354" width="290" height="52" rx="9" />

  <text class="h3" x="600" y="378" text-anchor="middle">
    Rule matching
  </text>

  <text class="sub" x="600" y="396" text-anchor="middle">
    translation · pattern · regex
  </text>

  <line class="line-f" x1="745" y1="380" x2="790" y2="380" marker-end="url(#head-faint)" />

  <rect class="row" x="790" y="354" width="290" height="52" rx="9" />

  <text class="h3" x="935" y="378" text-anchor="middle">
    Read / write split
  </text>

  <text class="sub" x="935" y="396" text-anchor="middle">
    reads → replicas, writes → primary
  </text>

  <line class="line" x1="600" y1="422" x2="600" y2="440" marker-end="url(#head)" />

  {/* Band C: Connection pools */}

  <rect class="band" x="104" y="440" width="992" height="100" rx="12" />

  <text class="label" x="120" y="462">
    CONNECTION POOLS
  </text>

  <text class="sub" x="304" y="462">
    session / transaction / statement modes  ·  per-pool credentials and protocol
  </text>

  <rect class="pg-box" x="120" y="472" width="222" height="52" rx="9" />

  <text class="mono-lg pg-t" x="231" y="504" text-anchor="middle">
    pg-pool
  </text>

  <rect class="my-box" x="366" y="472" width="222" height="52" rx="9" />

  <text class="mono-lg my-t" x="477" y="504" text-anchor="middle">
    mysql-pool
  </text>

  <rect class="an-box" x="612" y="472" width="222" height="52" rx="9" />

  <text class="mono-lg an-t" x="723" y="504" text-anchor="middle">
    analytics-pool
  </text>

  <rect class="ac-box" x="858" y="472" width="222" height="52" rx="9" />

  <text class="mono-lg ac-t" x="969" y="504" text-anchor="middle">
    cache-pool
  </text>

  {/* Arrows to backends */}

  <line class="line" x1="231" y1="556" x2="231" y2="594" marker-end="url(#head)" />

  <line class="line" x1="477" y1="556" x2="477" y2="594" marker-end="url(#head)" />

  <line class="line" x1="723" y1="556" x2="723" y2="594" marker-end="url(#head)" />

  <line class="line" x1="969" y1="556" x2="969" y2="594" marker-end="url(#head)" />

  {/* Backends */}

  <rect class="pg-box" x="116" y="602" width="230" height="78" rx="12" />

  <text class="h2" x="231" y="634" text-anchor="middle">
    PostgreSQL
  </text>

  <text class="sub" x="231" y="658" text-anchor="middle">
    primary / replicas
  </text>

  <rect class="my-box" x="362" y="602" width="230" height="78" rx="12" />

  <text class="h2" x="477" y="634" text-anchor="middle">
    MySQL*
  </text>

  <text class="sub" x="477" y="658" text-anchor="middle">
    primary / replicas
  </text>

  <rect class="an-box" x="608" y="602" width="230" height="78" rx="12" />

  <text class="h2" x="723" y="634" text-anchor="middle">
    Analytics*
  </text>

  <text class="mono" x="723" y="658" text-anchor="middle">
    querypilot-analytics
  </text>

  <rect class="ac-box" x="854" y="602" width="230" height="78" rx="12" />

  <text class="h2" x="969" y="634" text-anchor="middle">
    Accelerator
  </text>

  <text class="sub" x="969" y="658" text-anchor="middle">
    Readyset caches
  </text>

  {/* CDC replication */}

  <path class="dashed" d="M 231 680 L 231 712 L 723 712 L 723 686" marker-end="url(#head-faint)" />

  <path class="dashed" d="M 477 680 L 477 712" />

  <text class="sub" x="477" y="740" text-anchor="middle">
    CDC replication: snapshot first, then live changes
  </text>

  <text class="sub" x="80" y="740">
    \* Coming soon
  </text>
</svg>

## The Router

The Router (binary `querypilot`) is the core of the platform and the only required process. It is configured by a single TOML file, `querypilot.toml` (see the [configuration reference](/querypilot/reference/router-configuration)).

* **Wire protocols.** Each `[[listeners]]` entry serves either the PostgreSQL or the MySQL protocol. A single Router can serve both at once on different ports.
* **Connection pooling.** Named `[pools.<name>]` hold connections to backend servers, with three modes: `session` (connection held for the whole client session), `transaction` (released at COMMIT/ROLLBACK, the default), and `statement` (released after every statement). Backends within a pool are selected round-robin, and replicas can be skipped when their measured lag exceeds `max_replica_lag`.
* **Query routing.** For each query the Router first honors transaction pinning (in-transaction statements stay on the same backend connection), then translation rules, then pattern rules, then regex rules, then the read/write split, falling back to `default_pool`.
* **Query translation.** Translation rules rewrite a query's SQL and pin it to a target pool, rewriting a function call the target backend does not support into its equivalent. Literals are parameterized on both sides, so one rule covers every query with the same shape regardless of values.
* **Cross-protocol pools.** A pool can override the backend `protocol`, so a MySQL client can be served transparently from a PostgreSQL-speaking backend.
* **Observability and control.** With `[metrics] enabled = true` the Router serves Prometheus metrics (`sqp_*` series) and a REST [admin API](/querypilot/reference/admin-api) on the same IP at the metrics port + 1 (9090 metrics / 9091 admin by convention).

## Accelerator

The Accelerator watches query traffic, ranks the hottest queries, creates caches for them on a Readyset deployment, and installs the routing rules that steer matching queries to the Readyset pool. It runs in two forms: in-process, enabled by a `[plugins.accelerator]` block in `querypilot.toml`, or standalone as the `querypilot-accelerator` binary managing a ProxySQL or Router deployment. See the [Accelerator guide](/querypilot/accelerator).

## Guard

Guard is an in-process plugin enabled by a `[plugins.guard]` block in `querypilot.toml`. It assigns each session a trust level, evaluates YAML policies and a trusted-query registry against every query, and can allow, amend, or block, or run in shadow/warn mode that only records what it would have done. Every decision is written to an audit sink. See the [Guard guide](/querypilot/guard).

## How the components compose

* **Router alone** is a protocol-aware pooling proxy with routing rules: read/write splitting, query rejection, multi-pool fan-out.
* **Router + Accelerator (+ Readyset)** adds automatic caching: the plugin creates Readyset caches for hot queries and routes matching traffic to them.
* **Guard** layers policy enforcement onto any of the above.

Plugins are opt-in via their config blocks; when none are enabled the plugin chain is empty and adds zero per-query overhead.

## Compatibility

| Surface                                          | GA v1 status                                                                                                                                                                     |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PostgreSQL proxying (wire protocol and backends) | GA. Tested against PostgreSQL 15 and 16.                                                                                                                                         |
| MySQL proxying (wire protocol and backends)      | Preview. Tested against MySQL 8.0.                                                                                                                                               |
| Client authentication                            | PostgreSQL SCRAM-SHA-256; MySQL `mysql_native_password`.                                                                                                                         |
| Client drivers                                   | Any driver speaking the PostgreSQL or MySQL wire protocol. Proven in tests with `psql`, `mysql`, and standard Rust drivers; prepared statements are supported on both protocols. |
| Platforms                                        | Linux amd64 and arm64 container images.                                                                                                                                          |

<Callout type="warning">
  The Router does not terminate TLS in GA v1. Run it on a trusted network segment and terminate TLS in front of it if clients connect over untrusted networks. See [Security](/querypilot/security).
</Callout>

{/* source: verified against code @ 2026-07-18 */}


# Readyset AI (/readyset-ai)
RDST is a desktop app for Continuous monitoring of PostgreSQL and MySQL. It
records query activity, reports changes in the Inbox, and analyzes queries in
the background. Start with [RDST](/readyset-ai/rdst).

The [CLI](/readyset-ai/rdst/cli) supports query analysis, code scans, database
audits, and cache management for scripts and CI.

The [Readyset MCP server](/readyset-ai/mcp-server) lets AI assistants inspect a
Readyset deployment and manage its caches. For RDST's query analysis tools,
use the [RDST integration](/readyset-ai/rdst/cli/integrations/claude-code).


# MCP Server (/readyset-ai/mcp-server)
import { Callout } from 'fumadocs-ui/components/callout'

# Readyset MCP Server

The Readyset [Model Context Protocol](https://modelcontextprotocol.io) server
lets AI assistants inspect a Readyset deployment and manage its caches.

This server connects to Readyset. For RDST query analysis and audits, use
[RDST's MCP tools](/readyset-ai/rdst/cli/integrations/claude-code). Neither MCP
server exposes RDST's Continuous monitoring Inbox or nightly reports.

Two deployment shapes are supported:

| Shape                                          | Use case                            | Auth                          |
| ---------------------------------------------- | ----------------------------------- | ----------------------------- |
| **Standalone stdio binary** (`readyset-mcp`)   | Local development, individual users | Database credentials          |
| **Embedded HTTP endpoint** (inside `readyset`) | Shared / remote access              | Bearer tokens managed via SQL |

Both expose the same set of tools.

## Tools

| Tool                     | What it does                                                        | Scope required |
| ------------------------ | ------------------------------------------------------------------- | -------------- |
| `readyset_status`        | Replication lag, snapshot progress, adapter health                  | `read_only`    |
| `readyset_version`       | Server version and build metadata                                   | `read_only`    |
| `show_caches`            | List all active caches                                              | `read_only`    |
| `show_proxied_queries`   | Queries currently proxied to upstream                               | `read_only`    |
| `show_proxied_supported` | Proxied queries Readyset could cache (best CREATE CACHE candidates) | `read_only`    |
| `explain_cache_support`  | Check whether a given SQL query is cacheable, and why not if not    | `read_only`    |
| `create_cache`           | Create a cache from a SQL query or `query_id`                       | `cache_admin`  |
| `drop_cache`             | Remove an existing cache by name                                    | `cache_admin`  |

Each tool issues a Readyset SQL command. See the [command reference](/command-reference) for details on each command.

## Stdio binary: local setup

The `readyset-mcp` binary spawns as a child process of your MCP client (e.g. Claude Code) and connects to Readyset over the standard SQL wire protocol.

### Install

Build from source in the Readyset repo:

```bash
cargo build --release -p readyset-mcp
# Binary at target/release/readyset-mcp
```

### Register with Claude Code

```bash
claude mcp add readyset -- /path/to/readyset-mcp
```

Then edit `~/.claude.json` and add the connection environment variables to the `readyset` entry:

```json
{
  "mcpServers": {
    "readyset": {
      "command": "/path/to/readyset-mcp",
      "env": {
        "READYSET_HOST": "127.0.0.1",
        "READYSET_PORT": "3307",
        "READYSET_USER": "root",
        "READYSET_PASSWORD": "",
        "READYSET_DB_TYPE": "mysql"
      }
    }
  }
}
```

### Configuration

| Variable                            | Required | Description                                                             |
| ----------------------------------- | -------- | ----------------------------------------------------------------------- |
| `READYSET_HOST`                     | Yes      | Readyset adapter hostname                                               |
| `READYSET_PORT`                     | Yes      | Readyset SQL port                                                       |
| `READYSET_USER`                     | Yes      | Database username                                                       |
| `READYSET_PASSWORD`                 | Yes      | Database password                                                       |
| `READYSET_DB_TYPE`                  | No       | `mysql` (default), `postgres`, or `postgresql`                          |
| `READYSET_DATABASE`                 | No       | Default database name                                                   |
| `READYSET_SSLMODE`                  | No       | `disable` (default) or `require` to negotiate TLS                       |
| `READYSET_TLS_ROOT_CERT`            | No       | Path to a PEM file with one or more root certs to trust                 |
| `READYSET_TLS_DISABLE_VERIFICATION` | No       | Set to `true` to skip server certificate verification (encryption only) |

### TLS

Set `READYSET_SSLMODE=require` to connect over TLS. The system root store is used by default. To trust a custom CA, point `READYSET_TLS_ROOT_CERT` at a PEM file. For self-signed setups where verification isn't desired, set `READYSET_TLS_DISABLE_VERIFICATION=true` (encryption is still negotiated, only the server's identity isn't checked).

```json
{
  "mcpServers": {
    "readyset": {
      "command": "/path/to/readyset-mcp",
      "env": {
        "READYSET_HOST": "readyset.internal",
        "READYSET_PORT": "3307",
        "READYSET_USER": "root",
        "READYSET_PASSWORD": "",
        "READYSET_DB_TYPE": "mysql",
        "READYSET_SSLMODE": "require",
        "READYSET_TLS_ROOT_CERT": "/etc/ssl/readyset-ca.pem"
      }
    }
  }
}
```

### When to use stdio

* Individual developer, single workstation
* Quick local experimentation
* You already have SQL credentials and don't want to manage tokens

## Embedded HTTP: shared / remote setup

The `readyset` binary itself hosts an MCP endpoint on a dedicated port. AI assistants connect over HTTP(S) using Bearer tokens that you create from inside a SQL session.

### Enable the endpoint

```bash
readyset \
  --enable-mcp \
  --mcp-address 127.0.0.1:6035 \
  ... # your usual flags
```

<Callout type="warn">
  The MCP endpoint currently accepts plaintext HTTP only. Bearer tokens travel in the clear. The default bind address is `127.0.0.1:6035` (loopback) so the endpoint isn't network-reachable until you opt in. Only bind to a non-loopback address behind a TLS-terminating proxy.
</Callout>

Flags:

| Flag            | Default          | Description                           |
| --------------- | ---------------- | ------------------------------------- |
| `--enable-mcp`  | `false`          | Enable the embedded MCP HTTP endpoint |
| `--mcp-address` | `127.0.0.1:6035` | Address the MCP endpoint binds to     |

### Create a token

Connect to Readyset with any SQL client and run:

```sql
CREATE MCP TOKEN 'claude-desktop' WITH SCOPE cache_admin;
```

Readyset returns a single row containing the raw token value:

```
+-------------------------------------------+
| token                                     |
+-------------------------------------------+
| rs_mcp_aB3xK9mNpQr2Vt4yZ7wE5sU8hJ1fLdGc  |
+-------------------------------------------+
```

This is the only time the raw value is visible. Copy it immediately.

You can also set an expiration when creating the token:

```sql
CREATE MCP TOKEN 'claude-desktop'
  WITH SCOPE cache_admin
  EXPIRES '2027-01-01T00:00:00Z';
```

### Register with Claude Code

```bash
claude mcp add --transport http readyset https://readyset.example.com:6035/mcp \
  --header "Authorization: Bearer rs_mcp_aB3xK9mNpQr2Vt4yZ7wE5sU8hJ1fLdGc"
```

Or edit `~/.claude.json` directly:

```json
{
  "mcpServers": {
    "readyset": {
      "type": "http",
      "url": "http://readyset.example.com:6035/mcp",
      "headers": {
        "Authorization": "Bearer rs_mcp_aB3xK9mNpQr2Vt4yZ7wE5sU8hJ1fLdGc"
      }
    }
  }
}
```

### When to use HTTP

* Multiple users sharing one Readyset
* Remote access (MCP client not on the same host as Readyset)
* You want fine-grained permissions (per-token scopes, expiration)
* Administrative control over who can do what via MCP

## Token management

All MCP tokens are managed with SQL. There are no separate admin tools.

### `CREATE MCP TOKEN`

```sql
CREATE MCP TOKEN '<name>'
  [WITH SCOPE <scope>]
  [EXPIRES '<rfc3339-datetime>']
```

[`CREATE MCP TOKEN`](/command-reference#create-mcp-token) creates a new token
and returns the raw value once.

* `<name>`: human-readable identifier, used in later `DROP`/`ALTER` statements. Must be unique.
* `<scope>`: one of `read_only`, `cache_admin`, `full`. Defaults to `read_only`.
* `EXPIRES '<rfc3339>'`: optional UTC timestamp after which the token becomes invalid. Omit for a non-expiring token.

### `SHOW MCP TOKENS`

[`SHOW MCP TOKENS`](/command-reference#show-mcp-tokens) lists tokens and metadata.
It doesn't show the raw value or hash.

```sql
SHOW MCP TOKENS;
```

Each row shows the token's `name` and `scope`. Check `created_at` and `expires_at`
for its creation and expiration times.

### `ALTER MCP TOKEN`

```sql
ALTER MCP TOKEN '<name>' SET EXPIRES '<rfc3339-datetime>'
ALTER MCP TOKEN '<name>' SET NEVER EXPIRES
```

[`ALTER MCP TOKEN`](/command-reference#alter-mcp-token) updates a token's
expiration without rotating its value. Useful for extending a soon-to-expire token without having to reconfigure the client.

### `DROP MCP TOKEN`

```sql
DROP MCP TOKEN '<name>';
```

[`DROP MCP TOKEN`](/command-reference#drop-mcp-token) revokes the token. The next
request using it returns 401.

## Scopes

Each token carries one of three scopes. The MCP endpoint enforces the scope on every tool invocation. Requests that violate scope are rejected with HTTP 403.

| Scope         | Permitted tools                                                              |
| ------------- | ---------------------------------------------------------------------------- |
| `read_only`   | All `show_*`, `readyset_status`, `readyset_version`, `explain_cache_support` |
| `cache_admin` | `read_only` + `create_cache`, `drop_cache`                                   |
| `full`        | Everything, including future administrative tools                            |

Choose the narrowest scope that covers the client's needs. Most interactive AI use cases are fine with `read_only`; only promote to `cache_admin` when you want the assistant to actually modify cache state.

## Security notes

* **Token values are hashed**: Readyset stores only the SHA-256 hash. If a token is lost, you must `DROP MCP TOKEN` and `CREATE MCP TOKEN` to issue a new one.
* **Plaintext HTTP**: the current MCP endpoint doesn't terminate TLS itself. For any non-local deployment, put it behind a TLS-terminating proxy (nginx, Caddy, Envoy, an ingress controller, etc.).
* **Bearer tokens are the only auth**: there's no IP allowlist, no OAuth, no mTLS. Treat a token like a password.
* **Scope enforcement is centralized**: adding a new MCP tool without updating the scope map causes it to default to `full`, failing closed.

## Troubleshooting

### "Connection failed" on initial Claude Code registration

The MCP server binary must be able to reach Readyset over its SQL port. For stdio, check the env vars; for HTTP, check the `--mcp-address` and firewall.

Quick test (HTTP transport):

```bash
curl -i -X POST http://readyset.example.com:6035/mcp \
  -H "Authorization: Bearer rs_mcp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

A 200 response means the HTTP layer and token auth are working; the problem is in the Claude Code config.

### Stdio binary fails to connect with a TLS handshake error

Readyset is presenting a certificate the system root store doesn't trust. Two options:

1. Point `READYSET_TLS_ROOT_CERT` at the PEM file that issued Readyset's certificate. This is the recommended path for internal CAs.
2. For a quick local check, set `READYSET_TLS_DISABLE_VERIFICATION=true`. Encryption is still negotiated, but the server's identity isn't verified, so don't use this in production.

### Tool call returns "token scope 'read\_only' doesn't permit tool 'drop\_cache'"

The token doesn't have the required scope. Either create a new token with a broader scope or drop this one and recreate it.

### CREATE CACHE over MCP reports "can't parse query"

The `create_cache` tool passes the SQL text through to Readyset's parser exactly as you provide it. Test the same query against Readyset directly via `mysql` or `psql` to confirm whether the issue is the query itself or the tool pipeline.

### Token appears in `SHOW MCP TOKENS` but requests get 401

Check the `expires_at` column. If the timestamp is in the past, the token is expired. Either `ALTER MCP TOKEN` to extend it or drop and recreate.


# Benchmarking with cache-compare (/readyset-ai/rdst/cli/cache/compare)
import { Callout } from 'fumadocs-ui/components/callout'

`rdst query cache-compare` runs a query against its source database and a
temporary local Readyset sandbox, then reports side-by-side latency statistics.
RDST prepares the sandbox, validates that both sides return equivalent results,
and removes the temporary cache when the test finishes.

## Common usage

```bash
# Compare using the default workload
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders

# Scale up the sample size
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders --count 1000

# Time-bounded run
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders --duration 60

# Sustained concurrent load on each side
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders \
  --concurrency 10 --duration 120

# Fixed start interval on each side
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders \
  --interval 100 --duration 60

# Share the count across several queries
rdst query cache-compare a1b2c3d4 f6e5d4c3 9a8b7c6d \
  --target prod-orders --count 500
```

<Callout type="info">
  Pass the source database target to `cache-compare`. RDST automatically
  prepares its one local Readyset sandbox; no Readyset deployment or generated
  cache target is required.
</Callout>

## Execution modes

| Mode           | Flags             | Behavior                                             |
| -------------- | ----------------- | ---------------------------------------------------- |
| Fixed count    | `--count N`       | Run at most N measured executions on each side       |
| Duration       | `--duration SECS` | Stop starting work after the per-side time limit     |
| Concurrency    | `--concurrency N` | Maintain up to N concurrent executions on each side  |
| Fixed interval | `--interval MS`   | Start sequential executions at the selected interval |

`--interval` and `--concurrency` are mutually exclusive. `--count` remains a
hard execution cap when combined with `--duration`.

For multiple queries, RDST shares the requested count and duration limits
across them and tests each query sequentially. Each query gets its own temporary
cache and result row. The aggregate invocation never multiplies the requested
production-load limit by the number of queries.

<Callout type="warn">
  `cache-compare` runs real queries against the source database. Check that the
  selected count, concurrency, and duration are safe for that environment.
</Callout>

## What RDST manages

For each query, RDST:

1. Acquires the managed sandbox for the selected source target.
2. Checks Readyset compatibility.
3. Creates and warms an owner-scoped temporary cache.
4. Validates source and Readyset results.
5. Runs the bounded comparison.
6. Drops the temporary cache before releasing the sandbox.

The clean sandbox may remain warm for reuse for up to 24 hours. It's not an
application-facing Readyset deployment.

## Flags reference

| Flag                  | Purpose                                                      |
| --------------------- | ------------------------------------------------------------ |
| `queries`             | One or more registry hashes, names, or inline SQL statements |
| `-t, --target NAME`   | Source database target                                       |
| `--count N`           | Maximum measured executions per side, shared across queries  |
| `--duration SECS`     | Per-side time limit, shared across queries                   |
| `--interval MS`       | Fixed start interval per side                                |
| `-c, --concurrency N` | Concurrent executions per side                               |
| `--quiet`             | Minimal output                                               |
| `--skip-warning`      | Skip the source-query execution warning                      |

## Interpreting the result

| Signal                                   | Meaning                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| Readyset has lower mean and tail latency | The query benefits from Readyset under the selected workload                             |
| Similar latency                          | The source may already be fast, or the sample may be too small                           |
| Source is faster                         | Readyset doesn't improve this query under the selected workload                          |
| Results differ                           | RDST stops before benchmarking and reports the validation failure                        |
| Cleanup is partial                       | RDST preserves valid measurements, marks the sandbox dirty, and replaces it before reuse |

## See also

* [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze) - inspect query behavior and static Readyset compatibility
* [`rdst query run`](/readyset-ai/rdst/cli/configuration#running-queries-for-load-generation) - generate source-only query load


# rdst cache deploy (/readyset-ai/rdst/cli/cache/deploy)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

`rdst cache deploy` starts a Readyset process pointed at an existing database
target, then registers a new RDST target for that Readyset instance (typically
named `<original>-cache`).

## Common usage

```bash
# Local Docker deployment
rdst cache deploy --target prod-orders --mode docker

# Remote host via SSH (still Docker-mode, but on another machine)
rdst cache deploy --target prod-orders --mode docker \
    --host 10.0.1.50 --ssh-user ubuntu --ssh-key ~/.ssh/prod.pem

# Systemd service on the local or remote machine
rdst cache deploy --target prod-orders --mode systemd --host 10.0.1.50 \
    --ssh-user ubuntu --ssh-key ~/.ssh/prod.pem

# Kubernetes deployment
rdst cache deploy --target prod-orders --mode kubernetes \
    --namespace readyset --kubeconfig ~/.kube/config

# Generate the deploy script but don't run it
rdst cache deploy --target prod-orders --mode docker --script-only
```

## What `cache deploy` does

<Tabs items={['docker', 'systemd', 'kubernetes']}>
  <Tab value="docker">
    1. Pulls the Readyset Docker image (only if not already present)
    2. Starts a container pointed at your database target, with correct wire-protocol
       port and credentials
    3. Waits for Readyset to become ready
    4. Registers a new RDST target (`<original>-cache`) pointing at the container
    5. Prints connection info so you can point your application at it

    Remote Docker (`--host`) runs the same flow, just via SSH on the remote host.
  </Tab>

  <Tab value="systemd">
    1. Copies the Readyset binary to the host
    2. Writes a systemd unit file with your target's connection details
    3. Enables and starts the service
    4. Waits for readiness
    5. Registers a new RDST target pointing at the service
    6. Prints connection info and the `systemctl` commands to manage it

    Use `--host` + `--ssh-user` + `--ssh-key` to deploy to a remote systemd host.
  </Tab>

  <Tab value="kubernetes">
    1. Applies a Deployment, Service, and ConfigMap in the namespace you specify
    2. Configures the Deployment to connect to your target (credentials via
       Kubernetes Secret)
    3. Waits for the pod to report ready
    4. Registers a new RDST target pointing at the in-cluster Service
    5. Prints the Service DNS name so you can point your application at it

    If you want custom resource limits, node selectors, etc., use `--script-only` to
    generate the manifests and edit before applying.
  </Tab>
</Tabs>

## Accessibility matters

RDST needs network access to the Readyset instance it just deployed in order to
run `rdst cache add`, `rdst cache show`, or any other follow-up command against it.

<Callout type="warn">
  If you deploy to a target RDST can't reach directly over the network, follow-up
  cache commands will fail. Common causes:

  * The Readyset port (5432 for Postgres-wire, 3306 for MySQL-wire) is closed on
    the remote host's firewall or security group.
  * The remote host is only reachable over SSH. RDST can deploy through SSH but
    doesn't tunnel every subsequent command through SSH.
  * A Kubernetes Service is `ClusterIP`-only and not exposed outside the cluster.

  Before running `rdst cache deploy --host <remote>`, confirm you can reach the
  target port from your laptop (e.g. `nc -zv <host> 5432`). For cluster-only
  deployments, plan to run `rdst cache add` from inside the cluster.
</Callout>

## After deployment

RDST prints the connection string and the name of the new target it registered:

```text
✓ Readyset deployed (mode: docker, container: readyset-prod-orders)
✓ Readyset is ready
✓ Registered target: prod-orders-cache

Connection string:
  postgresql://rdst:*****@localhost:5434/orders

Next steps:
  rdst cache add <query-hash> --target prod-orders-cache
  rdst query cache-compare <query-hash> --target prod-orders
```

Use the registered cache target (`prod-orders-cache`) to manage cached queries. Every `rdst cache` command takes `--target <cache-target>`.

## Script-only mode

`--script-only` is useful when you want to:

* Review exactly what will run before running it
* Adapt the deploy script for an environment RDST doesn't natively support (Nomad,
  custom CI, etc.)
* Deploy in a context where RDST can't reach the target (e.g., an air-gapped host)

```bash
rdst cache deploy --target prod-orders --mode docker --script-only > deploy.sh
# Review deploy.sh, edit as needed, run it yourself
bash deploy.sh
```

<Callout type="warn">
  When you use `--script-only`, RDST doesn't register the cache target for you.
  You'll need to register it manually with `rdst configure add` pointing at the
  deployed Readyset instance.
</Callout>

## Configs

`--config <name>` picks between Readyset deployment profiles:

| Config               | What it's                                                           |
| -------------------- | ------------------------------------------------------------------- |
| `readyset` (default) | Standard Readyset: shallow caching                                  |
| `readyset-squeepy`   | Readyset with SQueePy preset: tuned defaults for specific workloads |

Most users should stick with the default.

## Flags reference

| Flag                                   | What it does                                    |
| -------------------------------------- | ----------------------------------------------- |
| `--target <name>`                      | Which database target to cache                  |
| `--mode {docker,systemd,kubernetes}`   | Deployment mode (required)                      |
| `--config {readyset,readyset-squeepy}` | Deployment config preset                        |
| `--host <ip>`                          | Remote host for SSH deployment (omit for local) |
| `--ssh-user <user>`                    | SSH username (default: `root`)                  |
| `--ssh-key <path>`                     | SSH private key path                            |
| `--port <port>`                        | Override Readyset listen port                   |
| `--namespace <ns>`                     | Kubernetes namespace                            |
| `--kubeconfig <path>`                  | Path to kubeconfig for Kubernetes deployment    |
| `--script-only`                        | Generate deployment script without executing    |
| `--json`                               | Machine-readable output                         |

## Tearing down

To stop and remove a local cache deployment entirely:

```bash
rdst cache remove --target prod-orders-cache
```

This stops the Docker container (or systemd service, or Kubernetes deployment),
removes the persistent state, and unregisters the `<original>-cache` RDST target.

Use `rdst cache drop-all --target <name>` instead if you want to remove cached
queries but keep Readyset running. See [Managing caches](/readyset-ai/rdst/cli/cache/manage).

## See also

* [Managing caches](/readyset-ai/rdst/cli/cache/manage): add, list, and delete cached queries
  after Readyset is deployed
* [Benchmarking with cache-compare](/readyset-ai/rdst/cli/cache/compare): measure upstream vs
  cached performance head-to-head
* [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit): the report that tells you which
  targets would benefit most from caching


# Readyset caches (/readyset-ai/rdst/cli/cache)
import { Callout } from 'fumadocs-ui/components/callout'
import { Cards, Card } from 'fumadocs-ui/components/card'

Use `rdst cache deploy` for an application-facing Readyset deployment.
For a local benchmark, `rdst query cache-compare` prepares a temporary sandbox;
it doesn't require deployment first.

## The RDST cache workflow

1. [Deploy Readyset](/readyset-ai/rdst/cli/cache/deploy) for a source database.
2. [Add queries](/readyset-ai/rdst/cli/cache/manage) using the registered cache target.
3. Point your application at the Readyset endpoint when you're ready to use it.

```bash
rdst cache deploy --target prod-orders --mode docker
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache
```

To evaluate a query using the temporary sandbox:

```bash
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders
```

## Deployment modes

`rdst cache deploy` supports three modes, each appropriate for a different
environment:

| Mode         | Use when                                                        |
| ------------ | --------------------------------------------------------------- |
| `docker`     | Use a local or remote Readyset container                        |
| `systemd`    | You've a dedicated host for Readyset (EC2, bare metal, etc.)    |
| `kubernetes` | Your infrastructure runs on K8s and you want Readyset there too |

Combined with `--host` (for remote deployment via SSH) and `--script-only`
(generate the deploy script without running it), this gives you four real flows:

```bash
# Local Docker
rdst cache deploy --target prod-orders --mode docker

# Remote host via SSH
rdst cache deploy --target prod-orders --mode docker \
    --host 10.0.1.50 --ssh-user ubuntu --ssh-key ~/.ssh/prod.pem

# Systemd service
rdst cache deploy --target prod-orders --mode systemd

# Kubernetes
rdst cache deploy --target prod-orders --mode kubernetes \
    --namespace readyset --kubeconfig ~/.kube/config

# Generate the script without executing
rdst cache deploy --target prod-orders --mode docker --script-only
```

See [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy) for the full reference.

## Sections in this guide

<Cards>
  <Card title="rdst cache deploy" href="/readyset-ai/rdst/cli/cache/deploy" description="Deploy Readyset locally, remotely via SSH, or in Kubernetes." />

  <Card title="Managing caches" href="/readyset-ai/rdst/cli/cache/manage" description="Add, list, delete, and tear down caches on a deployed Readyset instance." />

  <Card title="Benchmarking with cache-compare" href="/readyset-ai/rdst/cli/cache/compare" description="Measure upstream vs cached performance head-to-head with real traffic." />
</Cards>

## See also

* [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit): the audit report ranks Readyset
  cache candidates across your database
* [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze): per-query cache-fit evaluation
* [Readyset QueryPilot](/querypilot/proxysql): fully-managed caching on top of Readyset,
  when you want auto-discovery and deep caching


# Managing caches (/readyset-ai/rdst/cli/cache/manage)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

After [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy) registers a cache target (typically
named `<original>-cache`), the remaining `rdst cache` commands act on that target.

## Add a cache

```bash
# From the query registry (preferred)
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache

# Direct SQL
rdst cache add "SELECT * FROM orders WHERE customer_id = ?" --target prod-orders-cache

# Check cacheability without actually adding
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache --dry-run

# Tag the query in the registry while adding
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache --tag high-priority
```

<Callout type="info">
  `rdst cache add` uses Readyset's `CREATE CACHE` command under the hood. Passing a
  hash from the registry is preferred because RDST can show you exactly which query
  will be cached and verify it's still cacheable before acting.
</Callout>

### What "cacheable" means

Readyset supports a specific subset of SQL features for caching. If `rdst cache add`
reports a query isn't cacheable, the reason is printed:

```text
$ rdst cache add f6e5d4c3b2a1 --target prod-orders-cache --dry-run

Checking cacheability for query f6e5d4c3b2a1 ...

  SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '7 days'

✗ NOT CACHEABLE
  Reason: Query contains non-deterministic function NOW() which cannot be
          parameterized for caching. Consider parameterizing the time cutoff:
          WHERE created_at > $1
```

Use `rdst analyze --hash <id>` for the full cacheability analysis including
suggestions to make a query cacheable.

## List caches

```bash
# Every cache on the target
rdst cache show --target prod-orders-cache

# JSON output for scripting
rdst cache show --target prod-orders-cache --json
```

```text
Caches on prod-orders-cache (3 total)

  Hash      Cache Name      Query                                                 Type     TTL
  ────────  ──────────────  ────────────────────────────────────────────────────  ───────  ─────
  a1b2c3d4  q_01            SELECT * FROM orders WHERE customer_id = ?            shallow  10s
  f6e5d4c3  q_02            SELECT o.id, o.total_cents FROM orders o JOIN cu...   shallow  10s
  9a8b7c6d  session-lookup  SELECT 1 FROM session_cache WHERE token = ?           shallow  10s

Readyset Connection String
  postgresql://rdst:${PROD_ORDERS_PASSWORD}@localhost:5434/orders

  Compare: rdst query cache-compare a1b2c3d4 --target prod-orders --count 100
```

The **Hash** column is the first 8 characters of the query's registry hash, pass
it to `rdst query cache-compare` to benchmark the query against a temporary sandbox.
The **Cache Name** is what you hand to `rdst cache delete`.

## Delete a cache

```bash
# By cache name (from the "Cache Name" column of `rdst cache show`)
rdst cache delete q_01 --target prod-orders-cache
```

To remove every cache from a Readyset instance without tearing the instance down:

```bash
rdst cache drop-all --target prod-orders-cache --yes
```

The `--yes` flag skips the confirmation prompt. Without it, RDST lists everything
that will be removed first.

## Tear down the whole deployment

To remove Readyset entirely (stops the container, cleans up persistent state,
unregisters the `-cache` target):

```bash
rdst cache remove --target prod-orders-cache
```

This is the inverse of `rdst cache deploy`. Use it when you're done testing a
cache and want to clean up the artifacts.

| Command                  | What goes away                                     | Readyset still running? |
| ------------------------ | -------------------------------------------------- | ----------------------- |
| `rdst cache delete <id>` | One cached query                                   | Yes                     |
| `rdst cache drop-all`    | All cached queries                                 | Yes                     |
| `rdst cache remove`      | Readyset itself + all caches + the `-cache` target | No                      |

## Flags reference

<Tabs items={['add', 'show', 'delete', 'drop-all', 'remove']}>
  <Tab value="add">
    | Flag              | Purpose                                      |
    | ----------------- | -------------------------------------------- |
    | `query`           | Hash (12 hex chars) or direct SQL            |
    | `--target <name>` | Readyset target (usually `<original>-cache`) |
    | `--tag <tag>`     | Tag the query in the registry while adding   |
    | `--dry-run`       | Check cacheability without adding            |
    | `--json`          | JSON output                                  |
  </Tab>

  <Tab value="show">
    | Flag              | Purpose         |
    | ----------------- | --------------- |
    | `--target <name>` | Readyset target |
    | `--json`          | JSON output     |
  </Tab>

  <Tab value="delete">
    | Flag              | Purpose                         |
    | ----------------- | ------------------------------- |
    | `cache_id`        | Cache ID from `rdst cache show` |
    | `--target <name>` | Readyset target                 |
    | `--json`          | JSON output                     |
  </Tab>

  <Tab value="drop-all">
    | Flag              | Purpose                  |
    | ----------------- | ------------------------ |
    | `--target <name>` | Readyset target          |
    | `--yes`           | Skip confirmation prompt |
    | `--json`          | JSON output              |
  </Tab>

  <Tab value="remove">
    | Flag              | Purpose                      |
    | ----------------- | ---------------------------- |
    | `--target <name>` | Readyset target to tear down |
    | `--yes`           | Skip confirmation prompt     |
  </Tab>
</Tabs>

## See also

* [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy): deploy Readyset before adding caches
* [Benchmarking with cache-compare](/readyset-ai/rdst/cli/cache/compare): measure source and sandbox latency
* [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze): per-query cache-fit evaluation


# Core concepts (/readyset-ai/rdst/cli/concepts)
## Targets

A target is a named database connection. Use `--target <name>` to select it, or
set a default with `rdst configure default <name>`.

Targets contain an engine, host, port, database, user, and password environment
variable name. Passwords come from that variable or the operating system's
keychain. They're never saved in `config.toml`.

Add targets with [configure](/readyset-ai/rdst/cli/configuration#targets),
[fleet import or discovery](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup), or
the desktop app. The target list is local to the operating system user.

## The query registry

The query library records SQL from monitoring, `top`, `scan`, Ask, and analysis.
You can also add SQL yourself.

Queries are normalized before hashing. Different literal values for the same
query shape share an identity across the desktop app, CLI, and MCP tools.

```bash
rdst query list
rdst query list --filter customer_id
rdst query show a1b2c3d4e5f6
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders
rdst query add order-detail -q "SELECT * FROM orders WHERE id = 42"
```

Saved names and analyses remain available after database statistics reset.
Monitoring and Ask save queries in the same library.

## The semantic layer

The semantic layer describes tables, columns, relationships, and business terms
for a target. It helps Ask interpret questions such as which order statuses
count as completed sales.

```bash
rdst schema init --target prod-orders
rdst schema annotate --target prod-orders --use-llm
rdst schema show --target prod-orders
rdst schema edit --target prod-orders
rdst schema refresh --target prod-orders
```

Review generated descriptions and add meanings the schema can't provide.
Desktop [Ask](/readyset-ai/rdst/desktop/ask#schema-context) uses the same
per-target descriptions.

## The LLM

AI generates query explanations, candidate rewrites, SQL for Ask, audit insights,
and schema annotations. ORM call-site detection uses code parsing; translation
to SQL can use AI.

AI calls can include query text, execution plans, schema metadata, semantic
context, and parameter values. Query result rows and connection passwords aren't
included. See [AI access](/readyset-ai/rdst/desktop/ai-credits) for provider
selection and usage limits.

Recommendations can vary. Check suggested SQL and test it against representative
data before using it in your application.

## Audits and snapshots

An [audit](/readyset-ai/rdst/cli/fleet-and-audit/audit) collects a database's
health, sizing, query activity, and recommendations. Fleet audits run this
across several targets.

Audits save snapshots. Use
[snapshots and diff](/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff) to
read an earlier run or compare changes. Audit snapshots are separate from
monitoring's [nightly reports](/readyset-ai/rdst/desktop/monitoring/nightly-report).

## Readyset caches

[Cache deployment](/readyset-ai/rdst/cli/cache/deploy) starts an application-facing
Readyset instance and registers a `<target>-cache` connection. Add and manage
cached queries using that cache target.

[cache-compare](/readyset-ai/rdst/cli/cache/compare) takes the source database
target and prepares a temporary local sandbox for benchmarking. It doesn't
require a deployed cache target.

### Cache targets are restricted targets

Use source database targets for analysis, Ask, `top`, audits, and monitoring.
Use cache targets for `rdst cache add`, `show`, `delete`, `drop-all`, and `remove`.

## Where state lives

The desktop app and CLI share `~/.rdst` under the same operating system user.
`RDST_DATA_DIR` selects another data directory. It holds targets, `library.db`,
semantic layers, and audit snapshots. Monitoring also uses `monitor.db` and
`agent_activity.db`.

Database connections and AI calls use the network. Cloud discovery calls the
provider API, and the audit email flow sends a report for delivery.

## Continuous monitoring

Configure monitoring in the [desktop app](/readyset-ai/rdst/desktop/monitoring)
or [rdst web](/readyset-ai/rdst/cli/integrations/web). There isn't an `rdst monitor`
command. `rdst top` samples queries during its run; it doesn't start background
monitoring or produce Inbox items.

When your account's AI usage limit is reached, AI monitoring stops gracefully. Local
monitoring keeps running, and the app asks you to contact us.


# Configuration (/readyset-ai/rdst/cli/configuration)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Use `rdst configure`, `rdst schema`, and `rdst query` to manage RDST.
The desktop app shares the same configuration under the same operating system user.

## Targets

A **target** is a named database connection. Every analysis command takes
`--target <name>` so you never have to pass connection details on the command line.

### Add a target

<Tabs items={['Interactive', 'Non-interactive', 'From CSV', 'From AWS']}>
  <Tab value="Interactive">
    ```bash
    rdst configure add
    ```

    RDST asks you to name the target and enter its connection details. For the
    password, give the name of the environment variable that holds it.
  </Tab>

  <Tab value="Non-interactive">
    ```bash
    rdst configure add \
        --target prod-orders \
        --engine postgresql \
        --host db.example.com \
        --port 5432 \
        --database orders \
        --user rdst_ro \
        --password-env PROD_ORDERS_PASSWORD
    ```
  </Tab>

  <Tab value="From CSV">
    ```bash
    rdst fleet import --from fleet.csv --password-env FLEET_PASS
    ```

    See [Setting up a fleet](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup) for the CSV format.
  </Tab>

  <Tab value="From AWS">
    ```bash
    rdst fleet discover --regions us-east-1,us-west-2
    ```

    See [Setting up a fleet](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup) for AWS-specific
    details.
  </Tab>
</Tabs>

<Callout type="info">
  RDST stores passwords in the operating system's keychain or reads them from
  a named environment variable. The environment wins when set. `config.toml`
  records the variable name, never the password.
</Callout>

### Use a target

Export the password, then run any command against it:

```bash
export PROD_ORDERS_PASSWORD='...'
rdst top      --target prod-orders
rdst analyze  --hash abc123 --target prod-orders
rdst audit    --target prod-orders
```

### Manage targets

```bash
rdst configure list                   # list all targets
rdst configure edit <name>            # edit a target
rdst configure remove <name>          # delete a target
rdst configure default <name>         # set the default target (used when --target is omitted)
rdst configure test <name>            # verify connectivity and permissions
```

<Callout type="warn">
  Use a **read-only database user** for your RDST targets. RDST only runs
  diagnostic queries (EXPLAIN, system views), so it never needs write permissions
  on your application data. See [Database
  permissions](/readyset-ai/rdst/cli/database-permissions) for the minimum grants,
  optional monitoring access, and PostgreSQL and MySQL examples.
</Callout>

## LLM provider

Sign in to Readyset for hosted AI:

```bash
rdst account login
rdst account status
```

Finish the browser sign-in opened by the command. The app shows your account's
AI usage. When a usage limit is reached, AI monitoring stops gracefully, local
monitoring keeps running, and the app asks you to contact us.

You can also use your own Anthropic key:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

The saved provider preference controls routing. With Anthropic selected, RDST
uses the environment key before the keychain. With Readyset selected, it uses
your account even if the environment key is set. Without a saved preference,
RDST checks the environment, keychain, then Readyset sign-in.

Use the desktop [AI access settings](/readyset-ai/rdst/desktop/ai-credits) to
review or switch the saved provider. Monitoring change checks and query
classification always use Readyset's service.

## Semantic layer

The [semantic layer](/readyset-ai/rdst/cli/concepts#the-semantic-layer) describes your schema to the
LLM in plain language: what each table represents, what enum values mean, and how
tables relate. Add business meanings and review generated descriptions before relying on them.

```bash
rdst schema init      --target mydb                 # introspect
rdst schema annotate  --target mydb --use-llm       # AI-generated descriptions
rdst schema show      --target mydb                 # review
rdst schema edit      --target mydb                 # hand-edit in $EDITOR
rdst schema refresh   --target mydb                 # pick up new indexes, keep annotations
rdst schema profile   --target mydb                 # collect column stats (nulls, distinct, top values)
rdst schema export    --target mydb --format yaml   # export for source control
rdst schema list                                     # list all configured semantic layers
rdst schema delete    --target mydb
```

## Query registry

The [query registry](/readyset-ai/rdst/cli/concepts#the-query-registry) is RDST's local catalog of
SQL queries. It's populated automatically by `rdst top`, `rdst scan`, and
`rdst analyze --save-as`. Browse it through the CLI:

```bash
rdst query list                    # list all saved queries
rdst query list --filter "users"   # filter by text
rdst query show <hash-or-name>     # show SQL and metadata
rdst query add <name> -q "SQL..."  # manually add
rdst query import -f file.sql      # bulk import from a .sql file
rdst query edit <name>             # edit in $EDITOR
rdst query delete <hash-or-name>   # remove
```

### Running queries for load generation

```bash
# Round-robin run 500 executions of a saved query
rdst query run my-saved-query --target prod-orders --count 500

# Sustained 10 concurrent executions for 2 minutes
rdst query run my-saved-query --target prod-orders -c 10 --duration 120

# Run a CSV of queries through the target
rdst query run --file queries.csv --target prod-orders --duration 300
```

Use [`rdst query cache-compare`](/readyset-ai/rdst/cli/cache/compare) for the benchmarking variant
that compares upstream against a Readyset cache.

## Audit and fleet snapshots

Every audit and fleet-audit run is persisted. Manage them through the CLI:

```bash
rdst audit list                                 # past single-target audits
rdst audit show <run_id>                        # view a saved audit
rdst fleet snapshots                            # past fleet audits
rdst fleet diff snap1 snap2                     # compare two snapshots
```

See [Snapshots and diff](/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff) for patterns.

## Environment variables

| Variable                                                             | Used by                                                  | Purpose                                                     |
| -------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| `ANTHROPIC_API_KEY`                                                  | Most commands                                            | Anthropic API key, subject to the saved provider preference |
| `<YOUR_TARGET>_PASSWORD`                                             | Every target                                             | Whatever name you set when adding the target                |
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION` | `rdst fleet discover`                                    | AWS credentials for RDS discovery                           |
| `AWS_PROFILE`                                                        | `rdst fleet discover`                                    | Alternative to explicit AWS keys (SSO/profiles)             |
| `EDITOR`                                                             | `rdst schema edit`, `rdst query edit`, `rdst guard edit` | Which editor to launch                                      |
| `RDST_DATA_DIR`                                                      | CLI and desktop backend                                  | Override the default local data directory                   |
| `RDST_LOG_LEVEL`                                                     | All commands                                             | `debug`, `info` (default), `warn`, `error`                  |

## Security model

### What gets sent to the LLM

| Data                                                | Sent?            | Notes                                                   |
| --------------------------------------------------- | ---------------- | ------------------------------------------------------- |
| Query text (SQL)                                    | yes              | May include real parameter values used during analysis  |
| EXPLAIN / EXPLAIN ANALYZE plans                     | yes              | Includes row estimates and operator details             |
| Schema metadata (table, column, index names, types) | yes              | For index and rewrite reasoning                         |
| Row count estimates                                 | yes              | For scale-aware recommendations                         |
| Semantic layer descriptions                         | yes (if present) | To improve NL-to-SQL and analysis quality               |
| Result rows                                         | **no**           | Query output is never sent to the LLM                   |
| Credentials                                         | **no**           | Passwords are only used to open the database connection |

### Review generated recommendations

RDST validates suggestions against schema context, but recommendations can vary.
Review rewrites and index definitions, and test them before deployment.

## Feedback and bug reports

File feedback directly from the CLI. RDST attaches your version, OS, and the most
recent error (without secrets) for context.

```bash
# Report an issue
rdst report --negative -r "Index suggestion was incorrect"

# Positive feedback
rdst report --positive -r "Great recommendation!"

# Include specific query context
rdst report --hash abc123 --include-query -r "Unexpected result"
```

| Flag                        | Purpose                                                |
| --------------------------- | ------------------------------------------------------ |
| `--hash <id>`               | Query hash to provide feedback on                      |
| `-r, --reason <text>`       | Description of the issue (or open a prompt if omitted) |
| `-e, --email <addr>`        | Email for follow-up                                    |
| `--positive` / `--negative` | Mark sentiment                                         |
| `--include-query`           | Include raw SQL                                        |
| `--include-plan`            | Include execution plan                                 |

## See also

* [Core concepts](/readyset-ai/rdst/cli/concepts): targets, the registry,
  and the semantic layer
* [Setting up a fleet](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup): bulk target import
  and AWS discovery


# Data Agents (/readyset-ai/rdst/cli/data-agents)
import { Callout } from 'fumadocs-ui/components/callout'

`rdst agent` and `rdst guard` are a pair of commands for exposing scoped,
read-only access to a database target, typically to a Slack bot, an HTTP client,
or an AI assistant, without handing out raw database credentials.

Use agents and guards when another user or service needs access through a
restricted interface. Configure the tables, query rules, and output masking
that interface requires.

## Guards

A **guard** is a reusable safety policy. Guards combine output masking, query-shape
requirements, cost limits, and runtime bounds:

```bash
rdst guard create --name pii-safe \
    --mask "*.email:email" \
    --require-where \
    --require-limit \
    --no-select-star \
    --max-rows 10000

rdst guard list
rdst guard show pii-safe
rdst guard check "SELECT * FROM users" --guard pii-safe
```

`rdst guard check` is a dry-run. It takes SQL and tells you whether the guard
would allow or reject it. Useful in CI to ensure the queries your application
generates will be accepted.

See `rdst guard --help` for the full flag set (masking types, required filters,
cost thresholds, natural-language `--intent`, and more).

## Agents

An **agent** binds a database target to a guard:

```bash
rdst agent create --name sales-bot \
    --target prod-orders \
    --guard pii-safe

rdst agent list
rdst agent chat --name sales-bot       # interactive terminal session
rdst agent serve --name sales-bot      # HTTP API
rdst agent slack --name sales-bot      # Slack bot (requires rdst slack setup first)
```

Every agent interaction runs through the guard before SQL is generated and again
before execution, so output masking and cost limits apply consistently across all
serving modes.

<Callout type="info">
  Agent serving modes, Slack app setup, and advanced guard policies are subject to
  change. Run `rdst agent --help` and `rdst guard --help` for the current flag
  surface before building anything on top.
</Callout>

## Code Scan

Use [rdst scan](/readyset-ai/rdst/cli/query-analysis/scan) to find ORM queries
in application source. The app's experimental Code Scan route is `/scan`; it's hidden from the sidebar. For CI, use the CLI's `--check` mode.

## See also

* [`rdst ask`](/readyset-ai/rdst/cli/query-analysis/ask): interactive natural-language SQL for
  the case where you don't need a guarded interface
* [Slack integration](/readyset-ai/rdst/cli/integrations/slack): Slack app setup, separate from
  attaching an agent to it


# Database permissions (/readyset-ai/rdst/cli/database-permissions)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

RDST CLI should connect with a dedicated read-only database user. Most features need
permission to connect, inspect the schema, and read the application tables you
want RDST to analyze. Live and historical workload monitoring need additional
access to server-wide statistics.

RDST doesn't run these `GRANT` statements for you. Ask a database administrator
to create the user, replace the example names, and limit it to the databases and
schemas you want RDST to inspect.

## Permissions by feature

| Feature                                     | PostgreSQL                                                                                      | MySQL                                                                                                                               |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Connect and test credentials                | `CONNECT` on the database                                                                       | Permission to connect to the server                                                                                                 |
| Schema, Analyze, Ask, and query execution   | `USAGE` on each schema and `SELECT` on the relevant tables and views                            | `SELECT` on the relevant database; `SHOW VIEW` when inspecting or explaining views                                                  |
| Realtime monitoring of this user's sessions | Baseline access                                                                                 | Baseline access                                                                                                                     |
| Realtime monitoring of all sessions         | Membership in `pg_read_all_stats`                                                               | Global `PROCESS`                                                                                                                    |
| Historical slow queries                     | `pg_stat_statements` enabled, plus `pg_read_all_stats` to see other users' query text           | `performance_schema` enabled and `SELECT` on `performance_schema.*`                                                                 |
| Health Check                                | Baseline access gives partial results; `pg_monitor` provides the most complete server-wide view | Baseline access gives partial results; `PROCESS`, Performance Schema access, and `REPLICATION CLIENT` provide more complete results |
| RDST cache deploy and compare               | Baseline query-read access; current RDST deployments use shallow caching                        | Baseline query-read access; current RDST deployments use shallow caching                                                            |
| Deep Readyset caching                       | Replication and database-administration setup described in the Readyset Cache guides            | Snapshot and replication setup described in the Readyset Cache guides                                                               |

<Callout type="info">
  Optional monitoring privileges expose query text and activity from other
  database users. If you omit them, RDST can still connect and analyze queries,
  but TOP and Health Check may show only RDST's own sessions or incomplete
  historical statistics. Some checks degrade to partial or empty results rather
  than returning an explicit permission error.
</Callout>

## Create a read-only user

<Tabs items={['PostgreSQL', 'MySQL']}>
  <Tab value="PostgreSQL">
    Run the following as an administrator. Replace `my_database`, `public`, and
    `app_owner` with the database, schema, and role that owns your application
    tables.

    ```sql
    CREATE ROLE rdst_readonly
      LOGIN
      PASSWORD 'replace_with_a_strong_password'
      NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;

    GRANT CONNECT ON DATABASE my_database TO rdst_readonly;

    -- Run the remaining statements while connected to my_database.
    GRANT USAGE ON SCHEMA public TO rdst_readonly;
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO rdst_readonly;

    -- Keep access when app_owner creates new tables in this schema.
    ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA public
      GRANT SELECT ON TABLES TO rdst_readonly;
    ```

    Repeat the schema grants for every application schema RDST should inspect.
    `ALTER DEFAULT PRIVILEGES` affects only objects subsequently created by the
    named owner, so repeat it for each role that creates tables.

    For complete workload monitoring, add the predefined statistics role:

    ```sql
    GRANT pg_read_all_stats TO rdst_readonly;
    ```

    For the most complete Health Check instead, grant `pg_monitor`, which
    includes `pg_read_all_stats` as well as access to additional settings and
    statistics. You don't need to grant both roles.

    ```sql
    GRANT pg_monitor TO rdst_readonly;
    ```

    A database administrator must also enable `pg_stat_statements` before RDST
    can show historical query statistics:

    ```sql
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    ```

    PostgreSQL may also require `pg_stat_statements` in
    `shared_preload_libraries`, which is a server or managed-service parameter
    rather than a user privilege.
  </Tab>

  <Tab value="MySQL">
    Run the following as an administrator. Replace `my_database` and the host
    pattern with the narrowest values that match the RDST machine.

    ```sql
    CREATE USER 'rdst_readonly'@'10.0.0.%'
      IDENTIFIED BY 'replace_with_a_strong_password';

    GRANT SELECT ON `my_database`.*
      TO 'rdst_readonly'@'10.0.0.%';
    ```

    If RDST must inspect or explain views, add:

    ```sql
    GRANT SHOW VIEW ON `my_database`.*
      TO 'rdst_readonly'@'10.0.0.%';
    ```

    For complete realtime and historical monitoring, add:

    ```sql
    -- Shows statements run by sessions belonging to other users.
    GRANT PROCESS ON *.* TO 'rdst_readonly'@'10.0.0.%';

    -- Reads statement digests and other diagnostic statistics.
    GRANT SELECT ON performance_schema.*
      TO 'rdst_readonly'@'10.0.0.%';

    -- Adds replication status to Health Check.
    GRANT REPLICATION CLIENT ON *.*
      TO 'rdst_readonly'@'10.0.0.%';
    ```

    Performance Schema statement instrumentation and the `statements_digest`
    consumer must also be enabled. Those are MySQL server settings; granting
    `SELECT` can't enable collection by itself.

    If you explicitly use TOP's MySQL slow-log source, also grant
    `SELECT ON mysql.slow_log` and configure the server with
    `slow_query_log=ON` and `log_output=TABLE`.
  </Tab>
</Tabs>

## Verify the account

After creating the user, connect with it and run a target test:

```bash
rdst configure test my-target
```

The test verifies connectivity and reports if RDST detects write privileges.
Then exercise the features you intend to use:

```bash
rdst schema refresh --target my-target
rdst top --target my-target --duration 10
rdst top --target my-target --historical
```

An empty or incomplete TOP result doesn't necessarily mean the database is
idle. It can mean the account can see only its own sessions, the statistics
extension is unavailable, or statement collection is disabled.

<Callout type="warn">
  `EXPLAIN ANALYZE` executes the query while collecting its plan and timing.
  Keep the account read-only, and use RDST's fast or schema-only analysis when
  executing a potentially expensive query isn't appropriate.
</Callout>

## Readyset caching uses different permissions

The grants above are sufficient for RDST's diagnostic, analysis, and current
shallow cache-deployment features. A deep Readyset deployment additionally
snapshots tables and follows the database replication stream, so it requires
broader upstream permissions and server configuration.

* [PostgreSQL Readyset Cache permissions](/cache/connect/postgres)
* [MySQL Readyset Cache permissions](/cache/connect/mysql)

Treat those as a separate deployment credential when possible. Don't add
replication or administrative privileges to a diagnostics-only RDST user unless
you're intentionally using it to deploy deep caching.

## Why least privilege matters

RDST applies query-safety checks and uses read-only sessions where configured,
but database permissions are the final enforcement boundary. Audit direct,
inherited, default, `PUBLIC`, and routine-execution privileges: a role that has
no direct table-write grant may still inherit broader access or invoke a
security-definer routine with side effects.

On MySQL, incomplete Performance Schema access can make unavailable index
counters look like zeroes, which may cause Health Check to report a false
"unused index" finding. Confirm permissions and collection settings before
acting on that recommendation.


# rdst audit (/readyset-ai/rdst/cli/fleet-and-audit/audit)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

`rdst audit` collects database metrics, query activity, and recommendations in
a one-off report. For ongoing reports, use
[Continuous monitoring](/readyset-ai/rdst/desktop/monitoring/nightly-report).

Use a read-only account and choose a capture window that suits the workload.

## Common usage

```bash
# Quick audit (no live capture)
rdst audit --target prod-orders

# Audit with a five-minute live capture of running queries
rdst audit --target prod-orders --duration 5m

# Print the full report to the terminal instead of emailing
rdst audit --target prod-orders --verbose

# Save under a friendly name for later diffing
rdst audit --target prod-orders --save march-baseline

# Compare today against an earlier baseline
rdst audit --target prod-orders --diff march-baseline

# JSON output for scripting
rdst audit --target prod-orders --json

# Skip LLM insights (faster, useful when you just want raw metrics)
rdst audit --target prod-orders --no-insights
```

## What the audit collects

<Tabs items={['Always', 'With --duration']}>
  <Tab value="Always">
    * **Database metrics**: version, database size, connection pool state, cache
      hit rate, read/write ratio
    * **Sizing assessment**: cross-references instance size and utilization to
      classify as `oversized`, `right-sized`, or `under-provisioned`
    * **Cache opportunity score**: a 0 to 100 score for how much Readyset caching
      would likely help, driven by query mix and cacheability
    * **Top queries**: ranked by total time and call frequency, with EXPLAIN plans
      and rewrite suggestions
    * **LLM insights**: structured health summary, bottleneck analysis, index
      recommendations, Readyset candidates, prioritized next steps
  </Tab>

  <Tab value="With --duration">
    Everything above, plus:

    * **Live query capture**: RDST watches `pg_stat_activity` or the MySQL
      equivalent for the entire window. Queries observed during sampling are captured with
      wall-clock duration.
    * **Time-series patterns**: how query patterns change across the window (e.g.,
      batch jobs kicking off at :00)
    * **Captured-query insights**: the LLM analyzes the actual running workload,
      not just historical stats. Use it to compare active work with cumulative statistics.
  </Tab>
</Tabs>

## The email-first flow

By default, RDST emails you the full HTML report and prints an actionable terminal
summary. This is how it works:

```text
$ rdst audit --target prod-orders

This is your first audit on this machine.
Enter your email:  ellen@example.com
We sent a verification link to ellen@example.com. Click the link to continue ...
  Waiting for verification ... ✓ Email verified.

Running audit on prod-orders ...
  ✓ Metrics collected
  ✓ Top queries ranked
  ✓ LLM insights generated
  ✓ Snapshot saved as audit_prod-orders_20260421_120402

Audit Summary  -  prod-orders
────────────────────────────────────────────────────────────────
  Size:                  482 GB  →  right-sized
  Cache opportunity:     82/100  (HIGH)
  Top query:             SELECT * FROM orders WHERE customer_id = $1 ...
                         4.8k calls, 412ms avg
  Biggest win:           Deploy Readyset cache for hash a1b2c3d4e5f6
                         ↳ rdst cache deploy --target prod-orders --mode docker
                         ↳ rdst cache add a1b2c3d4e5f6 --target prod-orders-cache

Full report emailed to ellen@example.com
  → View Full Report: https://rdst.readyset.io/audit/01HY...
```

<Callout type="info">
  The terminal summary includes commands for analyzing queries and testing
  caching candidates. Follow those links in the report or use the printed
  query hashes in your next command.
</Callout>

Later runs skip the verification step:

```text
$ rdst audit --target prod-orders --duration 2m

Running audit on prod-orders (capturing queries for 2m) ...
  [==========================================================] 120/120s
  ✓ Captured 4,837 query executions
  ✓ LLM insights generated
  ✓ Snapshot saved as audit_prod-orders_20260421_154212

Full report emailed to ellen@example.com.
```

### Print to terminal instead with `--verbose`

```bash
rdst audit --target prod-orders --verbose
```

`--verbose` skips the email flow entirely and prints the full report inline as Rich
panels. The snapshot is still saved. There's no separate `--no-email` flag, verbose
*is* the no-email mode.

## Capturing a live workload

Use `--duration` to sample running queries alongside cumulative statistics.
Sampling can miss queries that finish between readings.

```bash
# Quick smoke test
rdst audit --target prod-orders --duration 30s

# Representative workload capture
rdst audit --target prod-orders --duration 5m

# Long capture across a batch window
rdst audit --target prod-orders --duration 1h
```

<Callout type="warn">
  Live capture reads `pg_stat_activity` (Postgres) or `SHOW FULL PROCESSLIST`
  (MySQL) every few seconds. Both are already-running internal views, so the
  overhead on the database is minimal. Even so, generate application load *into*
  the database while the capture is running, a 5-minute capture of an idle
  database tells you very little.
</Callout>

### Captured queries are benchmarked against a Readyset cache

During `--duration`, RDST also runs a built-in benchmark. If a
[Readyset cache is deployed](/readyset-ai/rdst/cli/cache/deploy) for the target (`<target>-cache`
exists), the captured queries are added to that cache and run against it. If no
cache is deployed, RDST offers to spin up a local Docker cache for the benchmark,
cache the captured queries there, and tear it down after the audit.

The result is a head-to-head performance block in the audit report: you see the
upstream latency for each captured query alongside the latency through Readyset,
without having to set any of this up manually.

```text
Captured Query Benchmark  -  5m window, 2,847 executions across 18 query shapes
──────────────────────────────────────────────────────────────────────────────────
  Hash      Calls   Upstream avg   Cache avg    Speedup   Cached?
  ────────  ──────  ─────────────  ───────────  ────────  ─────────
  a1b2c3d4    834        412.1 ms      13.2 ms       31x   ✓
  f6e5d4c3    217        139.6 ms       9.8 ms       14x   ✓
  9a8b7c6d  1,204          1.6 ms       0.9 ms      1.8x   ✓
  4d3c2b1a    312         74.1 ms       -                -     ✗ not cacheable
  ...

Cache verdict
  ✓ 5 of 18 captured queries would produce substantial speedups if cached
     (total time saved ≈ 3m 42s over the 5m window).
  ✗ 3 queries are not cacheable in Readyset today (non-deterministic functions,
     unsupported SQL features)  -  see per-query notes.
```

The same numbers drive the Readyset cache opportunity score at the top of the
report. You can verify any individual line with `rdst query cache-compare <hash> --target <name>` afterward.

## Diffing against a baseline

Use `--save <name>` to name a snapshot, then `--diff <name>` later to compare:

```bash
# Today: save a baseline
rdst audit --target prod-orders --duration 5m --save march-baseline

# Next month: compare against it
rdst audit --target prod-orders --duration 5m --diff march-baseline
```

The diff report highlights:

* Metrics that changed (database size, connection count, cache hit rate)
* Queries that got slower (and by how much)
* New top queries that weren't in the baseline
* Changes to the Readyset cache opportunity score
* Schema changes (new tables, dropped indexes, etc.)

See [Snapshots and diff](/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff) for more patterns.

## Exports

The audit report is the headline output, but for ad-hoc investigation you can also
extract the raw query text:

| Flag                        | Exports                                                 |
| --------------------------- | ------------------------------------------------------- |
| `--export-queries`          | Captured queries *or* top queries (whichever is richer) |
| `--export-top-queries`      | Cumulative top queries from stats only                  |
| `--export-captured-queries` | Queries captured during a `--duration` window only      |

Each flag produces a CSV with full query text, parameters, timing, and source file
info where available.

## Flags reference

| Flag                                          | What it does                                           |
| --------------------------------------------- | ------------------------------------------------------ |
| `-t, --target <name>`                         | Target database                                        |
| `--duration <spec>`                           | Live capture window (e.g. `30s`, `5m`, `1h`)           |
| `--source {auto,pg_stat_statements,activity}` | Override where to read from                            |
| `--limit <N>`                                 | Top-N queries to include in LLM analysis (default 50)  |
| `--no-insights`                               | Skip LLM analysis (faster; metrics + top queries only) |
| `--save <name>`                               | Save the snapshot under a friendly name                |
| `--no-save`                                   | Don't persist the snapshot                             |
| `--diff <baseline>`                           | Compare this run against a saved snapshot              |
| `--export-queries`                            | Export top or captured queries to CSV                  |
| `--export-top-queries`                        | Export cumulative top queries only                     |
| `--export-captured-queries`                   | Export only the `--duration` capture                   |
| `--json`                                      | JSON output (for scripting)                            |
| `-y, --yes`                                   | Auto-accept any cache-deploy prompts                   |
| `--verbose`                                   | Print full report to terminal instead of emailing      |

## Audit subcommands

```bash
rdst audit list                           # all past audit runs
rdst audit list --target prod-orders      # only runs for a specific target
rdst audit show audit_prod-orders_...     # view a saved audit
rdst audit show <run_id> --export-captured-queries
```

See [Snapshots and diff](/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff) for the full
snapshot lifecycle.

## See also

* [Setting up a fleet](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup): so you can run audits
  against more than one target at a time
* [`rdst fleet audit`](/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit): the same workflow,
  fanned out concurrently
* [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy): the natural next step after an audit
  recommends Readyset caching


# rdst fleet audit (/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit)
import { Callout } from 'fumadocs-ui/components/callout'

`rdst fleet audit` runs the same analysis as [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit)
against every target in your fleet, concurrently. The fleet report shows which queries could benefit from Readyset across
instances and estimates the cost savings. It also summarizes your fleet's health.

## Common usage

```bash
# Audit every target in the fleet
rdst fleet audit

# Audit one group (e.g. an Aurora cluster)
rdst fleet audit --group orders-prod

# Filter by tag
rdst fleet audit --tag aurora --tag writer

# Capture live workloads (per target)
rdst fleet audit --duration 5m

# Save a named fleet snapshot
rdst fleet audit --save march-baseline

# Compare against an earlier snapshot
rdst fleet audit --diff march-baseline
```

## What you get back

The audit produces two things:

1. **One per-target audit report** (same format as `rdst audit --target X`, emailed
   separately per target by default)
2. **A fleet-level summary** with cross-instance analysis

### Example fleet summary

```text
Fleet Audit Summary  -  2026-04-21
────────────────────────────────────────────────────────────────
  Fleet:                12 targets audited (group: orders-prod)
  Capture window:       5 minutes
  Duration:             4m 12s concurrent

  Health:
    Right-sized:        8
    Oversized:          3   (review capacity)
    Under-provisioned:  1   ⚠  prod-orders-writer hitting 94% CPU

  Readyset opportunity (fleet-wide):
    High (80+):         5 targets
    Medium (50-79):     4 targets
    Low (<50):          3 targets

  Top cross-instance recommendations:
    1. 7 of 12 instances run similar `SELECT * FROM orders WHERE ...` query.
       Deploy a Readyset cache once at the cluster level instead of 7 times.
       Estimated combined savings: 31s/min saved across the fleet.

    2. Missing index on customers(segment, created_at) recurs in 9 targets.
       Propagate the same fix to the whole cluster.

  Per-target actions:
    ✓ prod-orders-writer      → rdst audit show audit_prod-orders-writer_...
    ✓ prod-orders-reader-1    → rdst audit show audit_prod-orders-reader-1_...
    ✓ prod-orders-reader-2    → rdst audit show audit_prod-orders-reader-2_...
    ...

Full reports emailed to ellen@example.com.
Fleet snapshot saved: fleet_snapshot_orders-prod_20260421_120402
```

## How concurrency works

`rdst fleet audit` audits targets in parallel, typically with a small per-target
concurrency limit to avoid hammering your network or exhausting LLM rate limits.
RDST manages the pool for you. You don't need to tune it manually.

Large fleets take time. Use a small group first to measure audit time for your network and databases.

<Callout type="info">
  If you're worried about timing, start with `rdst fleet audit --group <small-group>`
  to audit a handful of targets first, then expand. You can always audit subsets.
</Callout>

## Filtering the fleet

Every fleet command supports the same filters:

```bash
# By group (typically a cluster or environment)
rdst fleet audit --group orders-prod

# By tag (repeatable: multiple tags AND together)
rdst fleet audit --tag aurora --tag writer

# By group AND tag
rdst fleet audit --group orders-prod --tag reader
```

If you aren't sure what groups and tags exist, `rdst fleet list` shows them all.

## Fleet-wide insights vs per-target

The fleet summary answers questions you can't answer one database at a time:

* **"Which databases would most benefit from Readyset?"**: The summary
  ranks Readyset opportunity fleet-wide, so you cache the top few instead of hunting
  manually.
* **"Is this index missing everywhere, or just here?"**: Cross-instance
  recommendations surface patterns that repeat across many databases, so you fix
  them at the cluster level.
* **"Are we over-provisioning?"**: Sizing verdicts across the fleet, with
  capacity recommendations for oversized instances.
* **"Did anything regress this month?"**: `--diff <baseline>` highlights every
  target where metrics, top queries, or cache opportunity scores changed
  significantly.

## The email flow

Like `rdst audit`, the default output is email. The first fleet audit prompts for
email verification, then sends:

* One email per target with the per-target HTML report
* One email with the fleet summary and links to all per-target reports

Use `--verbose` to print everything to the terminal instead. `--json` produces a
single machine-readable fleet report.

## Flags reference

| Flag                | What it does                                        |
| ------------------- | --------------------------------------------------- |
| `--group <name>`    | Only audit targets in this group                    |
| `--tag <tag>`       | Only audit targets with this tag (repeatable)       |
| `--duration <spec>` | Per-target live capture window (e.g. `2m`, `5m`)    |
| `--save <name>`     | Save the fleet snapshot under a friendly name       |
| `--no-save`         | Don't persist the snapshot                          |
| `--diff <baseline>` | Compare against a saved fleet snapshot              |
| `--no-insights`     | Skip LLM analysis (faster; per-target metrics only) |
| `--json`            | JSON output                                         |
| `-y, --yes`         | Auto-accept any cache-deploy prompts                |

## A complete workflow

Going from zero to a fleet audit on day one:

```bash
# 1. Discover
rdst fleet discover --regions us-east-1

# 2. Verify connectivity
rdst fleet status

# 3. Audit with a 5-minute capture
rdst fleet audit --duration 5m --save baseline-2026-q2

# 4. Act on the top cross-instance recommendation
rdst analyze --hash <from-report> --target <top-candidate>
rdst cache deploy --target <top-candidate> --mode docker
rdst cache add <hash> --target <top-candidate>-cache

# 5. Three months later, measure progress
rdst fleet audit --duration 5m --diff baseline-2026-q2
```

## See also

* [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit): the per-target command. Start here
  if you want to learn the audit format against one database.
* [Setting up a fleet](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup): build your fleet list
  before running fleet audits.
* [Snapshots and diff](/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff): how to use
  `--save` / `--diff` effectively.


# Setting up a fleet (/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Step, Steps } from 'fumadocs-ui/components/steps'

Before you can run `rdst fleet audit`, you need a fleet. RDST gives you three ways
to build one:

| Path               | When to use                                 | Command                                   |
| ------------------ | ------------------------------------------- | ----------------------------------------- |
| AWS discovery      | Your databases are AWS RDS / Aurora         | `rdst fleet discover --regions us-east-1` |
| CSV import         | You've a list of databases in a spreadsheet | `rdst fleet import --from fleet.csv`      |
| Interactive wizard | You want guided setup                       | `rdst fleet configure`                    |

## Option A: AWS discovery

`rdst fleet discover` calls the AWS RDS API and registers every RDS instance and
Aurora cluster it finds. Use it to import connection metadata from AWS.

<Steps>
  <Step>
    **Set up AWS credentials** if you've not already:

    <Tabs items={['SSO (recommended)', 'Access keys']}>
      <Tab value="SSO (recommended)">
        ```bash
        aws configure sso
        aws sts get-caller-identity   # verify
        ```
      </Tab>

      <Tab value="Access keys">
        ```bash
        export AWS_ACCESS_KEY_ID="AKIA..."
        export AWS_SECRET_ACCESS_KEY="..."
        export AWS_DEFAULT_REGION=us-east-1
        aws sts get-caller-identity   # verify
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    **Run discovery:**

    ```bash
    rdst fleet discover --regions us-east-1,us-west-2
    ```

    Use `--name-pattern` to scope to specific instance names, and
    `--engine-filter postgresql` or `mysql` to filter by engine.
  </Step>

  <Step>
    **Set credentials when prompted:**

    * `[1] Shared password`: one password for all discovered instances
    * `[2] Individual`: set user/password per instance
    * `[3] Skip`: register targets without credentials (configure later)
  </Step>

  <Step>
    **Export the password env vars RDST prints.** Discovery outputs a set of
    `export FOO_PASS=...` lines you need to run in your shell. Passwords saved in a working OS keychain persist across
    sessions. Otherwise, set the environment variables in each session.
  </Step>
</Steps>

### What Aurora clusters look like after discovery

For every Aurora cluster, discovery creates:

| Target                 | Endpoint                | Tags               |
| ---------------------- | ----------------------- | ------------------ |
| `<cluster>-writer`     | Cluster writer endpoint | `aurora`, `writer` |
| `<cluster>-reader-<n>` | Each reader instance    | `aurora`, `reader` |

All instances from one cluster share the same `group`, so you can audit just that
cluster with `rdst fleet audit --group <cluster-name>`.

### Flags

| Flag                                     | Purpose                                       |
| ---------------------------------------- | --------------------------------------------- |
| `--regions <list>`                       | Comma-separated AWS regions                   |
| `--engine-filter {postgresql,mysql,all}` | Filter by engine                              |
| `--name-pattern <glob>`                  | Only discover instance names matching a glob  |
| `--password-env <var>`                   | Env var for all discovered targets' passwords |
| `--user <username>`                      | Override default DB user                      |
| `--group <name>`                         | Assign all discovered targets to one group    |
| `--dry-run`                              | Preview without saving                        |

## Option B: CSV import

```bash
rdst fleet import --from ./fleet.csv --password-env FLEET_PASS
```

### CSV format

Each row must include `name`, `host`, and `engine`.

You can also set the connection's `port`, `database`, and `user`. Use `group` and
`tags` to organize targets. Set `password_env` or `password_secret_arn` to tell
RDST where to read the password.

```csv title="fleet.csv"
name,host,engine,port,database,user,group,tags,password_env
prod-orders,db1.example.com,postgresql,5432,orders,rdst_ro,orders-prod,pii,PROD_ORDERS_PASS
prod-inventory,db2.example.com,postgresql,5432,inventory,rdst_ro,inventory-prod,,PROD_INV_PASS
staging-orders,staging.example.com,postgresql,5432,orders,rdst_ro,staging,,STAGING_PASS
legacy-mysql,legacy.example.com,mysql,3306,appdb,rdst_ro,legacy,mysql,LEGACY_PASS
```

<Callout type="info">
  `tags` is a semicolon-separated list (`aurora;writer;pii`). `password_env` can be
  set per-row or left blank to fall back to the global `--password-env` value.
</Callout>

### Flags

| Flag                   | Purpose                                               |
| ---------------------- | ----------------------------------------------------- |
| `--from <csv>`         | Path to the CSV file                                  |
| `--password-env <var>` | Default env var for any row with blank `password_env` |
| `--group <name>`       | Assign all imported rows to one group (overrides CSV) |
| `--tag <tag>`          | Add a tag to all imported rows (repeatable)           |
| `--dry-run`            | Preview what would be imported                        |

## Option C: Interactive wizard

```bash
rdst fleet configure
```

Choose AWS discovery or CSV import from the menu and enter the requested fields.

## Listing and filtering the fleet

Once your fleet is populated:

```bash
# List every target
rdst fleet list

# Filter by group
rdst fleet list --group orders-prod

# Filter by tag
rdst fleet list --tag aurora --tag writer

# JSON output
rdst fleet list --json
```

## Changing a target's group or tags

Groups and tags are per-target attributes, so you change them through
[`rdst configure edit`](/readyset-ai/rdst/cli/configuration#targets):

```bash
# Move a target into a different group
rdst configure edit prod-orders-reader-2 --group orders-prod-readers

# Replace the tags on a target
rdst configure edit prod-orders-writer --tags aurora,writer,pii

# Clear a target's group (back to ungrouped)
rdst configure edit legacy-mysql --group ""
```

The change is local and takes effect immediately, every subsequent `rdst fleet
list --group ...` or `rdst fleet audit --group ...` will reflect it. There's no
bulk "move group" command; if you need to re-group several targets at once, loop
over them in your shell:

```bash
for name in prod-orders-reader-1 prod-orders-reader-2 prod-orders-reader-3; do
  rdst configure edit "$name" --group orders-prod-readers
done
```

## Checking connectivity

```bash
rdst fleet status
rdst fleet status --group orders-prod
```

`status` opens a connection to every target (or every filtered target) and prints
latency plus any errors. It's the first thing to run after import or discovery to
confirm passwords are exported and network paths are clear.

```text
Name                  Host                   Engine      Status     Latency
────────────────────  ─────────────────────  ──────────  ─────────  ────────
prod-orders           db1.example.com        postgresql  ✓ OK        12 ms
prod-inventory        db2.example.com        postgresql  ✓ OK        15 ms
staging-orders        staging.example.com    postgresql  ✓ OK        28 ms
legacy-mysql          legacy.example.com     mysql       ✗ FAILED     -
                      authentication failed (LEGACY_PASS not set)
```

## Using AWS Secrets Manager

If your passwords live in AWS Secrets Manager, set `password_secret_arn` on a target
(either in the CSV or during discovery). RDST will fetch the secret value at the
start of each session and cache it for the duration of the run.

```csv
name,host,engine,password_env,password_secret_arn
prod-orders,db1.example.com,postgresql,,arn:aws:secretsmanager:us-east-1:123...:secret:prod-orders
```

Precedence: `password_env` wins if both are set, so you can override with a local env
var when needed.

## See also

* [`rdst fleet audit`](/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit): once your fleet is
  populated, audit every target at once
* [Configuration: Targets](/readyset-ai/rdst/cli/configuration#targets): how individual targets
  are structured


# Fleet and Audit (/readyset-ai/rdst/cli/fleet-and-audit)
import { Callout } from 'fumadocs-ui/components/callout'
import { Cards, Card } from 'fumadocs-ui/components/card'

RDST has two complementary features for managing and auditing many databases:

* **Audit**: a deep health report for a single database target. Metrics, sizing
  verdict, Readyset cache opportunity score, top queries, live workload capture, and
  LLM insights in one command.
* **Fleet**: bulk management of multiple targets. Import from a CSV, discover from
  AWS, check connectivity across all of them, and run audits concurrently.

The two are designed to be used together: `rdst fleet discover` fills your target
list, then `rdst fleet audit` runs `rdst audit` against every target in parallel.

## What is a fleet?

A **fleet** is the set of database targets RDST knows about, scoped to the machine
it's installed on. There's no shared fleet across users or machines, everyone
manages their own list.

Fleets automatically exclude Readyset cache targets (those created by
`rdst cache deploy`). Fleet commands act on **upstream databases only**.

Targets in a fleet can be organized with:

| Dimension | Example                             | Set by                                                  |
| --------- | ----------------------------------- | ------------------------------------------------------- |
| **Group** | `orders-prod`, `staging`            | `--group` on import/discover, or `rdst fleet configure` |
| **Tag**   | `aurora`, `writer`, `pii-sensitive` | `--tag` on import/discover                              |

You can filter most fleet commands by group or tag:

```bash
rdst fleet list    --group orders-prod
rdst fleet status  --group orders-prod
rdst fleet audit   --group orders-prod --duration 5m
rdst fleet audit   --tag aurora --tag writer
```

<Callout type="info">
  Aurora clusters discovered with `rdst fleet discover` are automatically grouped by
  cluster name and tagged `aurora` plus `writer` or `reader` per instance endpoint.
</Callout>

## Single vs fleet audit

`rdst audit` and `rdst fleet audit` produce the **same per-target report**. The
differences are:

|                | `rdst audit`                                     | `rdst fleet audit`                                                         |
| -------------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
| Targets        | One (`--target`)                                 | Many (every fleet member, or filtered by `--group` / `--tag`)              |
| Execution      | Sequential                                       | Concurrent                                                                 |
| Snapshot       | Single-target snapshot                           | Fleet snapshot grouping every target's report                              |
| Extra insights | None                                             | Fleet-wide summary (cross-instance Readyset candidates, estimated savings) |
| Output         | Emailed report (default) or `--verbose` terminal | Same, plus a fleet summary                                                 |

Start with `rdst audit --target <name>` to learn the workflow against one database,
then use `rdst fleet audit` for the configured fleet.

## The audit report

Every audit report contains:

| Section                              | What it tells you                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Metrics**                          | Database version, size, connection count, cache hit rate, read/write ratio                                 |
| **Sizing verdict**                   | `oversized`, `right-sized`, or `under-provisioned` (driven by pricing + utilization)                       |
| **Cache opportunity score**          | 0 to 100 rating for Readyset candidacy, based on query mix and cacheability                                |
| **Top queries**                      | Ranked by total time and call frequency, each with EXPLAIN context                                         |
| **Live capture** (with `--duration`) | Queries RDST saw actually running during the window                                                        |
| **LLM insights**                     | Health assessment, bottleneck analysis, index recommendations, Readyset candidates, prioritized next steps |

<Callout type="info">
  The audit report is **emailed by default**. The first `rdst audit` on a new
  machine prompts you to verify an email address. Every subsequent audit sends
  there automatically with a link to a hosted HTML version. Use `--verbose` to
  print the report to the terminal instead.
</Callout>

## Sections in this guide

<Cards>
  <Card title="rdst audit" href="/readyset-ai/rdst/cli/fleet-and-audit/audit" description="Audit one database and capture its live workload. Compare past runs, export the results, or receive the report by email." />

  <Card title="Setting up a fleet" href="/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup" description="Import from CSV, discover from AWS, configure groups and credentials." />

  <Card title="rdst fleet audit" href="/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit" description="Audit every target in a fleet concurrently. Filter by group or tag." />

  <Card title="Snapshots and diff" href="/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff" description="Revisit past audits, compare across time, and track changes to your fleet." />
</Cards>


# Snapshots and diff (/readyset-ai/rdst/cli/fleet-and-audit/snapshots-and-diff)
import { Callout } from 'fumadocs-ui/components/callout'

Every `rdst audit` and `rdst fleet audit` run is persisted as a **snapshot**, whether
you used the default email flow or `--verbose`. Snapshots are the foundation of
historical comparison, diffing today's audit against last month's tells you whether
things are getting better or worse.

## Single-target snapshots

Every `rdst audit` run gets a unique run ID (e.g. `audit_prod-orders_20260421_120402`).

```bash
# List past audits for any target
rdst audit list

# List for one target
rdst audit list --target prod-orders

# View a past audit
rdst audit show audit_prod-orders_20260421_120402

# Export the captured queries from a past run
rdst audit show audit_prod-orders_20260421_120402 --export-captured-queries
```

`rdst audit show` prints the same report the original run produced. It doesn't
re-run anything, so it's safe to invoke against very old snapshots.

## Named baselines

For anything you plan to compare against later, give it a readable name with
`--save <name>`:

```bash
# March: save a baseline
rdst audit --target prod-orders --duration 5m --save march-baseline

# April: compare against it
rdst audit --target prod-orders --duration 5m --diff march-baseline
```

The diff output highlights:

| What changed               | How it's shown                                       |
| -------------------------- | ---------------------------------------------------- |
| Database size              | `+18 GB` (`4% growth`)                               |
| Connection pool state      | new peak `active_connections: 142 → 184`             |
| Cache hit rate             | `97.2% → 94.8%  ⚠`                                   |
| Top-query latency          | per-query `avg_time` deltas, with winners and losers |
| New queries                | queries that weren't in the baseline at all          |
| Missing queries            | queries that were in the baseline but dropped out    |
| Readyset opportunity score | `78 → 84` (up 6)                                     |
| LLM insight drift          | "new bottleneck" / "resolved" annotations            |

## Fleet snapshots

`rdst fleet audit` produces a **fleet snapshot**: a single snapshot containing every
target's per-target snapshot plus the fleet-wide summary.

```bash
# List all saved fleet snapshots
rdst fleet snapshots

# Save a named fleet snapshot
rdst fleet audit --duration 5m --save baseline-2026-q2

# Diff two fleet snapshots
rdst fleet diff baseline-2026-q1 baseline-2026-q2
```

### Fleet diff output

```text
Fleet Diff  -  baseline-2026-q1 → baseline-2026-q2
────────────────────────────────────────────────────────────────
  Fleet changes:
    + 2 targets added      (prod-newcluster-writer, prod-newcluster-reader-1)
    - 1 target removed     (legacy-mysql)
    Net: 11 → 12 targets

  Cross-instance patterns:
    RESOLVED:  customers(segment, created_at) index now deployed on 9/12 targets
               (was 0/11 in baseline)
    NEW:       orders.total_cents growth 840% on prod-orders-writer (5GB → 47GB)

  Readyset opportunity deltas:
    prod-orders-writer      78 → 92   (up)    ← cache even more helpful now
    prod-inventory-writer   52 → 38   (down)  ← workload shifted away from cacheables

  Sizing verdict changes:
    staging-orders          oversized → right-sized   (capacity changed)

  Per-target diffs:  (see `rdst audit show <run_id>` for each)
```

## Patterns that work well

**Quarterly baselines**: Save a named snapshot every quarter, keep a growing audit
trail of how the fleet evolved.

```bash
rdst fleet audit --duration 5m --save baseline-2026-q4
```

**Before-and-after changes**: Save a baseline before a big database change, re-audit
after, and diff.

```bash
rdst audit --target prod-orders --duration 5m --save before-index-migration
# ... deploy the migration ...
rdst audit --target prod-orders --duration 5m --diff before-index-migration
```

**CI for sizing drift**: Run a nightly fleet audit with `--json` and alert on
targets that flip from `right-sized` to `under-provisioned` overnight.

```bash
rdst fleet audit --duration 1m --json --no-insights > /tmp/fleet.json
# diff against yesterday's file, alert on any sizing-verdict regressions
```

<Callout type="info">
  `--no-insights` makes a nightly fleet audit much cheaper (skips the LLM step)
  while still producing metrics, sizing, and top-queries data, enough for
  monitoring.
</Callout>

## Snapshot commands

Use these commands to list, read, and compare snapshots:

|             | Single-target audit                                                 | Fleet audit                                                     |
| ----------- | ------------------------------------------------------------------- | --------------------------------------------------------------- |
| What it's   | One snapshot per target per run                                     | One snapshot containing N per-target snapshots                  |
| Listed with | `rdst audit list`                                                   | `rdst fleet snapshots`                                          |
| Shown with  | `rdst audit show <run_id>`                                          | `rdst audit show <target_run_id>` (for one target)              |
| Diffed with | `rdst audit --diff <baseline>` (re-runs a fresh audit and compares) | `rdst fleet diff snap1 snap2` (compares two existing snapshots) |

## See also

* [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit): where single-target snapshots come
  from
* [`rdst fleet audit`](/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit): where fleet snapshots
  come from


# Getting Started (/readyset-ai/rdst/cli/getting-started)
import { Callout } from 'fumadocs-ui/components/callout'
import { Cards, Card } from 'fumadocs-ui/components/card'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Step, Steps } from 'fumadocs-ui/components/steps'

Install the CLI, configure a target, then run the commands below. For Continuous
monitoring, use the [desktop setup](/readyset-ai/rdst/desktop/install).

## Requirements

| Requirement | Notes                                                                     |
| ----------- | ------------------------------------------------------------------------- |
| Platform    | macOS or glibc-based Linux on x86\_64 or arm64                            |
| Downloader  | `curl` or `wget`                                                          |
| Database    | PostgreSQL 13+ or MySQL 8.0+                                              |
| LLM access  | A Readyset sign-in or your own Anthropic API key                          |
| Optional    | Docker for `rdst demo`, local Readyset cache deploys, and the guided tour |

RDST never writes to your primary database. It issues read-only diagnostic queries
(`EXPLAIN`, `EXPLAIN ANALYZE`, `pg_stat_statements`, `performance_schema`, and
`pg_stat_activity` or `SHOW PROCESSLIST` for live monitoring). Query text, plans,
and schema metadata are streamed to an LLM; result rows are never sent.

Use a dedicated read-only account. [Database
permissions](/readyset-ai/rdst/cli/database-permissions) lists the baseline grants
and the optional privileges needed to observe other users' query activity.

## Install

### Desktop app

Follow [desktop installation](/readyset-ai/rdst/desktop/install) for the tray
app and Continuous monitoring.

### Command line

<Tabs items={['Installer', 'Package managers']}>
  <Tab value="Installer">
    ```bash
    curl -fsSL https://downloads.readyset.io/packages/rdst-cli/install.sh | sh
    ```

    The installer uses user-owned directories and doesn't require sudo, pip, or a
    preinstalled Python. Open a new shell after installation.
  </Tab>

  <Tab value="Package managers">
    ```bash
    uv tool install rdst
    # or: pipx install rdst
    ```

    RDST leaves these installations under the control of their package manager.
  </Tab>
</Tabs>

Verify with `rdst version`.

Installer-managed RDST installations update when you request it. Check for or
install a release explicitly:

```bash
rdst update --check
rdst update
```

When the installed version is current, `rdst update` returns without replacing
the managed environment. For package-manager installations, use `uv tool upgrade rdst` or
`pipx upgrade rdst` instead.

## Run the setup wizard

```bash
rdst init
```

The wizard handles four things, in order:

<Steps>
  <Step>
    **AI access.** Sign in with `rdst account login` for hosted AI, or set your
    Anthropic key. See [Configuration](/readyset-ai/rdst/cli/configuration#llm-provider)
    for provider selection and usage limits.
  </Step>

  <Step>
    **Your first target.** Enter a short name (e.g. `prod-orders`), database type
    (`postgresql` or `mysql`), host, port, database name, and username. For the
    password, enter the **name** of an environment variable that holds it (e.g.
    `PROD_ORDERS_PASSWORD`). RDST records the variable name in its config. It can also read a password
    saved in the operating system's keychain.
  </Step>

  <Step>
    **Test the connection.** The wizard runs a read-only query to confirm the env
    var is set and the database is reachable.
  </Step>

  <Step>
    **Optionally deploy a local Readyset cache.** After the target is verified, the
    wizard offers to start a local Docker-based Readyset cache for it and register
    the resulting `<target>-cache` target. To deploy later, run
    [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy) later. Skipped automatically when the
    cache already exists, when the target is itself a Readyset target, or when
    you're not in an interactive terminal.
  </Step>
</Steps>

Export the password in your shell before running any command:

```bash
export PROD_ORDERS_PASSWORD='your-password'
```

<Callout type="info">
  If you want to try RDST without pointing at your own database, `rdst demo setup &&
    rdst demo load` spins up a local PostgreSQL container with a 2-million-row DBA
  StackExchange dataset. `rdst demo tour` walks you through every workflow against
  it.
</Callout>

## 1. Find your slow queries (`rdst top`)

```bash
rdst top --target prod-orders
```

`top` reads `pg_stat_activity` (Postgres) or `SHOW FULL PROCESSLIST` (MySQL) every
few seconds, groups identical query shapes together, and ranks them by total time
consumed. Pass `--historical` to read from `pg_stat_statements` or
`performance_schema` instead for totals since the last statistics reset.

```text
#   Hash          Total time   Calls    Avg time   Query
1   a1b2c3d4e5f6  00:04:17     4,812    53.4 ms    SELECT * FROM orders WHERE customer_id = $1 ORDER BY ...
2   f6e5d4c3b2a1  00:02:48     1,204    139.6 ms   SELECT o.*, c.name FROM orders o JOIN customers c ...
3   9a8b7c6d5e4f  00:01:22     51,003   1.6 ms     SELECT 1 FROM session_cache WHERE ...
```

Every query surfaced by `top` is saved to the [query
registry](/readyset-ai/rdst/cli/concepts#the-query-registry). The short hash in the first column is
what you hand to `rdst analyze --hash <id>` in the next step.

## 2. Analyze a slow query (`rdst analyze`)

```bash
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders
```

RDST runs `EXPLAIN` and `EXPLAIN ANALYZE` against the query, collects relevant
schema context (including index definitions and row estimates), and produces a
report with a performance rating, findings, candidate indexes and rewrites,
and a Readyset cache-fit score.

```text
Query Analysis: a1b2c3d4e5f6
  Performance:       FAIR (65/100)
  Execution time:    412.1 ms
  Rows examined:     2,847,201  (38.2% of orders)
  Scan efficiency:   INEFFICIENT

Key Issues
  • Full index scan on orders_created_at_idx; composite needed
  • Sort step: 41% of execution time

Index Recommendations
  1. CREATE INDEX idx_orders_status_created
       ON orders (status, created_at DESC)
       WHERE status = 'shipped';
     Expected impact: cuts scan ~90%, -300ms (~73%)

Readyset Cache Fit
  Candidate:        YES  (confidence: high)
  Next step:        rdst cache add a1b2c3d4e5f6 --target prod-orders-cache
```

## 3. Ask a question in plain English (`rdst ask`)

```bash
rdst ask "What were our top 10 customers by revenue last month?" --target prod-orders
```

RDST uses your schema, and your [semantic layer](/readyset-ai/rdst/cli/concepts#the-semantic-layer),
if configured, to generate a read-only, `LIMIT`-bounded SQL query, show it to you
for confirmation, execute it with a timeout, and render the result.

```text
Generated SQL:
  SELECT c.id, c.name, SUM(o.total_cents) AS revenue_cents
  FROM   customers c
  JOIN   orders    o ON o.customer_id = c.id
  WHERE  o.created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month')
    AND  o.created_at <  DATE_TRUNC('month', NOW())
  GROUP BY c.id, c.name
  ORDER BY revenue_cents DESC
  LIMIT 10;

Execute? [Y/n]
```

For ambiguous or multi-step questions, add `--agent` to let RDST explore the schema
iteratively before generating SQL.

## 4. Audit the database (`rdst audit`)

`rdst audit` collects database health, sizing, top queries, index coverage,
and caching recommendations in a one-off report.

```bash
rdst audit --target prod-orders --duration 5m
```

`--duration` tells RDST to also capture live queries for a five-minute window, then
deploy a local Readyset cache (in Docker) and run each captured query through both
the upstream database and the cache for comparison. The cache-fit section of the
report is then based on real measured performance, not just plan analysis.

<Callout type="info">
  **Default output is email.** The first `rdst audit` run on a new machine prompts
  you to verify an email address. Every subsequent audit sends the HTML report
  there automatically, with a link back to a hosted version. A terminal summary is
  printed either way so you always see actionable next-step commands inline. Pass
  `--verbose` to print the full report to the terminal instead of email.
</Callout>

Every audit is saved. Browse past runs with `rdst audit list`, open one with
`rdst audit show <run_id>`.

## 5. Deploy an application cache (`rdst cache`)

This step is optional. Benchmarking in the next step prepares its own sandbox.
To deploy a separate Readyset instance for application traffic, run:

```bash
rdst cache deploy --target prod-orders --mode docker
```

This starts a Readyset container, waits for it to become ready, and registers a
new RDST target named `prod-orders-cache`. Add the query from step 2 to the cache:

```bash
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache
```

## 6. Measure the impact (`rdst query cache-compare`)

```bash
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders --count 500 -c 10
```

This runs 500 executions of the query against the upstream database *and* against
a temporary Readyset sandbox, with 10 concurrent workers on each side, then prints a
side-by-side comparison:

```text
Resolving targets ...
  Upstream:  prod-orders        (PostgreSQL)
  Cache:     temporary Readyset sandbox

Running 500 executions per target, concurrency 10 ...
  [==============================] 500/500  upstream
  [==============================] 500/500  cache

Results
────────────────────────────────────────────────────────────────────
  Query: SELECT * FROM orders WHERE customer_id = $1 ORDER BY ...

                          Upstream        Cache         Improvement
  ─────────────────────── ─────────── ──────────────── ──────────────
  Total executions         500         500
  Total time               00:04:12    00:00:08
  Throughput               2.0 qps     62.5 qps        31x
  Avg latency              412 ms      13 ms           32x
  p50 latency              389 ms      11 ms           35x
  p95 latency              512 ms      18 ms           28x
  p99 latency              847 ms      41 ms           21x
  Errors                   0           0

Verdict
  ✓ Cache provides substantial latency and throughput improvements.
  ✓ Tail latency (p99) improves significantly, suggesting the cache absorbs
    variable load effectively.
```

## Command guides

<Cards>
  <Card title="Core Concepts" href="/readyset-ai/rdst/cli/concepts" description="Learn how RDST connects to databases and saves queries. Add schema context for AI analysis and see where Readyset caching fits." />

  <Card title="Query Analysis" href="/readyset-ai/rdst/cli/query-analysis" description="Choose a query command and look up how to use it." />

  <Card title="Fleet and Audit" href="/readyset-ai/rdst/cli/fleet-and-audit" description="Audit a single database or an entire fleet. Diff snapshots over time." />

  <Card title="Readyset Cache" href="/readyset-ai/rdst/cli/cache" description="Deploy Readyset and manage its cached queries. Measure how much faster queries run through the cache." />

  <Card title="Claude Code integration" href="/readyset-ai/rdst/cli/integrations/claude-code" description="Drive RDST from inside Claude Code over MCP." />
</Cards>

## Getting help without leaving your terminal

`rdst help` answers natural-language questions about RDST itself using RDST's
bundled documentation.

```bash
rdst help                           # show top-level commands and common patterns
rdst help "how do I analyze a query?"
rdst help "how do I find slow queries without running a benchmark?"
rdst help "how do I set up a cache for a MySQL target?"
```

With an LLM key configured, `rdst help` uses Anthropic's Haiku model to give a
tailored answer pulled from the bundled docs. **Without a key, it still works.** It falls back to a keyword search of the same docs and prints the most relevant
sections. Useful when you don't have `ANTHROPIC_API_KEY` set yet or haven't
signed in to Readyset.

## Troubleshooting

| Symptom                                             | Likely cause                                             | Fix                                                                         |
| --------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
| `rdst: command not found`                           | pip/uv bin directory not on `PATH`                       | Restart your shell, or add `~/.local/bin` to `PATH`                         |
| `Authentication failed` on any command              | Target's `password_env` points at an unexported variable | `export <VAR>=...` in the shell you run RDST from                           |
| `LLM timeout` on `rdst analyze`                     | Large EXPLAIN plan or a slow LLM round-trip              | Retry with `--fast` to skip `EXPLAIN ANALYZE`                               |
| `No AWS credentials found` on `rdst fleet discover` | AWS CLI or SSO session not configured                    | `aws configure sso` or export `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` |

If you hit something this table doesn't cover, run
[`rdst report`](/readyset-ai/rdst/cli/configuration#feedback-and-bug-reports) to send feedback with
your version, redacted config, and most recent error.


# RDST CLI (/readyset-ai/rdst/cli)
import { Cards, Card } from 'fumadocs-ui/components/card'

The RDST CLI supports query analysis, code scans, database audits, and Readyset
cache management. Use it for individual checks, scripts, and CI.

For always-on monitoring, start with the
[desktop app](/readyset-ai/rdst/desktop/monitoring). The CLI shares its targets,
saved queries, and analyses under the same operating system user.

`rdst top` runs a query sampler in your terminal. It doesn't start Continuous
monitoring or expose the Inbox. Configure those in the desktop app or
[rdst web](/readyset-ai/rdst/cli/integrations/web).

## What RDST is good for

| If you want to...                                                        | Reach for                                                                                       |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| See which queries are consuming the most database time right now         | [`rdst top`](/readyset-ai/rdst/cli/query-analysis/top)                                          |
| Get an full analysis of one query with index and rewrite recommendations | [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze)                                  |
| Ask a question in plain English and get safe, read-only SQL back         | [`rdst ask`](/readyset-ai/rdst/cli/query-analysis/ask)                                          |
| Find and analyze the SQL your application is actually generating         | [`rdst scan`](/readyset-ai/rdst/cli/query-analysis/scan)                                        |
| Get a single, health report for a database                               | [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit)                                     |
| Audit several databases in one run                                       | [`rdst fleet audit`](/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit)                         |
| Auto-discover your RDS and Aurora fleet                                  | [`rdst fleet discover`](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup)                      |
| Deploy a Readyset cache in front of a database                           | [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy)                                       |
| Compare upstream vs. cached query performance head-to-head               | [`rdst query cache-compare`](/readyset-ai/rdst/cli/cache/compare)                               |
| Let Claude Code or a Slack bot drive RDST for you                        | [Integrations](/readyset-ai/rdst/cli/integrations)                                              |
| Get an answer about how to use RDST itself without leaving your terminal | [`rdst help`](/readyset-ai/rdst/cli/getting-started#getting-help-without-leaving-your-terminal) |

## Command guides

<Cards>
  <Card title="Getting Started" href="/readyset-ai/rdst/cli/getting-started" description="Install RDST and walk through every core workflow against a real database." />

  <Card title="Core Concepts" href="/readyset-ai/rdst/cli/concepts" description="Learn how RDST connects to databases and saves queries. Add schema context for AI analysis and see where Readyset caching fits." />

  <Card title="Query Analysis" href="/readyset-ai/rdst/cli/query-analysis" description="Choose the query command for your task and see what it returns." />

  <Card title="Fleet and Audit" href="/readyset-ai/rdst/cli/fleet-and-audit" description="Audit a single database or an entire fleet. Capture live workloads. Diff across time." />

  <Card title="Readyset Cache" href="/readyset-ai/rdst/cli/cache" description="Deploy Readyset, add shallow caches, and benchmark upstream against cache." />

  <Card title="Integrations" href="/readyset-ai/rdst/cli/integrations" description="Drive RDST from Claude Code, Slack, or the browser-based web UI." />
</Cards>

## How RDST relates to the rest of Readyset

| Tool                    | Role                                                                    | Where it runs                          |
| ----------------------- | ----------------------------------------------------------------------- | -------------------------------------- |
| **Readyset**            | Real-time SQL cache for Postgres and MySQL                              | Alongside your database                |
| **Readyset QueryPilot** | Automated cache discovery and deployment on top of Readyset             | Readyset Cloud or self-hosted          |
| **RDST**                | Diagnose queries, audit databases, and optionally drive Readyset caches | Your laptop, CI, or a diagnostics host |


# Claude Code (/readyset-ai/rdst/cli/integrations/claude-code)
import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'

Run `rdst claude` to register RDST's MCP tools with Claude Code. The tools can
find queries, analyze SQL, deploy caches, and read audit snapshots.

The integration registers your installed RDST binary. It doesn't expose the
Continuous monitoring Inbox or nightly reports. Audit tools read one-off audit
snapshots.

## Add RDST to Claude Code

<Steps>
  <Step>
    Make sure RDST is [installed](/readyset-ai/rdst/cli/getting-started#install) and `rdst version` works.
  </Step>

  <Step>
    Register RDST with Claude Code:

    ```bash
    rdst claude
    ```

    This updates Claude Code's local config so it knows how to call your installed
    `rdst` binary. Everything stays on your machine.
  </Step>

  <Step>
    Restart Claude Code (or open a new session). The RDST tools will appear in the
    tool list.
  </Step>
</Steps>

To remove the integration later:

```bash
rdst claude remove
```

## What Claude Code can do with RDST

Once registered, Claude Code has tool access to the core RDST workflows:

| Tool                                                                             | What Claude can do                                 |
| -------------------------------------------------------------------------------- | -------------------------------------------------- |
| `rdst_configure_list` / `rdst_configure_add`                                     | Inspect or add database targets                    |
| `rdst_test_connection`                                                           | Verify a target is reachable                       |
| `rdst_top`                                                                       | Find the slowest queries (real-time or historical) |
| `rdst_query_list` / `rdst_query_add` / `rdst_query_delete`                       | Manage saved queries                               |
| `rdst_analyze`                                                                   | Analyze a query by hash, name, or inline SQL       |
| `rdst_schema`                                                                    | Inspect the semantic layer                         |
| `rdst_audit`                                                                     | Run a single-target audit                          |
| `rdst_audit_list` / `rdst_audit_show`                                            | Browse past audit snapshots                        |
| `rdst_fleet_list` / `rdst_fleet_status`                                          | List and check the fleet                           |
| `rdst_fleet_audit`                                                               | Run a fleet-wide audit                             |
| `rdst_fleet_snapshots` / `rdst_fleet_diff`                                       | Browse and compare fleet snapshots                 |
| `rdst_cache_deploy` / `rdst_cache_add` / `rdst_cache_show` / `rdst_cache_delete` | Deploy Readyset and manage caches                  |
| `rdst_scan`                                                                      | Scan a codebase for ORM queries                    |
| `rdst_agent_list` / `rdst_agent_create` / `rdst_agent_ask`                       | Manage data agents                                 |
| `rdst_help`                                                                      | Look up RDST documentation                         |

Review Claude Code's configured tool permissions before using database or
cache-management tools.

## Typical patterns

### Investigate a slow endpoint

> Our `/orders/recent` endpoint has gotten slow over the last week. Find the top
> queries on the `prod-orders` target, identify the ones that look like they
> correspond to that endpoint, and tell me which ones RDST thinks should go through
> a Readyset cache.

Claude will call `rdst_top`, filter the output, follow up with `rdst_analyze` on the
top candidates, and summarize the results.

### Review an audit snapshot

> Look at the most recent audit snapshot for `prod-orders`. Which recommended
> indexes would have the biggest impact if I shipped them today?

Claude calls `rdst_audit_list` to find the latest, then `rdst_audit_show` to read
the stored recommendations.

### Deploy a cache

> I ran `rdst audit` on `prod-orders` earlier. Walk through the top Readyset
> candidate: analyze it in depth, deploy Readyset, add the cache, and run a
> cache-compare to show me the impact.

Claude can read the audit, analyze the query, deploy Readyset, and add the cache.
The benchmark uses a separate temporary sandbox. Configure permissions for
deployment and cache changes before running them.

### Generate SQL from a product question

> What does our `status = 3` mean for orders? Check the semantic layer via
> `rdst_schema`: my guess is "shipped".

<Callout type="info">
  `rdst_ask` isn't exposed as an MCP tool. Use `rdst_schema` to inspect schema
  context, then review generated SQL with `rdst_analyze`. For interactive
  clarification, use [rdst ask](/readyset-ai/rdst/cli/query-analysis/ask).
</Callout>

## MCP tools vs a dedicated data agent

With `rdst claude`, Claude Code can configure database targets and analyze
queries. It can also run audits and manage caches.

For giving a **different** audience (a teammate, a non-engineer, an external
client) scoped, guarded access, use a [data agent](/readyset-ai/rdst/cli/data-agents) with
`rdst agent mcp --name <agent>` instead. That exposes a single, policy-checked
interface rather than the whole toolset.

## Security considerations

* Everything runs locally. RDST inherits your shell environment and uses the same
  configured targets, password environment variables, and LLM API key you would
  use from the CLI. No data crosses the network except your normal database
  connection and LLM API calls.
* Claude Code requires your approval before each tool call by default. Review your
  Claude Code tool permissions if you want to tighten or loosen this.
* Tool calls return the same structured analysis output the CLI produces, never
  raw row data.
* Configure approval rules for actions that deploy Readyset, add caches, or
  modify guards.

## Troubleshooting

| Symptom                                               | Likely cause                                                       | Fix                                                                                |
| ----------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| RDST tools don't appear                               | Claude Code wasn't restarted after `rdst claude`                   | Quit and relaunch Claude Code                                                      |
| Tools appear but do nothing                           | `rdst` binary on `PATH` differs between your shell and Claude Code | Re-run `rdst claude` from the same shell you launch Claude Code from               |
| Tools fail with `Authentication failed`               | Password env var isn't set in Claude Code's shell                  | Set the env var in your shell profile, then relaunch Claude Code                   |
| Tools fail with `LLM timeout`                         | `ANTHROPIC_API_KEY` missing in Claude Code's environment           | Check the saved AI provider, account sign-in, and key in Claude Code's environment |
| `rdst claude` reports success but tools still missing | Multiple Claude installations; config was written to the wrong one | Re-run `rdst claude` from inside the terminal session you launch Claude Code from  |

## See also

* [Data Agents](/readyset-ai/rdst/cli/data-agents): for scoped, guarded access patterns vs. full
  toolset exposure
* [Slack integration](/readyset-ai/rdst/cli/integrations/slack): the Slack equivalent for
  non-Claude users


# Integrations (/readyset-ai/rdst/cli/integrations)
import { Cards, Card } from 'fumadocs-ui/components/card'

RDST can be driven from places other than your terminal:

<Cards>
  <Card title="Claude Code" href="/readyset-ai/rdst/cli/integrations/claude-code" description="Add RDST to Claude Code so it can call top, analyze, audit, and cache commands directly." />

  <Card title="Slack" href="/readyset-ai/rdst/cli/integrations/slack" description="Deploy a Slack bot that answers natural-language database questions via Socket Mode." />

  <Card title="Web UI" href="/readyset-ai/rdst/cli/integrations/web" description="Start a local HTTP server that backs the RDST web client for a browser-based experience." />
</Cards>

## Choose an interface

| If you want...                                                | Use                                                           |
| ------------------------------------------------------------- | ------------------------------------------------------------- |
| Claude Code to run RDST commands for you                      | [Claude Code](/readyset-ai/rdst/cli/integrations/claude-code) |
| Your team to ask questions in Slack                           | [Slack](/readyset-ai/rdst/cli/integrations/slack)             |
| A browser-based alternative to the CLI                        | [Web UI](/readyset-ai/rdst/cli/integrations/web)              |
| A scoped, guarded database interface for an external consumer | [Data Agents](/readyset-ai/rdst/cli/data-agents)              |

Claude Code calls RDST's MCP tools. Slack uses a guarded data agent to answer
questions. Neither exposes the monitoring Inbox or nightly reports.

For the case where you want *guarded, audited* access (not the full RDST command
surface), see [Data Agents](/readyset-ai/rdst/cli/data-agents).


# Slack (/readyset-ai/rdst/cli/integrations/slack)
import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'

RDST can run as a Slack bot that answers natural-language database questions. The
bot uses [Socket Mode](https://api.slack.com/apis/connections/socket), so you do
**not** need a public URL, the bot connects outbound to Slack from wherever RDST is
running.

## Common usage

```bash
# One-time Slack app setup (interactive wizard)
rdst slack setup

# Start the bot for a specific agent
rdst slack start --agent sales-bot

# List configured agents
rdst slack list

# Check bot status
rdst slack status --agent sales-bot
```

This Slack bot answers data questions. It doesn't send monitoring alerts.
Monitoring notifications are configured in the
[desktop app](/readyset-ai/rdst/desktop/monitoring/notifications).

## How it works

The bot:

1. Reads messages directed at it (mentions, DMs) in channels it has access to
2. Routes each message through the underlying [data agent](/readyset-ai/rdst/cli/data-agents)
3. Generates SQL and runs the agent's [guard](/readyset-ai/rdst/cli/data-agents#guards)
4. Returns the result as a threaded reply with the SQL and data

No part of the flow requires a public URL or reverse proxy.

## Setup

<Steps>
  <Step>
    **Create a Slack app.** Run `rdst slack setup`: it walks you through creating
    a Slack app with the right scopes and enabling Socket Mode.

    ```bash
    rdst slack setup
    ```

    The wizard prints the OAuth scopes and event subscriptions you need, then asks
    for the App-Level Token and Bot User OAuth Token your Slack app issues.
  </Step>

  <Step>
    **Create a data agent** if you haven't already. This is what the bot will serve.

    ```bash
    rdst guard create --name pii-safe \
        --mask "*.email:email" \
        --require-where \
        --no-select-star

    rdst agent create --name sales-bot \
        --target prod-orders \
        --guard pii-safe \
        --description "Read-only sales data"
    ```

    See [Data Agents](/readyset-ai/rdst/cli/data-agents) for guard and agent patterns.
  </Step>

  <Step>
    **Start the bot.** This is a foreground process, keep it running in a
    terminal, a tmux pane, or a systemd service.

    ```bash
    rdst slack start --agent sales-bot
    ```

    ```text
    ✓ Connected to Slack as @sales-bot
    ✓ Socket Mode active
    ✓ Guard: pii-safe (7 rules)
    ✓ Target: prod-orders (PostgreSQL 15.4)

    Listening for messages ...
    ```
  </Step>

  <Step>
    **Invite the bot** to the channels where it should respond, then `@mention`
    or DM it with a question:

    > @sales-bot How many orders did we process last week?
  </Step>
</Steps>

<Callout type="info">
  For a production deployment, run `rdst slack start` under a process supervisor
  (systemd, pm2, Docker, Kubernetes) so it restarts on failure. The bot is
  stateless. You can restart it without losing any Slack state.
</Callout>

## What the bot replies look like

````text
ellen: @sales-bot top 5 customers by revenue this month

sales-bot:
  Generated SQL (ran via guard pii-safe ✓):
  ```sql
  SELECT c.id, c.name, SUM(o.total_cents) AS revenue_cents
  FROM   customers c
  JOIN   orders    o ON o.customer_id = c.id
  WHERE  o.created_at >= DATE_TRUNC('month', NOW())
    AND  o.status = 'paid'
    AND  o.tenant_id = $1
  GROUP BY c.id, c.name
  ORDER BY revenue_cents DESC
  LIMIT 5;
````

| id  | name               | revenue\_cents |
| --- | ------------------ | -------------- |
| 42  | Acme Manufacturing | 4,820,135      |
| 118 | Blue Orchid Foods  | 3,914,200      |
| 745 | Hendricks Retail   | 3,120,980      |
| ... |                    |                |

5 rows, 84 ms

````

Every reply shows the SQL, the guard that was applied, and the results. Users
never see raw upstream errors.

## Managing multiple agents

You can run **one Slack bot per agent**. Typical pattern:

```bash
# Customer-support team
rdst slack start --agent support-bot &

# Sales team
rdst slack start --agent sales-bot &

# Engineering dashboard
rdst slack start --agent eng-dashboard &
````

Each bot has its own app token and operates independently. List what's configured:

```bash
rdst slack list
rdst slack status --agent sales-bot
```

## Security considerations

* Every question runs through the agent's guard before SQL is generated and again
  before execution. Output masking applies automatically.
* Slack Socket Mode never exposes an inbound port. All traffic is outbound from the
  host running RDST.
* The Slack app tokens are managed by you. If a token leaks, revoke it in the Slack
  admin panel; the bot stops working immediately.
* Every question and its SQL are logged locally (for audit), but result **rows are
  not logged**: only the row count.

## Flags reference

| Command             | Flag                 | Purpose                              |
| ------------------- | -------------------- | ------------------------------------ |
| `rdst slack setup`  | :                    | Interactive setup wizard             |
| `rdst slack start`  | `-a, --agent <name>` | Agent to serve                       |
| `rdst slack list`   | :                    | List configured agents               |
| `rdst slack status` | `-a, --agent <name>` | Show connection status for one agent |

## See also

* [Data Agents](/readyset-ai/rdst/cli/data-agents): what the Slack bot is serving
* [Guards](/readyset-ai/rdst/cli/data-agents#guards): the safety policies that protect what users
  in Slack can see
* [`rdst ask`](/readyset-ai/rdst/cli/query-analysis/ask): the underlying NL-to-SQL engine the bot
  uses


# Web UI (/readyset-ai/rdst/cli/integrations/web)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

`rdst web` serves RDST's interface in a local browser. Use it for Continuous
monitoring when you can't install the desktop app. Keep the server running to
collect readings; a browser tab is only required for browser notifications.

The CLI and desktop app share targets, saved queries, and analyses under the
same operating system user. Run one monitoring backend for a data directory to
avoid duplicate background checks.

## Start the server

```bash
# Default: 127.0.0.1:8787
rdst web
```

Then open `http://localhost:8787/` in your browser.

### Other binding options

```bash
# Different port
rdst web --port 9000

# Bind to all interfaces (for remote access, see warning below)
rdst web --host 0.0.0.0 --port 8787
```

<Callout type="warn">
  The server binds to `127.0.0.1` by default so only your local browser can reach
  it. If you pass `--host 0.0.0.0`, the server is reachable from your whole
  network. The server has no authentication of its own, so make sure the port is
  not exposed to untrusted networks.
</Callout>

## Continuous monitoring in the browser

1. Open the local URL printed by `rdst web`.
2. [Connect a database](/readyset-ai/rdst/desktop/connect).
3. [Sign in to Readyset](/readyset-ai/rdst/desktop/ai-credits) for AI monitoring.
4. Open **Database** and [turn on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on).

The browser has the same Database, Inbox, Agent activity, Ask, and report
pages as the desktop app. It has no desktop tray or start-at-login controls.
To get pop-ups, enable **Browser notifications** and keep a tab open.

When your account's AI usage limit is reached, AI monitoring stops gracefully. Local
monitoring keeps running, and the app asks you to contact us.

## Shared data and startup

The default data directory is `~/.rdst`. Use `RDST_DATA_DIR` to select another
one. The first startup after an upgrade may take longer while files migrate.
Keep the installed CLI and desktop versions compatible.

## Deployment patterns

For local development the default `127.0.0.1:8787` binding is exactly what you
want. For shared team use, a few common patterns:

<Tabs items={['Shared host behind SSH', 'Docker', 'Systemd']}>
  <Tab value="Shared host behind SSH">
    Run `rdst web` on a bastion host and forward the port over SSH:

    ```bash
    # On the bastion, in a tmux session or similar:
    rdst web --host 127.0.0.1 --port 8787

    # On your laptop:
    ssh -L 8787:localhost:8787 bastion.example.com
    # Then open http://localhost:8787/
    ```

    Forwarding keeps authentication at the SSH layer, so the web server doesn't
    need to be exposed publicly.
  </Tab>

  <Tab value="Docker">
    `rdst web` can run inside a container if you bind to `0.0.0.0` and map the
    port. Keep the container on a private network.

    ```bash
    docker run --rm -it \
        -p 127.0.0.1:8787:8787 \
        -e ANTHROPIC_API_KEY \
        -e PROD_ORDERS_PASSWORD \
        -v $HOME/.rdst:/root/.rdst \
        rdst:latest web --host 0.0.0.0 --port 8787
    ```
  </Tab>

  <Tab value="Systemd">
    For a persistent install on a dedicated diagnostic host, run `rdst web` as a
    systemd service. Put a reverse proxy (nginx, Caddy) in front if you need
    TLS or auth.

    ```ini
    # /etc/systemd/system/rdst-web.service
    [Unit]
    Description=RDST web server
    After=network.target

    [Service]
    User=rdst
    Environment=ANTHROPIC_API_KEY=...
    Environment=PROD_ORDERS_PASSWORD=...
    ExecStart=/usr/local/bin/rdst web --host 127.0.0.1 --port 8787
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target
    ```
  </Tab>
</Tabs>

## Flags reference

| Flag             | Purpose                             |
| ---------------- | ----------------------------------- |
| `-p, --port <N>` | Port to listen on (default 8787)    |
| `--host <ip>`    | Host to bind to (default 127.0.0.1) |

## See also

* [Claude Code integration](/readyset-ai/rdst/cli/integrations/claude-code): MCP-based CLI-style
  access instead of a browser
* [Data Agents](/readyset-ai/rdst/cli/data-agents): scoped, guarded HTTP API for external
  consumers (different from `rdst web`, which exposes the full RDST surface)


# rdst analyze (/readyset-ai/rdst/cli/query-analysis/analyze)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Step, Steps } from 'fumadocs-ui/components/steps'

`rdst analyze` reports how your database plans to run a query and how long it
takes. Review its suggestions for improving the query and check whether Readyset
can cache it.

## Common usage

```bash
# Analyze an inline query
rdst analyze -q "SELECT * FROM orders WHERE customer_id = 42" --target prod-orders

# Analyze a query from the registry by hash
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders

# Analyze a query from the registry by name
rdst analyze --name top-customers-by-revenue --target prod-orders

# Analyze a multi-line query from a file
rdst analyze -f ./reports/top_customers.sql --target prod-orders

# Analyze from stdin
echo "SELECT COUNT(*) FROM orders" | rdst analyze --stdin --target prod-orders
```

## What it does

<Steps>
  <Step>
    **Run `EXPLAIN`.** Read the planner's plan without executing the query.
    Missing permissions, unsupported SQL, or missing parameter values can cause
    this step to fail.
  </Step>

  <Step>
    **Run `EXPLAIN ANALYZE`.** This actually runs the query against the target. On
    large tables this can take minutes, RDST prompts you to skip after 10 seconds,
    and keeps the `EXPLAIN` plan for the rest of the analysis.
  </Step>

  <Step>
    **Collect schema.** RDST extracts the relevant tables, columns, index
    definitions (including `USING` clause), and row estimates so the LLM has
    concrete numbers to reason about.
  </Step>

  <Step>
    **Generate recommendations.** The LLM produces candidate index
    definitions, candidate rewrites, and a Readyset
    cache-fit score.
  </Step>

  <Step>
    **Validate.** A post-hoc check runs against your real schema to catch common LLM
    hallucinations, for example, a suggested index that already exists, or a
    rewrite that references a non-existent column.
  </Step>
</Steps>

## Example output

```text
Query Analysis
════════════════════════════════════════════════════════════════
  Hash:              a1b2c3d4e5f6
  Target:            prod-orders (PostgreSQL 15.4)

  SELECT o.id, o.customer_id, o.total_cents, c.name
  FROM   orders o
  JOIN   customers c ON c.id = o.customer_id
  WHERE  o.status = 'shipped' AND o.created_at >= $1
  ORDER BY o.created_at DESC
  LIMIT  50;

Performance
  Execution time:    412.1 ms   →  SLOW (optimization needed)
  Rows examined:     2,847,201  (38.2% of orders)
  Rows returned:     50
  Scan efficiency:   INEFFICIENT
  Rating:            FAIR (65/100)

Key Issues
  • Full index scan on orders_created_at_idx; composite needed
  • Sort step: 41% of execution time
  • JOIN order picks customers first despite smaller filtered set

Index Recommendations
  1. CREATE INDEX idx_orders_status_created
       ON orders (status, created_at DESC)
       WHERE status = 'shipped';
     Expected impact: cuts scan ~90%, -300ms (~73%)

Query Rewrites
  (None suggested  -  rewrite candidates would not improve correctness-preserving
   performance. Fix the missing index above first.)

Readyset Cache Fit
  Candidate:        YES  (confidence: high)
  Parameter:        $1 (created_at lower bound)
  Next step:        rdst cache add a1b2c3d4e5f6 --target prod-orders-cache
```

<Callout type="info">
  If a Readyset cache is already deployed for the target (i.e. a `<target>-cache`
  target exists from [`rdst cache deploy`](/readyset-ai/rdst/cli/cache/deploy)), `analyze` also
  runs the query against the cache and reports the actual measured latency next to
  the upstream latency. The report labels measured latency separately from the cache-fit assessment.
</Callout>

<Callout type="warn">
  Review and test suggested rewrites for equivalent results, including ordering
  and NULL handling. If a rewrite changes results, report it with
  `rdst report --hash <id> --negative`.
</Callout>

## Interactive follow-up

Pass `--interactive` to enter a Q\&A loop after the analysis:

```bash
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders --interactive
```

```text
> Why not suggest a partial index on created_at alone?
RDST: The query filters by status='shipped' first (~18% of rows), so indexing on
status, created_at lets the scan skip 82% of rows before the sort. A plain
created_at index would need to scan every shipped *and* unshipped row before
filtering.

> What if I cache this in Readyset instead?
RDST: With customer_id bound and $1 as a time cutoff, Readyset can keep the result
set warm. Cache-fit is high. You can test it with:
  rdst cache add a1b2c3d4e5f6 --target prod-orders-cache
```

The same conversation is saved, replay it later with `--review`:

```bash
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders --review
```

## Flags reference

| Flag                | What it does                                                                   |
| ------------------- | ------------------------------------------------------------------------------ |
| `-q, --query <sql>` | Inline SQL (quote multi-line queries)                                          |
| `-f, --file <path>` | Read SQL from a file                                                           |
| `--stdin`           | Read SQL from stdin                                                            |
| `--hash <id>`       | Load a query by hash from the registry                                         |
| `--name <name>`     | Load a query by saved name                                                     |
| `--target <name>`   | Target database                                                                |
| `--fast`            | Skip `EXPLAIN ANALYZE`; use `EXPLAIN` only (much faster, less accurate timing) |
| `--save-as <name>`  | Save the query to the registry under a friendly name                           |
| `--interactive`     | Enter Q\&A mode after analysis                                                 |
| `--review`          | Replay the previous conversation for this query without re-running             |
| `--workload`        | Analyze multiple queries together for holistic index recommendations (preview) |
| `--json`            | Machine-readable output                                                        |
| `--skip-warning`    | Skip the `EXPLAIN ANALYZE` safety confirmation                                 |

## When to use `--fast`

`EXPLAIN ANALYZE` actually runs the query. On a production database with a 500 ms
query that's fine. On a 2-minute query against a 500M-row table, it's a real cost.
`--fast` skips execution and uses the `EXPLAIN` plan alone.

The tradeoff: row counts in `EXPLAIN` are planner estimates, not actual measurements,
so timing-related recommendations are approximate. Review index and rewrite recommendations against the estimated plan. Measured
results may reveal additional issues.

## See also

* [`rdst top`](/readyset-ai/rdst/cli/query-analysis/top): the easiest way to get a hash to pass to
  `analyze`
* [`rdst cache add`](/readyset-ai/rdst/cli/cache/manage): deploy a Readyset cache when `analyze`
  says the query is a good fit
* [`rdst query cache-compare`](/readyset-ai/rdst/cli/cache/compare): measure upstream vs cached
  performance for the same query
* [Core concepts: The LLM](/readyset-ai/rdst/cli/concepts#the-llm): determinism and what RDST
  sends to the model


# rdst ask (/readyset-ai/rdst/cli/query-analysis/ask)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

`rdst ask` takes a natural-language question and generates SQL that's safe to run
against your database. It validates the query before executing (read-only, valid
columns, required `LIMIT`), shows you the SQL for confirmation, runs it with a
timeout, and renders the results.

Quality depends heavily on your [semantic layer](/readyset-ai/rdst/cli/concepts#the-semantic-layer):
Descriptions and enum meanings help the model interpret your question.

## Common usage

```bash
# Simple question
rdst ask "How many customers signed up last month?" --target prod-orders

# Generate SQL without running it
rdst ask "Average order value by segment" --target prod-orders --dry-run

# Agent mode for ambiguous or multi-step questions
rdst ask "Which suppliers are most at risk of losing their top customer?" \
  --target prod-orders --agent

# Non-interactive for scripts
rdst ask "Count of orders in the last 24h" --target prod-orders --no-interactive
```

## Modes

| Mode      | When to use                       | Behavior                                                                                          |
| --------- | --------------------------------- | ------------------------------------------------------------------------------------------------- |
| Default   | Clear, schema-grounded questions  | Linear flow: generate SQL → confirm → execute → show results                                      |
| `--agent` | Ambiguous or multi-step questions | The LLM iteratively explores the schema, runs `EXPLAIN` checks, and drafts SQL over several turns |

## Example interaction

```text
$ rdst ask "What were our top 10 customers by revenue last month?" --target prod-orders

Using semantic layer (34 tables annotated).

Generated SQL:
  SELECT c.id, c.name, SUM(o.total_cents) AS revenue_cents
  FROM   customers c
  JOIN   orders    o ON o.customer_id = c.id
  WHERE  o.created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month')
    AND  o.created_at <  DATE_TRUNC('month', NOW())
    AND  o.status = 'paid'
  GROUP BY c.id, c.name
  ORDER BY revenue_cents DESC
  LIMIT 10;

Validation: OK
  ✓ Read-only
  ✓ All referenced columns exist
  ✓ LIMIT present (10)

Execute? [Y/n] y

Results (10 rows, 78 ms):
  id       name                    revenue_cents
  ─────── ────────────────────── ──────────────
  1023    Acme Manufacturing     4,820,135
  2118    Blue Orchid Foods       3,914,200
  745     Hendricks Retail        3,120,980
  ...
```

## How it works

`rdst ask` runs every question through the same pipeline:

| Step                      | What happens                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| **1. Load schema**        | Prefer the semantic layer (fast, annotated); fall back to live introspection if no layer is configured. |
| **2. Clarify (optional)** | Detect ambiguity. For example: "last month" → prompt if you want calendar month or rolling 30 days.     |
| **3. Generate SQL**       | AI produces candidate SQL.                                                                              |
| **4. Validate**           | Read-only? All columns exist? `LIMIT` present? If not, retry with the error as context, up to 3 times.  |
| **5. Confirm**            | Show the SQL. You can accept, reject, or edit before running.                                           |
| **6. Execute**            | Run with `--timeout`. Render results.                                                                   |

`--agent` inserts a schema-exploration loop before step 3 for questions where the
model needs to learn about the schema before it can write good SQL.

## Flags reference

| Flag                  | What it does                                   |
| --------------------- | ---------------------------------------------- |
| `--target <name>`     | Target database                                |
| `--dry-run`           | Generate and show SQL without executing it     |
| `--timeout <seconds>` | Query execution timeout                        |
| `--verbose`           | Show detailed reasoning and intermediate steps |
| `--agent`             | Use agent mode (iterative schema exploration)  |
| `--no-interactive`    | Skip confirmation prompts (for scripts)        |

## Get better results

Configure a semantic layer so Ask can use business meanings alongside table
and column names:

```bash
rdst schema init      --target prod-orders
rdst schema annotate  --target prod-orders --use-llm   # AI-generated descriptions
rdst schema show      --target prod-orders             # review
rdst schema edit      --target prod-orders             # tweak enum meanings and business terms
```

Before:

> *The LLM sees `status VARCHAR(16)` and has to guess what values mean.*

After:

> *The LLM sees that `status` is an enum with `paid`, `refunded`, `shipped`, `cancelled`,
> and that `paid` and `shipped` both represent completed orders in your business.*

<Callout type="info">
  Semantic layers are per-target. For targets with identical schemas,
  you can export one and import it into the others with
  `rdst schema export` / `rdst schema import`.
</Callout>

## Safety checks

`rdst ask` enforces three rules on every query it generates before execution:

1. **Read-only.** No `INSERT`, `UPDATE`, `DELETE`, `DDL`, or procedure calls.
2. **Columns must exist.** The validator checks every referenced column against the
   actual schema before executing.
3. **`LIMIT` is required.** Bounds returned rows; it doesn't bound the work needed to find them.

On top of this, the generated query is shown to you for confirmation before
execution. `--no-interactive` bypasses the confirmation prompt but doesn't bypass
the validation rules.

## See also

* [`rdst schema`](/readyset-ai/rdst/cli/concepts#the-semantic-layer): how to build the semantic
  layer that powers `ask`
* [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze): when you already have a SQL
  query and want performance insights instead
* [Data agents](/readyset-ai/rdst/cli/data-agents): expose `ask`-style access to external clients
  with stricter safety policies


# Query Analysis (/readyset-ai/rdst/cli/query-analysis)
import { Cards, Card } from 'fumadocs-ui/components/card'
import { Callout } from 'fumadocs-ui/components/callout'

RDST has four commands that help you work with SQL queries. They share a common
foundation, the [query registry](/readyset-ai/rdst/cli/concepts#the-query-registry), so a query
found by one command can be analyzed, cached, or re-run by another.

## Which command do I reach for?

| If you want to...                                                  | Use                                                            |
| ------------------------------------------------------------------ | -------------------------------------------------------------- |
| See which queries are actively consuming the most database time    | [`rdst top`](/readyset-ai/rdst/cli/query-analysis/top)         |
| Get a full analysis of one specific query                          | [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze) |
| Translate a plain-English question into SQL and run it             | [`rdst ask`](/readyset-ai/rdst/cli/query-analysis/ask)         |
| Find SQL queries in your application's source code (ORMs included) | [`rdst scan`](/readyset-ai/rdst/cli/query-analysis/scan)       |

## A common workflow

The four commands are often used together:

```bash
# 1. Find the slowest queries on a target
rdst top --target prod-orders

# 2. Analyze one of them
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders

# 3. Explore related data in plain English
rdst ask "Which customers trigger this query most often?" --target prod-orders

# 4. Find where the query comes from in your code
rdst scan ./backend --schema prod-orders --diff HEAD
```

<Callout type="info">
  Every command in this section saves the queries it touches to the registry. You
  never need to copy a query from one command's output to another's input, use
  `--hash <id>` instead.
</Callout>

<Cards>
  <Card title="rdst top" href="/readyset-ai/rdst/cli/query-analysis/top" description="Monitor the slowest queries on a target in real time." />

  <Card title="rdst analyze" href="/readyset-ai/rdst/cli/query-analysis/analyze" description="Analyze a single query full with index and rewrite recommendations." />

  <Card title="rdst ask" href="/readyset-ai/rdst/cli/query-analysis/ask" description="Turn a natural-language question into safe, read-only SQL." />

  <Card title="rdst scan" href="/readyset-ai/rdst/cli/query-analysis/scan" description="Find and analyze SQL generated by your application's ORM." />
</Cards>


# rdst scan (/readyset-ai/rdst/cli/query-analysis/scan)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

`rdst scan` walks a codebase, finds ORM-generated SQL in Python and TypeScript
projects, converts it to real SQL, and (optionally) analyzes each query for
performance issues. With `--check` it becomes a CI gate.

## Supported ORMs

| Language                | ORMs                                 |
| ----------------------- | ------------------------------------ |
| Python                  | SQLAlchemy (1.x and 2.0), Django ORM |
| TypeScript / JavaScript | Prisma, Drizzle                      |

All four work against both PostgreSQL and MySQL targets.

## Common usage

```bash
# Scan a directory and list the queries it finds
rdst scan ./backend --schema prod-orders

# Analyze each query against the live database
rdst scan ./backend --schema prod-orders --analyze

# Schema-only analysis (no DB connection needed, useful in CI)
rdst scan ./backend --schema prod-orders --analyze --shallow

# Only scan files changed in the current PR
rdst scan ./backend --schema prod-orders --diff HEAD --analyze --check

# Fail the build if any query has a risk score below 30
rdst scan ./backend --schema prod-orders --analyze --check --fail-threshold 30
```

## How extraction works

RDST detects ORM call sites with code parsing. Python detection looks for
SQLAlchemy and Django expressions. TypeScript and JavaScript detection looks
for Prisma and Drizzle expressions.

AI translates detected call sites into SQL using schema context. Review that
SQL before relying on the analysis. Fixed prompts and low temperature don't
guarantee identical SQL or recommendations across runs.

## Example output

```text
$ rdst scan ./backend --schema prod-orders --analyze --shallow

Scanning ./backend ...
  Found 47 ORM call sites in 22 files.
  Extracted 47 SQL queries.
  Analyzing with shallow mode (no DB connection) ...

  Score   File                           Query
  ─────── ────────────────────────────── ────────────────────────────
   88     services/order_service.py:42   SELECT o.id, o.total_cents ...
   72     services/order_service.py:114  SELECT COUNT(*) FROM orders...
   65     services/customer_service.py:8 SELECT c.* FROM customers c ...
   48     services/reports.py:201        SELECT c.id, COUNT(o.id) ...  ⚠  warn
   21     services/reports.py:233        SELECT * FROM orders WHERE ... ✗ fail
   ...

Summary
  47 queries analyzed.
  Worst score:    21  (below fail threshold 30)
  Below warn (50): 3
  Below fail (30): 1

  CI status: FAIL
```

## Analysis modes

| Mode                  | Needs DB? | What it checks                                                                                        |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| (no flag)             | no        | Extraction only: produces SQL and saves to registry                                                   |
| `--analyze --shallow` | no        | Schema-only LLM analysis. Detects `SELECT *`, missing `LIMIT`, obvious missing indexes, N+1 patterns. |
| `--analyze`           | yes       | Full `EXPLAIN ANALYZE` against the target plus LLM analysis. Most accurate, slowest.                  |

Shallow mode is the recommended default for CI. It doesn't require a database
password or network access to your production database, yet catches most practical
issues.

## CI mode (`--check`)

`--check` turns `rdst scan` into a build gate:

```bash
rdst scan ./backend --schema prod-orders --analyze --shallow --check \
    --fail-threshold 30 --warn-threshold 50
```

| Exit code | Meaning                                        |
| --------- | ---------------------------------------------- |
| `0`       | All queries meet the fail threshold (PASS)     |
| `1`       | At least one query below fail threshold (FAIL) |

The summary panel shows worst-query score, thresholds, and the counts in
each band. Without `--check`, scores are informational only and the command always
exits 0.

## Scanning just the diff

Pair `--diff <ref>` with `--check` to only gate queries that were touched in the
current change:

```bash
rdst scan ./backend --schema prod-orders --diff HEAD~1 --analyze --check
```

| Ref              | What gets scanned                      |
| ---------------- | -------------------------------------- |
| `HEAD`           | Uncommitted changes                    |
| `HEAD~1`         | Files changed in the last commit       |
| `main`, `abc123` | Files changed since that commit/branch |

## Flags reference

| Flag                    | What it does                                                   |
| ----------------------- | -------------------------------------------------------------- |
| `directory`             | Directory to scan (positional)                                 |
| `--dry-run`             | Show what would be scanned without scanning                    |
| `--analyze`             | Run performance analysis against the extracted queries         |
| `--shallow`             | Schema-only analysis (no DB connection). Use with `--analyze`. |
| `--schema <target>`     | Target name to use for schema context                          |
| `--output {table,json}` | Output format                                                  |
| `--diff <ref>`          | Only scan files changed since `ref`                            |
| `--check`               | CI mode: exit 1 if issues found                                |
| `--warn-threshold <N>`  | Risk score threshold for warnings (default 50)                 |
| `--fail-threshold <N>`  | Risk score threshold for failures (default 30)                 |
| `--file-pattern <glob>` | Glob pattern to filter files (e.g. `*.py`)                     |
| `--nosave`              | Don't save extracted queries to the registry                   |
| `--sequential`          | Run analysis queries one at a time                             |

## Risk scoring

Each query gets a score from 0 to 100:

| Range     | Meaning                                              |
| --------- | ---------------------------------------------------- |
| 80 to 100 | Low risk                                             |
| 50 to 79  | Medium risk                                          |
| 30 to 49  | High risk                                            |
| 0 to 29   | Very high risk: likely to cause production incidents |

RDST computes the score from the analyzer's findings. A query scores lower when
it lacks supporting indexes or scans too much data. Selecting every column from
a large table or repeating a query for each result row also lowers the score.

<Callout type="info">
  Scores depend on translated SQL, schema context, and analysis output. Review
  changes in scores alongside the findings that produced them.
</Callout>

## See also

* [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze): re-analyze any extracted query
  by hash for a full report
* [`rdst query list`](/readyset-ai/rdst/cli/concepts#the-query-registry): browse every query scan
  has saved
* [Core concepts: The semantic layer](/readyset-ai/rdst/cli/concepts#the-semantic-layer):
  annotate your schema once and every scan gets better


# rdst top (/readyset-ai/rdst/cli/query-analysis/top)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

`rdst top` is a Unix-`top`-style view of the queries running against a database. It
has two modes. For persistent history and Inbox findings, use
[Continuous monitoring](/readyset-ai/rdst/desktop/monitoring).

The CLI modes are:

* **Real-time monitoring** (default): samples active queries every few seconds, groups
  identical query shapes together, and tracks how long each has been running.
* **Historical** (`--historical`): reads cumulative stats from `pg_stat_statements`
  (Postgres) or `performance_schema` (MySQL) for totals since statistics were last reset.

Every query `top` surfaces is saved to the [query registry](/readyset-ai/rdst/cli/concepts#the-query-registry)
so you can hand its hash to `rdst analyze`, `rdst cache add`, or `rdst query run`.

## Common usage

```bash
# Watch live activity
rdst top --target prod-orders

# Capture a 30-second window, then exit (great for CI)
rdst top --target prod-orders --duration 30

# Cumulative view from pg_stat_statements or performance_schema
rdst top --target prod-orders --historical

# JSON output for scripting
rdst top --target prod-orders --duration 10 --json
```

## What the output looks like

```text
rdst top   -   target: prod-orders  (PostgreSQL 15.4)
Sampling every 2s.  Press 'z' then a row number to analyze, 'q' to quit.

  #   Hash          Calls    Avg time   Max time   Current   Query
  1   a1b2c3d4e5f6  4,812    53.4 ms    412.1 ms   2 active  SELECT * FROM orders WHERE customer_id = $1 ORDER ...
  2   f6e5d4c3b2a1  1,204    139.6 ms   988.2 ms   1 active  SELECT o.*, c.name FROM orders o JOIN customers ...
  3   9a8b7c6d5e4f  51,003   1.6 ms     48.0 ms    0 active  SELECT 1 FROM session_cache WHERE token = $1
  4   4d3c2b1a0f9e  892      74.1 ms    201.8 ms   0 active  UPDATE inventory SET quantity = quantity - $1 ...
```

The **Hash** column is your handle for follow-up commands:

```bash
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders
```

## Flags reference

| Flag                                                      | What it does                                           |
| --------------------------------------------------------- | ------------------------------------------------------ |
| `--target <name>`                                         | Which configured target to read from                   |
| `--duration <seconds>`                                    | Run for a fixed window and exit (non-interactive)      |
| `--historical`                                            | Use cumulative stats instead of sampling live activity |
| `--source {auto,pg_stat,activity,slowlog,digest,rds,pmm}` | Override the data source (see below)                   |
| `--sort {freq,total_time,avg_time,load}`                  | Change the ordering                                    |
| `--limit <N>`                                             | Cap the number of rows printed                         |
| `--filter <regex>`                                        | Only show queries matching a regex                     |
| `--watch`                                                 | Continuously refresh (default in TTY mode)             |
| `--interactive`                                           | Pick a query inline and drop into `rdst analyze`       |
| `--json`                                                  | Machine-readable output                                |
| `--no-color`                                              | Disable ANSI color formatting                          |

## Data sources

`--source` tells RDST where to read query data from. `auto` picks a sensible default
per database type:

<Tabs items={['PostgreSQL', 'MySQL']}>
  <Tab value="PostgreSQL">
    | Source                                 | What it reads                                  |
    | -------------------------------------- | ---------------------------------------------- |
    | `pg_stat` (default for `--historical`) | `pg_stat_statements` cumulative stats          |
    | `activity`                             | `pg_stat_activity` live connections            |
    | `rds`                                  | Performance Insights via AWS API (RDS targets) |
  </Tab>

  <Tab value="MySQL">
    | Source                                | What it reads                                            |
    | ------------------------------------- | -------------------------------------------------------- |
    | `digest` (default for `--historical`) | `performance_schema.events_statements_summary_by_digest` |
    | `slowlog`                             | `mysql.slow_log` table (requires setup, see below)       |
    | `activity`                            | `SHOW PROCESSLIST`                                       |
    | `pmm`                                 | Percona Monitoring & Management, if configured           |
  </Tab>
</Tabs>

### Enabling MySQL slow log

The `slowlog` source requires MySQL's slow query log with `TABLE` output:

```sql
-- Self-hosted MySQL
SET GLOBAL slow_query_log    = 'ON';
SET GLOBAL long_query_time   = 1;
SET GLOBAL log_output        = 'TABLE';
```

For RDS or Aurora, modify the parameter group (`slow_query_log=1`,
`log_output=TABLE`). No restart is required.

## Interactive mode

In a TTY, `top` accepts single-keypress commands:

| Key                | Action                                                        |
| ------------------ | ------------------------------------------------------------- |
| `<digit>`          | Save that query to the registry (row number from the display) |
| `z` then `<digit>` | Hand that query to `rdst analyze`                             |
| `a`                | Save every query currently on screen to the registry          |
| `q` or Ctrl+C      | Quit                                                          |

<Callout type="info">
  `--duration <seconds>` forces snapshot mode regardless of TTY. This is the right
  flag for CI, cron jobs, or anything that needs a predictable exit. Use `--sort`
  and `--filter` on the command line to change ordering and filtering instead of
  keybinds.
</Callout>

## See also

* [`rdst analyze`](/readyset-ai/rdst/cli/query-analysis/analyze): the natural follow-up for any hash
  `top` surfaces
* [`rdst audit`](/readyset-ai/rdst/cli/fleet-and-audit/audit): includes a more complete `top`-like
  view alongside metrics and sizing data
* [Core concepts: The query registry](/readyset-ai/rdst/cli/concepts#the-query-registry): what
  `top` is saving to and why


# AI access (/readyset-ai/rdst/desktop/ai-credits)


## Sign in to Readyset

AI monitoring needs a Readyset sign-in. While you're signed in, RDST checks
each monitored database every few minutes and tells you when a query starts
taking more of the database's time. The same sign-in covers deep analysis,
nightly reports, Analyze and Ask, so there's no API key to manage.

The first time you open RDST, it asks you to choose how it uses AI. Pick
**Sign up or sign in**.

<img alt="The first screen, Choose how RDST uses AI, with Sign in to Readyset as the recommended choice and a link to add an Anthropic key below it" src={__img0} placeholder="blur" />

1. Select **Sign up or sign in**. You can also find it later under
   [Settings](/readyset-ai/rdst/desktop/settings), on the **AI** tab.
2. Continue with Google, GitHub, or an email sign-in link.
3. Finish in your browser. The app shows **Signed in as** with your email.

RDST currently allows AI monitoring on up to 3 databases per account.
[Contact us for more](mailto:hello@readyset.io). Monitoring beyond that runs
locally without AI. The database limit applies across computers.

Your account also has a monthly AI usage limit. If it runs out, the app says
**You've run out of AI usage for now** and offers **Contact us**.

## Without a sign-in

Local monitoring works when you're signed out, tracking up to 10,000 queries
per database and counting the rest in the totals. The chart, the
query list and locally measured alerts keep working, including lost
connections and stuck queries. The Database page and the turn-on dialog show
**Sign in to turn on AI monitoring** and say that monitoring is local only.

The monitoring switch area warns **You won't get automatic AI recommendations
for this database.** Its **Sign in** action lets you turn on AI monitoring.

You can open the Inbox and add a database without AI access. The full-screen
AI choice still appears on first run.

Change checks, automatic deep analysis and report summaries wait until you
sign in.

## What uses AI

| Feature                                                               | AI work                                                                                                                   |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [Continuous monitoring](/readyset-ai/rdst/desktop/monitoring)         | Query classification, change checks every few minutes, automatic deep analysis, and report summaries                      |
| [Actions](/readyset-ai/rdst/desktop/monitoring/actions)               | Ranking open changes alongside change checks, and writing why each new change matters, at most 3 calls per database a day |
| [Analyze now](/readyset-ai/rdst/desktop/monitoring/deep-analysis)     | Query explanation, index recommendations, and rewrites                                                                    |
| [Ask](/readyset-ai/rdst/desktop/ask)                                  | SQL generation and clarification                                                                                          |
| [Nightly report](/readyset-ai/rdst/desktop/monitoring/nightly-report) | Written findings and next steps                                                                                           |

To use less AI, check for changes less often or deeply analyze fewer queries a
day in the [monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings).

## When a usage limit is reached

AI monitoring stops gracefully. Local monitoring keeps recording, the charts
and query list keep updating, and locally measured alerts still work. The app
says **You've run out of AI usage for now** and asks you to contact us. Use its
contact action or email
[hello@readyset.io](mailto:hello@readyset.io). AI monitoring resumes once the
limit is raised.

If a database can't get an AI monitoring slot, choose **Turn on local
monitoring**. Its AI change checks, automatic deep analysis, and written report
summary stay off. See
[Monitoring limits](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#the-database-limit).

## Your own Anthropic key

An Anthropic key covers deep analysis and reports. It doesn't replace signing
in: AI monitoring's change checks and query classification always run through
your Readyset account, and automatic deep analysis and reports only run while
you're signed in. With a key added, you can use AI monitoring on up to 10
databases. [Contact us for more](mailto:hello@readyset.io).

To add one, open the **AI** tab in Settings, or use **Add Anthropic key** on
the first screen:

1. Select **Set key** and enter the key.
2. Select **Test key** to check it.
3. Check the provider shown in Settings before running an analysis.

The key is stored in your operating system's keychain. Ask, Analyze, deep
analysis and report summaries use it while it's selected.

**Use the included AI** switches back to your Readyset account. The CLI shares
the saved provider choice. A saved Readyset preference takes precedence over
`ANTHROPIC_API_KEY`. See [CLI configuration](/readyset-ai/rdst/cli/configuration#llm-provider).

## What is sent

AI calls can include SQL, execution plans, schema metadata, and sampled parameter
values used for deep analysis. Query result rows aren't sent.
[Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity) shows AI
calls and the kinds of data sent. The activity log doesn't store sampled values.


# Ask (/readyset-ai/rdst/desktop/ask)


1. Select the database at the top of the sidebar and open **Ask**.
2. Enter a question about your data.
3. Answer any clarifying questions. For example, revenue might mean order totals
   or the amount paid after refunds.
4. Review the answer and its results. **Show the SQL that ran** opens the query.

Ask validates table and column references and rejects writes. Check the SQL and
its interpretation before using an answer for a decision.

<img alt="Ask showing a verified answer and its results" src={__img0} placeholder="blur" />

## Schema context

The [semantic layer](/readyset-ai/rdst/cli/concepts#the-semantic-layer) describes tables,
status codes, and business terms. Ask uses it to interpret your question, and
the answer says where it came from, for example **Answered from demoshop via
semantic layer**. Without one, Ask works from column names and types. To build
or edit it, run `rdst schema init` and `rdst schema annotate` from the
[CLI](/readyset-ai/rdst/cli).

## Use a monitored query

On the [Database page](/readyset-ai/rdst/desktop/monitoring/database-page), expand
a query and select **Send to Ask**. The SQL is carried into Ask.

Generated queries are saved in the
[query library](/readyset-ai/rdst/cli/concepts#the-query-registry). To check a query's
performance before adding it to your application, use **Analyze a query** on
the Database page.

Ask needs [AI access](/readyset-ai/rdst/desktop/ai-credits). The
[CLI equivalent](/readyset-ai/rdst/cli/query-analysis/ask) is `rdst ask`.


# Import from AWS (/readyset-ai/rdst/desktop/connect/discover)


1. Open **Settings**, select **Add target**, and choose **AWS** on the
   **Integrations** tab.
2. Choose an AWS CLI profile in **Profile**, then select **Sign in with AWS SSO**.
   Use **Add another profile** for another account or role, and **Check again**
   after signing in elsewhere.
3. Pick the regions. **Add another region...** lists more regions.
4. Select **Discover**.
5. Select databases from the results and choose **Add N selected**.

<img alt="AWS in Add target, with the profile, Sign in with AWS SSO, and region controls" src={__img0} placeholder="blur" />

Discovery reads identifiers, engines, endpoints, ports, instance classes,
regions, VPCs, and public-access settings. The instance identifier becomes the
target name.

## Complete the connection

RDST still needs a database credential. Enter it when prompted; RDST stores it
in your operating system's keychain.

If RDS doesn't report a database name, enter one in the target's connection
details. Test the connection before
[turning on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on).

## Empty results or private databases

If discovery returns nothing, check that the selected profile can list the
databases in the chosen account and region.

Discovery imports private endpoints but doesn't create a network route. For
**Publicly accessible: No**, connect to the VPC or add an
[SSH jump host](/readyset-ai/rdst/desktop/connect/private).

## CLI discovery

Use [`rdst fleet discover`](/readyset-ai/rdst/cli/fleet-and-audit/fleet-setup)
for bulk or scripted imports. The desktop app and CLI share the target list.


# Connect a database (/readyset-ai/rdst/desktop/connect)


import { Cards, Card } from 'fumadocs-ui/components/card'

A target is a named database connection. Select one at the top of the sidebar
to open its Database page or ask questions about it.

Open **Settings**, then **Targets**, to manage connections.

<Cards>
  <Card title="Import from AWS" href="/readyset-ai/rdst/desktop/connect/discover" description="Find RDS and Aurora databases using your AWS account." />

  <Card title="Managed providers" href="/readyset-ai/rdst/desktop/connect/providers" description="Import databases from Supabase, Neon, or DigitalOcean." />

  <Card title="Private databases" href="/readyset-ai/rdst/desktop/connect/private" description="Reach a private database through an SSH jump host." />
</Cards>

## Adding a target by hand

1. Select **Add target** in Settings and open **Manual setup**.
2. Enter a name, engine, host, port, database, and user. **Quick Setup** can fill
   these fields from a connection URL.
   Target names must be unique. RDST checks as you type and when you save.
   If the name is taken, it says **A target named \<name> already exists.**
3. Enter the database password.
4. Expand **Connect via SSH jump host** if you need a tunnel, or **Advanced**
   for TLS settings.
5. Select **Test connection**, then **Add target**. The **Turn on monitoring**
   dialog opens next for that database.

```text
postgresql://readonly@db.example.com:5432/myapp
```

<img alt="Manual setup in Add target, with Quick setup and the connection fields" src={__img0} placeholder="blur" />

## Check a connection

The target list shows the engine, host, port, server version, and measured
round-trip latency. **Test** checks one target; **Check all** checks the list.

**Password stored** means RDST can use the saved keychain credential.
**Tunnel active** means its SSH tunnel is open.

Use a [read-only account](/readyset-ai/rdst/desktop/database-permissions) with
access to application tables and query statistics. RDST warns when it detects
write privileges. **How to create a read-only user** opens example grants for
an administrator to run.

Passwords are saved in the operating system's keychain or read from a named
environment variable. They're never written into `config.toml`.

## Start monitoring

After you add a database, from Targets or during your first launch, the
[Turn on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on) dialog opens
next in the same flow. RDST checks statistics collection and access before
taking its first readings.


# Private databases (/readyset-ai/rdst/desktop/connect/private)


An SSH jump host lets RDST reach a database in a private network. RDST opens a
local tunnel through the host and uses it for the database connection.

## Configuring a jump host

1. Open the target in **Settings**, or select **Add target** and open
   **Manual setup**.
2. Enter the database's private endpoint, port, and database name. Use the
   address the jump host can reach.
3. Expand **Connect via SSH jump host**.
4. Choose a saved host or **Enter manually**.
5. Enter the jump host address, SSH port, user, and private-key path.
6. Select **Test connection** to test the tunnel and database together.

<img alt="SSH jump host fields in Add target" src={__img0} placeholder="blur" />

RDST reads the private key to authenticate. It doesn't copy the key.
The target list shows **Tunnel active** while the tunnel is open.

## Reusing a jump host

Select the same saved jump host for each database it can reach. Editing that
host updates the targets that use it.

If one database fails while another works through the same host, check routing
and security rules between the host and the failing database.

## Monitoring through a tunnel

Continuous monitoring needs the SSH host and database to remain reachable.
RDST manages the tunnel while it collects readings. If the connection fails,
check the Inbox and the connection details.

[AWS discovery](/readyset-ai/rdst/desktop/connect/discover) imports endpoints;
you still need to configure the route to a private database.

## Other network paths

For VPN access, connect the VPN first. RDST uses your computer's routing.

If the database is reachable only inside its network, install the
[CLI](/readyset-ai/rdst/cli) on a host there. Run
[`rdst web`](/readyset-ai/rdst/cli/integrations/web#deployment-patterns) and
forward its local port over SSH. Keep `rdst web` running to collect monitoring
history.


# Supabase, Neon, and DigitalOcean (/readyset-ai/rdst/desktop/connect/providers)
Open **Settings**, select **Add target**, and choose your provider on the
**Integrations** tab.

| Provider     | Sign-in                                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Neon         | API key from the Neon console's account settings                                                                         |
| Supabase     | Browser authorization for your organization                                                                              |
| DigitalOcean | Browser sign-in                                                                                                          |
| AWS          | Existing AWS CLI profile or IAM Identity Center login; see [Import from AWS](/readyset-ai/rdst/desktop/connect/discover) |

Select **Discover**, choose the databases to import, and select **Add**.
The app lists projects, branch endpoints, or managed clusters for the provider.

## After import

Test each connection. Enter missing database credentials when prompted.
RDST stores passwords in the operating system's keychain.

Check the provider's allowed-address settings. Where supported, RDST offers to
add your current address and records the entry it created. Otherwise, add the
address in the provider's console.

Supabase and Neon can provide direct and pooled endpoints. RDST prefers a pooled
endpoint where it's needed for IPv4 access. Edit the host if your network needs
the direct endpoint.

For a private endpoint, connect to its network or configure an
[SSH jump host](/readyset-ai/rdst/desktop/connect/private). Then
[turn on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on).


# Database permissions (/readyset-ai/rdst/desktop/database-permissions)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

RDST Desktop should connect with a dedicated read-only database user. The
baseline account needs permission to connect, inspect the schema, and read the
application tables you want RDST to analyze. Monitoring activity from other
database users requires additional statistics privileges.

RDST Desktop doesn't run these `GRANT` statements for you. Ask a database
administrator to create the account, replace the example names, and limit it to
the databases and schemas you want RDST to inspect.

## Permissions by feature

| Feature                                     | PostgreSQL                                                                                      | MySQL                                                                                                                               |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Connect and test credentials                | `CONNECT` on the database                                                                       | Permission to connect to the server                                                                                                 |
| Schema, Analyze, Ask, and query execution   | `USAGE` on each schema and `SELECT` on relevant tables and views                                | `SELECT` on the relevant database; `SHOW VIEW` when inspecting or explaining views                                                  |
| Realtime monitoring of this user's sessions | Baseline access                                                                                 | Baseline access                                                                                                                     |
| Realtime monitoring of all sessions         | Membership in `pg_read_all_stats`                                                               | Global `PROCESS`                                                                                                                    |
| Historical slow queries                     | `pg_stat_statements` enabled, plus `pg_read_all_stats` to see other users' query text           | Performance Schema enabled and `SELECT` on `performance_schema.*`                                                                   |
| Health Check                                | Baseline access gives partial results; `pg_monitor` provides the most complete server-wide view | Baseline access gives partial results; `PROCESS`, Performance Schema access, and `REPLICATION CLIENT` provide more complete results |

<Callout type="info">
  Optional monitoring privileges expose query text and activity from other
  database users. Without them, RDST Desktop can still connect and analyze
  queries, but TOP and Health Check may show only RDST's sessions or incomplete
  historical data. Some checks return partial or empty results instead of an
  explicit permission error.
</Callout>

## Create a read-only account

<Tabs items={['PostgreSQL', 'MySQL']}>
  <Tab value="PostgreSQL">
    Run this as an administrator. Replace `my_database`, `public`, and
    `app_owner` with your database, schema, and table-owning role.

    ```sql
    CREATE ROLE rdst_readonly
      LOGIN
      PASSWORD 'replace_with_a_strong_password'
      NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;

    GRANT CONNECT ON DATABASE my_database TO rdst_readonly;

    -- Run these while connected to my_database.
    GRANT USAGE ON SCHEMA public TO rdst_readonly;
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO rdst_readonly;

    -- Keep access when app_owner creates new tables.
    ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA public
      GRANT SELECT ON TABLES TO rdst_readonly;
    ```

    Repeat the schema grants for every application schema RDST should inspect.
    Repeat `ALTER DEFAULT PRIVILEGES` for each role that creates tables.

    For complete workload monitoring, add:

    ```sql
    GRANT pg_read_all_stats TO rdst_readonly;
    ```

    For the most complete Health Check, grant `pg_monitor` instead. It includes
    `pg_read_all_stats`, so you don't need to grant both.

    ```sql
    GRANT pg_monitor TO rdst_readonly;
    ```

    Historical query monitoring also requires `pg_stat_statements` to be enabled
    by a database administrator:

    ```sql
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    ```

    PostgreSQL may require `pg_stat_statements` in `shared_preload_libraries`, a
    server or managed-service setting rather than a user privilege.
  </Tab>

  <Tab value="MySQL">
    Run this as an administrator. Replace `my_database` and the host pattern
    with the narrowest values that match the RDST machine.

    ```sql
    CREATE USER 'rdst_readonly'@'10.0.0.%'
      IDENTIFIED BY 'replace_with_a_strong_password';

    GRANT SELECT ON `my_database`.*
      TO 'rdst_readonly'@'10.0.0.%';
    ```

    If RDST must inspect or explain views, add:

    ```sql
    GRANT SHOW VIEW ON `my_database`.*
      TO 'rdst_readonly'@'10.0.0.%';
    ```

    For complete realtime monitoring and Health Check, add:

    ```sql
    GRANT PROCESS ON *.* TO 'rdst_readonly'@'10.0.0.%';
    GRANT SELECT ON performance_schema.*
      TO 'rdst_readonly'@'10.0.0.%';
    GRANT REPLICATION CLIENT ON *.*
      TO 'rdst_readonly'@'10.0.0.%';
    ```

    Performance Schema statement instrumentation and the `statements_digest`
    consumer must also be enabled. Granting `SELECT` can't enable collection.

    If you explicitly use TOP's MySQL slow-log source, also grant
    `SELECT ON mysql.slow_log` and configure `slow_query_log=ON` with
    `log_output=TABLE`.
  </Tab>
</Tabs>

## Verify the account in Desktop

1. Open **Settings**.
2. Select **Add target**, or edit an existing target.
3. Enter the read-only account credentials.
4. Select **Test connection** and save the target.

After the connection succeeds, open **Database** and click **Turn on
monitoring**. Its [prerequisite checks](/readyset-ai/rdst/desktop/monitoring/turn-on#prerequisites)
confirm the account can read every user's statements, that the statistics
extension or Performance Schema is collecting, and that new statements show up.
Each failed check comes with the fix.

<Callout type="warn">
  `EXPLAIN ANALYZE` executes the query while collecting its plan and timing.
  Keep the account read-only. Choose **EXPLAIN only** in monitoring setup to
  inspect plans without executing the query.
</Callout>

## Readyset caching uses different permissions

The grants above cover RDST Desktop diagnostics, analysis, and current shallow
cache deployment. A deep Readyset deployment additionally snapshots tables and
follows the replication stream, requiring broader upstream permissions and
server configuration.

* [PostgreSQL Readyset Cache permissions](/cache/connect/postgres)
* [MySQL Readyset Cache permissions](/cache/connect/mysql)

Use a separate deployment credential when possible. Don't add replication or
administrative privileges to a diagnostics-only RDST account unless you're
intentionally deploying deep caching.

## Why least privilege matters

Database permissions are the final enforcement boundary. Audit direct,
inherited, default, `PUBLIC`, and routine-execution privileges: a role with no
direct table-write grant may still inherit broader access or invoke a
security-definer routine with side effects.

On MySQL, incomplete Performance Schema access can make unavailable index
counters look like zeroes, potentially producing a false "unused index"
finding. Confirm permissions and collection settings before acting on that
recommendation.


# Demo (/readyset-ai/rdst/desktop/demo)








import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'

The demo starts a local orders database, a QueryPilot router, and Readyset.
It runs traffic so you can compare throughput with caching on and off.
Docker is required.

This demo tests caching against sample data. To monitor your own database,
[connect it](/readyset-ai/rdst/desktop/connect) and
[turn on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on).

## What the Readyset Platform is

QueryPilot routes SQL traffic and selects queries to cache. Readyset serves the
cached results. The [QueryPilot documentation](/querypilot/what-is-querypilot)
describes the architecture.

## What RDST sets up for you

RDST creates and manages the local containers for the orders database, Readyset,
and QueryPilot.

<img alt="The Demo screen before starting, listing the requirements and the container images to be downloaded" src={__img0} placeholder="blur" />

The first run downloads container images. Later runs can reuse them.

<Callout type="info">
  The environment cleans itself up after an hour, and **Shut down demo** removes
  it immediately. Nothing it creates touches any database you've configured.
</Callout>

## Running it

<Steps>
  <Step>
    **Start the demo.** RDST pulls the images if it needs to, starts Postgres,
    loads an orders dataset, and brings up Readyset and QueryPilot in front of
    it.
  </Step>

  <Step>
    **Start traffic.** A workload runs against the database through both paths,
    directly to Postgres and through QueryPilot, so the two can be compared under
    identical load.

        <img alt="The demo chart with traffic running and caching still off, both paths carrying about the same throughput" src={__img1} placeholder="blur" />
  </Step>

  <Step>
    **Turn QueryPilot on.** The Accelerator picks queries to cache according to
    the policy you choose, creates the Readyset caches, and routes matching
    traffic to them. The chart marks the moment it takes effect.
  </Step>
</Steps>

## Reading the chart

With traffic running and caching off, both paths carry the same load, because
every query reaches Postgres either way. QueryPilot is proxying, not yet
accelerating.

<img alt="The demo chart with QueryPilot enabled, showing throughput jumping from 19 queries per second to 1.6k, an 86x difference" src={__img2} placeholder="blur" />

Switching QueryPilot on changes that. In the run above, throughput through the
platform went from matching Postgres to roughly 1.6k queries per second against a
19 qps baseline, and the green line shows the moment the caches came online.

**Caching policy** decides which queries the Accelerator picks. **Most frequent**
targets the queries that run most often, and **Most expensive** targets the ones
consuming the most database time. Switching between them resets the comparison
window and marks the chart, so the effect of each choice is visible separately.

**Show per-query detail** breaks the same numbers down by query, with hit counts
and average latency for each path.

<img alt="The per-query detail table, listing each query with its Postgres and Readyset hit counts, averages, and cache status" src={__img3} placeholder="blur" />

Check per-query detail to see which queries account for the measured change.

## Moving on to your own database

1. [Connect your database](/readyset-ai/rdst/desktop/connect).
2. [Turn on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on).
3. Expand a query on the Database page and select **Benchmark** to compare it
   with a [local Readyset cache](/readyset-ai/rdst/desktop/monitoring/database-page#benchmarks).

The demo's measurements describe its sample workload. Benchmark your own queries
before deciding whether caching helps your application.


# RDST Desktop (/readyset-ai/rdst/desktop)
import { Cards, Card } from 'fumadocs-ui/components/card'

RDST Desktop monitors PostgreSQL and MySQL from your computer. It records query
activity, checks for changes, and runs background analyses. Open the Inbox to
review findings or the Database page to inspect a query and its history.

Closing the window keeps RDST running in the system tray on Windows and Linux,
or in the menu bar on macOS. Your computer must be awake and connected to the
database to collect readings.

<Cards>
  <Card title="Get started" href="/readyset-ai/rdst/desktop/install" description="Download RDST, connect a database, and turn on monitoring." />

  <Card title="Continuous monitoring" href="/readyset-ai/rdst/desktop/monitoring" description="Watch your database's load and analyze its queries. Review findings in the Inbox and read its nightly reports." />

  <Card title="Connect a database" href="/readyset-ai/rdst/desktop/connect" description="Add connection details, import cloud databases, or configure an SSH tunnel." />

  <Card title="AI access" href="/readyset-ai/rdst/desktop/ai-credits" description="Sign in to Readyset for AI monitoring, or add your own Anthropic key." />
</Cards>

## The app's navigation

| Page               | What you'll find                                                                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Home**           | Connection and monitoring status                                                                                                                            |
| **Database**       | [Query charts and analyses](/readyset-ai/rdst/desktop/monitoring/database-page), plus the [Report tab](/readyset-ai/rdst/desktop/monitoring/nightly-report) |
| **Inbox**          | [Findings and actions](/readyset-ai/rdst/desktop/monitoring/inbox)                                                                                          |
| **Agent activity** | [Analysis, AI calls, and diagnostic statements](/readyset-ai/rdst/desktop/monitoring/agent-activity)                                                        |
| **Ask**            | [Questions about your data](/readyset-ai/rdst/desktop/ask)                                                                                                  |
| **Try the demo**   | [A local caching demo](/readyset-ai/rdst/desktop/demo)                                                                                                      |
| **Settings**       | [Connections, AI access, and local data](/readyset-ai/rdst/desktop/settings)                                                                                |

## Requirements

* A PostgreSQL or MySQL database reachable from this computer.
* A [read-only account with statistics access](/readyset-ai/rdst/desktop/database-permissions).
* Query statistics enabled. [Turn on monitoring](/readyset-ai/rdst/desktop/monitoring/turn-on)
  checks the prerequisites.
* A Readyset sign-in for AI monitoring. Local monitoring works without AI.
* Docker for the caching demo and benchmarks.

The [CLI](/readyset-ai/rdst/cli) shares RDST's local configuration and saved
queries under the same operating system user.


# Get started (/readyset-ai/rdst/desktop/install)


import { Step, Steps } from 'fumadocs-ui/components/steps'

## Desktop download

Choose your platform at [readyset.io/downloads](https://readyset.io/downloads).
The stable download routes open the downloads page:

| Platform             | Download                                                                                | Install                                                   |
| -------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| macOS, Apple Silicon | [DMG](/docs/download/rdst/macos-arm64)                                                  | Open the disk image and drag RDST Desktop to Applications |
| Windows, x64         | [Installer](/docs/download/rdst/windows-x64)                                            | Run the installer. It installs for your user              |
| Linux, x64           | [AppImage](/docs/download/rdst/linux-appimage)                                          | Mark it executable and run it                             |
| Linux, x64           | [Debian package](/docs/download/rdst/linux-deb) or [RPM](/docs/download/rdst/linux-rpm) | Install with your package manager                         |

For an AppImage, replace the filename with the one you downloaded:

```bash
chmod +x rdst-desktop.AppImage
./rdst-desktop.AppImage
```

## First launch

<Steps>
  <Step>
    **Choose how RDST uses AI.** The first screen asks you to sign in to
    Readyset. AI monitoring needs a sign-in, so pick **Sign up or sign in**.
    **Add Anthropic key** below it covers deep analysis and reports, and doesn't
    replace signing in. See [AI access](/readyset-ai/rdst/desktop/ai-credits).
  </Step>

  <Step>
    **Connect a database.** Fill in the connection details, or paste a
    connection URL into **Quick setup**, and select **Test & connect**. You can
    also discover databases at AWS, Supabase, Neon or DigitalOcean. See
    [Connect a database](/readyset-ai/rdst/desktop/connect).
  </Step>

  <Step>
    **Let RDST see your queries.** RDST checks that it can read the database's
    query statistics and shows the fix for anything missing.
  </Step>

  <Step>
    **Select Turn on monitoring.** It opens the
    [turn-on dialog](/readyset-ai/rdst/desktop/monitoring/turn-on) on the
    database's Database page. Pick how deep analysis reads a query and turn it
    on. The first readings arrive within seconds.
  </Step>
</Steps>

<img alt="Let RDST see your queries, with every check passed and Turn on monitoring" src={__img0} placeholder="blur" />

When your account's AI usage limit is reached, AI monitoring stops gracefully,
local monitoring keeps running, and the app asks you to contact us.

## Running in the tray

Closing the window hides it. RDST keeps monitoring from the system tray on
Windows and Linux, or the menu bar on macOS. Select the icon to reopen it.

**Start at login** is enabled on the first packaged launch where supported.
RDST starts in the background without opening a window. Clear **Start at login**
in the tray menu to disable it. Linux AppImage builds don't support this setting.

| Tray item              | Action                                                                                                                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open RDST              | Show the window                                                                                                                                                        |
| Inbox                  | Open the [Inbox](/readyset-ai/rdst/desktop/monitoring/inbox)                                                                                                           |
| Monitoring             | Turn monitoring on or off for a database or all databases; see [tray controls](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#control-monitoring-from-the-tray) |
| Start at login         | Control startup with your computer                                                                                                                                     |
| Notifications          | Enable or disable system notifications                                                                                                                                 |
| Send test notification | Check notification delivery                                                                                                                                            |
| Open logs folder       | Open [backend logs](/readyset-ai/rdst/desktop/monitoring/troubleshooting#the-backend-log)                                                                              |
| Quit RDST              | Stop the app and monitoring                                                                                                                                            |

The icon shows whether RDST is running, needs attention, or has monitoring off. Hover it for details.
Monitoring can't collect while your computer is asleep or off. The chart keeps
that gap when collection resumes.

## Updates and upgrades

Published main releases download updates in the background. Use the app's
restart control or quit RDST from the tray to apply a downloaded update.
Preview and local builds need a manual reinstall.

On the first launch after an upgrade, RDST may migrate its data files. Leave
**Upgrading your data, this can take a minute** to finish. Failed startup offers
**Try again** and **Open logs**.

Update a separately installed CLI too. An older CLI may read saved queries but
fail to write data upgraded by the desktop app. See
[Data and retention](/readyset-ai/rdst/desktop/monitoring/data-and-retention).

## Running in a browser

Install the [CLI](/readyset-ai/rdst/cli/getting-started#install) and run
[`rdst web`](/readyset-ai/rdst/cli/integrations/web). It serves the same database,
Inbox, and report interface locally.

Keep `rdst web` running to collect readings. Closing a browser tab doesn't stop
the server, but browser notifications need an open tab. The browser interface
has no desktop tray or start-at-login controls.


# Actions (/readyset-ai/rdst/desktop/monitoring/actions)




import { Callout } from 'fumadocs-ui/components/callout'

Actions is where RDST tells you what to change. While monitoring runs, it keeps
a ranked list of changes for each database, built from what it measures: which
queries take the database's time, which indexes they read, how hard each table
is written to, and how the server is set up. Each action says what to change,
why it matters for this database, and the SQL or steps to do it.

<img alt="Actions for a database, with the changes ranked best first" src={__img0} placeholder="blur" />

<Callout type="info">
  RDST never changes your database. It doesn't run the SQL in an action. You
  run it, through your own migration or change process, and RDST checks the
  database afterwards to see that it happened.
</Callout>

## Kinds of change

| Kind                | Where it comes from                                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Add an index**    | The index plan. RDST reads the deep analyses of your busiest queries, works out which indexes would speed them up, and weighs each one against the writes it would cost on its table         |
| **Drop an index**   | The index plan. An index no query reads, or one another index already covers, still costs every write. RDST suggests dropping it only when it's confident or the table is written to heavily |
| **Rewrite a query** | Deep analysis, which tests the rewrites it suggests. One shows up when it ran at least 20% faster, or the planner estimates 20% less work, on a read that takes at least 2% of database time |
| **Server settings** | Database checks, such as connections near the limit, sorts spilling to disk, or a buffer that's too small for the measured cache hit ratio                                                   |
| **Maintenance**     | Database checks, such as tables that need a vacuum, stale statistics, or transactions left open                                                                                              |

The index plan also lists the indexes to keep, and smaller adds that would help
a little but still cost every write. Index changes on PostgreSQL use
`CREATE INDEX CONCURRENTLY` and `DROP INDEX CONCURRENTLY`, so writes keep
flowing while they run. Each index change comes with the SQL to undo it.

A drop on a database with replicas carries a note to check them first: a
replica can read an index the primary doesn't.

## When actions update

Actions follow the database as it changes. You don't need to start anything.

* **First plan.** When you turn monitoring on, RDST deep analyzes the 10
  busiest reads first. The first plan is ready once they're done, usually
  within about 10 minutes. Until then, Actions shows how many of those
  analyses have finished.
* **Index plan and rewrites.** About every 5 minutes, RDST rereads table,
  index and setting statistics and rebuilds the plan from them and the latest
  deep analyses. A deep analysis that finishes can add or change an action on
  the next pass.
* **Settings and maintenance.** Database checks run when the database is added,
  again once there are a couple of minutes of traffic to measure rates, and
  then every 15 minutes. They don't use AI.
* **Index changes.** When RDST sees an index appear or disappear, the plan and
  the actions follow on the next pass.

Each kind of change says when it was last checked and when it's checked next.

## How they're ranked

Every action gets a score for how much database time it should save. For an
index or a rewrite, that's the share of database time its queries take times
how much faster they'd get. Settings and maintenance findings are scored by how
serious the check rates them.

While AI monitoring is on, a short AI read of each database's open actions
adjusts the order by how urgent each one looks now, and can retire one it's
sure no longer applies.

Actions are grouped into tiers by score:

| Tier         | What goes there                                                      |
| ------------ | -------------------------------------------------------------------- |
| **Do first** | The changes that save the most: up to three per database             |
| **Then**     | Changes that still save a meaningful part of what the best one saves |
| **Later**    | Small wins                                                           |

{/* REDESIGN: tier names Do first / Then / Later land with CL 16395. Main shows High impact,
  Worth doing and Small win. */}

## Why each change matters

Each new change gets a one-sentence explanation tied to this database's
evidence: the queries it touches, their share of database time, and the writes
it costs or saves. The index plan gets two or three sentences on why its
changes fit together.

RDST writes these with a short AI call, once per change. Changes found close
together share a call, and each database gets at most 3 a day, at least 15
minutes apart. A change found after that day's calls are used shows without its
explanation until the next day's first call. Nothing new means no call.

## What you can do with one

Open an action to see its steps, its SQL and the queries it affects. From
there:

<img alt="An open action with its steps, SQL, the queries it affects and its choices" src={__img1} placeholder="blur" />

| Choice                | What it does                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Copy** the SQL      | Copies the statements to run, and the undo statements where there are any                                                                                                 |
| **Copy as migration** | Copies the change as a migration for Alembic, Prisma, Rails or Flyway                                                                                                     |
| **I did this**        | Tells RDST you made the change. It rereads the database's indexes and statistics right away. If the change doesn't show yet, it says so and checks again in a few minutes |
| **Set aside**         | Puts it away until a date you pick, with a reason. It comes back on its own after that                                                                                    |
| **Dismiss**           | Closes it, with a reason. It stays closed until you bring it back, whatever the database does                                                                             |
| **Bring back**        | Reopens something you set aside or dismissed                                                                                                                              |

{/* REDESIGN: Copy as migration, Set aside with a date and reason, and Dismiss with a reason
  land with CL 16395. Main has Not now (one week) in place of Set aside. */}

A rewrite asks you to check that it returns the same rows before you ship it.

## After you make a change

RDST closes an action on its own when the fix shows up in the database: the new
index exists, the dropped index is gone, the setting moved the way the action
asked, the maintenance ran, or the old query stopped running in favor of the
rewrite. You don't need to press **I did this** for that to happen.

For an index or a rewrite, RDST then measures the queries it was meant to help,
before and after the change:

* **Verified** means they got faster, with the before and after latency.
* **Didn't help** means they didn't, and the change may be worth undoing.

Applied changes, with these results, stay in the action history. You can undo
an index change with its undo SQL and tell RDST with **I undid this**.

{/* REDESIGN: the Applied view and I undid this land with CL 16395. Main lists these under
  Done recently. */}

An action also closes when its evidence fades, for example when the query it
was about stops carrying load. If the same problem comes back later, the action
reopens.

## Actions and the Inbox

The [Inbox](/readyset-ai/rdst/desktop/monitoring/inbox) holds things that
happened and need you, like a query that slowed down or a lost connection.
Actions holds the standing list of changes worth making. When new changes are
ready for a database, the Inbox gets one item that points to them.

{/* REDESIGN: the "changes ready" Inbox item lands with CLs 16375 and 16395. */}

## Without AI

Database checks and the index plan's measurements run without AI, so settings,
maintenance and drop-index actions keep coming with local monitoring. Changes
that come from deep analysis, the AI ranking and the written explanations need
AI monitoring. See [AI access](/readyset-ai/rdst/desktop/ai-credits).


# Agent activity (/readyset-ai/rdst/desktop/monitoring/agent-activity)


import { Callout } from 'fumadocs-ui/components/callout'

**Agent activity** in the sidebar is RDST's audit log. When RDST analyzes a
query, answers a question or checks your database, it's written here as it
happens, newest first.

<img alt="The Activity page listing what RDST did today, newest first" src={__img0} placeholder="blur" />

## Read-only diagnostics

The page lists these diagnostic rules:

| Rule                            | What it means                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| **Only reads**                  | Plans, statistics and `SELECT`s. Monitoring leaves data and schema changes to you   |
| **EXPLAIN ANALYZE is bounded**  | Read-only statements with execution timeouts. Open an entry to check its time limit |
| **No result rows go to the AI** | The AI sees SQL, plans, schema and sampled values. The log doesn't keep the values  |

## What's listed

| Action                    | What it's                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Deep analysis**         | One query analyzed, with its key finding, like "suggested an index on events(event\_type, created\_at)" |
| **Skipped deep analysis** | A query RDST chose not to run, with the reason                                                          |
| **Attention checks**      | The regular look for changes that need you                                                              |
| **Query classification**  | The quick AI read of a new query                                                                        |
| **Daily report**          | The nightly report being written                                                                        |
| **Ask**                   | A question you asked in [Ask](/readyset-ai/rdst/desktop/ask)                                            |
| **Benchmark**             | A comparison against a Readyset cache                                                                   |

Routine work, like a day of attention checks, folds into one line per database
per day. Open it to see each hour, then each check.

Open any entry to see:

* **Statements**: each one RDST ran on your database, with literals shown as
  `?`, what kind it was (EXPLAIN, EXPLAIN ANALYZE, a statistics read, a
  parameter sampling read, a hypothetical index check), how long it took and
  its time limit.
* **AI calls**: the model, what it was for, what kind of data it was sent,
  and tokens.

The once-a-minute statistics read and the look at running sessions for parameter
values aren't listed one by one.

## Filter and export

Filter by **Time**, **Database** and **Action**. **Export CSV** downloads one
row per entry for the days you pick.

The log keeps 90 days.

<Callout type="info">
  Costs for AI calls through your Readyset account are what Readyset charged.
  Costs for calls on your own Anthropic key are estimates from published prices.
</Callout>


# Data and retention (/readyset-ai/rdst/desktop/monitoring/data-and-retention)
import { Callout } from 'fumadocs-ui/components/callout'

## Where your data lives

Monitoring history stays on your computer, in RDST's data folder:

| Platform        | Folder                |
| --------------- | --------------------- |
| macOS and Linux | `~/.rdst`             |
| Windows         | `%USERPROFILE%\.rdst` |

**Settings**, then **Data & privacy**, shows the folder RDST is using.

The folder holds the readings, Inbox items, nightly reports, deep analyses,
the [Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity) log,
and your saved queries. The [CLI](/readyset-ai/rdst/cli) uses the same folder,
so a query analyzed in one shows up in the other.

## How long things are kept

| Data                                    | Kept for                                                                         |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| Per-minute readings                     | 48 hours for the top 1,000 queries by load; other tracked queries roll up sooner |
| Minute-level evidence for an Inbox item | As long as that Inbox item exists                                                |
| 5-minute readings                       | 7 days                                                                           |
| Hourly readings                         | 90 days                                                                          |
| Daily readings                          | As long as monitoring has room                                                   |
| Sampled parameter values                | 48 hours                                                                         |
| Inbox and report event history          | 30 days                                                                          |
| Agent activity                          | 90 days                                                                          |

RDST tracks the top 10,000 queries per database. The top 1,000 get full detail.
The remaining tracked queries keep 5-minute readings for 48 hours and hourly
readings for 30 days. Heavier new queries replace the lightest tracked ones;
traffic beyond the limit stays in database totals and the **Other** band.

Older readings roll up into coarser ones, so a 90-day chart still works after
the per-minute detail is gone.

## Disk use

Each monitored database has a local storage limit, 250 MB by default. When it
fills, RDST rolls up and removes the oldest minute-level readings first to make
room. Minute-level evidence for existing Inbox items stays available. The **Usage** panel in the
[monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings)
shows how much a database uses.

## Removing the data

Export any data you need before uninstalling RDST Desktop. Uninstalling removes
app data, including monitoring history. Updating the app keeps it. To keep the
app and clear the data, use **Remove all local data** in
[Settings](/readyset-ai/rdst/desktop/settings).

<Callout type="info">
  Database passwords are never in the data folder. They're in your operating
  system's keychain. See [Settings](/readyset-ai/rdst/desktop/settings#password-handling).
</Callout>


# The Database page (/readyset-ai/rdst/desktop/monitoring/database-page)






import { Callout } from 'fumadocs-ui/components/callout'

The Database page shows one database: its live chart and query list, covered
here, and its [nightly reports](/readyset-ai/rdst/desktop/monitoring/nightly-report).
The changes worth making on it are in
[Actions](/readyset-ai/rdst/desktop/monitoring/actions).

The header under the database's name shows its monitoring state and how much
history RDST has. The green monitoring dot pulses while RDST collects readings,
with reduced motion when your computer requests it. The monitoring state
opens the [monitoring menu](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#the-monitoring-menu),
where you can turn monitoring off or open the monitoring
settings.

Switching databases keeps you on the same page for the new database. From
Inbox or another page that isn't tied to one database, switching opens that
database's Database page.

## The chart

The chart stacks each query's share of the work, one colored band per query, so
the biggest bands are where your database spends its time. Switch what it plots:

| Metric         | What it shows                        |
| -------------- | ------------------------------------ |
| **Queries/s**  | Calls per second                     |
| **Latency**    | Time per call                        |
| **Time spent** | Each query's recorded execution time |

<img alt="The live chart with the Queries/s, Latency and Time spent switch, above the queries list" src={__img0} placeholder="blur" />

* Hover a band to find its query in the list below. Click it to open that query.
* Drag across the chart to zoom into a stretch of time. **Reset zoom** goes back.
* When a query is open, the chart draws that query's own line with its name, so
  you can always tell which one you're looking at.

A hatched band marks a gap in readings. **Monitoring paused: RDST couldn't reach
the database** links to the Inbox item for that outage. **No readings** marks a gap with no known cause.
For example, RDST or the computer may have been off.

## Health metrics

Under the chart, three tiles show the database as a whole. Click one to plot it.

| Tile                | What it tells you                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Connections**     | Open connections against the server's maximum, and the peak                                                |
| **Cache hit ratio** | The share of reads served from memory instead of disk. A drop means more reads go to disk, which is slower |
| **Rollbacks**       | Transactions your app started and then cancelled, per minute, plus deadlocks                               |

## Time frames

Pick a preset above the query list: **5m**, **15m**, **1h**, **24h**, **7d**,
**30d**, **90d** or **All**. **Custom** takes any start and end date and time,
from 5 minutes up to all the history RDST has stored.

The chart, the list and every number on the page follow the time frame you
pick.

## The query list

The list ranks queries by their load in the time frame. Its heading says how
much of the total they cover, for example "These 10 queries are 97% of your
database load in the last 5 minutes".

RDST tracks at most **10,000 queries per database**. Heavier new queries
replace the lightest tracked queries. Traffic beyond that limit still counts
in the database totals and the chart's **Other** band. The top **1,000** queries
get full detail; the remaining tracked queries keep coarser history. See
[Data and retention](/readyset-ai/rdst/desktop/monitoring/data-and-retention).

Each row shows:

| Column            | What it shows                                                                                                                                                                                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Score**         | The deep analysis score out of 100. Lower is worse. While work is queued or running, it shows **Queued** with its place, **Analyzing** with the current step (sampling values, running EXPLAIN or asking the AI), or **Retrying**. Otherwise, it shows **No score** until the query is analyzed |
| **Query**         | A name RDST gives it from what it does, like `COUNT on users and orders`, its status, and its SQL. Names are unique within a database; when two queries would share one, the later one gets a number, like `COUNT on events by props (3)`                                                       |
| **Calls/s**       | Calls per second in the time frame                                                                                                                                                                                                                                                              |
| **Avg latency**   | Mean time per call                                                                                                                                                                                                                                                                              |
| **Share of time** | Its share of the database's recorded execution time                                                                                                                                                                                                                                             |

Expand a row for the query's own charts, its deep analysis, its SQL and
classification, and its actions: **Analyze now** (or **View analysis progress**
while one is under way), **Benchmark**, which opens a
[benchmark](#benchmarks) with this query already picked, and **Send to Ask**.

**Analyze a query** above the list takes SQL you paste, runs a deep analysis on
it, and adds it to the list.

### Statuses

Every query gets one status, the first of these that applies, with a one-line
reason like "Traffic up 3.5x since yesterday 9:39 PM":

| Status               | Meaning                                                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Needs attention**  | It has an open [Act now](/readyset-ai/rdst/desktop/monitoring/inbox#act-now-watch-and-back-to-normal) item in the Inbox                                       |
| **Watch**            | It has an open Watch item                                                                                                                                     |
| **Fix suggested**    | Deep analysis found an index, a rewrite or a setting that would help                                                                                          |
| **Healthy**          | Analyzed, with nothing to fix                                                                                                                                 |
| **Not analyzed yet** | It hasn't had a deep analysis. The score column shows **Queued** with its place, **Analyzing** with the current step, or **Retrying** while work is under way |
| **Not analyzed**     | RDST won't analyze it. Hover for the reason, for example "UPDATE changes data, so RDST doesn't run it"                                                        |

Needs attention and Watch come straight from the Inbox, so the list and the
Inbox always agree.

<img alt="Query rows during a first run, with scores, Queued, 1st and Retrying" src={__img1} placeholder="blur" />

### Sort and filter

**Sort** orders the list by:

| Sort                                               | Orders by                                            |
| -------------------------------------------------- | ---------------------------------------------------- |
| **Impact** (default)                               | Database time in the time frame                      |
| **Biggest change**                                 | The largest significant latency change               |
| **Most frequent**                                  | Calls per second                                     |
| **Slowest**                                        | Mean latency per call                                |
| **Score, lowest first** / **Score, highest first** | The deep analysis score. Queries without one go last |

Filters narrow it down:

* **Status**: any status above, or a classification such as **Missing index**,
  **Broad scan**, **Join growth**, **Repeated work** or **Index bypassed**.
* **Table**: only queries that touch one table.
* **Search**: matches query text and table names. Press `/` to jump to it.

**Clear filters** resets them.

### Writes

`INSERT`, `UPDATE` and `DELETE` statements are hidden from the list by default.
**Show writes (N)** brings them back. They always count toward the chart and the
totals, and a heavy write can still raise an Inbox item. RDST never runs or
deep-analyzes them.

<Callout type="info">
  An Inbox item's link opens this page already set to that item's time frame
  and filtered to the queries it's about. A banner at the top says which item
  you came from, and **Show the last 24 hours** steps back out.
</Callout>

## Benchmarks

A benchmark runs one or more read queries over and over and measures latency
and throughput. The **Benchmarks** section at the bottom of the Database page
lists past runs. To start one:

1. Select **Benchmark** in the Benchmarks section, or on an expanded query,
   which picks that query for you.
2. Under **Pick queries**, select the queries to measure. The list has this
   database's monitored and saved queries, with a search box. Writes and schema
   changes can't be picked. Queries with parameters take values, filled in with
   values RDST observed where it can.
3. Choose **How long**:
   * **Quick**: 30 seconds on one connection, with a short pause between runs.
     Light load.
   * **Standard**: 2 minutes on two connections, back to back, to see how much
     throughput the query can reach. Higher load.
4. Choose **Where to run**:
   * **Source only** measures your database.
   * **Source plus Readyset** also runs the same queries at the same pace
     through Readyset. RDST starts Readyset in a temporary container on this
     computer first, which needs Docker and can add a few minutes. If Readyset
     can't start, the benchmark still measures your database.
   * **Readyset only** measures a Readyset deployment you've already set up for
     this database: a target named after it with `-cache` on the end, like
     `demoshop-cache`, which [rdst cache deploy](/readyset-ai/rdst/cli/cache/deploy)
     adds. Queries Readyset hasn't cached still reach your database through it.
5. Select **Start benchmark**.

<img alt="Benchmark queries with three queries picked, the Quick and Standard lengths, and the Source only, Source plus Readyset and Readyset only choices" src={__img2} placeholder="blur" />

A benchmark runs against your live database and adds load to it while it runs.
Only reads run, and you can stop it at any time.

With Readyset in the run, RDST creates and warms a temporary cache for each
query, checks that the results match, and measures both sides. It drops the
temporary caches when the run finishes. The container can stay up for the next
run.

Use parameter values and a load that represent your application. Compare mean
and tail latency for each side. The result describes those queries, their
parameters, and the test workload.

The temporary Readyset uses shallow caching. It doesn't configure replication
or put Readyset in front of your application. See [Readyset Cache](/cache) for
a production deployment, or use
[rdst query cache-compare](/readyset-ai/rdst/cli/cache/compare) from the CLI.


# Deep analysis (/readyset-ai/rdst/desktop/monitoring/deep-analysis)




import { Callout } from 'fumadocs-ui/components/callout'

A deep analysis reads a query's execution plan and works out where its time
goes. When a change would help, it may suggest adding an index, rewriting the
query, or changing a database setting. It gives the query a score out of 100 and shows up in the query's
**Deep analysis** section on the [Database page](/readyset-ai/rdst/desktop/monitoring/database-page).

Background analysis runs up to 3 queries at a time per database, and up to 6
across all your databases. It saves the full analysis record, including plans,
findings, and suggested changes, and tests the rewrites it suggests. Tested
indexes and rewrites feed [Actions](/readyset-ai/rdst/desktop/monitoring/actions).

## How many run each day

Each database has two settings in the
[monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings):

* **Deeply analyze the top N queries per day** defaults to **10**. When
  monitoring turns on, all of the top N get their first deep analysis right
  away. You can pick 5, 10, 25, 50, 100, 200 or 500.
* **Analyze up to M new top queries per day** defaults to **25**. With
  **Analyze new top queries** on, queries entering the top N for the first time
  get analyzed automatically, up to this separate daily ceiling.

RDST re-ranks queries by their current load every few minutes. A query that
falls out of the top before its turn can give its place to a busier one.
When the day's ceiling is reached, the query isn't queued. RDST picks it up
on the next day if it's still in the top N. Daily ceilings reset at midnight
on your computer's clock. The Analyses list only contains work queued to run now.

## What gets analyzed

With **Deep analysis** on, RDST picks queries in this order:

* **Initial top queries get analyzed right away.** All of the top N are eligible
  as soon as readings arrive. RDST aims to score the first page within about
  10 minutes, with only a few analyses running at once to limit database load.
* **New top queries get analyzed automatically.** A query entering the top N for
  the first time uses the newcomer setting while **Analyze new top queries** is on.
* **Top queries get analyzed again.** Each of the 15 busiest queries is eligible
  for re-analysis once its last analysis is more than a day old. These runs
  follow the daily ceiling, so scores keep up with your data and load.

RDST only analyzes reads. Writes, schema changes and session commands show
**Not analyzed**, with the reason on hover.

If a deep analysis gets an unusable answer from the AI, RDST retries once
right away and shows **Retrying**. Classifications get the same immediate retry.

If the AI service still doesn't answer, RDST tries again after 1, 5 and 30 minutes.
The row shows **Will retry at** with a time, then **Retrying** when the retry
is near. After that, the query waits for its normal turn.

## Analyze a query yourself

A query you pick always gets its turn first:

* **Analyze now** on a query row puts it at the front of the line, ahead of
  every automatic analysis. It works with **Deep analysis** switched off and
  after the day's automatic analyses are used. If the query's already waiting,
  the row shows its place, like **Queued, 2nd**.
* **Analyze a query** above the list takes SQL you paste and analyzes it right
  away.

You can deep analyze any query yourself, as many times as you like, from its
row or detail. Manual analysis always runs and never counts toward either
automatic daily ceiling. Raise the settings to have more queries analyzed
automatically.

## The values it uses

A query with parameters needs real values to run. RDST picks them in this
order and says which it used on the analysis:

| Analysis says                                        | Where the values came from                                                     |
| ---------------------------------------------------- | ------------------------------------------------------------------------------ |
| Measured with values from live traffic               | Values sampled from your app's own running queries                             |
| Measured with values taken from the table's own data | Real values read from the table, when none were sampled                        |
| Plan only                                            | No real values were available, so RDST read the plan without running the query |

RDST never makes values up. With **EXPLAIN only** chosen, every analysis is plan
only. See [EXPLAIN ANALYZE or EXPLAIN only](/readyset-ai/rdst/desktop/monitoring/turn-on#explain-analyze-or-explain-only).

## The Analyses list

**Analyses** at the bottom of the sidebar lists the work that's queued or
running on every database:

* Deep analyses appear in one group per database that expands to each query.
  They show **Analyzing now**, **Queued, 2nd** and so on, or **Retrying**.
* Reports appear while they're being written.
* Analyses you started appear while they're queued or running.

**Done today** stays collapsed at the bottom. Work that isn't queued isn't
listed. The score column on the Database page shows **Queued** with its place,
**Analyzing** with the current step, or **Retrying**.

Click a queued or analyzing item to open that query in the main list, on its
page, scrolled into view and highlighted. Your filters and sort stay as they
are. If a filter hides it, RDST offers **Show it**, which clears only the
filters needed to reveal it.

<img alt="The Analyses list with queued deep analyses, a retry, and the day's finished work collapsed" src={__img0} placeholder="blur" />

The **Deep analysis** group in a database's monitoring settings shows the same
list for that database.

## Read an analysis

<img alt="A full analysis with its plan score, what it found and the exact fix" src={__img1} placeholder="blur" />

Expand a query on the [Database page](/readyset-ai/rdst/desktop/monitoring/database-page)
and find **Deep analysis**. Start with its findings and score, then inspect the
plan and supporting measurements.

| Section                   | What to check                                                 |
| ------------------------- | ------------------------------------------------------------- |
| Execution plan            | Operators that consume the most work                          |
| Estimates and actual rows | Differences that may point to stale statistics or a poor plan |
| Indexes                   | Suggested definitions and why they may help                   |
| Rewrites                  | Candidate SQL to review and test                              |
| Readyset assessment       | Whether the query is supported for caching                    |

Measured timings appear only when RDST ran the query. Plan-only analysis uses
planner estimates. For parameterized SQL, the analysis labels where its values
came from.

Suggested changes need review and testing. RDST never applies them; the ones
worth making show up in [Actions](/readyset-ai/rdst/desktop/monitoring/actions). Use a
[benchmark](/readyset-ai/rdst/desktop/monitoring/database-page#benchmarks) to
measure a caching candidate, or [rdst analyze](/readyset-ai/rdst/cli/query-analysis/analyze)
for CLI analysis and follow-up questions.

<Callout type="info">
  Query execution has a timeout. Check the limit used by a run in
  [Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity).
</Callout>


# The Inbox (/readyset-ai/rdst/desktop/monitoring/inbox)




import { Callout } from 'fumadocs-ui/components/callout'

**Inbox** in the sidebar lists what RDST noticed on all your monitored
databases. The badge next to it counts unread items. **All databases** at the
top shows everything; pick a database there to see only its items. Opening an
item for another database switches the app to that database.

The Inbox holds things that happened and need you. The standing list of
changes worth making, like an index to add, lives in
[Actions](/readyset-ai/rdst/desktop/monitoring/actions). When new changes are
ready for a database, the Inbox gets one item that points to them.

{/* REDESIGN: the "changes ready" Inbox item lands with CLs 16375 and 16395. */}

## What raises an item

RDST raises an item when something changes in a way that matters for the
database. A consistently heavy query is covered in the
[nightly report](/readyset-ai/rdst/desktop/monitoring/nightly-report). The Inbox
focuses on changes and incidents.

| Item                                                                                            | When                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query latency increased**                                                                     | A query that carries real load got slower than its own usual level                                                                                                    |
| **Query plan may have changed**                                                                 | A query's latency jumped in a way that points to a new plan                                                                                                           |
| **Query traffic increased**                                                                     | A query that carries real load is being called much more often                                                                                                        |
| **New heavy query**                                                                             | A query first seen in the last day is already carrying real load                                                                                                      |
| **Query stopped running**                                                                       | A busy query stopped. RDST skips queries that normally run in bursts                                                                                                  |
| **Stuck query**                                                                                 | A query has been running for over a minute                                                                                                                            |
| Several queries at once                                                                         | Several queries changed in the same burst, so they share one item named after the biggest. Smaller ones are listed as "N smaller queries also moved at the same time" |
| **Rollbacks or deadlocks increased**, **Cache hit ratio dropped**, connections near the maximum | A change across the whole database                                                                                                                                    |
| **Can't reach the database**                                                                    | RDST lost its connection. See [Notifications](/readyset-ai/rdst/desktop/monitoring/notifications#lost-connection)                                                     |
| **Sign in to resume alerts**, **Database password not set**, and similar                        | Monitoring needs something from you before it can carry on                                                                                                            |
| **Daily report ready**                                                                          | The nightly report has been written                                                                                                                                   |

RDST considers queries near the top by database time, new heavy queries, and
changes that add substantial database work. Call count alone doesn't qualify a
cheap query for an alert. Smaller changes can appear in a report or as context
inside another item.

## Act now, Watch and back to normal

Items sit in sections by how urgent they are. Each item has a one-line reason
that says why, like "Act now: latency up 3.2x on a top-10 query today, still
happening".

| Section               | What goes there                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Act now** (red)     | Hurting the database right now, like a lost connection or a big slowdown on a key query that's still happening |
| **Watch** (amber)     | Worth a look today. Smaller changes and reports list last                                                      |
| **Recovered** (green) | Back to normal, or closed, in the last 24 hours                                                                |

RDST closes an item on its own once the measurements are back to normal for 3
checks in a row. The item turns green and names what recovered and when, like
"Latency back to normal at 11:25 PM". Something that's back to normal never
stays in Act now.

The tabs at the top filter to **Open**, **Act now** or **Watch**.

<img alt="The Inbox with its Watch items and one opened, showing what to do and its history" src={__img0} placeholder="blur" />

## Repeats

When the same burst happens again, RDST adds it to the existing item instead of
opening a new one. Expand the item to see each occurrence, newest first, with its
time and size.

A burst that repeats on a schedule, every hour or at the same time each day,
becomes normal. It's marked **Usual** and ranks Watch at most. It alerts again
only when an occurrence is bigger or lasts longer than usual, and the item says
so: "This happens every day around 2:00 AM, and this time it's bigger than
usual."

## Opening an item

Items start collapsed to one line. Click one to expand it and see the queries
involved, before and after numbers, and a small chart for each.

Each item links to the right place:

| Link                      | Opens                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Open query**            | That query on the [Database page](/readyset-ai/rdst/desktop/monitoring/database-page), at the right section |
| **Open affected queries** | The Database page filtered to just the item's queries, set to the item's time frame                         |
| **Open this time frame**  | The Database page zoomed to one occurrence, showing the tracked queries that ran then                       |
| **Check connection**      | The connection details, for a lost connection or a missing password                                         |

<img alt="The Database page opened from an Inbox item, with its banner and the zoomed chart" src={__img1} placeholder="blur" />

Some items also offer next steps as tiles, like **See when it stopped**, **See
what else ran then** or **Check its plan**. When the fix is outside RDST, the
item lists the steps, with SQL you can copy.

## Dismiss, snooze and mute

From an item's menu:

* **Dismiss** closes it. It stays silent for the rest of that episode.
* **Snooze** hides it for 1 hour, 1 day or 1 week.
* **Mute** stops that kind of alert for the query, the database or all
  databases, for a day, a week, or until you unmute it.

Temporary mutes end at their set time. Alerts after that time follow your
notification settings again.

Muted alerts are still recorded. **Show muted** lists them, and
**Notification settings** holds the mute rules.

<Callout type="info">
  An item notifies once per episode. It notifies again only if the problem goes
  away and comes back, or gets at least twice as bad as when you were last told.
</Callout>


# Continuous monitoring (/readyset-ai/rdst/desktop/monitoring)
import { Cards, Card } from 'fumadocs-ui/components/card'
import { Callout } from 'fumadocs-ui/components/callout'

Continuous monitoring keeps RDST running in the background, reading your
database's query statistics every minute. It learns what normal looks like for
each query, and when something changes in a way that matters, you hear about it.

Once monitoring is on, RDST:

* **Records** calls, latency and share of database time for up to 10,000
  queries per database. Traffic beyond that still counts in the totals and
  the **Other** band. The top 1,000 queries get full detail.
* **Spots changes** that matter: a busy query getting slower, a new heavy query,
  a traffic spike, a query stuck for over a minute, connections near the limit.
* **Deep-analyzes** the heaviest queries in the background and tests the
  indexes and rewrites it suggests.
* **Keeps a ranked list of [Actions](/readyset-ai/rdst/desktop/monitoring/actions)**:
  the indexes to add or drop, the rewrites, the settings and the maintenance
  worth doing, with the SQL to run. It checks that each change took effect and
  measures whether it helped.
* **Files what it finds** in the [Inbox](/readyset-ai/rdst/desktop/monitoring/inbox),
  most urgent first, and sends a
  [system notification](/readyset-ai/rdst/desktop/monitoring/notifications)
  for the things that need you now.
* **Writes a [nightly report](/readyset-ai/rdst/desktop/monitoring/nightly-report)**
  on each database's day.
* **Logs analyses and AI work** in [Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity),
  with the diagnostic statements and AI calls for each action.

RDST never writes to your database. Monitoring uses read-only diagnostics,
and you apply any change yourself.

<Callout type="info">
  Monitoring runs inside the desktop app, which stays in your system tray (the
  menu bar on macOS) after you close its window. See
  [Get Started](/readyset-ai/rdst/desktop/install#running-in-the-tray).
</Callout>

## What you need

| Requirement          | Notes                                                                                                                                                                                                                                    |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A connected database | PostgreSQL 13+ or MySQL 8.0+. See [Connect a database](/readyset-ai/rdst/desktop/connect)                                                                                                                                                |
| Query statistics     | `pg_stat_statements` on PostgreSQL, `performance_schema` on MySQL. RDST checks both when you turn monitoring on                                                                                                                          |
| A Readyset sign-in   | AI monitoring needs it: change checks every few minutes, deep analysis and reports. An Anthropic key of your own covers deep analysis and reports, and doesn't replace signing in. See [AI access](/readyset-ai/rdst/desktop/ai-credits) |

Recording keeps working without AI. You still get the chart, the query list,
and locally measured alerts, including lost connections and stuck queries.

When your account's AI usage limit is reached, AI monitoring stops gracefully,
local monitoring keeps running, and the app asks you to contact us.

## Guides

<Cards>
  <Card title="Turn on monitoring" href="/readyset-ai/rdst/desktop/monitoring/turn-on" description="Check that RDST has access to your query statistics. Turn on monitoring and watch the first readings arrive." />

  <Card title="Actions" href="/readyset-ai/rdst/desktop/monitoring/actions" description="See the changes worth making on each database, best first, and the SQL to make them." />

  <Card title="The Database page" href="/readyset-ai/rdst/desktop/monitoring/database-page" description="See how busy your database is and which queries use most of its time." />

  <Card title="The Inbox" href="/readyset-ai/rdst/desktop/monitoring/inbox" description="Review changes on your databases and see what to do next." />

  <Card title="Troubleshooting" href="/readyset-ai/rdst/desktop/monitoring/troubleshooting" description="Check why monitoring isn't working and find the logs." />
</Cards>


# Nightly report (/readyset-ai/rdst/desktop/monitoring/nightly-report)


import { Callout } from 'fumadocs-ui/components/callout'

At the configured report time, RDST writes a report on each monitored
database's previous local day. Open it from the **Report** tab on the
[Database page](/readyset-ai/rdst/desktop/monitoring/database-page). A dot on
the tab means there's a new one, and the Inbox gets a **Daily report ready**
item.

## What's in it

<img alt="The Report tab on a database page: the daily report and the day in numbers" src={__img0} placeholder="blur" />

The report is titled with the day it covers, like "Tuesday, September 29". A
section bar at the top jumps between its parts:

| Section           | What it covers                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Health**        | Database health: connections, cache hit ratio, rollbacks and other checks                                        |
| **Numbers**       | The day in numbers, compared with the day before when there's one                                                |
| **Brief**         | The day in brief: the top priorities, each with what it means for your app                                       |
| **Actions**       | Database actions in order, with SQL you can copy                                                                 |
| **Chart**         | The day's chart                                                                                                  |
| **Spikes**        | When load jumped, and which queries drove it                                                                     |
| **What happened** | The day's alerts and events                                                                                      |
| **Queries**       | Queries to look at, with their deep analysis                                                                     |
| **All queries**   | Every query, sortable by calls, latency, database time and change on the day before. **Download CSV** exports it |

Report metrics come from recorded readings and database checks. The written parts, like the brief, come
from AI working from those numbers.

To work through the changes themselves, open
[Actions](/readyset-ai/rdst/desktop/monitoring/actions), which tracks each one
until it's applied and measured.

A report doesn't wait indefinitely for queued analyses. When its analysis wait
ends, it uses the available findings and plans to finish.

## Other days

Use the day picker to open an earlier report. **Print / Save as PDF** in the
report's toolbar gives you a copy to share.

## Write one now

The report menu has **Run today's snapshot now**. It covers today so far. Progress shows the
history, analyses, health checks, and summary as they finish.

## Change the time or turn it off

In the [monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings),
**Nightly report** turns it off for a database, and **Report time** moves it to
another hour.

<Callout type="info">
  If RDST wasn't running at report time, it writes the latest day's report when
  it next starts. A day with no readings gets no report.
</Callout>


# System notifications (/readyset-ai/rdst/desktop/monitoring/notifications)
import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'

Every alert lands in the [Inbox](/readyset-ai/rdst/desktop/monitoring/inbox).
Eligible items can also send a Windows notification, macOS alert, or Linux
desktop notification. Delivery follows your event switches, daily notification
setting, and operating system permissions. Click a notification to open the item.

Notifications come from the desktop app, so they keep coming while its window is
closed, as long as RDST is running in the tray.

## What notifies

Open **Inbox**, then **Notification settings**. Under **Notify me when**, each
event has its own switch:

| Event                                                                                                            | Default |
| ---------------------------------------------------------------------------------------------------------------- | ------- |
| **Database unreachable**: RDST can't connect, so monitoring is paused                                            | On      |
| **Monitoring resumed**: RDST reached the database again                                                          | Off     |
| **Stuck query**: a query has been running for over a minute                                                      | On      |
| **Query changes**: a query that carries real load slows down or changes plan, or a new heavy query shows up      | On      |
| **Database-wide changes**: connections near the maximum, a rollback or deadlock spike, or a cache hit ratio drop | On      |
| **Monitoring needs you**: sign-in expired, the database password is missing, or setup is incomplete              | On      |

An event that's off still files its Inbox item. It just doesn't pop up.

## How many a day

**Notifications a day** controls pop-ups per database. Check or change its
value in Notification settings. Past that setting, changes still land in the
Inbox and in the nightly report.

A lost connection doesn't count toward the cap and is never held back by it.

## Lost connection

When RDST can't reach a monitored database, it:

* raises **Can't reach the database** in Act now and requests a notification;
* shows the tray icon's problem state, with the database named in its tooltip;
* marks the gap on the chart as **Monitoring paused: RDST couldn't reach the
  database**.

A single blip doesn't count. RDST waits for 2 failed checks in a row, or 2
minutes since the first failure, before it raises the item. When the database
is back, the item closes on its own and says how long the gap was.

## Turn notifications on or off

Two switches control the same thing:

* **Notifications** in the tray menu.
* **System notifications** in **Notification settings**.

**Send test notification** in the tray menu shows a sample, so you can check
your system lets them through.

## Windows notification settings

Windows can block notifications without telling the app. RDST checks on launch
and every few minutes, and if they're blocked, it says so in the window and in
the tray menu (**Notifications are blocked by Windows... Fix**). To turn them
on:

<Steps>
  <Step>
    Open **Settings**, then **System**, then **Notifications**. The tray item
    opens this page for you.
  </Step>

  <Step>
    Turn **Notifications** on.
  </Step>

  <Step>
    Find **RDST Desktop** in the list of apps and turn it on.
  </Step>

  <Step>
    Check **Do not disturb** is off, or that RDST is allowed through it.
  </Step>
</Steps>

On macOS, allow RDST in **System Settings**, **Notifications**. RDST uses
alerts, which stay on screen until you dismiss them, so a lost database isn't
missed.

<Callout type="info">
  In the browser version, `rdst web`, there's no tray. **Browser notifications**
  in Notification settings pop up only while an RDST tab is open. Email and phone
  alerts aren't available yet.
</Callout>


# Settings and monitoring limits (/readyset-ai/rdst/desktop/monitoring/pause-and-limits)








import { Step, Steps } from 'fumadocs-ui/components/steps'

## The monitoring menu

On the Database page, the monitoring state under the database's name (for
example **AI monitoring on**) opens a menu:

| Item                    | What it does                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| **Turn off monitoring** | Stops reading this database, after you confirm                                                          |
| **Turn on monitoring**  | Shown while monitoring is off. Opens the [turn-on dialog](/readyset-ai/rdst/desktop/monitoring/turn-on) |
| **Monitoring settings** | Opens the settings below                                                                                |

<img alt="The monitoring menu open under the database name, with Turn off monitoring and Monitoring settings" src={__img0} placeholder="blur" />

## Monitoring settings

Each database has its own settings. Open them from the monitoring menu, or
with the gear button at the top right of the Database page. Changes apply right
away.

<img alt="Monitoring settings for a database with the default values" src={__img1} placeholder="blur" />

### What runs

| Setting                     | Default                  | What it does                                                                                                                                                                                                  |
| --------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Monitor this database**   | Off until you turn it on | Reads the database's query statistics every minute, tracking the top 10,000 queries. Switching it off asks you to confirm, like **Turn off monitoring**                                                       |
| **AI monitoring**           |                          | Shows whether AI monitoring is on for this database and how many of your account's AI monitoring slots are used. See [the database limit](#the-database-limit)                                                |
| **Deep analysis**           | On                       | Analyzes new and top queries automatically. Off, only the analyses you start run                                                                                                                              |
| **Measure real timings**    | On                       | On, RDST runs read-only `SELECT`s with `EXPLAIN ANALYZE`, each with a time limit, and records real timings. Off, it reads plans with `EXPLAIN` and your queries never run. The turn-on dialog sets this first |
| **Analyze new top queries** | On                       | Analyzes a query automatically the first time it enters the top N                                                                                                                                             |

### Automatic analysis

| Setting                                      | Default     | What it does                                                                                                                                                                                                                                                                  |
| -------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Deeply analyze the top N queries per day** | Top 10      | When monitoring turns on, all of the top N get their first deep analysis right away. They're re-analyzed as the ranking changes. Choose 5, 10, 25, 50, 100, 200 or 500. See [how many run each day](/readyset-ai/rdst/desktop/monitoring/deep-analysis#how-many-run-each-day) |
| **Analyze up to M new top queries per day**  | 25          | Analyzes queries entering the top N for the first time. Beyond this daily ceiling, a query isn't queued; RDST picks it up the next day if it's still in the top N. This setting applies while **Analyze new top queries** is on                                               |
| **Change checks**                            | Every 5 min | How often AI monitoring checks for new and changed queries: every 5 minutes, every 15 minutes, or hourly. Checking less often uses less AI, and changes take longer to reach the Inbox                                                                                        |
| **Pushes a day**                             | 3           | How many [system notifications](/readyset-ai/rdst/desktop/monitoring/notifications) this database can send a day: none, 1, 3, 5 or 10. Past the limit, alerts still land in the Inbox and the nightly report. A lost connection doesn't count toward it                       |
| **Nightly report**                           | On          | Writes a [report](/readyset-ai/rdst/desktop/monitoring/nightly-report) on this database once a day                                                                                                                                                                            |
| **Report time**                              | 12 AM       | The hour the nightly report is written, on your computer's clock                                                                                                                                                                                                              |

You can deep analyze any query yourself, as many times as you like, from its
row or detail. Manual analysis always runs and never counts toward either
automatic daily ceiling.

### Deep analysis and Usage

The **Deep analysis** group shows the queued and running work for this
database. It's the same list as
[Analyses](/readyset-ai/rdst/desktop/monitoring/deep-analysis#the-analyses-list)
in the sidebar.

**Usage** shows AI calls over the last 7 days and how much storage this
database's history uses. When your account's AI usage runs out, the app says
**You've run out of AI usage for now**. Local monitoring keeps running, and AI
resumes once your usage is raised. Use **Contact us** to ask for more.

## Control monitoring from the tray

<Steps>
  <Step>
    Right-click the RDST icon in the system tray (click it in the macOS menu
    bar).
  </Step>

  <Step>
    Open **Monitoring** and pick **Turn monitoring off for** or **Turn
    monitoring on for** the database. **Turn all monitoring off** and **Turn all
    monitoring on** apply to every database.
  </Step>
</Steps>

Monitoring is either on or off for each database. When it's off, RDST stops
collecting readings. The history it already recorded stays, and the chart
shows the gap. The tray icon shows when monitoring is off for every database.

## Turn it off and on again

Pick **Turn off monitoring** in the monitoring menu, or switch off **Monitor
this database**, and confirm.

<img alt="The confirmation before turning monitoring off" src={__img2} placeholder="blur" />

RDST stops reading the database. The charts keep the history recorded so far,
new changes go unnoticed until you turn it back on, and its AI monitoring slot
opens up for another database. **Settings**, then **Targets**, has the same switch for every
database.

To turn it back on, pick **Turn on monitoring** in the same menu. The
[turn-on dialog](/readyset-ai/rdst/desktop/monitoring/turn-on) runs its checks
again. A database with history picks up where it left off, and deep analysis
follows its automatic settings.

To stop RDST completely, pick **Quit RDST** from the tray menu.

## The database limit

RDST currently allows AI monitoring on up to 3 databases per account.
[Contact us for more](mailto:hello@readyset.io). Monitoring beyond that runs
locally without AI.

<img alt="The AI monitoring panel for a database on local monitoring when all 3 slots are in use" src={__img3} placeholder="blur" />

The app shows how many AI monitoring slots your account is using. The count
includes enabled databases even when they're unreachable, and it applies across
computers.

A database without an AI slot can use **Turn on local monitoring**. RDST records
it, draws its chart, lists its queries, and raises locally measured alerts.
Its AI change checks, automatic analyses, and written report summary are off.
The Database page labels this state as local monitoring.

To open up an AI slot, turn monitoring off for a database or remove its target.
Then select **Turn on AI monitoring** in the settings for the database you want
to use. If the app can't reach Readyset when you release a slot, the account
count can take a while to update.

Adding your own [Anthropic key](/readyset-ai/rdst/desktop/ai-credits#your-own-anthropic-key)
raises the limit to 10 databases. You still need to be signed in for AI
monitoring. [Contact us for more](mailto:hello@readyset.io).

Ask and individual Analyze calls don't claim an AI monitoring slot.


# Troubleshooting (/readyset-ai/rdst/desktop/monitoring/troubleshooting)
import { Callout } from 'fumadocs-ui/components/callout'

## The backend log

Most problems leave a trace in RDST's backend log. **Open logs folder** in the
tray menu opens it.

| Platform | Log file                                  |
| -------- | ----------------------------------------- |
| Windows  | `%APPDATA%\rdst-desktop\logs\backend.log` |
| macOS    | `~/Library/Logs/rdst-desktop/backend.log` |
| Linux    | `~/.config/rdst-desktop/logs/backend.log` |

The log rotates at 5 MB and keeps three older files. It can contain SQL and
error messages from your database, so check it before you share it.

## No notifications

1. Look at the tray menu. If it shows **Notifications are blocked by
   Windows... Fix**, click it and follow
   [Windows notification settings](/readyset-ai/rdst/desktop/monitoring/notifications#windows-notification-settings).
2. Check **Notifications** in the tray menu is ticked.
3. Pick **Send test notification** in the tray menu. If the test shows up,
   notifications work.
4. Open **Inbox**, then **Notification settings**, and check the event is
   switched on under **Notify me when**.
5. Check **Notifications a day** for that database. Past the cap, alerts wait in
   the Inbox. A lost connection bypasses the daily cap. Its event switch and system notifications must still be on.
6. Check the alert isn't muted. **Show muted** in the Inbox lists muted alerts.

Notifications need RDST running. If you picked **Quit RDST**, nothing is
watching until you open it again.

## RDST can't connect

**Can't reach the database** in the Inbox means RDST's last checks failed.

* Click **Check connection** on the item to see the error and edit the host,
  port, user or password.
* Check the database is up and reachable from this computer, including any VPN
  or SSH tunnel it needs. A database inside WSL is reachable from Windows
  through `localhost`.
* After a few failures in a row RDST checks less often, up to every 15 minutes.
  Once a check succeeds, it starts reading again right away and closes the item.
* **Database password not set** means the password isn't in this computer's
  keychain. Enter it again in [Settings](/readyset-ai/rdst/desktop/settings).

## No queries, or fewer than expected

* **Waiting for queries** means the database hasn't run anything since monitoring
  started. Point your app or a test suite at it.
* **Writes are hidden.** `INSERT`, `UPDATE` and `DELETE` statements are hidden
  from the list by default. Click **Show writes (N)** above the list.
* **Filters.** Check the status, table and search filters, and the time frame.
  **Clear filters** resets them.
* **Only RDST's own queries.** The user RDST connects as can't read other users'
  statistics. Grant `pg_read_all_stats` on PostgreSQL, or `SELECT` on
  `performance_schema.*` on MySQL. When RDST notices, the Inbox item's
  **Check setup** link runs the
  [prerequisite checks](/readyset-ai/rdst/desktop/monitoring/turn-on#prerequisites)
  again, with the fix for each.
* **SQL cut off.** Raise `track_activity_query_size` on PostgreSQL, or
  `performance_schema_max_digest_length` on MySQL, to 4096 or more.

## Alerts or analyses stopped

* **Sign in to resume alerts** or **Sign in to continue deep analysis**: your
  Readyset sign-in expired. Recording carries on; sign in again to restart the AI
  checks.
* **Monitoring limit reached**: this database is past the
  [database limit](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#the-database-limit).
* When an [automatic daily ceiling](/readyset-ai/rdst/desktop/monitoring/deep-analysis#how-many-run-each-day)
  is reached, additional queries aren't queued. They're picked up the next day
  if they're still in the top N. You can analyze any query yourself at any time;
  manual runs never count toward these ceilings.
* **You've run out of AI usage for now** means your account's AI usage limit
  has been reached. Local monitoring keeps running. Use **Contact us** to ask
  for more; AI resumes once your usage is raised. See
  [AI access](/readyset-ai/rdst/desktop/ai-credits).
* RDST needs about a day of readings before it alerts on changes.

## RDST is slow to start after an update

An update can migrate RDST's data files on the first launch. The window says
**Upgrading your data, this can take a minute** while it runs. Leave it to
finish. If it fails, the window offers **Try again** and **Open logs**.

<Callout type="info">
  Still stuck? Use **Give feedback** in the sidebar, or ask in the RDST Discord,
  and include the end of `backend.log`.
</Callout>


# Turn on monitoring (/readyset-ai/rdst/desktop/monitoring/turn-on)








import { Callout } from 'fumadocs-ui/components/callout'
import { Step, Steps } from 'fumadocs-ui/components/steps'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

## Turn it on

<Steps>
  <Step>
    **Open the Database page.** Pick the database in the selector at the top of
    the sidebar, then click **Database**. If you haven't added one yet, see
    [Connect a database](/readyset-ai/rdst/desktop/connect). After you add a
    database, either from Targets or during your first launch, the
    **Turn on monitoring** dialog opens next.
  </Step>

  <Step>
    **Click Turn on monitoring.** It's on the Database page, and in the
    monitoring menu under the database's name. RDST connects and runs its
    prerequisite checks. Each one shows **Passed** or the fix for your provider, with the SQL
    to copy. Fix a step and RDST checks again on its own.
  </Step>

  <Step>
    **Choose how deep analysis reads a query.** See
    [EXPLAIN ANALYZE or EXPLAIN only](/readyset-ai/rdst/desktop/monitoring/turn-on#explain-analyze-or-explain-only) below.
  </Step>

  <Step>
    **Click Turn on monitoring** in the dialog. The first reading starts right
    away.
  </Step>
</Steps>

<img alt="The Turn on monitoring dialog with the required checks passed, a recommended fix, and the signed-in AI monitoring explanation" src={__img0} placeholder="blur" />

If the database can't be reached, the dialog opens its connection details so you
can fix the host, port or password and test it right there.

If a required check fails, the button reads **Turn on anyway**. Monitoring turns
on, and RDST starts reading queries once the required checks pass.

A recommended check that isn't met says what's wrong and **Here's how to fix
it**, with the SQL and whether it needs a database restart. Monitoring works
without it.

When you're signed in, the dialog explains that turning on monitoring includes
AI checks through Readyset.

When AI isn't available, the monitoring switch area says **You won't get
automatic AI recommendations for this database.** It offers **Sign in** when
you're signed out, or **Manage databases** when your account's database slots
are all in use.

When you're signed out, the dialog's main action is **Sign in to turn on AI
monitoring**. It explains that local monitoring keeps charts and connection
alerts running. **Turn on local monitoring** lets you continue without signing
in. See
[AI access](/readyset-ai/rdst/desktop/ai-credits).

<img alt="The signed-out turn-on dialog explains local monitoring and offers Sign in to turn on AI monitoring as its main action" src={__img1} placeholder="blur" />

## Prerequisites

RDST reads the statistics your database already keeps. It needs those
statistics switched on, and permission to read them for every user, not just its
own sessions.

<Tabs items={['PostgreSQL', 'MySQL']}>
  <Tab value="PostgreSQL">
    | Check                                                   | What it means                                                                                  |
    | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | pg\_stat\_statements is loaded at server start          | It's in `shared_preload_libraries`. Changing this needs a restart                              |
    | pg\_stat\_statements is created in your database        | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements;`                                           |
    | Permission to read every user's statements and activity | The user is a member of `pg_read_all_stats`, or a superuser                                    |
    | RDST sees new statements as they run                    | RDST runs a tagged test statement on a second session and confirms the statistics picked it up |
    | Long queries are captured in full (recommended)         | `track_activity_query_size` is 4096 or more, so long SQL isn't cut off                         |

    To grant the permission:

    ```sql
    GRANT pg_read_all_stats TO rdst_readonly;
    ```
  </Tab>

  <Tab value="MySQL">
    | Check                                                 | What it means                                                                                  |
    | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | performance\_schema is on                             | `performance_schema = ON`. Changing this needs a restart                                       |
    | Permission to read performance\_schema                | `SELECT` on `performance_schema.*`                                                             |
    | Statement statistics are being collected              | The `global_instrumentation` and `statements_digest` consumers are on                          |
    | RDST sees new statements as they run                  | RDST runs a tagged test statement on a second session and confirms the statistics picked it up |
    | Recent statements are kept for analysis (recommended) | The statement history consumers are on, so deep analysis can use real parameter values         |
    | Long queries are captured in full (recommended)       | `performance_schema_max_digest_length` is 4096 or more                                         |

    To grant the permission and turn the consumers on:

    ```sql
    GRANT SELECT ON performance_schema.* TO 'rdst_readonly'@'%';

    UPDATE performance_schema.setup_consumers SET ENABLED = 'YES'
      WHERE NAME IN ('global_instrumentation', 'statements_digest');
    ```

    The `UPDATE` resets when MySQL restarts. On RDS and Aurora, set the matching
    `performance_schema_consumer_*` parameters in your DB parameter group to keep
    it.
  </Tab>
</Tabs>

For the full set of grants, including a read-only account to start from, see
[Database permissions](/readyset-ai/rdst/desktop/database-permissions).

## EXPLAIN ANALYZE or EXPLAIN only

When RDST deep-analyzes a query, it asks the database for the query's plan. The
dialog asks how:

| Option                                                   | What happens                                                                                                                                          |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Run EXPLAIN ANALYZE on problem queries** (recommended) | RDST runs the read-only query with a time limit and records real timings. It adds a little load to the database                                       |
| **EXPLAIN only**                                         | RDST gets the plan without running the query. The statement isn't executed. Other diagnostic reads still run, and there are no measured query timings |

This applies to automatic analyses and the ones you start. You can change it
later with **Measure real timings** in the
[monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings).

RDST only runs `SELECT` statements. It never runs an `INSERT`, `UPDATE`,
`DELETE` or schema change, whichever option you pick. Every execution has a timeout, shown in
[Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity).

**Include deep analysis** is on by default in the turn-on dialog. Turn it off
and the EXPLAIN ANALYZE and EXPLAIN only options are disabled, and no automatic
analyses run. Choosing EXPLAIN ANALYZE shows a short warning that confirms it
runs on problem queries. You can change **Deep analysis** later in the
[monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings).

## The first few minutes

On a database's first run, the Database page shows **This is your first run on
this database**, with what happens over the next few minutes:

<img alt="The first-run panel: queries found, the first deep analyses under way, and the nightly report tonight" src={__img2} placeholder="blur" />

| Step                    | What happens                                                                                                                                                                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Found your queries**  | The first reading lands right away. RDST reads every 10 seconds for the first 5 minutes, then once a minute, and the query list fills in                                                                                                                                                                                              |
| **First deep analyses** | All of the top N queries get their first deep analysis right away. N defaults to 10. Your first [Actions](/readyset-ai/rdst/desktop/monitoring/actions) follow once the 10 busiest reads are analyzed, usually within about 10 minutes. See [deep analysis](/readyset-ai/rdst/desktop/monitoring/deep-analysis#how-many-run-each-day) |
| **Nightly report**      | Written at the report time set for this database, midnight by default                                                                                                                                                                                                                                                                 |

Rows show **Classifying** until their quick AI read of the SQL and schema
arrives, then a classification such as **Missing index**. Rows waiting for a
deep analysis show their place, like **Queued, 1st**. **Hide** closes the
panel.

<img alt="The live chart drawing from the first readings" src={__img3} placeholder="blur" />

The panel only appears on a database's true first run. If you turn monitoring
off and on again, RDST picks up from the history it has, with no first-run
panel.

<Callout type="info">
  RDST needs about a day of readings before it alerts on changes, so it knows
  what normal looks like for each query. A lost connection or a stuck query
  alerts from the start.
</Callout>

### Waiting for queries

If nothing has run on the database yet, the page says **Waiting for queries**.
RDST shows what it sees, never simulated traffic, so send it some real work:

1. Start your app with this database as its connection, and click through the
   pages that matter.
2. Or run your test suite or a load script against it.
3. Keep RDST running. The list updates as readings arrive; the window can be closed.


# Privacy and data handling (/readyset-ai/rdst/desktop/privacy)
import { Callout } from 'fumadocs-ui/components/callout'

RDST runs on your machine and connects directly to your database. Your
monitoring history, settings and reports stay on your machine, and RDST never
writes to your database. Connect it with a read-only database user: when the
user you add can write, RDST warns you and gives you the SQL to create a
read-only one.

This page covers what RDST keeps, what leaves your machine, and how to turn off
the parts you don't want.

## What RDST stores

RDST keeps its data on your own machine: the databases you've added, your
saved queries, monitoring history, reports and settings. None of it is copied
to Readyset.

**Remove all local data** in [Settings](/readyset-ai/rdst/desktop/settings)
deletes all of it.

## Database passwords

RDST saves database passwords in your operating system's secure credential
store: Keychain on macOS, Credential Manager on Windows and the Secret Service
on Linux. They're never written to disk in plain text and never leave your
machine.

On a system without a credential store, RDST keeps passwords in memory for the
session only and asks for them again next time.

## Your Readyset account

AI monitoring needs a Readyset sign-in. See [AI access](/readyset-ai/rdst/desktop/ai-credits).
Your account holds your sign-in, your AI usage, and a count of the databases
you monitor with AI. RDST counts each database by a fingerprint, a hash of its
engine, host, port and database name salted with your account, so Readyset can
count them without learning which databases they are.

Signed out, monitoring runs locally without AI and RDST doesn't contact your
account.

## What is sent to the AI

Only features that need reasoning call an AI model:
[continuous monitoring](/readyset-ai/rdst/desktop/monitoring) while AI
monitoring is on, [Analyze](/readyset-ai/rdst/desktop/monitoring/deep-analysis),
[Ask](/readyset-ai/rdst/desktop/ask), [schema discovery](/readyset-ai/rdst/desktop/schema),
and the written parts of reports. Everything else in the app works without an AI
call.

| Sent                                                                                                  | Never sent                   |
| ----------------------------------------------------------------------------------------------------- | ---------------------------- |
| SQL text. Change checks and classification send it normalized, with literals replaced by placeholders | The rows your queries return |
| Execution plans from `EXPLAIN` and `EXPLAIN ANALYZE`                                                  | The contents of your tables  |
| Schema metadata: table and column names and types, indexes, row estimates                             | Your database credentials    |
| Measured numbers: calls, latency, share of database time, server settings                             | Your connection details      |
| Descriptions you wrote in the semantic layer                                                          |                              |

Deep analysis runs the query on your own database with real values, sampled
from your app's running queries or read from the table, so the plan shows how
the query actually behaves. The analysis says which source it used. The
[Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity) log
doesn't keep the values, and RDST deletes its local copy after 48 hours.

To stop automatic analyses from running queries with real values, turn off
**Deep analysis** in the
[monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings).

[Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity) lists
every AI call with the model, what it was for, and the kinds of data it sent.

### Where requests go

| Work                                                                                                                    | Where it goes                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Change checks, query classification and ranking actions                                                                 | Jev, Readyset's model for quick judgments, through your Readyset account. These calls carry normalized SQL with schema, index and timing evidence |
| Deep analysis, reports, Ask, with the included AI                                                                       | Claude Haiku from Anthropic, through Readyset's AI service                                                                                        |
| Deep analysis, reports, Ask, with [your own Anthropic key](/readyset-ai/rdst/desktop/ai-credits#your-own-anthropic-key) | Straight from your computer to Anthropic's API. Readyset doesn't see these requests                                                               |

{/* TODO: hosted analysis runs on Claude Haiku from Anthropic once Faruk's change lands
  (no Gerrit CL yet). Until then the hosted model is GLM 5.3 Flash through OpenRouter. Check
  this row before publishing. */}

Under Anthropic's API terms, Anthropic doesn't train models on API data, and
it deletes API inputs and outputs within 30 days by default.

## What is sent to Readyset

Your database's rows and table contents are never sent to Readyset. With the
included AI, the requests described above pass through Readyset's AI service on
their way to the model, and Readyset records how much AI each account uses.

When you run a [comparison](/readyset-ai/rdst/desktop/comparisons) or the
[demo](/readyset-ai/rdst/desktop/demo), Readyset runs as a container **on your
machine**. It connects to your database locally to serve cached results, and the
data stays between those two processes. Nothing is transmitted to Readyset the
company, and the containers are removed when you are done with them.

## Usage telemetry

RDST reports usage telemetry so we can see which features are used and where
they fail. Signed out, it's anonymous. When you're signed in, it's linked to your
Readyset account and its email.

| Collected                                                          | Never collected                   |
| ------------------------------------------------------------------ | --------------------------------- |
| A random device identifier, and your account when you're signed in | IP-derived identity               |
| RDST version, operating system, Python version                     | Query text                        |
| Which commands ran, and whether they succeeded                     | Table, column, or database names  |
| Query **hashes**, so repeat analyses can be counted                | Connection details or credentials |
| Cumulative counts of how often features are used                   | Anything your queries returned    |

Queries appear only as hashes. The hash identifies that the same query was
analyzed twice; it cannot be turned back into the query.

### Turning it off

Set this environment variable before you start RDST:

```bash
export RDST_TELEMETRY=off
```

It turns telemetry off completely, and nothing else in RDST changes.

## Working in a restricted environment

For a database that nothing outside its network may reach, run RDST next to it.
Install the [CLI](/readyset-ai/rdst/cli) on a host inside the perimeter and use
[`rdst web`](/readyset-ai/rdst/cli/integrations/web) over SSH port forwarding,
which puts this same interface in your browser while the database connection
stays inside the network.

Signed out and without an LLM key, RDST makes no outbound requests other than
telemetry, which the setting above disables.


# Settings (/readyset-ai/rdst/desktop/settings)
Open **Settings** at the bottom of the sidebar. It has three tabs:

* **Targets** lists your databases, each with its connection check and a
  **Monitoring** switch. **Add target** connects a new one by hand or imports
  databases from a provider. See [Connect a database](/readyset-ai/rdst/desktop/connect).
* **AI** has your Readyset sign-in and your Anthropic key. See
  [AI access](/readyset-ai/rdst/desktop/ai-credits).
* **Data & privacy** shows where RDST keeps its data, with **Remove all local
  data**.

Each database's monitoring controls are on its Database page. The monitoring
state under its name opens the
[monitoring menu](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#the-monitoring-menu),
and the gear button opens its
[monitoring settings](/readyset-ai/rdst/desktop/monitoring/pause-and-limits#monitoring-settings).

## Remove a database

Removing a database turns its monitoring off and cancels its queued analyses.
If you add a database with the same name again, monitoring starts off. Turn it
on when you're ready to collect readings.

## Password handling

Database passwords are stored in your operating system's keychain or read from
a named environment variable. `config.toml` stores the variable name, never its
value. Environment variables take precedence when set.

If you move RDST's data to another computer, enter the passwords and sign in
again. Copying the data directory doesn't copy keychain credentials.

## Local storage

The default data directory is `~/.rdst` on macOS and Linux, or
`%USERPROFILE%\.rdst` on Windows. `RDST_DATA_DIR` can select another directory.
The [CLI](/readyset-ai/rdst/cli) shares it under the same operating system user.

See [Data and retention](/readyset-ai/rdst/desktop/monitoring/data-and-retention)
for what monitoring keeps and for how long.

**Remove all local data** deletes RDST's data directory. Export anything you
need to keep first.

## Privacy

[Privacy and data handling](/readyset-ai/rdst/desktop/privacy) includes telemetry
controls. [Agent activity](/readyset-ai/rdst/desktop/monitoring/agent-activity)
shows background analyses, diagnostic statements, and AI calls.


# RDST (/readyset-ai/rdst)
import { Cards, Card } from 'fumadocs-ui/components/card'

RDST runs on your computer and monitors your PostgreSQL or MySQL databases.
It records query activity, checks for changes, and analyzes queries in the
background. The Inbox lists findings by urgency. A nightly report covers each
database's day.

You don't need a Readyset cache to use RDST.

<Cards>
  <Card title="Start monitoring" href="/readyset-ai/rdst/desktop/install" description="Install the desktop app, connect a database, and turn on monitoring." />

  <Card title="Continuous monitoring" href="/readyset-ai/rdst/desktop/monitoring" description="Read the Database page, review the Inbox, and control background analysis." />

  <Card title="Command line" href="/readyset-ai/rdst/cli" description="Analyze queries, scan application code, audit databases, and manage caches." />
</Cards>

## Desktop and command line

Use the desktop app for monitoring. Closing its window keeps it running in the
system tray or macOS menu bar. Monitoring stops when you quit RDST or your
computer sleeps.

Use the CLI for individual commands, scripts, and CI. It shares targets, saved
queries, and analyses with the desktop app under the same operating system
user. Keep both installations up to date so they can read and write the same
data files.

| Task                                  | Guide                                                                 |
| ------------------------------------- | --------------------------------------------------------------------- |
| Review a query's load and analysis    | [Database page](/readyset-ai/rdst/desktop/monitoring/database-page)   |
| Investigate a change                  | [Inbox](/readyset-ai/rdst/desktop/monitoring/inbox)                   |
| Read a database's daily health report | [Nightly report](/readyset-ai/rdst/desktop/monitoring/nightly-report) |
| Check SQL in a code change            | [rdst scan](/readyset-ai/rdst/cli/query-analysis/scan)                |
| Audit a fleet on a schedule           | [rdst fleet audit](/readyset-ai/rdst/cli/fleet-and-audit/fleet-audit) |
| Connect Claude Code to RDST           | [RDST MCP tools](/readyset-ai/rdst/cli/integrations/claude-code)      |

Continuous monitoring is configured in the desktop or
[browser interface](/readyset-ai/rdst/cli/integrations/web). There isn't an
`rdst monitor` command. The MCP tools don't expose the monitoring Inbox or
nightly reports.

## Local and AI monitoring

Local monitoring records query statistics and keeps the charts running. AI
monitoring checks changes, analyzes queries, and writes report summaries.
Sign in to Readyset for AI monitoring. When your account's AI usage runs out,
the app says **You've run out of AI usage for now**.

When an AI usage limit is reached, AI monitoring stops gracefully. Local monitoring
keeps running, and the app asks you to contact us. See
[AI access](/readyset-ai/rdst/desktop/ai-credits).

## Readyset caching

Readyset is a SQL cache that runs alongside your database. RDST can
[benchmark a query with Readyset](/readyset-ai/rdst/desktop/monitoring/database-page#benchmarks)
or [deploy a cache from the CLI](/readyset-ai/rdst/cli/cache). These are optional
workflows. Monitoring doesn't require Docker or a Readyset deployment.


# Readyset Cloud (/readyset-cloud)


Readyset Cloud is a managed offering of Readyset. Readyset runs inside your own environment, right next to your application and database, while the Readyset team deploys, operates, and monitors it for you through a managed control plane.

<img alt="Readyset Cloud architecture" src={__img0} />

Because Readyset stays inside your environment, your data never leaves your infrastructure. You get the performance benefits of Readyset's caching without taking on the operational burden of running it yourself.

## What you get

* **Deployed in your environment.** Readyset runs in your own VPC or Kubernetes cluster, alongside the database it caches. Your data and traffic stay within your network boundary.
* **Managed by the Readyset team.** Provisioning, upgrades, scaling, and health monitoring are handled for you by Readyset's managed control plane.
* **No operational burden.** You don't need to run, tune, or babysit Readyset infrastructure. The Readyset team keeps it healthy.

## Get started

Interested in Readyset Cloud? Get in touch with the Readyset team at [hello@readyset.io](mailto:hello@readyset.io) and we'll help you get set up in your environment.


# Authentication (/reference/authentication)
import { Callout } from 'fumadocs-ui/components/callout'

Clients authenticate to Readyset the same way they authenticate to your
upstream database: Readyset plays the server role in the client handshake and
verifies the supplied credentials before accepting the connection. Which
authentication methods are available depends on the client protocol,
PostgreSQL or MySQL.

## Allowed users

Readyset authenticates each connection against a set of allowed users.
[`--allowed-users`](/reference/config-options#--allowed-users) (env
`ALLOWED_USERS`) is a comma-separated list of `username:password` pairs; the
user from [`--upstream-db-url`](/reference/config-options#--upstream-db-url) is
accepted as well.

<Callout type="info">
  `--allowed-users` seeds the allowed-users set only on a deployment's
  **first** startup. After that the set is persisted, so later edits to
  `--allowed-users` are ignored. Manage users at runtime with
  [`ALTER READYSET ADD/MODIFY/DROP USER`](/command-reference#alter-readyset-add-user)
  instead. [User Management](/reference/user-management) covers the whole
  lifecycle, from this bootstrap to runtime changes.
</Callout>

To inspect the users that can currently authenticate, read the
[`readyset.users`](/reference/system-views#readysetusers) view (passwords are
never exposed):

```sql
SELECT "user" FROM readyset.users;
```

To turn authentication off, start Readyset with
`--allow-unauthenticated-connections`. Clients then connect without
credentials, the allowed-users list is ignored, and Readyset uses the
`--upstream-db-url` credentials for its own upstream connections.
[Cache authorization](/reference/cache-authorization) does not apply in this
mode, because there are no client identities to authorize.

## PostgreSQL

Readyset supports two PostgreSQL authentication methods for client
connections. The
[`--postgres-authentication-method`](/reference/config-options#--postgres-authentication-method)
flag (env `POSTGRES_AUTHENTICATION_METHOD`) selects which one Readyset
requests during the connection handshake.

### scram-sha-256

The default. Readyset requests SASL authentication and verifies the client
with the SCRAM-SHA-256 challenge-response exchange, so the password is never
sent over the wire. This is the same method modern PostgreSQL servers use by
default, and it works with standard PostgreSQL clients and drivers without
extra configuration.

Over a TLS connection, Readyset also offers channel binding
(`SCRAM-SHA-256-PLUS`), which ties the authentication exchange to the TLS
session. Clients that support channel binding negotiate it automatically.

### cleartext

Readyset requests the password in cleartext and compares it directly. Because
the password crosses the connection unhashed, use this method only over a
[TLS](/reference/tls) connection or on a trusted network.

To select it:

```bash
readyset --postgres-authentication-method cleartext [other options]
```

<Callout type="info">
  To require every client to connect over TLS, set
  [`--tls-mode`](/reference/config-options#--tls-mode) to `required`. Readyset
  then rejects any non-TLS connection during the handshake.
</Callout>

## MySQL

Readyset supports two MySQL authentication plugins: `mysql_native_password`
and `caching_sha2_password`. The
[`--mysql-authentication-method`](/reference/config-options#--mysql-authentication-method)
flag controls which plugin Readyset advertises to clients during the MySQL
handshake.

### mysql\_native\_password

The legacy authentication plugin, used by default in MySQL 5.7 and available
in MySQL 8.0. It uses a challenge-response protocol based on SHA-1 hashing. No
additional infrastructure (TLS or RSA keys) is required for password exchange.

This was the default in earlier versions of Readyset and remains available for
environments that have not migrated to `caching_sha2_password`.

### caching\_sha2\_password

The default authentication plugin in Readyset (and in MySQL 8.0+). It is the
only built-in plugin in MySQL 9.x (which removed `mysql_native_password`). It
uses SHA-256 hashing and supports two authentication paths:

* **Fast auth (cache hit):** If Readyset has already verified a user's
  password in a previous connection, it caches the password hash. Subsequent
  connections for the same user skip the full exchange and authenticate using
  only the cached hash. This is comparable in cost to `mysql_native_password`.

* **Full auth (cache miss):** On the first connection for a given user (or
  after a restart, which clears the cache), the client must send the password
  encrypted with the server's RSA public key or over a TLS connection. This
  requires either TLS to be enabled or the client to obtain the RSA public key.

<Callout type="info">
  The password cache is in-memory and is cleared when Readyset restarts. The
  first connection after a restart always performs full authentication.
</Callout>

### Configuration

Readyset defaults to `caching_sha2_password`. To use `mysql_native_password`
instead:

```bash
readyset --mysql-authentication-method mysql_native_password [other options]
```

Or using the environment variable:

```bash
MYSQL_AUTHENTICATION_METHOD=mysql_native_password readyset [other options]
```

### RSA key management

When `caching_sha2_password` is enabled, Readyset needs an RSA key pair for
full-auth password encryption on non-TLS connections.

#### Auto-generated keys

By default, Readyset generates a 2048-bit RSA key pair at startup and persists
it in the deployment subdirectory under
[`--storage-dir`](/reference/config-options#--storage-dir) (the storage
directory defaults to the current working directory) as two files:

* `caching_sha2_password_private_key.pem` (PKCS#1 PEM, mode `0600`)
* `caching_sha2_password_public_key.pem` (PKCS#8 PEM, mode `0644`)

On subsequent starts, Readyset loads the existing key from the private key file
so that the public key stays stable across restarts.

#### Supplying your own key

To use your own RSA key pair, place a PKCS#1 PEM-encoded private key at
`caching_sha2_password_private_key.pem` in the deployment subdirectory before
starting Readyset. Readyset loads this file at startup instead of generating a
new key, and derives the public key in memory.

#### Retrieving the public key

Clients that connect without TLS need the server's RSA public key to encrypt
their password. You can retrieve it with:

```sql
SHOW READYSET RSA PUBLIC KEY;
```

This returns a single row containing the PEM-encoded public key. Most MySQL
client libraries request this key automatically during the handshake (for
example, the `--get-server-public-key` option in the `mysql` CLI).

See the [command reference](/command-reference#show-readyset-rsa-public-key)
for details.

### Migrating from MySQL 8.x to 9.x

MySQL 9.x removed the `mysql_native_password` plugin entirely. Readyset
defaults to `caching_sha2_password`, so no configuration change is needed. If
you were previously overriding the authentication method to
`mysql_native_password`, remove that override:

1. Remove any
   [`--mysql-authentication-method`](/reference/config-options#--mysql-authentication-method)
   flag set to `mysql_native_password` (or the corresponding
   `MYSQL_AUTHENTICATION_METHOD` environment variable).
2. Ensure your client drivers support `caching_sha2_password`. Most modern
   MySQL connectors (MySQL Connector/J 8.0+, mysql2 for Node.js, Go `mysql`
   driver, mysqlclient for Python) support it out of the box.
3. If you do not use TLS, verify that your client can retrieve the RSA public
   key. Most drivers do this automatically, but some require an explicit option
   (e.g., `--get-server-public-key` for the `mysql` CLI, or
   `allowPublicKeyRetrieval=true` for JDBC).

<Callout type="info">
  If you use TLS between clients and Readyset, the RSA key exchange is not
  needed. The password is sent securely over the encrypted channel, and full
  auth completes without RSA.
</Callout>

### Performance considerations

* **Fast auth** is the common case in steady-state operation. Once a user has
  authenticated at least once after startup, all subsequent connections for
  that user use the cached hash. The performance is comparable to
  `mysql_native_password`.
* **Full auth** occurs only on the first connection per user after a Readyset
  restart (or if the cache is otherwise empty for that user). The RSA
  encryption adds a small amount of overhead to this initial connection.
* The password cache is per-process and is not shared across Readyset restarts.


# Cache Authorization (/reference/cache-authorization)
import { Callout } from 'fumadocs-ui/components/callout'

Your database decides which users may read which tables, and it re-checks
those grants on every query. A [shallow cache](/concepts/shallow-caching) hit
is answered by Readyset without reaching your database, so without extra care
a cache would let a user keep reading a query after their access to the
underlying tables was revoked.

Cache authorization prevents that. Before Readyset serves a cache hit, it
confirms that the connected user is still allowed to run that query. Users who
are allowed are served from the cache as usual; users who are not are sent to
your database, exactly as if the query were uncached.

Cache authorization is on whenever [authentication](/reference/authentication)
is enabled. There is nothing to configure and no opt-out, and it adds no
latency to a cache hit.

## What a user sees

Whether a given user is served from a cache depends only on whether your
database grants that user access to the query:

* **Allowed** users get cache hits, at the same hit rate as before. A user's
  identity never affects what is stored, so enabling cache authorization does
  not shrink or partition the cache.
* **Users without access** are transparently routed to your database, which
  applies its own permission check and returns the appropriate result or
  error. They simply never get a cache hit for that query.

Because an unauthorized user is always sent to your database rather than
guessed at, cache authorization can never turn a permitted query into an
error or an error into data. Your database stays the single source of truth
for who may read what; Readyset only mirrors its decisions and never
reimplements grants, roles, or inheritance.

<Callout type="info">
  Readyset learns each user's access by asking your database, on its own
  background connections, whether that user could run the cached query -- without
  actually running it. These connections identify themselves as
  `READYSET_ACL_POOLER` in your database's process list. No client connection is
  ever used for this, and no check ever runs while a query is being served.
</Callout>

## Keeping up with privilege changes

Readyset re-reads each user's privileges from your database on a fixed
interval (default 5 minutes, set with
[`--cache-acl-refresh-interval-secs`](/reference/config-options#--cache-acl-refresh-interval-secs)).
This interval is the longest a user can keep being served cache hits after a
`GRANT` or `REVOKE` you issue directly on your database -- the same kind of
staleness window a cache already has for data via its TTL. A user who is
newly granted access converges just as quickly; until Readyset picks up the
change, their queries are simply proxied to your database.

Some changes take effect immediately, without waiting for the interval:

* **Creating a cache** authorizes every user against it in the background,
  starting with its creator. Creating a cache is not itself a grant: the
  creator is served from it only once their own privileges check out, the
  same as everyone else.
* **[`ALTER READYSET ADD/MODIFY USER`](/command-reference#alter-readyset-add-user)**
  re-checks that user; `DROP USER` forgets them. See
  [User Management](/reference/user-management).
* **[`ALTER READYSET FLUSH PRIVILEGES`](/command-reference#alter-readyset-flush-privileges)**
  re-checks everyone on demand. Run it right after a `GRANT` or `REVOKE` on
  your database to apply the change without waiting for the next interval.

## Roles

### PostgreSQL

PostgreSQL evaluates privileges against a session's current role, and cache
authorization follows the same rule. A session that has switched roles with
`SET ROLE` is judged by that role's access, not the login user's. Readyset
does not decide role membership itself: a `SET ROLE` is forwarded to your
database on the session's own connection, and the session's identity changes
only if your database accepts it. Roles are authorized ahead of use, so
assuming a role does not cost a warm-up period.

### MySQL

On MySQL, a user is authorized under their default roles -- the same
privileges a fresh connection gets. Users whose access comes through roles are
fully supported as long as those roles are active by default (via
`SET DEFAULT ROLE` or `activate_all_roles_on_login=ON`).

A session that changes its active roles with `SET ROLE` mid-connection is not
served from the cache for the rest of that connection; its queries are proxied
to your database, which enforces privileges directly. Sessions that rely on
mid-connection role switching trade away caching on MySQL for now.

## Inspecting cache authorization

The [`readyset.cache_grants`](/reference/system-views#readysetcache_grants)
system view shows, for every user and cache, whether that user is currently
served from it and when Readyset last checked. Prometheus metrics under the
`readyset_cache_acl` prefix cover the same ground for dashboards, including how
often queries are routed to your database instead of served from a cache.

For a single connection,
[`EXPLAIN LAST STATEMENT`](/command-reference#explain-last-statement) reports
why its previous statement went to your database instead of a cache: a
`Readyset_reason` of `cache_acl_denied` or `cache_acl_unknown` means cache
authorization made the call.

## Limitations

* Cache authorization applies to [shallow caches](/concepts/shallow-caching)
  on both MySQL and PostgreSQL. It does not apply under
  [`--allow-unauthenticated-connections`](/reference/config-options), where
  there are no user identities to authorize.
* It enforces table-level grants. Row-level security is handled separately by
  Readyset's RLS-aware caching, which composes with cache authorization.
* [`SHOW CACHES`](/command-reference#show-caches) lists the query text of every
  cache, including caches over tables a user cannot read.


# Advanced Configurations (/reference/config-options)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Readyset configuration options are set using command flags or environment variables.
For many common `readyset` options, you can set environment variables once instead of manually passing the flags each time you execute commands.

* To find out which flags support environment variables, see the documentation for each [configuration option](#configuration-options).
* To output the current configuration of Readyset and other environment variables, run `env`.
* When a command uses environment variables, the variable names are printed to the command's logs.
* To get a list of possible configuration options, run `readyset --help`.

Readyset prioritizes command flags, environment variables, and defaults as follows:

1. If a flag is set for a command, Readyset uses it.
2. If a flag is not set for a command, Readyset uses the corresponding environment variable.
3. If neither the flag nor environment variable is set, Readyset uses the default for the flag.
4. If there's no flag default, Readyset returns an error.

### Command flags

```
readyset --option value [FLAG OPTIONS]
```

### Environment variables

```
OPTION=value [ENV OPTIONS] readyset
```

## Configuration Options

#### `--address`, `-a`

<div class="option-details" markdown="1">
  The IP address/hostname and port that Readyset listens on.

  This option accepts a list of addresses. Specify `--address` multiple times, or pass a comma-separated list via the `LISTEN_ADDRESS` environment variable, to bind several sockets at once (for example, to listen on both an IPv4 and an IPv6 interface).

  If not set, Readyset follows the upstream database's own listening convention:

  * **MySQL adapter:** `[::]:3307`, a dual-stack IPv6 wildcard socket, which accepts both IPv4 and IPv6 clients on Linux. Matches MySQL 8.0's `bind_address = '*'` default.
  * **PostgreSQL adapter:** `127.0.0.1:5433` and `[::1]:5433`, separate IPv4 and IPv6 loopback sockets. Matches PostgreSQL's `listen_addresses = 'localhost'` default.

  To listen only on IPv6, pass an IPv6 address explicitly. For example, use `--address '[::1]:5433'` for loopback, or `--address '[::]:5433'` for all interfaces. To listen on a specific pair of IPv4 and IPv6 interfaces, pass `--address` twice:

  ```
  readyset --address 10.0.0.5:5433 --address '[2001:db8::1]:5433'
  ```

  Or, via the environment:

  ```
  LISTEN_ADDRESS='10.0.0.5:5433,[2001:db8::1]:5433' readyset
  ```

  **Env variable:** `LISTEN_ADDRESS`
</div>

#### `--allowed-users`

<div class="option-details" markdown="1">
  Comma list of allowed `username:password` pairs to authenticate database connections with. If not set, the username and password in [`--upstream-db-url`](#--upstream-db-url) will be used. If `--allow-unauthenticated-connections` is passed, this will be ignored.

  Naming a user twice starts the deployment mid-[password rotation](/reference/user-management#rotating-a-password-without-downtime). The first password is the current one and the second is the old password retained alongside it. Password rotations require MySQL mode.

  **Env variable:** `ALLOWED_USERS`

  <Callout type="info">
    `--allowed-users` seeds the allowed-users set only on Readyset's **first** startup for a deployment (together with the [`--upstream-db-url`](#--upstream-db-url) user). After that, the set is persisted and read from stored values, so later edits to `--allowed-users` are ignored; manage users at runtime with [`ALTER READYSET ADD/MODIFY/DROP USER`](/command-reference#alter-readyset-add-user) and inspect the current set via [`readyset.users`](/reference/system-views). See [User Management](/reference/user-management) for the full lifecycle.
  </Callout>
</div>

#### `--auto-cache`

<div class="option-details" markdown="1">
  Enables Readyset's [automatic shallow caching](/concepts/shallow-caching/auto-caching) mode: every previously-unseen `SELECT` becomes a candidate for an automatically-created [shallow cache](/concepts/shallow-caching), with no `CREATE CACHE` statement or `/*rs+ ... */` hint required.

  This flag is shorthand for setting [`--cache-mode`](#--cache-mode) to `shallow` and [`--query-caching`](#--query-caching) to `inrequestpath`. It is mutually exclusive with both of those flags; pass them explicitly only when you need finer-grained control than this convenience flag provides.

  Bootstrap and introspection traffic (system-schema queries, session/user variables, non-deterministic functions like `NOW()` or `RAND()`) is filtered out by an [eligibility filter](/concepts/shallow-caching/auto-caching#eligibility-filter) and routed straight to the upstream database without creating a cache.

  **Default:** off

  **Env variable:** `AUTO_CACHE`
</div>

#### `--cdc-db-url`

<div class="option-details" markdown="1">
  The URL for snapshotting and replication from Readyset to the upstream database, or a list of URLs with the same syntax as [`--upstream-db-url`](#--upstream-db-url).
  If omitted, --upstream-db-url will be used.

  With a list, replication connects to the highest-weight server. When that server fails, replication moves to the next-highest-weight server. See [Failover](/reference/failover#automatic-failover-with-server-lists). Replication will use the new server until the next time the list changes or the next time the replication server fails.

  <Callout>
    By default, Readyset attempts to snapshot and replicate all tables in the
    database specified in [`--cdc-db-url`](#--cdc-db-url). However, if the queries
    you want to cache in Readyset access only a subset of tables in the database,
    you can use the [`--replication-tables`](#--replication-tables) option to
    narrow the scope accordingly. Filtering out tables that will not be used in
    caches will speed up the snapshotting process.
  </Callout>

  **Env variable:** `CDC_DB_URL`
</div>

#### `--cache-acl-refresh-interval-secs`

<div class="option-details" markdown="1">
  How often, in seconds, [cache authorization](/reference/cache-authorization) re-reads each user's privileges from the upstream database. The interval bounds how long a user revoked on the upstream can keep being served cache hits; run [`ALTER READYSET FLUSH PRIVILEGES`](/command-reference#alter-readyset-flush-privileges) to re-check immediately instead of waiting for the next interval. Applies only when authentication is enabled.

  **Default:** `300`

  **Env variable:** `CACHE_ACL_REFRESH_INTERVAL_SECS`
</div>

#### `--cache-ddl-address`

<div class="option-details" markdown="1">
  Sets up a separate listener address dedicated to cache DDL statements (like `CREATE CACHE`, `DROP CACHE`, `DROP ALL CACHES`, and [hint-based cache creation](/concepts/shallow-caching/hint-based-caches)).

  * **Not set (default):** Cache DDL statements are allowed from any connection on the main listening address.
  * **Set:** Readyset opens a second listener on the specified address. Only connections arriving on that address are allowed to run cache DDL statements. Connections on the main [`--address`](#--address--a) listener will have cache DDL rejected.

  This is an access control mechanism — it lets you expose the main proxy address to application traffic while restricting cache management operations to a separate, potentially internal-only, address.

  **Env variable:** `CACHE_DDL_ADDRESS`
</div>

#### `--cache-mode`

<div class="option-details" markdown="1">
  Controls how `CREATE CACHE` (without an explicit `DEEP` or `SHALLOW` modifier) behaves.

  **Possible values:**

  * `deep`: Always attempt a streaming dataflow (deep) cache. Queries unsupported by the dataflow engine return an error.
  * `shallow`: Always create a TTL-based shallow cache.
  * `deep-then-shallow`: Attempt a deep cache first; if the query is unsupported by the dataflow engine, fall back to a shallow cache automatically.

  **Default:** `shallow`

  **Env variable:** `CACHE_MODE`
</div>

#### `--client-connect-timeout-ms`

<div class="option-details" markdown="1">
  How long, in milliseconds, a client has to complete the connection handshake and authenticate before Readyset closes the connection.

  **Default:** `10000`

  **Env variable:** `CLIENT_CONNECT_TIMEOUT_MS`
</div>

#### `--cleanup`

<div class="option-details" markdown="1">
  If supplied, clean up assets for the supplied deployment. If an upstream URL is supplied, also clean up various assets related to upstream (replication slot, etc.).
</div>

#### `--default-coalesce-ms`

<div class="option-details" markdown="1">
  Default coalescing window (in milliseconds) for shallow caches when no `COALESCE` clause is specified in `CREATE SHALLOW CACHE`. During this window, concurrent requests for the same query and parameter values are coalesced on a cache miss: only the first request goes to upstream, and the rest wait for its result.

  Set to `0` to disable coalescing by default.

  **Default:** `5000`

  **Env variable:** `DEFAULT_COALESCE_MS`
</div>

#### `--default-ttl-ms`

<div class="option-details" markdown="1">
  Default TTL (in milliseconds) for shallow cache entries when no `POLICY TTL` clause is specified in `CREATE SHALLOW CACHE`. Each cache entry is considered stale after this duration since its last access.

  **Default:** `10000`

  **Env variable:** `DEFAULT_TTL_MS`
</div>

#### `--deployment-mode`

<div class="option-details" markdown="1">
  The operational mode for this Readyset process.

  Possible values:

  * `standalone`: Run an entire deployment of Readyset in this process (Adapter and Server).
  * `embedded-readers`: Store cached query results with this Adapter instead of the Server. To use
    this option, you must pass `--no-readers` when starting [`readyset-server`](readyset-server.md).
  * `adapter`: Run this process as an Adapter with no locally cached data (requires a Server to be run
    separately).

  **Default:** `standalone`

  **Env variable:** `DEPLOYMENT_MODE`
</div>

#### `--disable-create-publication`

<div class="option-details" markdown="1">
  Disable running `CREATE PUBLICATION` for PostgreSQL. If this flag is set a publication named `readyset` for all tables should be added manually on the primary server before streaming replication will start.

  <Callout>
     Contact support for instructions on how to manually add the publication. 
  </Callout>

  **Env variable:** `DISABLE_CREATE_PUBLICATION`
</div>

#### `--disable-setup-ddl-replication`

<div class="option-details" markdown="1">
  Disable running DDL Streaming Replication setup for PostgreSQL. If this flag is set the DDL setup SQL queries will need to be manually run on the primary server before streaming replication will start.

  <Callout>
     Contact support for instructions on how to manually run the DDL setup SQL queries. 
  </Callout>

  **Env variable:** `DISABLE_SETUP_DDL_REPLICATION`
</div>

#### `--disable-telemetry`

<div class="option-details" markdown="1">
  Don't sent anonymous [telemetry data](/reference/telemetry) to Readyset.

  **Env variable:** `DISABLE_TELEMETRY`
</div>

#### `--disable-upstream-ssl-verification`

<div class="option-details" markdown="1">
  Disable verification of SSL certificates supplied by the upstream database (PostgreSQL only; ignored for MySQL). Ignored if `--upstream-db-url` is not passed.

  <Callout type="warning">
    If invalid certificates are trusted, any certificate for any site will be trusted for use, including expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.
  </Callout>

  **Env variable:** `DISABLE_UPSTREAM_SSL_VERIFICATION`
</div>

#### `--require-gtid`

<div class="option-details" markdown="1">
  Require GTID-based replication for MySQL. When set, Readyset uses Global Transaction Identifiers (GTIDs) instead of traditional binlog file/position tracking for replication. If the upstream MySQL server does not have `gtid_mode=ON`, replication fails rather than falling back to binlog file/position.

  This flag is opt-in because many MySQL servers have `gtid_mode=ON` without requiring GTID-based replication. By defaulting to binlog file/position, existing deployments are unaffected and operators can choose when to switch.

  When not set, Readyset uses binlog file/position regardless of the server's `gtid_mode` setting.

  **Default:** `false`

  **Env variable:** `REQUIRE_GTID`
</div>

#### `--max-gtid-rows-to-skip`

<div class="option-details" markdown="1">
  Maximum number of row events to skip during GTID crash recovery within a single transaction. When Readyset restarts after a crash mid-transaction, it replays from the pending GTID and skips row events that were already applied. If the pending event index exceeds this limit, replication fails assuming the persisted state is corrupt. Increase this value if the upstream database has transactions with more than 10,000 row events.

  **Default:** `10000`

  **Env variable:** `MAX_GTID_ROWS_TO_SKIP`
</div>

#### `--enable-rls`

<div class="option-details" markdown="1">
  Postgres [row-level security](/concepts/shallow-caching/row-level-security) awareness for shallow caching. On by default. Readyset reads your RLS policies from `pg_catalog` and partitions each shallow cache over an RLS-protected table by the session state its policies read, so a cache hit can only return rows the session was entitled to see.

  Requires read access to the catalog relations listed under [Required privileges](/concepts/shallow-caching/row-level-security#required-privileges). If they are unreadable, Readyset refuses to start rather than cache RLS-protected tables with a shared key.

  Has no effect on a MySQL upstream.

  <Callout type="warning">
    Setting this to 

    `false`

     is dangerous. The RLS catalog is not consulted and every shallow cache is created with a shared, session-independent key. Enabling RLS on an already-cached table afterwards would serve one tenant's rows to another, with no later correction. Only set it to 

    `false`

     for a Postgres deployment where no table has, or will ever gain, RLS and whose connection role cannot be granted catalog access.
  </Callout>

  **Default:** `true`

  **Possible values:** `true`, `false`

  **Env variable:** `RLS_ENABLED`
</div>

#### `--feature-materialization-persistence`

<div class="option-details" markdown="1">
  Allow fully materialized nodes to be persisted to disk. Fully materialized nodes are populated during startup and stored in memory by default. They can use significant amount of memory and are not candidate for evictions. This feature stores them on disk instead. Full materialized nodes are removed during shutdown.

  <Callout type="warning">
    This feature is experimental and should not be used in production. Contact support if you want to enable this feature. 
  </Callout>

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `FEATURE_MATERIALIZATION_PERSISTENCE`
</div>

#### `--feature-mixed-comparisons`

<div class="option-details" markdown="1">
  Enable support for mixing equality and range comparisons on query parameters.

  <Callout type="warning">
    This feature is experimental and should not be used in production. Contact support if you want to enable this feature. 
  </Callout>

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `FEATURE_MIXED_COMPARISONS`
</div>

#### `--feature-pagination`

<div class="option-details" markdown="1">
  Enable support for Pagination in dataflow.

  <Callout type="warning">
    This feature is experimental and should not be used in production. Contact support if you want to enable this feature.
  </Callout>

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `FEATURE_PAGINATION`
</div>

#### `--feature-post-lookup`

<div class="option-details" markdown="1">
  Enable support for Post-Lookup (queries which do extra work after the lookup into the reader). If the Top K feature is disabled, Post-Lookup can still provide support for some queries supported by Top K, albeit with lower performance.

  <Callout type="warning">
    This feature is experimental and should not be used in production. Contact support if you want to enable this feature.
  </Callout>

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `FEATURE_POST_LOOKUP`
</div>

#### `--feature-straddled-joins`

<div class="option-details" markdown="1">
  Enable support for straddled joins (joins with partial keys traced to both parents).

  <Callout type="warning">
    This feature is experimental and should not be used in production. Contact support if you want to enable this feature.
  </Callout>

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `FEATURE_STRADDLED_JOINS`
</div>

#### `--feature-topk`

<div class="option-details" markdown="1">
  Enable support for Top K in dataflow.

  <Callout type="warning">
    This feature is experimental and should not be used in production. Contact support if you want to enable this feature.
  </Callout>

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `FEATURE_TOPK`
</div>

#### `--help`, `-h`

<div class="option-details" markdown="1">
  Print help information.
</div>

#### `--ignore-ulimit-check`

<div class="option-details" markdown="1">
  Allow Readyset to start even if the file descriptor limit (`ulimit -n`) is below the minimum requirement. If set, Readyset still raises the soft limit to `min(our requirement, hard limit)`. It just doesn't treat `(our requirement > hard limit)` as a fatal error.

  **Env variable:** `IGNORE_ULIMIT_CHECK`
</div>

#### `--listen-backlog`

<div class="option-details" markdown="1">
  The maximum number of client connections waiting to be accepted on each listen address. When a burst of clients connects at once, connections beyond this queue are dropped, and those clients stall until their connect timeout.

  The kernel caps the value at `net.core.somaxconn`. Readyset logs the effective value at startup and warns when the cap applies.

  **Default:** `4096`

  **Env variable:** `LISTEN_BACKLOG`
</div>

#### `--log-dir`

<div class="option-details" markdown="1">
  Optional path to a directory where log files will be placed. Logs will be written to `readyset.log` within this directory. If set, logs will rollover based on the chosen `log_rotation` policy, which defaults to daily. Readyset must have write permissions.

  **Env variable:** `LOG_DIR`
</div>

#### `--log-file`

<div class="option-details" markdown="1">
  Optional full log filename where logs will be appended. Incompatible with log rotation.

  **Env variable:** `LOG_FILE`
</div>

#### `--log-format`

<div class="option-details" markdown="1">
  Format to use when emitting log events. See the [docs for the tracing library](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/index.html#formatters) for details.

  **Possible values:** `"compact"`, `"full"`, `"pretty"`, `"json"`

  **Default:** `"full"`

  **Env variable:** `LOG_FORMAT`
</div>

#### `--log-level`

<div class="option-details" markdown="1">
  The [severity level(s)](https://docs.rs/tracing-core/0.1.30/tracing_core/metadata/struct.Level.html#implementations) to include in Readyset logs. Messages at the specified and more severe levels are included. For example, when set to `INFO`, messages at the `INFO`, `WARN`, and `ERROR` levels are included.

  Possible values, from most to least severe:

  * `ERROR`: Used for hazardous situations that require special handling, where normal operation cannot proceed as expected.
  * `WARN`: Used for potentially hazardous situations that may require special handling.
  * `INFO`: Used for information messages that do not require action.
  * `DEBUG`: Used for lower priority information.
  * `TRACE`: Used for very low priority, often extremely verbose information.

  <Callout type="info">
    The 

    `TRACE`

     level is not available for 

    [official releases of Readyset](https://github.com/readysettech/readyset/)

    , or for binaries built with the 

    `--release`

     flag.
    Also, 

    `--log-level`

     can be set to a comma-separated list of directives for debugging during development. For the directive syntax, see the 

    [docs for the tracing library](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html)

    .
  </Callout>

  **Default:** `INFO`

  **Env variable:** `LOG_LEVEL`
</div>

#### `--log-rotation`

<div class="option-details" markdown="1">
  Log Rotation policy to use if a log file is set. Defaults to daily. Does nothing if no log file is set.

  **Possible values:** `"daily"`, `"hourly"`, `"minutely"`, `"never"`

  **Default:** `"daily"`

  **Env variable:** `LOG_ROTATION`
</div>

#### `--max-parallel-snapshot-tables`

<div class="option-details" markdown="1">
  The maximum number of relations that will be snapshotted in parallel from the upstream.

  **Default:** Number of available cores - 1.

  **Env variable:** `MAX_PARALLEL_SNAPSHOT_TABLES`
</div>

#### `--memory-limit`, `-m`

<div class="option-details" markdown="1">
  The amount of memory, in bytes, available to the Readyset Server.

  This memory limit accounts for all memory use, including partial materializations (i.e., queries for which Readyset stores only part of the result set), full materializations (i.e., queries for which Readyset stores the entire result set), and other parts of the Readyset process (e.g., RocksDB).

  Once memory usage surpasses this limit, Readyset starts evicting cache entries from partial materializations based on the [`--eviction-policy`](#--eviction-policy).

  **Default:** 80% of the memory available to the process (the container memory limit, if one is set, otherwise the machine's total memory). Set to `0` for unlimited.

  **Env variable:** `READYSET_MEMORY_LIMIT`

  <Callout>
    For production deployments, run the system under load, observe, and increase or decrease as needed.
  </Callout>
</div>

#### `--metrics-address`

<div class="option-details" markdown="1">
  The IP address/hostname and port of the Prometheus endpoint for [Readyset metrics](http://docs/rustdoc/readyset_client/metrics/recorded/index.html).

  This option is ignored unless [`--prometheus-metrics`](#--prometheus-metrics) is passed. It determines the Prometheus endpoint for the Readyset adapter; the [`--external-address`](readyset-server.md#--external-address) option for the `readyset-server` command determines the Prometheus endpoint for the Readyset server.

  **Default:** `0.0.0.0:6034`

  **Env variable:** `METRICS_ADDRESS`
</div>

#### `--mysql-authentication-method`

<div class="option-details" markdown="1">
  Authentication method to use for MySQL client connections. This controls which authentication plugin Readyset advertises during the MySQL handshake.

  **Possible values:** `mysql_native_password`, `caching_sha2_password`

  **Default:** `caching_sha2_password`

  **Env variable:** `MYSQL_AUTHENTICATION_METHOD`

  See [Authentication](/reference/authentication) for details on each method and migration guidance.
</div>

#### `--no-color`

<div class="option-details" markdown="1">
  Disable colors in all log output.

  **Env variable:** `NO_COLOR`
</div>

#### `--postgres-authentication-method`

<div class="option-details" markdown="1">
  Authentication method to use for PostgreSQL clients.

  **Possible values:** `cleartext`, `scram-sha-256`

  **Default:** `scram-sha-256`

  **Env variable:** `POSTGRES_AUTHENTICATION_METHOD`
</div>

#### `--query-caching`

<div class="option-details" markdown="1">
  Controls when Readyset migrates a query (compiles it into a cache) relative to the request that uses it.

  **Possible values:**

  * `explicit`: Caches are only created in response to an explicit `CREATE CACHE` statement or a `/*rs+ CREATE SHALLOW CACHE */` [hint](/concepts/shallow-caching/hint-based-caches). Queries that have not been explicitly cached are proxied to the upstream database. This is the default and the only non-experimental value.
  * `inrequestpath`: Every previously-unseen `SELECT` becomes a candidate for cache creation as it is executed. Combined with [`--cache-mode`](#--cache-mode) `shallow`, this produces Readyset's [automatic shallow caching](/concepts/shallow-caching/auto-caching) mode; the [`--auto-cache`](#--auto-cache) flag is shorthand for that combination.
  * `async`: Experimental.

  Mutually exclusive with [`--auto-cache`](#--auto-cache).

  **Default:** `explicit`

  **Env variable:** `QUERY_CACHING`
</div>

#### `--readyset-identity-file`

<div class="option-details" markdown="1">
  The PKCS#12 identity file (certificate and key) used by Readyset for establishing TLS connections as the server. Readyset will not accept TLS connections if there is no identity file specified.

  **Env variable:** `READYSET_IDENTITY_FILE`
</div>

#### `--readyset-identity-file-password`

<div class="option-details" markdown="1">
  Password for the PKCS#12 identity file used by Readyset for establishing TLS connections as the server. If not provided, Readyset will try using an empty string to unlock the identity file.

  **Env variable:** `READYSET_IDENTITY_FILE_PASSWORD`
</div>

#### `--report-host`

<div class="option-details" markdown="1">
  Hostname to report when registering as a replica with the upstream database (MySQL only). If not set, no hostname will be reported

  **Env variable:** `REPORT_HOST`
</div>

#### `--report-password`

<div class="option-details" markdown="1">
  Password to report when registering as a replica with the upstream database (MySQL only). If not set, no password will be reported

  **Env variable:** `REPORT_PASSWORD`
</div>

#### `--report-port`

<div class="option-details" markdown="1">
  Port to report when registering as a replica with the upstream database (MySQL only). If not set, no port will be reported

  **Env variable:** `REPORT_PORT`
</div>

#### `--report-user`

<div class="option-details" markdown="1">
  Username to report when registering as a replica with the upstream database (MySQL only). If not set, no username will be reported

  **Env variable:** `REPORT_USER`
</div>

#### `--replication-server-id`

<div class="option-details" markdown="1">
  Server ID to use when registering as a replication follower with the upstream database.

  This can be used to differentiate different Readyset deployments connected to the same upstream DB.

  For Postgres, this ends up being a suffix of the replication slot or resnapshot replication slot, which have prefixes of `readyset_` and `readyset_resnapshot_`, respectively. Since a replication slot is limited by Postgres to a length of 63 bytes, this server id must be 43 bytes or fewer.

  For MySQL, this must be parseable as a `u32` that is unique across the replication topology.

  **Env variable:** `REPLICATION_SERVER_ID`
</div>

#### `--replication-tables`

<div class="option-details" markdown="1">
  By default, Readyset attempts to snapshot and replicate all tables in the database specified in [`--upstream-db-url`](#--upstream-db-url). However, if the queries you want to cache in Readyset access only a subset of tables in the database, you can use this option to limit the tables Readyset snapshots and replicates. Filtering out tables that will not be used in caches will speed up the snapshotting process.

  This option accepts a comma-separated list of `<schema>.<table>` (specific table in a schema) or `<schema>.*` (all tables in a schema) for Postgres and `<database>.<table>` for MySQL.

  Only tables specified in the list will be eligible to be used by caches.

  **Env variable:** `REPLICATION_TABLES`
</div>

#### `--replication-tables-ignore`

<div class="option-details" markdown="1">
  By default, Readyset attempts to snapshot and replicate all tables in the database specified in [`--upstream-db-url`](#--upstream-db-url). However, if you know the queries you want to cache in Readyset won't access a subset of tables in the database, you can use this option to limit the tables Readyset snapshots and replicates. Filtering out tables that will not be used in caches will speed up the snapshotting process.

  This option accepts a comma-separated list of `<schema>.<table>` (specific table in a schema) or `<schema>.*` (all tables in a schema) for Postgres and `<database>.<table>` for MySQL.

  Tables specified in the list will not be eligible to be used by caches.

  **Env variable:** `REPLICATION_TABLES_IGNORE`
</div>

#### `--replication-lag-interval`

<div class="option-details" markdown="1">
  Polling interval, in seconds, for the replication-lag reporter. Controls how often Readyset queries the upstream's current replication position and, if [`--replication-heartbeat`](#--replication-heartbeat) is enabled, writes a heartbeat timestamp to the upstream.

  The value is surfaced through [`readyset.replication_status`](/reference/system-views#readysetreplication_status) and the Prometheus gauge `readyset_replicator.replication_lag`.

  **Default:** `1`

  **Possible values:** integer in the range `1`–`30`

  **Env variable:** `REPLICATION_LAG_INTERVAL`
</div>

#### `--replication-heartbeat`

<div class="option-details" markdown="1">
  Enable pt-heartbeat-style time-based replication lag measurement. When enabled, Readyset maintains a small heartbeat table on the upstream and measures the round-trip time for a written timestamp to appear back through the replication stream. The result is exposed as `heartbeat_staleness_seconds` in [`readyset.replication_status`](/reference/system-views#readysetreplication_status) and as the Prometheus gauge `readyset_replicator.replication_staleness_seconds`.

  Requires write access to the upstream so Readyset can create and update the heartbeat table (`readyset._heartbeat` on Postgres, `_readyset_heartbeat` on MySQL). If write access is not granted, a warning is logged, heartbeat is disabled, and byte/transaction lag reporting is unaffected.

  The poll cadence is shared with [`--replication-lag-interval`](#--replication-lag-interval).

  **Default:** `false`

  **Possible values:** `true`, `false`

  **Env variable:** `REPLICATION_HEARTBEAT`
</div>

#### `--rls-poll-interval-secs`

<div class="option-details" markdown="1">
  How often, in seconds, Readyset polls `pg_catalog` for changes to [row-level security](/concepts/shallow-caching/row-level-security) policies, RLS-enabled flags, and role attributes.

  The interval bounds how long a shallow cache can keep serving under a stale view of your policies: a policy edited on the upstream takes effect in Readyset within one poll. This is independent of cache TTL, which bounds row staleness. Shorten it to tighten the policy-staleness window, at the cost of more catalog queries against the upstream; lengthen it to reduce that load.

  Values outside `[1, 86400]` are clamped into range and a warning is logged with the effective value.

  Applies only to a Postgres upstream with [`--enable-rls`](#--enable-rls) on. Monitor `readyset.rls.poll_age_seconds` against this value to detect a poller that has fallen behind.

  **Default:** `60`

  **Env variable:** `RLS_POLL_INTERVAL_SECS`
</div>

#### `--opportunistic-ryw-ms`

<div class="option-details" markdown="1">
  Opportunistic read-your-writes window (in milliseconds). Applies only *outside* transactions: after any write on a session, reads on that same session bypass every cache for this many milliseconds. In-transaction routing is unaffected and is governed by the per-cache transaction policy (`NEVER` (default), [`ALWAYS`](/command-reference#always), or [`UNTIL WRITE`](/command-reference#until-write)). See [Read-your-writes](/concepts/read-your-writes) for how the two layers fit together.

  <Callout type="warning">
    This is opportunistic, not a consistency guarantee. Once the window elapses, reads resume from the cache, and the cache may still hold a pre-write value (a TTL that has not yet expired, or a row Readyset has not yet refreshed). Use only when occasional stale reads after the window are acceptable. See 

    [Read-your-writes](/concepts/read-your-writes)

     for the full picture and tradeoffs.
  </Callout>

  Pick a window long enough to cover the gap between a write completing on the upstream and Readyset's cache reflecting it. Too short and a freshly-written row may still be served stale; too long and reads that could safely hit the cache go upstream instead.

  Unset (the default) disables the feature; the read path then never pays the clock comparison. A value of `0` also disables it.

  **Default:** unset (disabled)

  **Env variable:** `OPPORTUNISTIC_RYW_MS`
</div>

#### `--sampler-max-queries-per-second`

<div class="option-details" markdown="1">
  Specifies the maximum number of queries to sample per second.

  **Default:** `100`

  **Env variable:** `SAMPLER_MAX_QUERIES_PER_SECOND`
</div>

#### `--sampler-max-retries`

<div class="option-details" markdown="1">
  Specifies the maximum number of retries for a mismatched query.

  **Default:** `6`

  **Env variable:** `SAMPLER_MAX_RETRIES`
</div>

#### `--sampler-queue-capacity`

<div class="option-details" markdown="1">
  Specifies the maximum queue size for the background query sampler. Exceeding this size will cause the adapter to not add new queries to the sampler queue.

  **Default:** `1024`

  **Env variable:** `SAMPLER_QUEUE_CAPACITY`
</div>

#### `--sampler-retry-delay-ms`

<div class="option-details" markdown="1">
  Specifies the delay between retries for a mismatched query.

  **Default:** `10000`

  **Env variable:** `SAMPLER_RETRY_DELAY_MS`
</div>

#### `--sampler-sample-rate`

<div class="option-details" markdown="1">
  Specifies the sample rate for the background query sampler.

  **Default:** `0.001`

  **Env variable:** `SAMPLER_SAMPLE_RATE`
</div>

#### `--snapshot-query-comment`

<div class="option-details" markdown="1">
  A string to be included as a comment in snapshot queries for MySQL. The provided value is automatically enclosed within the delimiters `/*` and `*/`. Provide only the raw comment text without any comment markers.

  **Default:** `""`

  **Env variable:** `SNAPSHOT_QUERY_COMMENT`
</div>

#### `--shallow-adaptive-max-extra-load-percent`

<div class="option-details" markdown="1">
  Maximum extra refresh load an [adaptive](/concepts/shallow-caching#adaptive-refresh) shallow cache may send to the upstream database, as a percentage of the load required to refresh its current entries at the configured refresh interval. When shortened per-entry intervals reach this cap, intervals stop shrinking until aggregate load decreases.

  **Default:** `100`

  **Env variable:** `SHALLOW_ADAPTIVE_MAX_EXTRA_LOAD_PERCENT`
</div>

#### `--shallow-max-entry-bytes`

<div class="option-details" markdown="1">
  Maximum size, in bytes, of a single shallow cache entry's result set. Larger results are served from upstream without being cached. This is a backstop for pathological cases; [cost-aware admission](/concepts/shallow-caching#memory-and-eviction) normally decides which results are worth their memory.

  **Default:** `1073741824` (1 GiB)

  **Env variable:** `SHALLOW_MAX_ENTRY_BYTES`
</div>

#### `--shallow-memory-percent`

<div class="option-details" markdown="1">
  Percentage of [`--memory-limit`](#--memory-limit--m) to allocate to the shallow cache store, as a value from 0 to 100. Applies only when the memory limit is not `0`. When the store reaches this bound, [cost-aware admission](/concepts/shallow-caching#memory-and-eviction) decides which results are kept.

  **Default:** Unset. The shallow store uses the full memory limit with [`--cache-mode`](#--cache-mode) `shallow`, and half of it with `deep` or `deep-then-shallow`.

  **Env variable:** `SHALLOW_MEMORY_PERCENT`
</div>

#### `--shallow-refresh-workers`

<div class="option-details" markdown="1">
  Maximum number of concurrent background refresh queries allowed across all shallow caches. This value acts as a guardrail to prevent shallow cache refreshes from overwhelming your upstream database. It also determines the upper bound on the number of database connections used for refreshes.

  Even with this limit in place, choose `REFRESH EVERY` intervals carefully on individual caches. High-cardinality caches with many distinct parameter values can generate significant query volume even at modest per-key refresh rates.

  **Default:** `40`

  **Env variable:** `SHALLOW_REFRESH_WORKERS`
</div>

#### `--ssl-root-cert`

<div class="option-details" markdown="1">
  Path to the PEM or DER root certificate that the upstream database connection will trust.

  **Default:** System root store

  **Env variable:** `SSL_ROOT_CERT`
</div>

#### `--storage-dir`

<div class="option-details" markdown="1">
  The path to the directory where Readyset stores replicated table data.

  **Default:** Current working directory

  **Env variable:** `STORAGE_DIR`
</div>

#### `--tls-mode`

<div class="option-details" markdown="1">
  Specifies the types of client connections permitted to connect to Readyset.

  **Possible values:**

  * `optional`: Client can use either plain or TLS connections
  * `disabled`: TLS connections are disabled
  * `required`: Only TLS connections are allowed

  **Default:** `optional`

  **Env variable:** `TLS_MODE`
</div>

#### `--upstream-connect-retries`

<div class="option-details" markdown="1">
  How many times replication retries a CDC server that failed before it moves to the next server in the [`--cdc-db-url`](#--cdc-db-url) list. A single server is retried forever.

  **Default:** `3`

  **Env variable:** `UPSTREAM_CONNECT_RETRIES`
</div>

#### `--upstream-connect-timeout`

<div class="option-details" markdown="1">
  Seconds to wait for a connection to an upstream server before Readyset treats the server as unreachable. The limit applies to every connection Readyset opens to an upstream.

  **Default:** `5`

  **Env variable:** `UPSTREAM_CONNECT_TIMEOUT`
</div>

#### `--upstream-db-url`

<div class="option-details" markdown="1">
  The URL of the upstream database, or a list of URLs for a group of equivalent servers. To pass a list, repeat the option or separate the URLs with commas. Each URL includes the username and password for Readyset to authenticate with, and the database to snapshot and replicate.

  Each URL in a list can end with an optional `|<weight>` suffix, an integer from 1 to 100 that defaults to 50. This follows MySQL's asynchronous connection failover source lists.

  ```
  --upstream-db-url 'mysql://user:pass@replica-a:3306/db|60,mysql://user:pass@replica-b:3306/db'
  ```

  Lists are supported for MySQL only, because failover needs a replication position that means the same thing on every server. A PostgreSQL URL is always a single server. Every server in a list must use the same database type, database name, user, and password, and each `host:port` can appear only once.

  Readyset spreads client sessions and its own upstream connections at random across the servers that are up. A server that stops answering is treated as down and is skipped until it answers again. To see the list, each server's health, and its connection count, run `SELECT * FROM readyset.upstream_servers`.

  **Env variable:** `UPSTREAM_DB_URL`

  <Callout>
    A MySQL list with more than one server requires 

    `gtid_mode = ON`

     on every server. All servers must also have the same 

    `lower_case_table_names`

    , time zone, and server collation. At startup, Readyset connects to each server and rejects any server that fails these checks.
  </Callout>

  <Callout>
    Readyset saves the server list on the 

    **first**

     startup that passes 

    [verification](#--verify)

    . After that, Readyset uses the saved list and ignores this option. To change the list, use 

    [`ALTER READYSET CHANGE UPSTREAM`](/command-reference#alter-readyset-change-upstream)

    .
  </Callout>

  <Callout>
    By default, Readyset attempts to snapshot and replicate all tables in the database specified in 

    [`--upstream-db-url`](#--upstream-db-url)

    . However, if the queries you want to cache in Readyset access only a subset of tables in the database, you can use the 

    [`--replication-tables`](#--replication-tables)

     option to narrow the scope accordingly. Filtering out tables that will not be used in caches will speed up the snapshotting process.
  </Callout>

  <Callout>
    Special characters that may be interpreted as dividers of the connection string (e.g. 

    `@`

    , 

    `:`

    , 

    `/`

    , 

    `#`

    ) must be 

    [percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding)

    , including in passwords. For example, 

    `password#`

     should be 

    `password%23`

    . Encode a 

    `,`

     inside a password as 

    `%2C`

    , because commas separate the URLs in a list. A 

    `|`

     inside a password doesn't need encoding, because Readyset reads the weight from the last 

    `|`

     after the host.
  </Callout>

  <Callout type="info">
    On Readyset's **first** startup for a deployment, the user from `--upstream-db-url` is added to the allowed-users set so clients can authenticate to Readyset with those credentials. This seeding happens only once: the allowed-users set is then persisted and read from stored values. Changing `--upstream-db-url` later points Readyset at a different upstream but does **not** add the new URL's user to the allowed-users set. Manage users at runtime with [`ALTER READYSET ADD/MODIFY/DROP USER`](/command-reference#alter-readyset-add-user), as described in [User Management](/reference/user-management).
  </Callout>
</div>

#### `--upstream-health-interval-secs`

<div class="option-details" markdown="1">
  How often, in seconds, Readyset checks that each upstream server is up. Health checks may be disabled by setting this value to `0`, in which case Readyset discovers that a server is down only when a client connection to it fails.

  A check that gets no answer within [`--upstream-connect-timeout`](#--upstream-connect-timeout) counts as a failure. Readyset retries a server that is down by opening a new connection, first after 1 second, then waiting twice as long each time, up to 60 seconds. These connections use the program name `READYSET_HEALTH_MONITOR`, so you can find them in the upstream's process list.

  **Default:** `10`

  **Env variable:** `UPSTREAM_HEALTH_INTERVAL`
</div>

#### `--verify`

<div class="option-details" markdown="1">
  Run startup verification checks and exit, without starting the Readyset adapter.

  * On success: prints a confirmation message to stdout and exits with code `0`.
  * On failure: prints the error(s) to stderr and exits with a non-zero code.

  Use this flag in CI/CD pipelines or deployment scripts to validate your Readyset configuration before the adapter goes live.

  By default (when neither `--verify` nor [`--verify-skip`](#--verify-skip) is set), Readyset still runs the same checks at startup. A failure will stop the process, but output goes to the log rather than stdout/stderr.

  Cannot be used together with [`--verify-skip`](#--verify-skip).

  **Env variable:** `VERIFY`
</div>

#### `--verify-skip`

<div class="option-details" markdown="1">
  Skip all startup verification checks and proceed directly to starting the Readyset adapter.

  <Callout type="warning">
    Skipping verification means Readyset will not detect misconfigured upstream database settings (replication, permissions, disk space, etc.) before attempting to connect and snapshot. Use this option only when you have confirmed the configuration is correct or need to bypass a transient check failure.
  </Callout>

  Cannot be used together with [`--verify`](#--verify).

  **Env variable:** `VERIFY_SKIP`
</div>


# Failover (/reference/failover)
import { Callout } from 'fumadocs-ui/components/callout'

When the upstream database fails and a replica is promoted to primary, Readyset can be redirected to the new source without a full restart. The failover procedure depends on the database type and the replication mode in use.

## Automatic failover with server lists

For MySQL with GTID replication, Readyset can fail over by itself when you give it more than one server. [`--upstream-db-url`](/reference/config-options#--upstream-db-url) and [`--cdc-db-url`](/reference/config-options#--cdc-db-url) accept a list of URLs. Repeat the option or separate the URLs with commas, and add an optional `|<weight>` suffix from 1 to 100 (default 50) to each one.

```
--cdc-db-url 'mysql://user:pass@replica-a:3306/db|60,mysql://user:pass@replica-b:3306/db|50,mysql://user:pass@replica-c:3306/db'
```

Replication connects to the highest-weight server. When that server fails, Readyset retries it up to [`--upstream-connect-retries`](/reference/config-options#--upstream-connect-retries) times, then moves to the next server by weight. GTIDs name the same position on every server, so no rows are lost or duplicated. Replication will use the new server until that server fails or you change the list.

Client connections are spread across the servers in the [`--upstream-db-url`](/reference/config-options#--upstream-db-url) list that are up.

You can edit the list while replication runs, for example from a tool that adds and removes replicas:

```sql
ALTER READYSET CHANGE CDC TO 'mysql://user:pass@replica-a:3306/db|60,mysql://user:pass@replica-d:3306/db';
```

Readyset checks new servers before it accepts the list. If replication's current server is still in the new list, replication keeps using it. If you removed it, Readyset restarts replication, using a server from the new list.

To see the list, each server's health, which server replication is on, and each server's connection count, run:

```sql
SELECT * FROM readyset.upstream_servers;
```

<Callout type="info">
  Every server in a MySQL list must have `gtid_mode=ON`, use the same database name, and have the same `lower_case_table_names`, time zone, and server collation. Readyset checks each server at startup and when it is added to the list.
</Callout>

Use the manual steps below with a single server, to move to a server that isn't in the list, or with PostgreSQL.

## MySQL

### GTID replication

When Readyset is replicating with [GTIDs](/reference/config-options#--require-gtid), failover is straightforward because GTIDs are global identifiers that are consistent across all servers in a replication topology. No position adjustment is needed. Point Readyset at the new primary:

```sql
ALTER READYSET CHANGE CDC TO 'mysql://<user>:<password>@new-primary:3306/db';
```

Replication restarts on the new server and resumes from the last GTID Readyset processed. If the new primary has the same GTID history, replication continues without a gap. It is not necessary to stop replication first.

<Callout type="info">
  If Readyset was originally started without [`--require-gtid`](/reference/config-options#--require-gtid) (using binlog file and position), you can switch to GTID replication during failover by setting a GTID position with [`ALTER READYSET SET REPLICATION POSITION`](/command-reference#alter-readyset-set-replication-position) before starting replication. The new primary must have `gtid_mode=ON`.
</Callout>

### Binlog file and position replication

Binlog file names and positions are local to each MySQL server. When failing over to a new primary, you must determine the correct starting position on the new server. This is the same process as failing over any MySQL replica.

1. Stop replication:

```sql
ALTER READYSET STOP REPLICATION;
```

2. Check the current replication position in Readyset:

```sql
SHOW READYSET STATUS;
```

The `Minimum Replication Offset` field shows the current binlog file and position (e.g., `binlog.000003:154`).

3. Determine the equivalent position on the new primary. This step is environment-specific and is the same procedure used when failing over any MySQL replica. Common approaches include:
   * Using `SHOW BINARY LOG STATUS` on the new primary if the replica was in sync
   * Consulting your replication management tool (e.g., Orchestrator, MHA)
   * Comparing GTID sets if the servers have `gtid_mode=ON` (consider switching to GTID replication instead)

4. Set the replication position to the new primary's binlog coordinates:

```sql
ALTER READYSET SET REPLICATION POSITION 'binlog.000001:4587';
```

5. Point Readyset at the new primary:

```sql
ALTER READYSET CHANGE CDC TO 'mysql://<user>:<password>@new-primary:3306/db';
```

6. Resume replication:

```sql
ALTER READYSET START REPLICATION;
```

<Callout type="warn">
  Setting an incorrect replication position can cause missed writes or replication errors. Verify that the position on the new primary corresponds to the same point in the data as the position reported by `SHOW READYSET STATUS`.
</Callout>

## PostgreSQL

PostgreSQL logical replication uses replication slots that are local to the primary server. When the primary fails, the slot is lost and cannot be recreated at the old position on a new server. Readyset handles this automatically by performing a full resnapshot. Point Readyset at the new primary:

```sql
ALTER READYSET CHANGE CDC TO 'postgresql://<user>:<password>@new-primary:5432/db';
```

Readyset restarts replication, detects that the replication slot does not exist on the new primary, creates a new slot, and performs a full resnapshot of all tables. Once the snapshot completes, replication resumes from the new slot's starting position.

<Callout type="info">
  PostgreSQL supports only a single server, so [automatic failover](#automatic-failover-with-server-lists) isn't available. LSNs and replication slots belong to one server, and no position carries over to the next one.
</Callout>

<Callout type="info">
  `SET REPLICATION POSITION` is not useful for PostgreSQL failover. LSN values are specific to each server's WAL stream and are not transferable between servers.
</Callout>

## Monitoring failover

Use [`SHOW READYSET STATUS`](/command-reference#show-readyset-status) to monitor the failover process:

* **Status**: Shows `Replication Stopped` after stopping, then transitions back to `Online` once replication catches up.
* **CDC Server**: The `host:port` of the upstream server that replication is connected to. It doesn't appear while replication is stopped. After a failover, it shows the new server.
* **Minimum Replication Offset** / **Maximum Replication Offset**: Show the current replication position. For MySQL GTID, this displays the GTID set. For binlog file and position, it displays the file name and offset.

With a server list, `SELECT * FROM readyset.upstream_servers` shows one row per server. Each row has the server's weight, its purpose (`cdc`, `proxy`, or `cdc, proxy`), whether replication is using it, its health, and its connection count.


# Profiling Queries (/reference/profiling-queries)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Cards, Card } from 'fumadocs-ui/components/card'

Before deciding to cache a query, it's worth investigating the performance impact each query has on your application.

One method for doing so:

<Cards>
  <Card title="Use the database's slow query log" href="/reference/profiling-queries/view-query-metrics-with-the-databases-slow-query-log" />
</Cards>

## Enabling metrics

<Tabs items={['Using pg_stat_statements with Postgres', 'Using Readyset metrics']}>
  <Tab>
    You can use the [pg\_stat\_statements extension](https://www.postgresql.org/docs/current/pgstatstatements.html) to retrieve detailed information about the queries running against your Postgres instance.

    Connect to your database via the shell. Run the following command to see if pg\_stat\_statements is installed.

    ```sh copy
    SELECT calls, query FROM pg_stat_statements LIMIT 1;
    ```

    If an error is returned, enable pg\_stat\_statments with the following command:

    ```sh copy
    CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
    ```

    <Callout type="warning">
      In some environments, the pg_stat_statements extension may not be available. In that case, run 

      `ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';`

       and restart your Postgres instance before re-running the 

      `CREATE EXTENSION`

       command.
    </Callout>
  </Tab>

  <Tab>
    To enable Readyset metrics, start Readyset with the following options:

    * [`--prometheus-metrics`](/using/cli/readyset/#--prometheus-metrics)
    * [`--metrics-address`](/using/cli/readyset/#--metrics-address)

    To include query-specific execution metrics, also pass:

    * [`--query-log-mode=verbose`](/using/cli/readyset/#-query-log-mode)

    You can access Readyset metrics at `<metrics address>/metrics`, where the metrics address is defined by the [`--metrics-address`](/using/cli/readyset/#--metrics-address) option (default: `0.0.0.0:6034/metrics`).
  </Tab>
</Tabs>

## Analyzing per-query metrics

<Tabs items={['Using pg_stat_statements with Postgres', 'Using Readyset metrics']}>
  <Tab>
    Readyset can cache many `SELECT` queries.

    To find `SELECT` queries with the highest latency, run:

    ```sql copy
    SELECT query, calls, total_exec_time, mean_exec_time from pg_stat_statements WHERE query ILIKE '%SELECT%' order by mean_exec_time DESC;
    ```

    Similarly, Readyset can be used to offload high-impact queries to improve throughput.

    To find the most frequently-run `SELECT` queries, run:

    ```sql copy
    SELECT query, calls, total_exec_time, mean_exec_time from pg_stat_statements WHERE query ILIKE '%SELECT%' order by calls DESC;
    ```

    To find queries that cause the most total load on the database, run:

    ```sql copy
    SELECT query, calls, total_exec_time, mean_exec_time from pg_stat_statements WHERE query ILIKE '%SELECT%' order by total_exec_time DESC;
    ```
  </Tab>

  <Tab>
    Readyset metrics are formatted for easy integration with [Prometheus](https://prometheus.io/). However, the quickest way to examine per-query metrics is to use a simple metrics utility written in Python that queries the metrics endpoint and displays latencies for queries received by Readyset.

    1. Download the metrics utility and its `requirements.txt`:

    ```sql copy
    curl -L -O "https://readyset.io/quickstart/metrics.py"
    curl -L -O "https://readyset.io/quickstart/requirements.txt"
    ```

    2. Install dependencies for the utility:

    ```sh copy
    pip3 install -r requirements.txt
    ```

    3. Set the `METRICS_HOST` environment variable to the IP address/hostname portion of `--metrics-address`:

    ```sql copy
    export METRICS_HOST="<metrics-host>"
    ```

    4. Run the script with

    ```sql copy
    python3 metrics.py --host=${METRICS_HOST}
    ```

    5. You can filter the output of this script to show only queries displayed in `SHOW PROXIED QUERIES` or `SHOW CACHES` by passing the `--filter-queries` flag and piping the output of those Readyset commands into the script like so:

    ```sql copy
    PGPASSWORD=noria psql --host=127.0.0.1 --port=5433 --username=postgres --dbname=noria -c "SHOW CACHES" | python3 metrics.py --filter-queries
    ```
  </Tab>
</Tabs>


# View Query Metrics with the Database's Slow Query Log (/reference/profiling-queries/view-query-metrics-with-the-databases-slow-query-log)
import { Callout } from 'fumadocs-ui/components/callout'

After [connecting your app](/cache/connect/connect-an-application-via-an-orm) to Readyset, profile your app performance and identify queries to cache in Readyset. Generally, it's best to focus on frequent queries that are too slow and/or that are putting unwanted load on your upstream database.

### Enabling metrics

You can use the [pg\_stat\_statements extension](https://www.postgresql.org/docs/current/pgstatstatements.html) to retrieve detailed information about the queries running against your Postgres instance.

Connect to your database via the shell. Run the following command to see if pg\_stat\_statements is installed.

```sh copy
SELECT calls, query FROM pg_stat_statements LIMIT 1;
```

If an error is returned, enable pg\_stat\_statments with the following command:

```sh copy
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

<Callout type="warning">
  In some environments, the pg\_stat\_statements extension may not be available. In that case, run `ALTER SYSTEM SET` shared\_preload\_libraries = 'pg\_stat\_statements'; and restart your Postgres instance before re-running the `CREATE EXTENSION` command.
</Callout>

### Identifying queries to cache

To find queries that put the highest load on the database, run:

```sh copy
SELECT query, calls, total_exec_time, mean_exec_time from pg_stat_statements WHERE query ILIKE '%SELECT%' order by total_exec_time DESC;
```

To find queries with the highest latency, run:

```sh copy
SELECT query, calls, total_exec_time, mean_exec_time from pg_stat_statements WHERE query ILIKE '%SELECT%' order by mean_exec_time DESC;
```

To find the most frequently issued queries, run:

```sh copy
SELECT query, calls, total_exec_time, mean_exec_time from pg_stat_statements WHERE query ILIKE '%SELECT%' order by calls DESC;
```

Once you've identified queries to cache, you can [cache them in Readyset](/cache/cache#1-creating-a-cache).


# Integrating with ProxySQL (/reference/proxysql)
This manual provides instructions for configuring ProxySQL alongside Readyset. Readyset has developed its own [ProxySQL Scheduler](https://github.com/readysettech/proxysql_scheduler) designed to integrate both tools.
This scheduler enables the identification of slow queries, assesses whether Readyset supports these queries, and automatically generates query rules to reroute these queries to Readyset, serving them directly from its cache.
The scheduler is also responsible for checking the health of a Readyset instance and adjusting it's status if necessary.

## Pre-requirements

This guide assumes that you already have ProxySQL installed, Readyset set up, and three MySQL servers in place (one writer and two readers).

We will be using 3 hostgroups:

| Hostgroup | Role  |
| --------- | ----- |
| 10        | Write |
| 11        | Read  |
| 12        | Cache |

For demo purposes, we will be using below list of servers and IPS:

| Server        | Port | Hostgroup | Role     |
| ------------- | ---- | --------- | -------- |
| 172.20.238.10 | 3306 | 10        | Source   |
| 172.20.238.11 | 3306 | 11/12     | Replica1 |
| 172.20.238.12 | 3306 | 11/12     | Replica2 |
| 172.20.238.20 | 3306 | 12        | Readyset |

As a best practice, we will include the replicas in the cache hostgroup 12. This ensures that if Readyset becomes unavailable, the cache queries will be served by the Readers.

All commands will be executed in the admin interface of ProxySQL

```sql
mysql -u admin -padmin -P6032
```

## Configuring Users

We will configure our application user to connect by default to `hostgroup 10`

```sql
INSERT INTO mysql_users (username, password, default_hostgroup) VALUES ('app', 'app', 10);
LOAD MYSQL USERS TO RUNTIME; SAVE MYSQL USERS FROM RUNTIME; SAVE MYSQL USERS TO DISK;
```

## Configuring Servers

We will configure the server as follow:

```sql
INSERT INTO mysql_servers (hostgroup_id, hostname, port, weight, comment) VALUES
(10, '172.20.238.10', 3306, 1, 'Writer'),
(11, '172.20.238.11', 3306, 1, 'Read - Replica 1'),
(11, '172.20.238.12', 3306, 1, 'Read - Replica 2'),
(12, '172.20.238.20', 3306, 1000, 'Cache - Readyset'),
(12, '172.20.238.11', 3306, 1, 'Cache - Replica 1'),
(12, '172.20.238.12', 3306, 1, 'Cache - Replica 2');
LOAD MYSQL SERVERS TO RUNTIME; SAVE MYSQL SERVERS TO DISK;
```

<Callout type="info">
  Currently, Readyset does not support automatic failover; therefore, the configuration of mysql_replication_hostgroups has been omitted.
</Callout>

## Configuring Default Read / Write splitting

By default, we want to send all reads to `hostgroup 11`. The standard rules for splitting read and write operations are as follows::

```sql
INSERT INTO mysql_query_rules (username,destination_hostgroup,active,match_digest,apply) VALUES
('app',10,1,'^SELECT.*FOR UPDATE',1),
('app',11,1,'^SELECT ',0);
LOAD MYSQL QUERY RULES TO RUNTIME; SAVE MYSQL QUERY RULES TO DISK;
```

<Callout type="info">
   The last rule on 

  `^SELECT `

  should be set with 

  `apply=0`

  , allowing ProxySQL to evaluate additional rules that will be introduced through the scheduler.
</Callout>

## Configuring Scheduler

Download and install the latest release of [Readyset ProxySQL Scheduler](https://github.com/readysettech/proxysql_scheduler/releases).

Adjust `/etc/readyset_proxysql_scheduler.cnf` to reflect your credentials:

```
proxysql_user = 'admin'
proxysql_password = 'admin'
proxysql_host = '127.0.0.1'
proxysql_port = 6032
readyset_user = 'app'
readyset_password = 'app'
readyset_host = '172.20.238.20'
readyset_port = 3306
source_hostgroup = 11
readyset_hostgroup = 12
warmup_time = 60
lock_file = '/tmp/readyset_scheduler.lock'
```

We're setting the warmup\_time to 60 seconds. This configuration causes every new query identified by the scheduler to be mirrored to Readyset for this duration. It triggers the construction of the dataflow for the query, allowing Readyset to warm up the cache for this specific query entry.

Now, we need to proceed with adding a scheduler entry:

```sql
INSERT INTO scheduler (active, interval_ms, filename, arg1) VALUES (1, 10000, '/usr/bin/readyset_proxysql_scheduler', '--config=/etc/readyset_proxysql_scheduler.cnf');
LOAD SCHEDULER TO RUNTIME; SAVE SCHEDULER TO DISK;
```

That's everything required. Now, if we execute a sample query, it should activate the scheduler's query detection mechanism:

```sql
mysql> SELECT COUNT(*) FROM employees WHERE gender = 'F';
+----------+
| COUNT(*) |
+----------+
|   120051 |
+----------+
1 row in set (0,05 sec)
```

If we check the `proxysql.log` file, we should observe the following:

```
2024-04-04 17:42:37 [INFO] Readyset[98173]: Running readyset_scheduler
2024-04-04 17:42:37 [INFO] Readyset[98173]: Going to test query support for SELECT COUNT(*) FROM employees WHERE gender = ?
2024-04-04 17:42:37 [INFO] Readyset[98173]: Query is supported, adding it to proxysql and readyset
2024-04-04 17:42:37 [INFO] Readyset[98173]: Inserted warm-up rule
2024-04-04 17:42:37 [INFO] Received LOAD MYSQL QUERY RULES TO RUNTIME command
2024-04-04 17:42:37 [INFO] Computed checksum for 'LOAD MYSQL QUERY RULES TO RUNTIME' was '0x34AC063B91801340', with epoch '1712263357'
2024-04-04 17:42:37 [INFO] Received SAVE MYSQL QUERY RULES TO DISK command
2024-04-04 17:42:37 [INFO] Readyset[98173]: Finished readyset_scheduler
```

Running the same query while it is under the warm-up rule should yield the same 50ms runtime, as it is still been served by the read replicas while also warming up the Readyset cache. After the `warmup_time` has elapsed, the rule will automatically be migrated from `mirror_hostgroup` to `destination_hostgroup`, and from this point forward, Readyset will start receiving this query.

```
2024-04-04 17:43:47 [INFO] Readyset[98327]: Running readyset_scheduler
2024-04-04 17:43:47 [INFO] Readyset[98327]: Updated rule ID 13 from warmup to destination
2024-04-04 17:43:47 [INFO] Received LOAD MYSQL QUERY RULES TO RUNTIME command
2024-04-04 17:43:47 [INFO] Computed checksum for 'LOAD MYSQL QUERY RULES TO RUNTIME' was '0x3F6C96CD31D7261B', with epoch '1712263427'
2024-04-04 17:43:47 [INFO] Received SAVE MYSQL QUERY RULES TO DISK command
2024-04-04 17:43:47 [INFO] Readyset[98327]: Finished readyset_scheduler
```

Checking the query again should show that it completes in 0ms, indicating that the query is now being served from the Readyset cache:

```sql
mysql> SELECT COUNT(*) FROM employees WHERE gender = 'F';
+----------+
| COUNT(*) |
+----------+
|   120051 |
+----------+
1 row in set (0,00 sec)
```

If you add a new employee, the cache will be automatically updated by Readyset to reflect this change.

```sql
mysql> INSERT INTO employees VALUES (999999, '2000-01-01', 'Some', 'One', 'F',
'2020-01-01');
Query OK, 1 row affected (0,01 sec)

mysql> SELECT COUNT(*) FROM employees WHERE gender = 'F';
+----------+
| count(*) |
+----------+
|   120052 |
+----------+
1 row in set (0,00 sec)
```

The write operation mentioned above was redirected by ProxySQL to the source server, and the SELECT query was directed to Readyset, which again completed in 0ms while also bringing the updated cache entry.

Additionally, it's important to note that cache filters are parameterized, meaning that if we change the filter value, we will still be serving data from the cache:

```sql
mysql> SELECT COUNT(*) FROM employees WHERE gender = 'M';
+----------+
| count(*) |
+----------+
|   179973 |
+----------+
1 row in set (0,00 sec)
```


# QueryPilot Optional Configurations (/reference/querypilot-optional-configurations)
import { Callout } from 'fumadocs-ui/components/callout';

Provided artifacts and short recipes that do not belong to a single component page. The Router is the SQL proxy (binary `querypilot`). Everything here assumes the metrics/admin API is on (`[metrics] enabled = true`), which serves Prometheus on 9090 and the admin API on 9091 by default.

## Grafana dashboard

A ready-made Router overview dashboard (JSON) is available from your Readyset contact. Panels: Backend Health (`sqp_backend_health` by pool), Queries (query volume), Routing decisions (by pool), Pool connections, and Pool durations p99.

It expects a Prometheus datasource scraping the Router metrics port. A minimal scrape config:

```yaml
scrape_configs:
  - job_name: querypilot
    static_configs:
      - targets: ["<router-host>:9090"]
```

Point the scrape target at the metrics port; 9091 is the admin API and does not serve `/metrics`. Import the dashboard either way:

* **Grafana UI:** Dashboards, New, Import, upload the JSON file, select your Prometheus datasource.
* **Provisioning:** copy the JSON into your Grafana provisioning dashboards directory alongside a dashboard provider definition.

## Prometheus alert rules

Load alert rules through a `rule_files` glob in your Prometheus config. Thresholds below are conservative defaults to tune against your SLOs:

```yaml
groups:
  - name: querypilot-router
    rules:
      - alert: QueryPilotBackendUnhealthy
        expr: sqp_backend_health == 0
        for: 2m
        labels: { severity: page }
        annotations:
          summary: "Backend {{ $labels.backend }} in pool {{ $labels.pool }} is unhealthy"

      - alert: QueryPilotPoolSaturated
        expr: sqp_pool_utilization_ratio > 0.9
        for: 10m
        labels: { severity: warning }
        annotations:
          summary: "Pool {{ $labels.pool }} above 90% utilization"

      - alert: QueryPilotPoolTimeouts
        expr: increase(sqp_pool_timeouts_total[5m]) > 0
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "Sessions timing out waiting for connections in pool {{ $labels.pool }}"


```

The full metric catalog is in the [metrics reference](/querypilot/reference/metrics).

## Annotated example configuration

A fuller `querypilot.toml` showing the optional knobs beyond the minimal configs in [Getting Started](/querypilot/getting-started) and [Deployment](/querypilot/deployment):

```toml
[general]
pool_mode = "transaction"      # session | transaction | statement
worker_threads = 0             # 0 = one per CPU core
shutdown_timeout = "30s"       # drain window on SIGTERM

[[listeners]]
protocol = "postgres"
bind = "0.0.0.0:5433"

# MySQL clients are served from a second listener (preview).
#[[listeners]]
#protocol = "mysql"
#bind = "0.0.0.0:6433"

[pools.primary]
role = "primary"
username = "<your_pg_user>"
password = "<your_pg_password>"
database = "<your_database>"
min_connections = 2            # kept open when idle
max_connections = 20           # hard cap per pool
acquire_timeout = "30s"        # max wait for a connection before erroring
idle_timeout = "10m"           # prune idle connections after this
connect_timeout = "10s"        # backend TCP/auth budget
# query_timeout = "60s"        # per-statement deadline; unset = none
# raw_passthrough = true       # vanilla PG-to-PG pools only; see the
                               # Router guide before enabling

backends = [
    { host = "127.0.0.1", port = 5432 }
]

[routing]
default_pool = "primary"

[stats]
max_entries = 10000            # distinct query fingerprints tracked

[metrics]
enabled = true
bind = "0.0.0.0:9090"          # admin API always binds metrics port + 1

[logging]
level = "info"                 # trace | debug | info | warn | error
format = "pretty"              # pretty | json
```

Key-by-key detail lives in the [Router configuration reference](/querypilot/reference/router-configuration). Longer walkthroughs are tutorials: [read/write splitting](/demos/querypilot/read-write-split), [Accelerator caching](/demos/querypilot/accelerator-caching), and [Guard policies](/demos/querypilot/guard-policies).

## How-to: add a pattern routing rule and test it

Steer one query shape to a specific pool. Pattern rules match by normalized query shape; three `type`s exist: `template` (a literal example query whose values are parameterized away), `regex` (over the query text), and `hash` (a fingerprint hash). Get the fingerprint of any query from the admin API first:

```bash
curl "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20orders%20WHERE%20user_id%20=%2042"
# note "fingerprint_hash" and "normalized_sql" in the response
```

Add the rule to `querypilot.toml`:

```toml
[[routing.pattern_rules]]
name = "order_lookups_to_replica"
type = "template"
pattern = "SELECT * FROM orders WHERE user_id = 42"
pool = "replica"
priority = 10
```

Apply without a restart, then confirm the decision changed:

```bash
curl -X POST http://localhost:9091/api/config/reload
curl "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20orders%20WHERE%20user_id%20=%207"
# "decision": "pattern", "target_pool": "replica"
```

Any literal value matches: the template is normalized, so `user_id = 7` hits the rule created from the `= 42` example. Rules can also be created at runtime by fingerprint via `POST /api/pattern-rules`; those are ephemeral and cleared on config reload, so put durable rules in the config file.

## How-to: tune pool sizing and timeouts

The knobs, per `[pools.<name>]`: `min_connections` (kept open), `max_connections` (hard cap), `acquire_timeout` (how long a session waits for a free connection), `idle_timeout` (idle connections above the minimum are closed), `connect_timeout` (backend dial deadline), and optional `query_timeout`. A steady-service starting point:

```toml
[pools.primary]
min_connections = 2
max_connections = 10
acquire_timeout = "30s"
idle_timeout = "60s"
connect_timeout = "10s"
```

Verify under load: `sqp_pool_utilization_ratio` near 1.0 with growing `sqp_pool_queue_depth` and `sqp_pool_wait_duration_seconds` means the cap is too low, or backend capacity is the real limit. `sqp_pool_timeouts_total` and `sqp_pool_acquire_total{outcome="timeout"}` count requests that gave up after `acquire_timeout`. `sqp_pool_acquire_total{outcome="created"}` churning alongside a short `idle_timeout` means you are paying reconnect cost; raise `min_connections` or `idle_timeout`. Transaction pool mode (`pool_mode = "transaction"`, the default) lets one backend connection serve many clients, so size against concurrent transactions, not client count.

## How-to: connect from application frameworks

No driver changes are needed; point existing drivers at the Router and authenticate with the pool's credentials (see [Security](/querypilot/security) for the auth model).

**Go (pgx v5)** against a PostgreSQL listener:

```go
connStr := fmt.Sprintf("postgres://%s:%s@%s:%s/%s", user, pass, host, port, db)
conn, err := pgx.Connect(ctx, connStr)
```

pgx defaults to prepared statements and the binary protocol; both are supported through the Router, including numeric/decimal round-trips.

**Python (psycopg 3)** against a PostgreSQL listener:

```python
import psycopg
conn = psycopg.connect(host="proxy.internal", port=6432,
                       user="app", password="<your-password>", dbname="mydb")
conn.autocommit = True   # or manage transactions explicitly
```

**Python (PyMySQL)** against a MySQL listener:

```python
import pymysql
conn = pymysql.connect(host="proxy.internal", port=6433,
                       user="app", password="<your-password>", database="mydb")
```

<Callout type="info">
  MySQL support is in preview. Two type quirks to normalize for: `BOOLEAN` columns come back as `TINYINT(1)` integers, and binary payloads may arrive as `bytes` or `bytearray` depending on path.
</Callout>

One cross-cutting caution: leave `raw_passthrough` off for any pool that is not vanilla same-protocol PostgreSQL. Cross-protocol pools (MySQL client to PostgreSQL backend) need row re-encoding.

{/* source: verified against code @ 2026-07-18 */}


# Snapshotting (/reference/snapshots)
import { Callout } from 'fumadocs-ui/components/callout'

[Deep caches](/concepts/deep-caching) are maintained from a snapshot of your database's tables plus a continuous replication stream. Snapshotting copies the data of every table into Readyset's [storage directory](/reference/config-options#--storage-dir). Deep caches require every table to finish the initial snapshot. [Shallow caches](/concepts/shallow-caching) do not depend on snapshotting.

## Monitoring snapshot progress

Check overall snapshotting progress by connecting a SQL shell to Readyset and running:

```sql
SHOW READYSET STATUS;
```

The row labeled `Status` shows `Snapshot In Progress` until every table finishes snapshotting, then `Online`:

```text
name               | value
-------------------+---------
...
Status             | Online
Replication Status | Running
...
```

For per-table detail, use [`SHOW READYSET TABLES`](/command-reference#show-readyset-tables):

```sql
SHOW READYSET TABLES;
```

```text
table            | status       | description
-----------------+--------------+------------
"public"."small" | Online       |
"public"."big"   | Snapshotting | 43.21%
"public"."huge"  | Initializing |
(3 rows)
```

Tables waiting for their turn report `Initializing`. In-progress tables report `Snapshotting` with an estimated progress percentage in `description`, then `Compacting` while finalizing. `Online` means the table is fully snapshotted and replicating; restarts [do not re-snapshot](#restarting-during-snapshotting) online tables. Add `ALL` to also list upstream tables Readyset is not replicating, with the reason in `description`.

The Readyset log reports when each table's snapshot starts, with an estimated row count, and when it finishes, with the number of rows copied. While a table is snapshotting, the log reports its progress every 30 seconds.

## Tables Readyset does not replicate

Some upstream tables are never replicated at all. For example, on PostgreSQL, Readyset does not support tables with generated columns: PostgreSQL versions before 18 cannot send generated columns over logical replication, and Readyset publications does not yet support the `publish_generated_columns` option added in PostgreSQL 18.

Tables like these are refused when Readyset first sees them, during the initial snapshot or when a `CREATE TABLE` event arrives during replication. [`SHOW READYSET ALL TABLES`](/command-reference#show-readyset-tables) lists them as `Not replicated` and names the reason, for example `Tables with generated columns are not supported`. Queries against a non-replicated table fall through to the upstream database.

## Restarting during snapshotting

When Readyset restarts against an existing [storage directory](/reference/config-options#--storage-dir), snapshot progress is preserved **per table**:

* Tables whose snapshot completed before a clean shutdown are kept. Their data is read from the storage directory and they are not re-snapshotted; replication resumes from the position recorded for each table when its snapshot began.
* Tables that had not finished snapshotting start over **from the beginning of that table**. Rows already copied for that table are discarded.
* After an abrupt exit, such as a crash or `SIGKILL`, tables that finished snapshotting during that run may be snapshotted again.

If your deployment restarts routinely, avoid restarting while table snapshotting is in progress, for example during initial snapshotting or after changes to the ignored tables described in [Limiting which tables are snapshotted](#limiting-which-tables-are-snapshotted).

<Callout type="warn">
  Restarting with an empty or different storage directory discards all previously snapshotted data and starts a full snapshot of all tables.
</Callout>

## Parallel snapshotting

Readyset snapshots multiple tables in parallel, up to [`--max-parallel-snapshot-tables`](/reference/config-options#--max-parallel-snapshot-tables) (default: number of available cores - 1). Each table being snapshotted takes its own connection to the upstream database. Tables are snapshotted independently, so overall snapshot time is at least as long as the slowest single table.

## Limiting which tables are snapshotted

By default, Readyset snapshots and replicates every table in the upstream database. To narrow the scope, include only the tables your deep caches need with [`--replication-tables`](/reference/config-options#--replication-tables), or exclude specific tables with [`--replication-tables-ignore`](/reference/config-options#--replication-tables-ignore). See [Config Options](/reference/config-options#--replication-tables) for the accepted formats and eligibility behavior.

To add previously excluded or omitted tables to a running deployment, use [`ALTER READYSET ADD TABLES`](/command-reference#alter-readyset-add-tables):

```sql
ALTER READYSET ADD TABLES db.table, db.table2;
```

Readyset snapshots the added tables; tables that already finished snapshotting are not re-snapshotted. While the added tables snapshot, `SHOW READYSET STATUS` reports `Snapshot In Progress` again, and existing deep caches keep serving results but do not receive upstream changes until snapshotting completes.

## When a table snapshot fails

If a table fails to snapshot, Readyset continues with the rest, and the deployment can still reach `Online`. Queries against the failed table fall through to the upstream database, so results stay correct but are not cached. Check [`SHOW READYSET ALL TABLES`](/command-reference#show-readyset-tables) to find it: on PostgreSQL it is listed as `Not replicated` with the error, and is not retried; on MySQL it is retried automatically but can stay `Initializing` until the underlying problem is fixed.

Once the problem is fixed, add the table back with [`ALTER READYSET ADD TABLES`](/command-reference#alter-readyset-add-tables):

```sql
ALTER READYSET ADD TABLES db.table;
```

Readyset re-snapshots the added table, and the deployment reports `Snapshot In Progress` until it finishes. Restarting Readyset also recovers the table: restarts preserve tables whose snapshot completed and start over from the beginning for the rest, as described in [Restarting during snapshotting](#restarting-during-snapshotting).

## Re-snapshotting a table

To re-copy a single table's data, use:

```sql
ALTER READYSET RESNAPSHOT TABLE db.table;
```

For behavior when the upstream database fails over to a new primary, including the full resnapshot PostgreSQL requires after a replication slot is lost, see [Failover](/reference/failover).


# System Views (/reference/system-views)
Readyset exposes read-only system views under the `readyset` schema, queryable
with plain `SELECT` statements. Use them to monitor a running deployment.

## `readyset.replication_status`

Reports how far behind Readyset is relative to the upstream database's current
replication position. A single row is returned.

```sql
SELECT * FROM readyset.replication_status;
```

### Columns

| Column                        | Type               | Description                                                                                                                                                        |
| ----------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `replication_mode`            | `text`             | Replication protocol in use: `postgres`, `mysql_file`, or `mysql_gtid`.                                                                                            |
| `upstream_offset`             | `text`             | The upstream's current replication position. Format depends on `replication_mode`.                                                                                 |
| `replicator_offset`           | `text`             | Position of the most recent event Readyset has consumed from the stream.                                                                                           |
| `persisted_offset`            | `text`             | Persistence frontier: the furthest position any base table has durably recorded.                                                                                   |
| `consume_lag`                 | `bigint`           | Bytes (Postgres, MySQL file-based) or transactions (MySQL GTID) between `upstream_offset` and `replicator_offset`. How far behind Readyset is in ingesting events. |
| `persist_lag`                 | `bigint`           | Same units as `consume_lag`, between `upstream_offset` and `persisted_offset`. How far behind Readyset is in durably persisting events.                            |
| `heartbeat_staleness_seconds` | `double precision` | Wall-clock staleness in seconds. `NULL` when heartbeat is disabled.                                                                                                |

### Example output

```
 replication_mode | upstream_offset | replicator_offset | persisted_offset | consume_lag | persist_lag | heartbeat_staleness_seconds
------------------+-----------------+-------------------+------------------+-------------+-------------+-----------------------------
 postgres         | 0/1A3F2C8       | 0/1A3F200         | 0/1A3F1B0        |         200 |         280 |                       0.004
```

### Notes

* On a quiescent Postgres upstream, `consume_lag` and `persist_lag` report a
  small non-zero value (\~288 bytes). This is a measurement artifact from the
  WAL record that the position query itself generates, not real lag.
* When `replication_mode` is `mysql_gtid`, `consume_lag` and `persist_lag` are
  counts of transactions, not bytes.
* `heartbeat_staleness_seconds` requires
  [`--replication-heartbeat`](/reference/config-options#--replication-heartbeat)
  to be enabled on the Readyset server, which in turn requires write access to
  the upstream so Readyset can maintain a small heartbeat table
  (`readyset._heartbeat` on Postgres, `_readyset_heartbeat` on MySQL). If
  write access is not granted, Readyset logs a warning, disables heartbeat,
  and the column reports `NULL`; the other columns are unaffected.
* The poll cadence is controlled by
  [`--replication-lag-interval`](/reference/config-options#--replication-lag-interval)
  (default `1` second).

### Required upstream privileges

* **Postgres**: none beyond what replication already requires.
* **MySQL**: `REPLICATION CLIENT` (already required for replication).
* **Heartbeat** (optional, either dialect): write access to the upstream.

## `readyset.users`

Lists the usernames currently allowed to authenticate with Readyset. Passwords
are never exposed. The list reflects runtime changes made with
[`ALTER READYSET ADD/MODIFY/DROP USER`](/command-reference#alter-readyset-add-user)
immediately.

```sql
SELECT * FROM readyset.users;
```

### Columns

| Column             | Type   | Description                                                                                                                              |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `user`             | `text` | A username allowed to authenticate with Readyset.                                                                                        |
| `has_old_password` | `bool` | Whether the user has an old password retained by a [password rotation](/reference/user-management#rotating-a-password-without-downtime). |

### Notes

* `user` is a reserved word in PostgreSQL (it evaluates to `CURRENT_USER`), so
  quote the column to select it explicitly: `SELECT "user" FROM readyset.users`.
  On MySQL it may be used unquoted.
* The allowed-users set is seeded on Readyset's first startup from
  [`--allowed-users`](/reference/config-options#--allowed-users) and the
  [`--upstream-db-url`](/reference/config-options#--upstream-db-url) user, and is
  managed at runtime with
  [`ALTER READYSET ADD/MODIFY/DROP USER`](/command-reference#alter-readyset-add-user)
  thereafter. See [User Management](/reference/user-management).

## `readyset.cache_grants`

Exposes the current [cache authorization](/reference/cache-authorization)
verdict for every combination of user and cache: whether that user is served
from that cache, or routed to the upstream database instead. One row per
pair, including pairs the background checks have not resolved yet.

```sql
SELECT * FROM readyset.cache_grants;
```

### Columns

| Column      | Type   | Description                                                                                                                                                                   |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`      | `text` | The user (or assumed PostgreSQL role) the verdict applies to.                                                                                                                 |
| `cache`     | `text` | The cache's query ID, as shown by `SHOW CACHES`.                                                                                                                              |
| `verdict`   | `text` | `allowed` (served from the cache), `denied` (routed upstream, which rejects unauthorized access), or `unknown` (not checked yet; routed upstream, which authorizes directly). |
| `probed_at` | `text` | Timestamp of the check that produced this verdict; `NULL` for `unknown` pairs that have not been checked.                                                                     |

### Notes

* `user` is a reserved word in PostgreSQL, so quote the column to select it
  explicitly: `SELECT "user" FROM readyset.cache_grants`.
* `denied` and `unknown` are served identically (routed to the upstream);
  they differ only in whether the background check has an answer yet.
* Verdicts converge within one
  [`--cache-acl-refresh-interval-secs`](/reference/config-options#--cache-acl-refresh-interval-secs)
  interval, or immediately on
  [`ALTER READYSET FLUSH PRIVILEGES`](/command-reference#alter-readyset-flush-privileges).


# Telemetry (/reference/telemetry)
Readyset collects telemetry data to help us diagnose issues and understand how users interact with our product.

This telemetry data is anonymous by default. Users can opt into providing a persistent identifier, or disable telemetry completely.

Telemetry is reported using the [Segment](https://segment.com) customer data platform.

## Disabling telemetry

Telemetry can be disabled by running the Readyset installer with the `--disable-telemetry` option.

## Providing your own Segment source

By default, Readyset reports telemetry to an [HTTP Tracking API Source](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/) operated by Readyset, Inc. A different source can be specified by setting the `RS_SEGMENT_WRITE_KEY` environment variable to the write key corresponding to the source you wish to use.

## What telemetry data is collected?

Telemetry messages adhere to the [Segment Track API spec](https://segment.com/docs/connections/spec/track/). Each telemetry message contains a per-session anonymous UUID, an event name, a timestamp, and 0 or more properties. If the `RS_API_KEY` environment variable is set, its value will be used as the user ID.

The following OpenAPI schema describes all possible telemetry payloads reported by Readyset:

```yaml
components:
  schemas:
    TrackBody:
      type: object
      properties:
        userId:
          type: string
          description: the value in the RS_API_KEY env var, if present
        anonymousId:
          type: string
          description: a per-session UUID
        event:
          enum:
          - adapter_start
          - adapter_stop
          - server_start
          - server_stop
          - installer_run
          - deployment_started
          - deployment_finished
          - deployment_torn_down
          - installer_finished
        properties:
          $ref: '#/components/schemas/Properties'
        timestamp:
          type: string
          format: date-time
      required:
        - anonymousId
        - event
        - timestamp

    Properties:
      type: object
      properties:
        db_backend:
          enum:
          - mysql
          - postgres
        adapter_version:
            type: string
        server_version:
            type: string
        docker_version:
            type: string
        commit_id:
            type: string
```

### Events

Below are brief descriptions of each possible event:

* **Server Start**: The Readyset server was launched
* **Server Stop**: The Readyset server was shut down
* **Adapter Start**: The Readyset adapter was launched
* **Adapter Stop**: The Readyset adapter was shut down
* **Installer Run**: The Readyset installer was launched
* **Deployment Started**: A deployment of Readyset was initiated by the installer
* **Deployment Finished**: The Readyset installer finished deploying a new instance of Readyset
* **Deployment Torn Down**: The Readyset installer finished tearing down a deployment
* **Installer Finished**: The Readyset installer exited successfully


# TLS Support (/reference/tls)
import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Readyset supports TLS encryption between itself and your upstream database out
of the box. To do this, Readyset must have access to the root certificate used
by your upstream database. Operating systems typically come with the root
certificates for some common certificate authorities already installed. If your
upstream database uses a different root certificate, then you must either
install that certificate (such that all applications on your system can use it
to verify certificates) or provide the root certificate file path directly to
Readyset via the `--ssl-root-cert` option.

<Callout type="warning">
  The `--ssl-root-cert` option only supports a single certificate in the PEM or
  DER format. It does not support bundles containing multiple certificates.
</Callout>

<Callout type="warning">
  On macOS, providing the root certificate via the `--ssl-root-cert` option is
  not supported, the Apple Security framework (used by Readyset to provide TLS
  support) does not allow the use of untrusted certificates even when explicitly
  provided.
</Callout>

Below are instructions for installing and trusting a new root certificate on supported platforms:

<Tabs items={['Ubuntu', 'Amazon Linux 2', 'macOS']}>
  <Tab>
    Readyset uses the system-provided OpenSSL package on Linux.

    The following instructions are derived from [the Ubuntu docs](https://ubuntu.com/server/docs/security-trust-store).

    To install a new certificate, first download the certificate, then run the following:

    ```sh
    # Change the extension to .crt, and if necessary, convert from DER to PEM format
    # Place the output file in the appropriate system directory
    sudo openssl x509 -outform pem -in $INFILE -out /usr/local/share/ca-certificates/$OUTFILE.crt

    # Install the certificate
    sudo update-ca-certificates
    ```
  </Tab>

  <Tab>
    Readyset uses the system-provided OpenSSL package on Linux.

    The following instructions are derived from [the AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/SSL-on-amazon-linux-2.html).

    To install a new certificate, download the certificate, place it in `/etc/pki/tls/certs`,
    and set the file ownership and permissions as follows:

    ```sh
    sudo chown root:root $CERTIFICATE
    sudo chmod 600 $CERTIFICATE
    ```
  </Tab>

  <Tab>
    Readyset uses the Security framework on macOS.
    Certificates must be trusted by the system to be used.

    To install and trust a new certificate, do the following:

    1. Download the certificate you wish to install
    2. Open the Keychain Access application
    3. From the left-side menu, under System Keychains, select System
    4. Drag and drop the certificate into the keychain (or File > Import items...)
    5. Open the newly installed certificate (or File > Get Info)
    6. Set Trust > Secure Sockets Layer (SSL) to Always Trust and close the window (it prompts for authorization)
  </Tab>
</Tabs>

Below are download links for the root certificates for supported cloud database providers:

<Tabs items={['Amazon RDS', 'Azure Database', 'Google Cloud SQL']}>
  <Tab>
    The [Amazon RDS global certificate bundle](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)
    includes root certificates for every AWS region.

    Alternatively, only download the [region-specific bundle(s)](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html#UsingWithRDS.SSL.RegionCertificates)
    you need.
  </Tab>

  <Tab>
    The certificates used by Azure Database are probably already installed on your system.

    Both [Azure Database for PostgreSQL Single Server](https://learn.microsoft.com/en-us/azure/postgresql/single-server/concepts-ssl-connection-security)
    and [Azure Database for MySQL Single Server](https://learn.microsoft.com/en-us/azure/mysql/single-server/concepts-ssl-connection-security)
    require the [DigiCert Global Root G2](https://cacerts.digicert.com/DigiCertGlobalRootG2.crt.pem)
    certificate.

    Both [Azure Database for PostgreSQL Flexible Server](https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/how-to-connect-tls-ssl)
    and [Azure Database for MySQL Flexible Server](https://learn.microsoft.com/en-us/azure/mysql/flexible-server/how-to-connect-tls-ssl)
    require the [DigiCert Global Root CA](https://dl.cacerts.digicert.com/DigiCertGlobalRootCA.crt.pem)
    certificate.
  </Tab>

  <Tab>
    Google Cloud SQL creates a new root certificate per server instance. Follow [these instructions](https://cloud.google.com/sql/docs/mysql/configure-ssl-instance#server-certs)
    to locate and download the certificate for your particular instance.
  </Tab>
</Tabs>


# User Management (/reference/user-management)
import { Callout } from 'fumadocs-ui/components/callout'

Readyset keeps its own set of users that are allowed to authenticate with it.
That set has two stages in its life: it is seeded from command-line flags the
very first time a deployment starts, and from then on you manage it with SQL
against a running Readyset, with no restart and no dropped connections.

## Bootstrap on the first startup

On a deployment's **first** startup, Readyset seeds the allowed-users set from
two places:

* The user in [`--upstream-db-url`](/reference/config-options#--upstream-db-url),
  so the credentials Readyset already has can also be used to connect to it.
* [`--allowed-users`](/reference/config-options#--allowed-users) (env
  `ALLOWED_USERS`), a comma-separated list of `username:password` pairs.

```bash
readyset --upstream-db-url postgresql://readyset:<password>@db.internal/app \
         --allowed-users 'alice:<password>,bob:<password>'
```

That start accepts `readyset`, `alice`, and `bob`.

<Callout type="warn">
  Seeding happens **once**. Readyset then stores the set and reads it from
  storage on every later start, so editing `--allowed-users` or pointing
  `--upstream-db-url` at a different user has no effect on who may
  authenticate. After the first startup, use the commands below.
</Callout>

## Managing users at runtime

Connect to Readyset as any allowed user and run:

```sql
ALTER READYSET ADD USER 'carol' PASSWORD 'carolpw';
ALTER READYSET MODIFY USER 'carol' PASSWORD 'rotatedpw';
ALTER READYSET DROP USER 'carol';
```

Each command is stored before it returns, so it survives restarts, and takes
effect on the next connection attempt: an added user can connect right away, a
rotated password is required immediately, and a dropped user is refused. A
dropped or rotated user's connections that are already open are not closed;
the change applies when they reconnect.

[`ADD USER`](/command-reference#alter-readyset-add-user) fails if the user
already exists;
[`MODIFY USER`](/command-reference#alter-readyset-modify-user) and
[`DROP USER`](/command-reference#alter-readyset-drop-user) fail if it does not.
The user derived from `--upstream-db-url` cannot be modified or dropped, since
that identity backs Readyset's own connection to your database. All three
commands require
[authentication](/reference/authentication) to be enabled, so they are
unavailable under `--allow-unauthenticated-connections`.

<Callout type="info">
  A user in Readyset also needs to exist in your database with the same
  password. Readyset opens each session's connection to your database with
  that session's own credentials, so `ALTER READYSET ADD USER` is a companion
  to a `CREATE USER` upstream, not a replacement for it.
</Callout>

## Rotating a password without downtime

Changing a password with `MODIFY USER` normally requires new connections to
begin using the new password immediately. To allow the old password to remain
valid during a transitional period to the new password, perform:

```sql
ALTER READYSET MODIFY USER 'carol' PASSWORD 'rotatedpw' RETAIN CURRENT PASSWORD;
```

Carol can now authenticate with either password. Once all clients have moved to
the new one, retire the old password with:

```sql
ALTER READYSET MODIFY USER 'carol' DISCARD OLD PASSWORD;
```

A later `MODIFY USER ... RETAIN CURRENT PASSWORD` replaces any old retained
password with the current password, so only two passwords are ever valid at a
time. `MODIFY USER` without the clause changes the current password only and
leaves a retained one alone. `DISCARD OLD PASSWORD` is accepted even if there
is no old password.

To start a deployment already mid-rotation, name the user twice in
`--allowed-users`. The first password is the current one and the second is the
retained one:

```bash
readyset --allowed-users 'carol:newpassword,carol:oldpassword'
```

<Callout type="warn">
  Password rotation is available with a MySQL upstream only, mirroring MySQL's
  own dual-password support. Both clauses, and a repeated user in
  `--allowed-users`, are rejected in PostgreSQL mode.
</Callout>

Rotate the upstream account first, using MySQL's own `ALTER USER ... RETAIN
CURRENT PASSWORD`, and only then run the Readyset statement. Readyset connects
to your database with whichever of the two passwords the client presented, and
checks [cache authorization](/reference/cache-authorization) with the current
one, so both passwords must already be valid upstream. When the rotation is
complete, discard the old password in Readyset before discarding it upstream.

## Listing the current users

The [`readyset.users`](/reference/system-views#readysetusers) system view lists
the usernames that may authenticate right now, including runtime changes.
Passwords are never exposed.

```sql
SELECT "user" FROM readyset.users;
```

`user` is a reserved word in PostgreSQL, so quote the column there; on MySQL
`SELECT user FROM readyset.users` works unquoted. The `has_old_password` column
reports whether the user has a password rotation in progress.

## How it fits with the rest of Readyset

**[Authentication](/reference/authentication)** verifies each connection
against this set, whichever method the client protocol negotiates. On MySQL,
`caching_sha2_password` keeps a per-user fast-auth digest; `MODIFY USER` and
`DROP USER` clear it as part of the change, so a rotated password cannot be
bypassed by a client that authenticated earlier. A retained password keeps a
digest of its own until it is discarded.

**[Cache authorization](/reference/cache-authorization)** decides which users
are served from a cache, by asking your database what each of them is allowed
to read. `ADD USER` and `MODIFY USER` schedule that check for the new user, so
they start getting cache hits as soon as their privileges are confirmed;
`DROP USER` forgets them. Until then their queries are simply proxied to your
database.


# QueryPilot (/troubleshooting/querypilot)
import { Callout } from 'fumadocs-ui/components/callout';

Symptom-first fixes for the failure modes operators actually hit. The Router is the SQL proxy (binary `querypilot`). Port conventions used throughout: Router wire 5433, metrics 9090, admin API 9091 (always metrics port + 1). Most "cannot reach it" reports trace back to probing the wrong port.

## Startup failures

| Symptom                                                         | Likely cause                                                                                                   | Fix                                                                          |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Router exits with a TOML parse error naming a key               | The Router's schema is strict; an unknown or misspelled key anywhere fails startup                             | Fix the key; run `querypilot --check -c <file>` before deploying             |
| Router exits with `refusing to start: ... open proxy`           | A listener binds a non-loopback address with no pool credentials configured                                    | See below                                                                    |
| Router exits with an address-in-use error on 9090               | Something else owns port 9090, most often a Prometheus server on the same host (its default port is also 9090) | Move `[metrics] bind` (the admin API follows to port + 1) or move Prometheus |
| Router exits with a port-overflow error                         | `metrics.bind` port is 65535, so the derived admin port (metrics + 1) cannot exist                             | Pick a lower metrics port                                                    |
| Admin API connection refused on 9091, container flaps unhealthy | `[metrics] enabled = false` (the default), or metrics moved so the admin port moved with it                    | Set `enabled = true`; remember the shipped healthcheck assumes 9090/9091     |

### The open-proxy refusal

With no pool credentials configured, the Router accepts any client credentials, so it refuses to put a listener on a non-loopback address. The error is explicit:

```text
refusing to start: no client authentication is configured but listener(s)
[...] bind a non-loopback address, which would expose an open proxy.
Set username/password on a pool to require auth, bind listeners to loopback,
or set `[general] allow_anonymous = true` to deliberately run without auth.
```

Fix one of three ways: set `username`/`password` on a pool (these double as the client credentials), bind listeners to `127.0.0.1`, or set [`allow_anonymous = true`](/querypilot/reference/router-configuration#allow_anonymous) to deliberately run without auth after reading the [security page](/querypilot/security).

### A config setting has no effect

Which schema are you in? The components treat mistakes differently:

* **Router (`querypilot.toml`): strict.** Unknown keys fail at startup. If the Router started, your key was at least spelled correctly; check you edited the file the Router actually loaded (`--config` flag, then `QUERYPILOT_CONFIG`, then `./querypilot.toml`) and see `GET /api/config/status` for the live config path.

## Connection and authentication failures

| Symptom                                                        | Likely cause                                                                                        | Fix                                                                                                                 |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Credentials that work against the database fail via the Router | Clients must present the credentials of the first pool that defines them, not their database logins | Use the pool's `username`/`password`; check `sqp_auth_failures_total` for the reason                                |
| Unexpected credentials succeed                                 | No pool defines credentials, so the Router accepts anything (loopback-only state)                   | Set credentials on a pool                                                                                           |
| Clients connect but every query fails with a backend error     | Pool credentials or `database` wrong for the backend, or backend unreachable                        | Watch `sqp_backend_errors_total` and `sqp_backend_health`; test the pool's credentials directly against the backend |
| Connection refused on 5433                                     | Listener `bind` differs from the container convention, or the container publishes different ports   | Check `[[listeners]]` in the loaded config                                                                          |

## Routing surprises

| Symptom                                             | Likely cause                                                                                                                         | Fix                                                                              |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| A query went to the wrong pool                      | A pattern rule with higher precedence (lower `priority` number), or the read/write split classified it differently than you expected | Dry-run it: `GET /api/routing/test?sql=...` returns `decision` and `target_pool` |
| Reads inside transactions hit the primary           | Transaction pinning: statements inside an open transaction stay on the transaction's connection regardless of type                   | Expected; keep read-only work outside write transactions                         |
| A replica gets no traffic                           | Its measured replication lag exceeds its `max_replica_lag`, so it is skipped until it catches up                                     | Watch `sqp_backend_health` per backend and fix upstream lag                      |
| A rule added via `POST /api/pattern-rules` vanished | Runtime rules are ephemeral and cleared on config reload                                                                             | Put durable rules in `querypilot.toml`                                           |

The dry-run endpoint answers most routing questions without sending traffic:

```bash
curl "http://localhost:9091/api/routing/test?sql=SELECT%20*%20FROM%20orders%20WHERE%20id%20=%201"
```

The response includes `decision` (`translation`, `pattern`, `regex`, `default`, or `pinned`), `target_pool`, `fingerprint_hash`, and `normalized_sql`. Under live traffic, `sqp_routing_decisions_total` split by `decision_type` and `pool` shows where queries actually go.

## Pool exhaustion

**Symptom:** queries stall then fail after roughly `acquire_timeout`; `sqp_pool_timeouts_total` and `sqp_pool_acquire_total{outcome="timeout"}` increment.

Diagnose with the pool gauges: `sqp_pool_utilization_ratio` pinned near 1.0 with growing `sqp_pool_queue_depth` and `sqp_pool_wait_duration_seconds` means every connection is busy and sessions are queueing. Fixes, in order of preference:

1. Confirm the backend is not the real bottleneck (slow queries hold connections; check `sqp_query_duration_seconds`).
2. Raise `max_connections` on the pool if the backend has headroom.
3. With transaction pooling (`pool_mode = "transaction"`, the default), size against concurrent transactions, not client count; look for applications holding transactions open (`sqp_transaction_idle_seconds`, `sqp_transactions_active`).
4. If connections churn (`sqp_pool_acquire_total{outcome="created"}` climbing alongside a short `idle_timeout`), raise `min_connections` or `idle_timeout`.

Also check pool status: a pool set to `offline_soft` or `shunned` via the admin API rejects all acquires (`GET /api/pools` shows current statuses).

## Reading logs

Turn up verbosity with the environment override, not `RUST_LOG`, which the binary does not read:

```bash
QUERYPILOT_LOG_LEVEL=debug querypilot
```

Precedence is `--log-level` flag, then the environment variable, then the config's `logging.level`. Set `format = "json"` under `[logging]` when shipping logs to a pipeline; `pretty` is for terminals. The Router reloads `logging.level` via `POST /api/config/reload` if you need debug logs without a restart. See [environment variables](/querypilot/reference/environment-variables).

{/* source: verified against code @ 2026-07-18 */}