Migrating to a newer OmniFocus database format

When updating OmniFocus from an earlier version of the app, you may be prompted to migrate your database to a format capable of supporting the features of the latest version of the app. This article covers the database migration required to sync with OmniFocus 3 for iOS, as well as other database migrations that may not be immediately required (for example, the type of migration that you might encounter after updating your Mac to OmniFocus 2.6).

Syncing OmniFocus 3 with Previous Versions of OmniFocus

If you’ve previously set up sync in OmniFocus, OmniFocus 3 will perform a compatibility check the first time it syncs with your existing OmniFocus database. In order to offer new features, faster performance, and stronger security, OmniFocus 3 uses an upgraded database format, and other clients that sync with OmniFocus 3 must be able to read this database format. OmniFocus 3 is sync-compatible with OmniFocus 2.12.2 for Mac and OmniFocus 2.22.3 for iOS (OmniFocus 2.12 for Mac requires macOS 10.12; OmniFocus 2.22.3 for iOS requires iOS 11.3).

If all versions of OmniFocus syncing with your database are up to date, but your database has not yet been migrated to the newest format, OmniFocus 3 will prompt you to migrate your database after it attempts to sync for the first time. Simply tap Migrate Database to begin syncing with OmniFocus 3:

If OmniFocus 3 detects that older versions of OmniFocus are currently syncing with your OmniFocus database, it will present an alert that lists each incompatible client connected to your database (compatible clients syncing with your database will not be listed):

In order to begin syncing data with OmniFocus 3, incompatible clients must be either updated or disconnected. Tap the name of the device to learn more about the available options for the version of OmniFocus installed on it:

OmniFocus 2 clients syncing with your OmniFocus database should be updated to the most recent version of OmniFocus 2 before proceeding. Alternatively, you can choose to temporarily “disconnect” the OmniFocus 2 client from your sync database. However, if you choose to disconnect the client, OmniFocus will not be able to sync with that device again until it has been updated to the most recent version of OmniFocus. As there are no versions of OmniFocus 1 that are compatible with the new database format, the only option available is to disconnect the client:

OmniFocus 3 will detect when all versions of OmniFocus have either been updated to a compatible version or disconnected, and offer to migrate your database:

If you have questions about migrating your database in order to sync with OmniFocus 3, our Support team would be happy to help out! Feel free to drop an email our way or give us a call at 1 (800) 315-6664 or 1 (206) 523-4152.

Other Database Migrations

Some OmniFocus updates may prompt you to migrate your database in order to support the introduction of new features or enhancements in the future. Unlike the database migration that is required to sync with OmniFocus 3, these database migrations can be deferred.

OmniFocus observes which other copies of the app you are using to sync your database, and shortly after all of your devices with OmniFocus have updated to a version compatible with the new database format, the Migration window gives the green light to make the transition to the new database format. Here’s an example of the type of Migration prompt you may see, from our first database format change in OmniFocus 2.6 for Mac and OmniFocus 2.15 for iOS, which added support for end-to-end encryption:

Choose Migrate Database, and voilà! OmniFocus syncs your database in the new format to all of your devices. If you choose Later on the Mac, or dismiss the prompt with Done on iOS, you’ll be prompted to migrate again in one day. Alternatively, if you dismissed the prompt but later change your mind, or if you don’t want to wait to be prompted to migrate, you can use Migrate Database… from the OmniFocus for Mac File menu item or OmniFocus for iOS Settings to migrate sooner.

If you have some older versions of OmniFocus that need to be updated or disconnected from sync before you can migrate, OmniFocus will let you know about that as well. If you aren’t able to update some older devices, that’s okay—learn more here.

If you’d like to see which devices OmniFocus thinks are ready and which need to be updated or disconnected, choose Migrate Database from the OmniFocus File menu item (macOS) or from OmniFocus Settings (iOS). If this goes straight to the Migration prompt, that means you’re ready to Migrate and can proceed without updating any other devices.

Disconnecting Older Versions

OmniFocus will let you know if you have old versions of OmniFocus that need to be removed from syncing before you can migrate. This might include older copies of OmniFocus that were installed on a device that you’ve since updated. If you’ve verified that OmniFocus has been updated but an old entry is still showing up for that device during migration, it’s safe to manually remove the entry. All versions of OmniFocus include a list of clients, where these stale entries may appear as duplicates:

• On Mac, there’s a Show Clients button at the bottom of the Migration window–this button opens the Sync Devices sheet, where you can select duplicate entries and remove them using the Unregister button. The entry for the current device (the one you shouldn’t remove) appears in bold.
• On iOS, go to OmniFocus Settings > Registered Devices, and use the Edit button or swipe duplicate entries to unregister them. The entry for the current device (again, the one you shouldn’t remove) appears in purple.

Reverting

If you want to stop using the new format for some reason, you’ll need to restore a backup from before you migrated.

What happens if I decline the prompt, and don’t migrate to a newer database format?

If you’re still syncing with an older version of OmniFocus on any of your devices, and can’t install the latest OS to update to the latest version, don’t worry! You can decline the migration prompt to continue syncing the latest versions with older clients. Doing so means you won’t be able to take advantage of features that rely on the new database format (such as database encryption, or optimized attachment storage), but the rest of OmniFocus’s features that you’re already used to will still be available to you. Eventually, you may be required to migrate your database in order to sync with brand new versions of OmniFocus (like OmniFocus 3 for iOS).

The reason why OmniFocus asks if you want to migrate—instead of doing so automatically—is because we don’t want to create a situation where you have to stop using an older client on any older devices that can’t run the latest versions of macOS or iOS. We’ve designed our OmniFocus updates so that users with different OS requirements can decline migration prompts to a new database format, and maintain compatibility with older devices.

Installing subsequent updates of OmniFocus on some devices but not others won’t affect the database format, or otherwise break sync with your older clients, for as long as you continue using the older sync clients. If you go an extended period of time without syncing an older client, OmniFocus might interpret that as a sign that you’re no longer using that device, and may offer to migrate again. As long as you plan to continue using older clients, you can decline that offer. This process is designed to never let the migration happen on an existing database, unless you choose to allow it.