Codebook Sync Operations

Codebook's Sync feature in standard operation will exchange all changes with another device or cloud service. When there are conflicts (two records that were both changed on two different devices), the most recent change is accepted as authoritative. However, there are some scenarios where it can be useful to change how Sync operates. This can be done by displaying the Operations menu and selecting a different operation to perform on the next sync.

Note: Changing how Sync operates is a potentially destructive operation. Please contact our support team before using this feature.

The available operations are:

  • Sync (the standard exchange mode)
  • Overwrite
  • Restore
  • Merge

We use the following terms to assist in the discussion that follows:

  • Local – The copy of Codebook invoking the Sync operation.
  • Local Database – The strip.db file that is the main database for the local Codebook instance.
  • Remote – The cloud or WiFi service on the other end of the Sync operation.

This is the standard Codebook exchange operation, where previously unseen Local and Remote changes are exchanged and applied accordingly.

The purpose of the Overwrite operation is to wipe the data from a Remote and re-establish a brand new changeset using the Local data as a baseline. This is intended to let a Local Codebook instance "replace" potentially corrupt or incorrect data in the Remote with Local's known-good data. During Overwrite, all data on the Remote is removed (although the Remote database structure and Sync Key are left in place during WiFi sync). The remote is then treated like a "new" Remote that Codebook hasn't synced with previously: all local data is written to a changeset and sent to the remote.

The purpose of the Restore operation is to purge a Local Database which contains some corrupted or incorrect data, replacing it with the known-good data on the Remote. All Local data (categories, entries, fields, and labels) is deleted from the tables of the Local Database along with all change tracking information (the database structure itself along with the Sync Key are retained). Changeset data from the Remote is then replayed on the Local Database, creating a new instance of everything that had been on the Remote.

Note: Because one side is essentially clearing out the data on the other, Overwrite and Restore should be used carefully to avoid unintentional data loss.

The Merge operation allows you to combine both the Local and Remote databases to create a new, consolidated set of records. Use of this operation requires you to choose either the Local or the Remote database as the primary authority for any conflicts Codebook cannot resolve on its own. For any records that are conflicted and have the same updated_at audit timestamp, the winner is chosen according to the user's choice of primary conflict authority (either Local, or Remote). For records that exist in both source databases with different updated_at fields, conflicts will be resolved by the standard conflict handler (last update wins).

An additional feature of the Merge operation is that it does not process any deletes that have not already been synced. In other words, merging two databases will not delete data that exists in only one of the databases.

The Operations menu is not displayed by default. To enable it:

On Android

  1. Launch Codebook and log in
  2. Tap on Home > Sync
  3. Long-press on the label "Sync" in the Navigation Bar to display the Operation row
  4. Tap on the Operation row to display the menu

    Hidden Operations option on Android Operations menu on Android Primary Data Source prompt

Tapping on the Merge operation causes Codebook to prompt you to choose a primary data source in the event there is a conflict Codebook cannot resolve automatically.

On iOS

  1. Launch Codebook and log in
  2. Tap More
  3. Tap Sync
  4. Long-press on the label "Sync" in the Navigation Bar to display the Operation row
  5. Tap on the Operation row to display the menu

Hidden Operations option on iOS Operations menu on iOS Primary Data Source prompt

Tapping on the Merge operation causes Codebook to prompt you to choose a primary data source in the event there is a conflict Codebook cannot resolve automatically.

On macOS

Note: The Operation option will not be displayed if your Sync method is set to Desktop WiFi. Select the operation on your mobile device instead.

  1. Launch Codebook and log in
  2. Click on Sync in the Menu Bar and hold down the Option key to display the Operations row
  3. Move the mouse to this row to display the sub-menu

Hidden Operations menu on macOS

Selecting one of the alternative operations causes Codebook for macOS to update the Start Sync menu item to reflect the new behavior.

Updated Start Sync menu item

Choosing the Merge menu item causes Codebook to prompt you to choose a primary data source in the event there is a conflict Codebook cannot resolve automatically.

Primary Data Source prompt

On Windows

Note: The Operation option will not be displayed if your Sync method is set to Desktop WiFi. Select the operation on your mobile device instead.

  1. Launch Codebook and log in
  2. Click on the Help menu > About

    Hidden Operations option on Windows

  3. Click 4 times on "Codebook". You will see (Debug Mode) appear next to the 'Codebook for Windows version number'.

    Hidden Operations option on Windows

  4. Close the About Codebook window
  5. Click on Sync menu -> Operation to display the sub-menu

    Operations menu on Windows

    Selecting one of the alternative operations causes Codebook to update the Start Sync menu item to reflect the new behavior.

    Operations menu on Windows

    Choosing the Merge menu item causes Codebook to prompt you to choose a primary data source in the event there is a conflict Codebook cannot resolve automatically.

    Primary Data Source prompt Windows

Note: After you complete one of the non-standard Operations (Overwrite, Restore, and Merge), Codebook will revert the currently selected operation back to the default Sync operation.