EDB Upgrade Guide

July 10, 2026 · View on GitHub

This guide describes safe upgrade paths between EDB releases. Read it before replacing library files in a project that already has live data on EEPROM, SD, or SPIFFS.

2.0.0 uses the v3 on-disk format and does not upgrade older files in place. Any v1/v2 database must be converted offline with tools/edb_migrate.py (see MIGRATION.md); open() returns EDB_NEEDS_MIGRATION for a legacy file. The 1.0.7 line is a maintenance release that keeps the legacy file format. Always back up storage before upgrading to 2.0.0.

Which release should I use?

Your situationRecommended release
Existing project on 1.0.6, want zero risk1.0.7 (drop-in)
On 1.0.7 and want bug fixes onlyStay on 1.0.7
New project2.0.0
Need cross-platform .db files (AVR ↔ ESP32)2.0.0 + migration tool
SD/SPIFFS database created on a different MCU2.0.0 + edb_migrate.py
flowchart TD
  v106[1.0.6]
  v107[1.0.7 drop-in]
  v200[2.0.0]
  v106 -->|"Copy EDB.h + EDB.cpp"| v107
  v107 -->|"Replace library"| v200
  v106 -->|"Replace library + migrate if needed"| v200
  v200 -->|"create() on new projects"| v200

Path 1: 1.0.6 → 1.0.7 (drop-in)

Best for: Any existing 1.0.6 deployment where you want safety fixes without touching stored data.

Steps

  1. Back up your current EDB.h and EDB.cpp (optional but recommended).
  2. Copy release/1.0.7/EDB.h and release/1.0.7/EDB.cpp into your Arduino libraries/EDB/ folder.
  3. Restart the Arduino IDE.
  4. Recompile and upload your sketch — no sketch changes required.

What changes

Area1.0.61.0.7
On-disk formatUnchangedUnchanged
Public APIUnchangedUnchanged
recno == 0Silent corruption possibleReturns EDB_OUT_OF_RANGE
open() on bad headerAlways EDB_OKReturns EDB_ERROR
create() validationMinimalValidates params + read-back
Shift ops (insertRec / deleteRec)No malloc checkReturns EDB_ERROR on allocation failure

Data migration

None. Existing EEPROM, SD, and SPIFFS databases are read and written using the same layout as 1.0.6.

Rollback

Restore your backed-up 1.0.6 EDB.h and EDB.cpp. Data on storage is unaffected.

Best for: Projects already on 1.0.7 that are ready for 2.0.0 / v3 on-disk format and improved cross-platform support. Legacy v1/v2 files are migration inputs only — new create() writes v3.

Steps

  1. Back up all stored data (EEPROM dump, copy .db files).
  2. Replace library files with root EDB.h and EDB.cpp (version 2.0.0).
  3. Choose a storage-specific path below (EEPROM vs SD/SPIFFS).
  4. Call open() and verify it returns EDB_OK.
  5. Smoke test: count(), read first and last record, append one test record.

By storage backend

All legacy data must be migrated offline — 2.0.0 never upgrades a v1/v2 file in place, and open() on one returns EDB_NEEDS_MIGRATION.

EEPROM (AVR internal/external, ESP32, I2C)

  1. Dump the EEPROM region holding the database to a file on your PC.
  2. Migrate it: python tools/edb_migrate.py dump.db migrated.db --arch auto. The v3 file is larger than the source (bigger header + per-slot CRC); use --table-size to fit a fixed EEPROM region, or move to larger storage.
  3. Write migrated.db back to the same EEPROM offset.
  4. open(0) should return EDB_OK.

SD card / SPIFFS file (any origin MCU)

  1. Copy the .db file to your PC.
  2. Run python tools/edb_migrate.py device.db migrated.db --arch auto.
  3. Copy migrated.db back to the device.
  4. Open with db.open(0) and confirm EDB_OK.

clear() is a destructive wipe, not a migration — it resets the table to empty and writes a fresh v3 header. Use it only when you intend to discard existing records.

See MIGRATION.md and tools/README.md.

Path 3: 1.0.6 → 2.0.0 (direct)

Best for: New deployments or when you are prepared to migrate all stored databases in one step.

You may skip 1.0.7 if you accept the larger change set in a single upgrade. The storage-specific steps are the same as Path 2.

Recommended safer route: 1.0.6 → 1.0.7 first (verify in production), then 1.0.7 → 2.0.0.

Compatibility matrix

FromToLibrary actionSketch changesDB migrationData risk
1.0.61.0.7Copy release/1.0.7/EDB.*NoneNoneNone
1.0.71.0.6Restore old filesNoneNoneNone
1.0.x / v22.0.0Copy root EDB.*Update delete/insert/iteration idiomsOffline edb_migrate.pyMedium
—2.0.0New projectUse 2.0.0 APIcreate() writes v3None

Storage backend summary

Backend1.0.6 → 1.0.7legacy → 2.0.0 (v3)
AVR EEPROMNo migrationDump, edb_migrate.py, write back
ESP32 EEPROMNo migrationDump, edb_migrate.py, write back
SD card fileNo migrationRun edb_migrate.py
SPIFFS fileNo migrationRun edb_migrate.py
AT24C1024 / I2C EEPROMNo migrationDump, edb_migrate.py, write back

API changes in 2.0.0

Item1.0.6 / 1.0.72.0.0Breaking?
clear() return typevoidEDB_StatusNo — safe if return value ignored
appendRec()EDB_Recadds appendRec(rec, &recno) overloadNo — source-compatible
extern EDB edbDeclared in headerStill declared (use #define EDB_NO_GLOBAL to hide)No for single-table sketches
On-disk formatCompiler-dependent v1 layoutv3 (redundant CRC header + framed slots)Yes — migrate legacy files offline
recno after deleteRenumbers (shift)Slot index does not shift; slot may be tombstoned and later reused with new data — use payload record_id or enableStableIds() for durable identity; iterate with firstRec/nextRecYes
insertRec(recno, …)Positional insert (shift)Allocates a free slot; position not preservedYes
New statuses—EDB_DELETED, EDB_CORRUPT, EDB_NEEDS_MIGRATIONAdditive
open() on legacy DBopens (maybe wrongly)EDB_NEEDS_MIGRATIONYes

Upgrade checklist

Use this checklist for any upgrade that touches live data:

  • Back up storage (EEPROM dump, copy .db file, or export records over serial)
  • Note current library version (library.properties → version=)
  • Copy the correct EDB.h and EDB.cpp for your target release
  • If upgrading to 2.0.0 with SD/SPIFFS data, run edb_migrate.py
  • Recompile and upload the sketch
  • Call open() — expect EDB_OK on a healthy database
  • Read count() and spot-check first and last records
  • Append one test record and read it back
  • Remove the test record or restore from backup if this is production data

Rollback

RollbackActionData impact
1.0.7 → 1.0.6Restore backed-up 1.0.6 library filesNone
2.0.0 → 1.0.7Restore 1.0.7 library filesv2 databases may not open on 1.0.7 — restore storage from backup
2.0.0 → 1.0.6Restore 1.0.6 library filesSame as above

Always keep a storage backup taken before upgrading to 2.0.0.

Optional encryption (EDB_Crypto.h)

EDB_Crypto.h is additive — core EDB.h / EDB.cpp API is unchanged. Encryption is off unless you define EDB_ENABLE_CRYPTO. Existing sketches and databases without encryption extensions continue to work. See ENCRYPTION.md.