Clarification about v3 migration: Is manual data migration required and must it remain in the codebase permanently?

[hrastnik]

What happened?

Hi

I'm currently planning a migration to AsyncStorage v3 and had a question about how existing data should be handled.

I read the migration guide here:
https://react-native-async-storage.github.io/3.0/migration-to-3/

From my understanding, the new v3 API uses createAsyncStorage() and introduces namespaced storage instances. However, it's not completely clear to me how existing data stored using the old API should be accessed or migrated.

My concern

If a user already has data stored with the previous API (@react-native-async-storage/async-storage v2), is there a way to access that data using the new v3 storage instance, or is a manual migration step required?

For example, I implemented the following migration logic:

const storage = createAsyncStorage("database");

const hasMigrated = await storage.getItem("__migrated__");
if (!hasMigrated) {
  const keys = await RNAsyncStorage.getAllKeys();
  if (keys.length > 0) {
    const entries = await RNAsyncStorage.getMany(keys);

    const nonNullEntries: Record<string, string> = {};
    for (const key in entries) {
      const value = entries[key];
      if (value != null) {
        nonNullEntries[key] = value;
      }
    }

    await storage.setMany(nonNullEntries);
    await RNAsyncStorage.removeMany(keys);
  }
  await storage.setItem("__migrated__", "true");
}

Questions

1. Is this kind of manual migration approach the recommended way to move data from the old API to v3?
2. Is there any way for the new v3 storage instance to read existing keys directly, or are they completely separate storage namespaces?
3. If manual migration is required, does that mean this migration code needs to remain in the codebase indefinitely for users who might update from very old app versions?
4. Are there any best practices recommended by the maintainers for handling this migration safely in production apps?

My main goal is to ensure users don't lose previously stored data when upgrading to v3.

Thanks in advance for any clarification!

Version

3

What platforms are you seeing this issue on?

• Android
• iOS
• macOS
• Windows
• web

System Information

React Native 0.84.1

Steps to Reproduce

[krizzu]

hey @hrastnik, thanks for questions.

There is no enforcement for migration - it is optional. You use default import from Async Storage to access you data, as you were up to date.

The thing for scoped storage is that it can be introduced incrementally - when u create a new feature, you could use scoped storage for that. You could also migrate just part of your current storage. No need to jump in into migrate-everything mode now.

Is this kind of manual migration approach the recommended way to move data from the old API to v3?

Yes, if you want to migrate bits into scoped storage, you have to have a way to say "migration done". Personally, I have a scoped storage "migrations", where I keep info of which part of my domain is migrated.

Is there any way for the new v3 storage instance to read existing keys directly, or are they completely separate storage namespaces?

Each storage is separate, unless the name is the same. They are backed by separate sqlite files.

If manual migration is required, does that mean this migration code needs to remain in the codebase indefinitely for users who might update from very old app versions?

Well, yeah - if you decided something needs to be migrated, then yes.

Are there any best practices recommended by the maintainers for handling this migration safely in production apps?

It really depends on your app. Like I said, in my case, we have a config store we need to sync with backend, so we naturally have some work to do in "splash screen" - I found this to be good place to run few migrations, if required.

Let me know if this makes it bit more clear!