Migrations triggered at first store setup, causing undefined behaviors

[lsarrazi]

Introduction

Our company relies on electron-store as the primary database for our software. However, we have encountered issues related to undefined behaviors during the initial store setup. We would greatly appreciate any help on this topic 🙏

Our current configuration:

[email protected] -> 22.3.3
electron-store@^8.0.2 -> 8.1.0

Assumptions and Background

When a migration is defined in electron-store, it is generally assumed that the store's state matches a version that is strictly less than the version specified in the migration. For instance:

migrations: {
	"1.0.0": (store) => {
		// The "store" version is guaranteed to be strictly less than 1.0.0
		store.set("newPropertyName", store.get("oldPropertyName"));
		store.delete("oldPropertyName");
		// The "store" is updated to version 1.0.0 at the end of the migration
	},
}

This assumption ensures that migrations can be applied sequentially to upgrade to a target version.

Problem Description

The current implementation initializes the store's version as "0.0.0" (hardcoded) upon its first initialization. However, the store is actually initialized with the default values of the latest version (e.g., 1.0.0), which contradicts the assumption that the store should be given to the migration in a version strictly less than 1.0.0. This discrepancy leads to undefined behaviors and potential issues.

Analysis and Proposed Solutions

We found a workaround to ensure that the store is always considered up to date during its first initialization by modifying the default values:

/*
Hack to make sure the store is always up to date at first init,
default behavior of electron-store being to consider the store in version '0.0.0' by default
*/
defaults: {
	__internal__: {
		migrations: {
			version: app.getVersion(), // Our current version, e.g., '1.0.0'
		},
	},
}

Another possible solution is to replace the hardcoded 0.0.0 version in the conf package source code with options.projectVersion. This could potentially yield a similar result without modifying the default values.

We could not find any alternative method for setting the default version for migrations using the electron-store API.

Questions

Feel free to answer some of our questions if possible:

1. Is there a specific reason for initializing the store with a hardcoded "0.0.0" version, or was this an oversight in the implementation?
2. Are you aware of any other cases where the current version initialization may lead to issues or undefined behaviors?
3. Have you considered implementing an option in the electron-store API to allow users to set the default version for migrations directly, instead of relying on workarounds?
4. Are there any known limitations or potential side effects of using the workaround we proposed to ensure the store is up to date during its first initialization?
5. Would you be open to implementing the suggested change of using options.projectVersion instead of the hardcoded "0.0.0" version in the conf package source code, or do you have alternative recommendations?
6. Can you provide any guidance on best practices for managing store versions and migrations to prevent similar issues in the future?
7. Are there any plans to enhance the migration handling or version management in future releases of electron-store to address this issue or related concerns?

[sindresorhus]

Sorry to hear you're having problems with the migration feature. However, the migration feature was not added by me. It was added by an external contributor. I don't use the feature and I also cannot provide support for it.

[lsarrazi]

Thanks for your answer @sindresorhus, do you know the github account of this contributor, such that we can contact him ?

[sindresorhus]

I don't remember. You can search for the Pull Request.

[Enubia]

/*
Hack to make sure the store is always up to date at first init,
default behavior of electron-store being to consider the store in version '0.0.0' by default
*/
defaults: {
	__internal__: {
		migrations: {
			version: app.getVersion(), // Our current version, e.g., '1.0.0'
		},
	},
}

@lsarrazi thank you so much for this workaround, I was already going insane because of a bug report of some users who said my app would not launch on initial installation. After 4 hours of digging I found the undefined behavior which you described.

Can confirm that this workaround fixes the problem for anyone encountering the same