Capacitor SQLite plugin in-place migration persistence across version upgrade

To migrate a Capacitor app from SQLite 4.x to 5.x without losing data, you must understand the plugin's initialization lifecycle and file path resolution. The plugin prioritizes database continuity as long as the storage configuration in your capacitor.config.json remains consistent.

Initialization and Validation Timing

p>The ensurePluginConfig method functions during the plugin's initialization phase. In both Capacitor 4 and 5.x, this check is designed to validate schema compatibility before the database is fully available for queries.

• Does it block startup? It does not block the native-level app startup, but it does block the SQLite bridge from resolving the database connection until the validation logic completes.
• Is it guaranteed to run before the first query? Yes. The plugin architecture ensures that initialization scripts run sequentially. Any attempt to executeSql before this completes will typically be queued or fail depending on the implementation version.

AppData Continuity (4.x to 5.x)

p>The appDataDirectory setting determines where the .sqlite file resides. Between Capacitor 4 and 5, the underlying OS-level internal storage paths for Android and iOS remain stable.

• As long as you do not change the appDataDirectory value in your configuration during the upgrade, the plugin will look for the existing file in the same location.
• Risk: If you change the path during the upgrade, the plugin will treat the new path as a fresh install, potentially triggering createFromLocation or creating an empty database.

createFromLocation vs. Upgrades

p>The createFromLocation feature is intended for bootstrapping a fresh installation.

• Evaluation: It is evaluated only when the target database file does not exist at the target path.
• Upgrade Behavior: On a version upgrade where the database file is already present, createFromLocation is ignored. This prevents accidental overwriting of user data with the template database.

n

Recommended Migration Steps

1. Lock the Config: Ensure appDataDirectory is explicitly set in capacitor.config.json and unchanged.
2. Define Migration Scripts: Use the plugin's built-in migration array. Ensure your version number is incremented so the plugin triggers the in-place scripts.
3. Verify File Path: Before the major upgrade, use sqlitePlugin.getDatabasePath() to log the current location and verify it matches the expected path post-update.

Note: If you are using a custom encryption key, ensure the key management logic survives the upgrade, or the plugin will fail to open the existing file during migration.