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

Critical: If you are currently using an H2 database, we strongly recommend migrating to PostgreSQL before upgrading.

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.

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.

---

Upgrade Path Overview

┌─────────────────────────────────────────────────────────────────┐
│                      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

At this point your environment should have:

• Lenses Agent: 6.1.2

• SQL Processors: 4.3.6

---

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

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.

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:

# Export all processors
lenses-cli export processors

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

Warning: Changing the ProcessorID causes the processor to restart consuming from the beginning of the topic, potentially reprocessing all historical data.

---

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?

If you encounter issues during the upgrade process, please refer to the official Lenses documentation or contact support.