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

# Set up a PostgreSQL database for Code Review (optional)

> Set up a PostgreSQL database to enable full Code Review functionality, including persistent findings, incremental reviews, and concurrency management.

To get full functionality of Qodo Code Review, it is recommended to set up a PostgreSQL database to support the following internal capabilities:

* Persist review findings
* Track incremental reviews
* Measure suggestion adoption
* Deduplicate findings across reviews
* Manage concurrency

The database is optional, and Qodo Code Review works without one, but the experience differs meaningfully depending on whether it's configured. Without a database, Qodo Code Review will still function but will fall back to parsing findings from PR comments. This is less reliable and does not support incremental reviews, full deduplication, or concurrency management.

## Before you begin

**What data is stored in the database?**

The database contains two tables:

* **`findings`**: Stores the review findings generated by the agentic review. Each finding includes a title, description, category (such as correctness, security, or performance), and severity level. For code context, each finding stores a diff reference with the file path, line range, and a code snippet in unified diff format. Findings also store supporting evidence with citations, fix suggestions and prompts for downstream agents, and workflow metadata such as deduplication decisions, conversion approvals, attribution status, and Git provider comment IDs.
* **`review_runs`**: Stores review execution metadata, including the PR URL, commit SHA, start time, status, and request ID. This data is used for concurrency management and incremental review tracking.

<Note>
  Only the specific lines referenced by a finding are persisted. No full file contents or complete diffs are stored.
</Note>

**Which versions of Qodo Code Review are supported?**

| Feature                | Minimum version |
| ---------------------- | --------------- |
| Findings DB            | 1.6.0           |
| Concurrency management | 1.28.0          |
| Incremental review     | 1.63.0          |

## Set up the database

### Option A: Already have a Qodo Aware database

If you already deployed a PostgreSQL instance for Qodo Aware, you can reuse the same PostgreSQL server.

**Step 1: Create a dedicated database and user**

On your existing PostgreSQL instance, run the following as a `superuser`:

```sql theme={null}
-- Run as superuser
CREATE ROLE qodo_merge_user LOGIN PASSWORD 'your-password';
GRANT qodo_merge_user TO postgres;  -- replace 'postgres' with your superuser
CREATE DATABASE qodo_merge OWNER qodo_merge_user;
```

Then reconnect as the newly created user and lock down the schema:

```sql theme={null}
-- Run as qodo_merge_user
\c qodo_merge
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
GRANT USAGE, CREATE ON SCHEMA public TO qodo_merge_user;
```

**Step 2: Configure Qodo Review**

Proceed to the [Configure Qodo Review](#configure-qodo-review) section below.

### Option B: Fresh PostgreSQL setup

If you don't have an existing PostgreSQL instance, you need to provision one.

**Step 1: Recommended instance configuration**

This can be a managed service (AWS RDS, GCP Cloud SQL, Azure Database for PostgreSQL) or a self-hosted instance.

| Resource           | Minimum     |
| ------------------ | ----------- |
| PostgreSQL version | 17 or later |
| CPU                | 4 vCPU      |
| RAM                | 8 GB        |
| Disk               | 100 GB      |

**Step 2: Allow network access**

* Enable TCP connections on port 5432.
* Whitelist access from the Kubernetes cluster where Qodo Review is deployed.

**Step 3: Create the database and user**

Run the following as a `superuser`:

```sql theme={null}
-- Run as superuser
CREATE ROLE qodo_merge_user LOGIN PASSWORD 'your-password';
GRANT qodo_merge_user TO postgres;  -- replace 'postgres' with your superuser
CREATE DATABASE qodo_merge OWNER qodo_merge_user;
```

Then reconnect as the newly created user and lock down the schema:

```sql theme={null}
-- Run as qodo_merge_user
\c qodo_merge
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
GRANT USAGE, CREATE ON SCHEMA public TO qodo_merge_user;
```

<Note>
  The Alembic migration will auto-create tables, but creating the database and setting permissions explicitly is recommended for clarity and security.
</Note>

## Configure Qodo review

These steps apply to both option A and option B.

**Step 1: Add database credentials to `.secrets.toml`**

Add the following section to your `.secrets.toml` file:

```toml theme={null}
[database]
password = "your-password"
```

**Step 2: Enable database persistence**

Add the following environment variable to the `configMaps` section of your `values.yaml`:

```yaml theme={null}
configMaps:
  main:
    REVIEW_AGENT__ENABLE_DATABASE_PERSISTENCE: "true"
    DATABASE__HOST = "your-postgres-host"
    DATABASE__PORT = "5432"
    DATABASE__DATABASE = "qodo_code_review"
    DATABASE__USERNAME = "qodo_code__review_user"
```

**Step 3: Restart the server**

Restart the Qodo Review pods to pick up the new secret and configuration.

**Step 4: Add a database migration job**

Database schema migrations must run before the Qodo Review application starts, on every deployment. Add the following job to your `values.yaml`:

```yaml theme={null}
jobs:
  db-migration:
    annotations:
      "helm.sh/hook": pre-install,pre-upgrade
      "helm.sh/hook-weight": "-5"
      "helm.sh/hook-delete-policy": hook-succeeded
    command:
      - "python"
      - "-m"
      - "alembic"
      - "-c"
      - "pr_agent/database/migrations/alembic.ini"
      - "upgrade"
      - "head"
```

<Note>
  This runs as a Helm `pre-install/pre-upgrade` hook, ensuring the database schema is up to date before the application starts. Database credentials must be available to the job.
</Note>

<Warning>
  The migration job runs as a Helm `pre-install/pre-upgrade` hook (weight "-5"), which means it executes before the main deployment resources are created. The Kubernetes secret and configmap referenced by the job must already exist in the namespace before running `helm install` for the first time. Create them manually (steps 1–2 above) before your initial deployment. On subsequent upgrades, they will already be present.
</Warning>

**Step 5: Deploy**

Deploy or upgrade using the standard Helm commands:

```bash theme={null}
helm upgrade --install qodo-merge ./module-<version>.tgz \
  -f ./values.yaml \
  -n qodo-merge
```

## Verify

**Check the migration job**

After deployment, confirm the migration job completed successfully:

```bash theme={null}
kubectl get jobs -n qodo-merge
```

The `db-migration` job should show `1/1` completions.

## Test the app

Run the `/agentic_review` command and verify Qodo Review runs properly.