RecoverLand: Practical guide

User Guide

This guide covers the day-to-day use of RecoverLand: from installation to data restore. Every step is illustrated so that any QGIS user can follow along, even without technical knowledge of the plugin.

Installation

Open the plugin manager

In QGIS, open Plugins → Manage and Install Plugins.

Install RecoverLand

Search for "RecoverLand" in the search bar. Click Install Plugin.

If the plugin is not in the official repository, copy the recoverland folder to:

C:\Users\[your_name]\AppData\Roaming\QGIS\QGIS4\profiles\default\python\plugins\

Then restart QGIS.

Verify activation

A RecoverLand icon appears in the QGIS toolbar. If it does not appear, check in Plugins → Manage and Install Plugins → Installed that RecoverLand is checked.

Requirements: QGIS 3.44 minimum. No external dependency. The plugin uses only standard Python and SQLite, both included in QGIS.

First launch

Open a QGIS project with editable layers

RecoverLand needs at least one editable vector layer to work. If you do not have a project yet, create one and add a GeoPackage or Shapefile.

Click the RecoverLand icon

The RecoverLand window opens. At the top, the info bar shows:

Local journal: name and size of the SQLite journal
Counters: total events, updates, deletions, and insertions in the current scope
Recording toggle: enables or disables change capture
Health alert: appears when the journal is growing large or disk space is low (clickable to open Maintenance)

Verify recording is active

The toggle at the top right must show "Recording active" in green. If it is red, enable it.

From this moment, RecoverLand silently records every change you make on monitored layers. Nothing else needs to be configured.

Interface overview

The info bar

The bar at the top of the window shows a real-time summary of the journal. Counters update when you change the selection or period filters. Clicking a tile (Total, Updates, Deletions, Insertions) toggles the corresponding operation filter. If a health alert is visible (journal too large or low disk space), clicking it opens the Maintenance dialog.

Tracking changes

By default, RecoverLand monitors all editable layers in the project. You can restrict monitoring to specific layers in the Monitored layers section.

Enable/disable recording

The toggle at the top right of the info bar globally controls capture. When disabled, no change is recorded even if you edit layers.

Disabled = no protection. If you disable recording, changes made during that period are lost permanently. RecoverLand cannot recover what was never recorded.

Automatic disable on low disk space

If the disk volume hosting the journal drops below 100 MB free, RecoverLand automatically disables tracking to prevent data corruption. A red alert appears in the info bar. Free up disk space and re-enable the toggle to resume recording.

Choose monitored layers

Open the Monitored layers section (collapsed by default). Every vector layer loaded in the project appears with a checkbox. Uncheck a layer to stop monitoring its changes.

Searching for changes

Choose the layer and operation

In the Selection section:

Layer: "All saved layers" or a specific layer
Operation: All, UPDATE, DELETE, or INSERT

Set the time window

Use the Start date and End date fields, or the shortcuts (10 min, 30 min, 1 hour, 1 day) to quickly define the search window.

Click Recover

The Recover button launches the search in the SQLite journal. A progress bar is shown during processing. Results appear in the table.

Reading the results

The table shows each event with fixed columns and dynamic columns.

Fixed columns

Column	Content
Operation	INSERT, UPDATE, or DELETE
Layer	Layer name at the time of the change
Date	UTC date and time of the change
User	Name of the user who made the change (auto-resolved)

Dynamic columns (attributes)

The following columns show the feature's attributes at the time of the change. Cells are color-coded to indicate the type of change:

Color	Meaning
Light blue	Modified value (previous value shown)
Light red	Cleared value (was filled, now empty)
Light green	New value (was empty, now filled)
Light orange	Geometry changed

Text filter: A search field above the table filters rows by keyword. The search covers all visible columns.

The three buttons: Recover, Restore, Last

RecoverLand's workflow is built around three buttons. Each one plays a distinct role in the data recovery chain. Understanding them is the key to using the plugin effectively.

Recover: find what changed

PURPOSE

Search the audit journal

Recover queries the local SQLite journal and displays all recorded changes matching your filters: layer, operation type, date range, and text search.

SAFE

Read-only operation

Recover never modifies your data. It only reads the journal and displays results in the table. You can run it as many times as needed without risk.

Set filters → Layer + operation + period → Click Recover (F5) → Results appear in the table

Keyboard shortcut: Press F5 to trigger Recover. Use Ctrl+F to filter results by text.

Restore: revert changes

PURPOSE

Write previous values back to the layer

Restore reverses the selected events: it puts back old attribute values, re-inserts deleted features, or removes incorrectly inserted features.

CAUTION

Modifies data with preflight check

Before executing, RecoverLand runs a preflight validation (schema, capabilities, volume limits). A confirmation dialog shows the plan and any warnings.

Original event	What Restore does	Result
UPDATE	Puts back old attribute values + geometry	Feature reverted to its pre-edit state
DELETE	Re-inserts the feature with saved attributes	Deleted feature reappears in the layer
INSERT	Removes the incorrectly inserted feature	Feature deleted from the layer

Restore modifies data. It overwrites current values with the values stored in the journal. Make sure to select the correct rows before confirming.

Preflight validation

Last: undo the restore

PURPOSE

Revert to pre-restore state

After a Restore, the Last button puts your data back exactly as it was before the restore executed. It reverses the restore itself.

SAFE NET

One-click undo, available once

Last is only enabled after a successful Restore. After clicking it, the button disables. It does not depend on date filters or search criteria.

How it works internally: For UPDATE events, Last re-applies the post-edit values. For DELETE events (re-inserted by Restore), it deletes them again. For INSERT events (deleted by Restore), it re-inserts them. Each operation is reversed precisely.

Restore modes

When results are loaded, a mode selector appears above the buttons:

Mode	Use case	Behavior
By event	Undo specific changes	Each selected event is reversed individually. Failed events do not block others.
To date / version	Roll back to a point in time	All events after the cutoff are reversed in order. Strict atomicity: all succeed or all roll back.

Retention coverage

If you request a temporal restore with a cutoff date before the oldest available event, the preflight blocks the operation. This prevents silent partial restores.

Session tracking

Every restore execution produces a RestoreSession record (session ID, mode, timestamps, success/failure counts, status). Each restored feature also generates a trace event in the journal for auditability.

Restore on a repacked shapefile: If a shapefile was re-exported or packed between capture and restore, FIDs may have changed. Use GeoPackage to avoid this risk.

Schema drift warning

If a layer's structure has changed between capture and restore (field added, removed, or renamed), RecoverLand displays a warning before proceeding.

What happens concretely

You launch a restore

RecoverLand compares the schema stored in the event (field_schema_json) with the current layer schema.

Differences detected

The report shows:

Compatible fields: restored normally
Missing fields: existed at capture but have since been deleted. Values ignored.
New fields: did not exist at capture time. Left at their default value.
Incompatible fields: type has changed (e.g., text to integer). Conversion attempted.

Best practice: Avoid modifying a layer's structure if you plan to restore old data. If unavoidable, review the compatibility report carefully before confirming.

Managing journal retention

The SQLite journal grows over time. RecoverLand provides tools to control its size via the Maintenance dialog.

Age-based purge

Delete events older than a configurable threshold (default: 365 days, up to 10 years). Purged events are permanently deleted.

Max-events cap

Set a maximum event count. When the cap is exceeded, the oldest events are automatically removed. The default cap is 1,000,000 events.

Session purge

Delete all events from a specific edit session. Useful to clean up test sessions or large imports.

Compaction (VACUUM)

After a purge, the physical size of the SQLite file does not decrease automatically. VACUUM reclaims disk space. It runs in a background thread so the UI stays responsive.

Purge = permanent deletion. Once purged, events cannot be recovered. Make sure the purged history is no longer needed.

Automatic purge on startup

In the Maintenance dialog, you can enable "Auto-purge at startup". When active, events outside the retention policy are removed every time the journal is opened.

Size monitoring

The info bar at the top of the RecoverLand window permanently displays the journal size and event count. These indicators change color (blue → orange → red) as the journal grows. Click the health alert to open the Maintenance dialog.

Maintenance dialog

Open the Maintenance dialog from the health alert in the info bar, or from the Maintenance button in the main dialog.

What it shows

Path: full path to the journal file (selectable for copy)
Size: current file size
Events: total event count
History span: time range from oldest to newest event
Schema version: current database schema version
Health: Healthy / Info / Warning / Critical with a color indicator

What you can do

Open journal folder: opens the .recoverland/ directory in the file explorer
Save retention policy: set retention days, max events, and auto-purge option
Purge old events: removes events outside the retention policy (with confirmation)
VACUUM: reclaims physical disk space after a purge (runs in background)
Integrity check: runs PRAGMA integrity_check and WAL validation
Export journal: copies the SQLite file (and WAL sidecar if present) to a user-chosen destination

Export before purge: If you are unsure whether old events may be needed, export the journal first, then purge. The export is a plain SQLite file you can inspect later.

Health alerts

RecoverLand evaluates journal health and disk space every time the dialog is opened. Alerts appear in the info bar as a colored message.

Color	Level	Trigger
Blue	Info	Journal > 50 MB or > 100,000 events
Orange	Warning	Journal > 200 MB or > 500,000 events, or disk < 500 MB free
Red	Critical	Journal > 500 MB or > 1,000,000 events, or disk < 100 MB free (tracking auto-disabled)

Clicking the alert message opens the Maintenance dialog. The tooltip on the alert shows the suggested action.

User identity

Every recorded event carries the name of the user who made the change. RecoverLand resolves this automatically in the following priority order:

Plugin config → Env var RECOVERLAND_USER → OS login → QGIS profile name → "unknown"

Override the user name

To force a specific user name (e.g., a service account or a shared workstation), set the RECOVERLAND_USER environment variable before launching QGIS. Alternatively, configure the user name override in the plugin settings: it takes the highest priority and overrides all other sources.

The resolved user name is shown in the User column of the results table. It cannot be empty: if all sources fail, the fallback value "unknown" is used.

Scenario: Undo a mistake

You just accidentally modified 50 attributes on a vegetation layer.

Open RecoverLand → Layer = vegetation → Operation = UPDATE → Period = 10 min → Recover

The 50 changes appear. Select them all, then click Restore. The attributes revert to their previous state.

Changed your mind? Click Last immediately after a Restore to undo it. Your data goes back to the state it was in before you clicked Restore.

Scenario: Compare before/after

You want to see what changed on a layer since yesterday.

Layer = parcels → Operation = All → Period = 1 day → Recover

The table shows all changes. Color-coded cells indicate exactly which attributes changed and what the previous values were.

Scenario: Recover a deleted feature

A colleague accidentally deleted an important feature.

Layer = buildings → Operation = DELETE → Period = 1 day → Recover

The deleted feature appears with all its attributes and geometry at the time of deletion. Select it and click Restore to re-insert it into the layer.

The restored feature is inserted as a new feature with a new FID. Attributes and geometry are identical to the saved state. If the wrong feature was recovered, click Last to undo.