# 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.2.0.

***

### 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.2.0         │
│                                              │                  │
│   SQL Processors 4.3.6 ─────────────────────►│                  │
│                                              ▼                  │
│                                    SQL Processors 6.2.0         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

***

### 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.2.0

Once Lenses is running on version 5.5:

1. Perform the conversion from Lenses 5.5 to **Lenses Agent 6.2.0**
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.2.0
* **SQL Processors**: 4.3.6
  {% endhint %}

***

### Step 3: Upgrade SQL Processors to 6.2.0

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

***

### 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.2.0      |
| 3    | SQL Processors          | 4.3.6        | 6.2.0      |

***

### Need Help?

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/deployment/upgrade-to-lenses-6/upgrade-path-for-sql-processors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.