# Upgrade path for SQL Processors

## SQL Processors Upgrade Guide

This guide outlines the upgrade path for Lenses SQL Processors from version 4.3.6 to 6.1.2.

***

### H2 Database Migration Notice

{% hint style="danger" %}
**Critical**: If you are currently using an H2 database, we strongly recommend migrating to **PostgreSQL** before upgrading.
{% endhint %}

Starting with **Lenses Agent v6.0.6**, H2 has been upgraded to version 2.x. This new version **does not support migration** from previous H2 versions. If you proceed with the upgrade while using H2, you will lose your existing data.

**Recommendation**: Migrate to PostgreSQL before beginning the upgrade process.

### Prerequisites

Before starting the upgrade process, ensure your SQL Processors are running on **version 4.3.6 or higher**.

{% hint style="warning" %}
**Important**: If your SQL Processors are running a version below 4.3.6, you must first upgrade to 4.3.6 before proceeding with this guide.
{% endhint %}

***

### Upgrade Path Overview

```mmd
┌─────────────────────────────────────────────────────────────────┐
│                      UPGRADE PATH                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Lenses < 4.3.6  ──►  Lenses 4.3.6  ──►  Lenses 5.5           │
│                                              │                  │
│                                              ▼                  │
│                                      Lenses Agent 6.1.2        │
│                                              │                  │
│   SQL Processors 4.3.6 ─────────────────────►│                  │
│                                              ▼                  │
│                                    SQL Processors 6.1.2        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

***

### Step 1: Upgrade Lenses to 5.5

#### If currently on Lenses 4.3.6

Upgrade Lenses directly from 4.3.6 to 5.5.

#### If currently below Lenses 4.3.6

You must perform a two-step upgrade:

1. First, upgrade Lenses to **4.3.6**
2. Then, upgrade Lenses from 4.3.6 to **5.5**

***

### Step 2: Convert Lenses to Lenses Agent 6.1.2

Once Lenses is running on version 5.5:

1. Perform the conversion from Lenses 5.5 to **Lenses Agent 6.1.2**
2. During this step, keep the SQL Processors image at **4.3.6** — do not upgrade the processors yet

{% hint style="info" %}
At this point your environment should have:

* **Lenses Agent**: 6.1.2
* **SQL Processors**: 4.3.6
  {% endhint %}

***

### Step 3: Upgrade SQL Processors to 6.1.2

With Lenses Agent running on 6.1.2 and SQL Processors on 4.3.6, you can now upgrade the SQL Processors to version 6.1.2.

***

### How to Safely Update an Existing SQL Processor

{% hint style="warning" %}
**Warning**: The Lenses 5.x CLI is completely incompatible with Lenses 6.0 — a new CLI is coming soon. You can utilize creation of processors through UI or API.
{% endhint %}

Lenses does not allow direct editing of SQL Processors because changes may create incompatibility with existing state.

#### Step-by-step instructions

1. **Stop the processor**\
   Navigate to Actions → Stop
2. **Document the processor details**
   * Copy the Processor ID *(critical for maintaining offsets)*
   * Copy the complete SQL query
   * Record any configuration settings
3. **Delete the old processor**\
   Lenses doesn't allow duplicate Processor IDs
4. **Create a new processor**\
   Use the same Processor ID in Advanced Settings, which allows the new processor to continue from the previous consumer group offset position
5. **Start the new processor**

Processors can be also exported running command `lenses-cli export processors` or specific one `lenses-cli export processors --id <application_id>`

#### Exporting Processors via CLI

Processors can also be exported by running the following commands:

```bash
# Export all processors
lenses-cli export processors

# Export a specific processor
lenses-cli export processors --id <application_id>
```

{% hint style="info" %}
**Warning**: Changing the ProcessorID causes the processor to restart consuming from the beginning of the topic, potentially reprocessing all historical data.
{% endhint %}

***

### Summary

| Step | Component               | From Version | To Version |
| ---- | ----------------------- | ------------ | ---------- |
| 1a   | Lenses (if below 4.3.6) | < 4.3.6      | 4.3.6      |
| 1b   | Lenses                  | 4.3.6        | 5.5        |
| 2    | Lenses → Lenses Agent   | 5.5          | 6.1.2      |
| 3    | SQL Processors          | 4.3.6        | 6.1.2      |

***

### Need Help?

{% hint style="success" %}
If you encounter issues during the upgrade process, please refer to the official Lenses documentation or contact support.
{% endhint %}