Core Data Lab

Tips and Tricks


Core Data Lab is an app to view and track the SQLite data of a Core Data app. It shows all entities, attributes and relationships conform the object model. The app includes tools to view, filter, edit and export data, to track data changes, to inspect the model, and more.

Core Data Lab is a project based app. All settings regarding selected database and object model combinations are stored in a project document file together with other settings like ad-hoc data filters.

Overview

To properly view the data inside a Core Data database, Core Data Lab needs the associated Core Data object model. This concerns a compiled object model with a .mom extension, not the object model file in your Xcode project. The compiled object model file is normally located in a sub folder ending with .momd in the Resources folder within an app bundle.

When Core Data generates a SQLite database based on the object model, the object model is also stored within the database as a cache. Core Data Lab can read this cached object model, but can also use the compiled object model file embedded in the app bundle.

How to setup a new project

There are several ways to make a new project in Core Data Lab:

The easiest way to start a new Core Data Lab project is by opening a Core Data SQLite database that contains a cached object model. This is nearly always the case when the database is saved by a recent Core Data framework version.

  • Choose File > Open Database… in the menu.
  • Select a SQLite based Core Data database in the open file dialog.
  • Confirm by clicking on the Select Database button.
  • The database will be checked for the existence of a cached object model. If present and valid, it will be used to load the rest of the database. A label Cached Core Data Object Model will be displayed in the status panel of the toolbar.

Please take note of the following:

  • Setting Allow usage of cached Core Data object model data in the Advanced section of the Core Data Lab Preferences must be enabled.
  • For this feature you need macOS 10.15 or newer.
  • A cached model may be out of date or miss some aspects of the model, such as Fetch Requests.

If you app concerns an iOS, iPadOS, watchOS or tvOS app which has been run in a simulator, you can make a new Core Data Lab project by simply selecting the database and app combination in the Simulator browser.

  • Choose File > New Project > Browse Simulators in the menu.
  • Select a device in the left panel of the Simulator browser.
  • Select an app and database combination in the right panel of the Simulator browser.
  • Confirm your selection by clicking on the Select button.
  • A new project will be opened based on the selected app and database.

After selecting a Core Data app, you can start a search action for matching databases.

  • Choose File > New Project > Select App… in the menu.
  • Select a Core Data app in the open file dialog.
  • Confirm by clicking on the Select App button.
  • Choose Project > Search Database in the menu.
  • The Search database dialog is being opened.
    • If this is the first time, an additional dialog is presented to select a default search path.
    • Otherwise the search dialog will start immediately to search for databases that match one of the Core Data object models in the selected app.
    • You can cancel the running search operation at any time, and select another search path by clicking on the Search Path button.
  • Select a database from the search results list and click on the Select Database button.

After selecting a Core Data object model, you can start a search action for matching databases.

  • Choose File > New Project > Select Model… in the menu.
  • Select a Core Data object model in the open file dialog. This concerns the compiled object model with a .mom extension, not the object model in your Xcode project. The compiled object model file is normally located in a sub folder ending with .momd of the Resources folder within an app bundle.
  • Confirm by clicking on the Select Model button.
  • Choose Project > Search Database in the menu.
  • The Search database dialog is being opened.
    • If this is the first time, an additional dialog is presented to select a default search path.
    • Otherwise the search dialog will start immediately to search for databases that match the selected Core Data object model.
    • You can cancel the running search operation at any time, and select another search path by clicking on the Search Path button.
  • Select a database from the search results list and click on the Select Database button.

After selecting a Core Data database, you can start a search action for matching apps.

  • Choose File > Select Database… in the menu.
  • Select a SQLite based Core Data database in the open file dialog.
  • Confirm by clicking on the Select Database button.
  • Choose Project > Search App in the menu.
  • The Search app dialog is being opened.
    • If this is the first time, an additional dialog is presented to select a default search path.
    • Otherwise the search dialog will start immediately to search for apps that matches the selected Core Data database.
    • You can cancel the running search operation at any time, and select another search path by clicking on the Search Path button.
  • Select an app from the search results list and click on the Select App button.

After selecting a database, you can manually select an app. Or vice versa.

  • Choose File > New Project > Select Database… in the menu.
  • Select a SQLite based Core Data database in the open file dialog.
  • Confirm by clicking on the Select Database button.
  • Choose Project > Select App in the menu.
  • Select a Core Data app in the open file dialog.
  • Confirm by clicking on the Select App button.
  • Core Data Lab will check whether the selected combination is compatible. A warning will be shown when this is not the case, otherwise the selected combination will be loaded in the project window.

After exporting the data of a Core Data app to an app container using the Devices and Simulators dialog in Xcode, you can use Core Data Lab to automatically open the database located in the container. App containers do have a .xcappdata extension and are described in Finder as 'Xcode Application Data Package'.

  • Choose File > Open Container… in the menu.
  • Select an app container in the open file dialog.
  • Confirm by clicking on the Open button.
  • When the container file contains one database, then it will be automatically selected and opened. In case of multiple databases a selection list will be presented. The selected database will be checked for the existence of a cached object model. If present and valid, it will be used to load the rest of the database. A label Cached Core Data Object Model will be displayed in the status panel of the toolbar.

Alternatively you can also open app containers directly in Finder by using the right-click context menu item Open with > Core Data Lab.

The most flexible way to start a new Core Data Lab project is by using the Project assistant.

  • Choose File > New Project > Project Assistant in the menu.
  • Follow the instructions.

After making a new project, you can always adjust all choices you made earlier in the Project assistant.

Sidebar

The sidebar on the left side of the document window shows the following item categories:

  • Entities: a Core Data object model always contains at least one or more entities.
  • Fetch Requests: this category is only shown when you have defined one or more fetch requests in the Core Data object model.
  • Saved Predicates: all predicates you have made and saved in Core Date Lab are listed here.

You can filter items in the sidebar by using the filter box at the bottom of the sidebar.

Grid view

The middle and main part of the Core Data Lab document window shows the data of the item selected in the sidebar, presented as a table grid view.

You can perform the following column adjustments on grid views:

  • The column position can be changed by dragging it to the desired position. To drag a column, click on the header and move the column while keeping the main mouse button pressed.
  • The column visibility can be changed to hidden by clicking on the Hide Column item of the right-click context menu of the column header. To make all columns visible again, click on context menu item Show All, or choose menu item View > Show All Columns.
  • The column sorting can be set by clicking on the column header that you want to sort. Click again to change the sorting direction. To remove the sorting, use the Remove Sorting context menu item of the header of the sorted column.

Column adjustment of the main grid are saved as part of the Core Data Lab project when working with stored predicates.

Relationships viewer

If the project consists of a valid database and object model, you'll see two sub panels at the lower side of the document window. The first sub panel shows data related to the selected row according to the selected relationship in the dropdown situated on top of the sub panel. With this dropdown you can switch to another relationship, if available.

Content viewer

If the project consists of a valid database and object model combination, you'll see two sub panels at the lower side of the document window. The second sub panel is a field level viewer. It shows only the content of one field of the selected row in the main grid view or a selected row in the relationship view. The dropdown on top of the content viewer let you switch to any field of the entity of the selected row. Default the first field is being shown. The content view automatically detects and shows web site URL's, image URL's, XML URL's, JSON URL's. In addition to this it also detects and show the content of binary fields containing images, XML, JSON or PLIST data.

Details view

The panel on the right side shows all fields of the selected row in one vertical column. If you have opened the database with a valid object model, you can also edit the data, unless you have opened the database as read-only. As soon as you have changed a field value, a Cancel and Save button pair will be shown at the bottom of the Details view panel. Clicking Cancel will revert all data changes, clicking Save will store all changes you have made for the selected data row.

Details window

If you want to edit the data of a row in a more spacious view, then you can open a row in a separate window or tab. Double-click a row to open the data in a window, or use the context menu of a selected row to open the data in a tab.

If an entity is selected in the sidebar, you can filter the related data by using the Predicate editor, which becomes visible after clicking on the filter button in the toolbar.

  • The first row in the predicate editor defines whether all, some or none of the conditions must be true. You may change this, but in most cases you need the default 'All' setting.
  • The second and up following rows in the middle panel of the Query editor consists of 2 or more rows, representing selection criteria and conditions:
    • Click on the + button on the right side to add a new condition row.
    • Click on the - button to remove a condition row.
    • The first drop down in the condition row is filled with selection criteria fields related to the selected entity. Make adjustments if needed.
    • The second drop down in the condition row is the operator that being applied to the selected criteria field. Adjust this if needed.
    • Depending on the selected operator, a third entry field is presented. Enter the criteria value that you want to use as a filter condition.
    • Apply the current combination of conditions rows to the current view by pressing Enter on the keyboard.
  • You can save a predicate by clicking on the Save button. This will also save the sorting of the table view, if you have changed this.

Anytime data is saved in a Core Data managed object context connected to a SQLite based persistent store, the related database files will change. These changes are monitored by Core Data Lab and can be used to track data changes.

  • Click on the Start button in the toolbar to start tracking data changes, or choose Data > Track Changes in the menu.
  • Data changes are displayed with distinctive background colors:
    • Mutated data is being presented with a purple background. Each tracked change will be presented in a separate row, changed data is being displayed with a dark font color, unchanged data with a grayed out font color.
    • Created data is being presented with a green background. Subsequence changes to a new data row are treated as data mutations, and do have a purple background.
    • Deleted data is being presented with a red background.
  • Tracking colors can be changed in the Colors section of the Core Data Lab Preferences.
  • All tracked data changes can be exported by using menu Data > Export to JSON or menu Data > Export to CSV.
  • Click on the Stop button in the toolbar to stop tracking data changes or choose Data > Stop Tracking in the menu.

The tracking feature is available when a standard entity is selected in the sidebar. The feature is not compatible with parent or child entities, predicates or read-only databases.

Edit existing data

Data of a selected row can be edited in the Details panel or a Details window, when the database is opened together with a valid Core Data object model.

Add new data

You can add new data objects for the selected entity by making use of menu item Data > New Object. To add a new related object to the currently selected parent object and relationship combination, choose Data > New Related Object in the menu.

Details view

The panel on the right side of the project window shows all fields of the selected row in one vertical column. As soon as you change a field value, a Cancel and Save button pair will be shown at the bottom of the Details view panel. Clicking Cancel will revert all data changes, clicking Save will store all changes you have made for the selected data row.

Details window

If you want to edit the data of a row in a more spacious view, then you can open a row in a separate window or tab. Double-click a row to open the data in a window, or use the context menu of a selected row to open the data in a tab.

Data can be exported to JSON or CSV format, if the project contains a valid database and object model combination. Follow these steps to export data:

  • To export all content of any item selected in the sidebar, or just the content of one selected row, choose Export to JSON or Export to CSV in the Data menu.
  • A dialog will be presented, to select a target file name.
  • When exporting to a JSON file, you have the option to include Relationship data. Including relationship data may lead to larger files and longer processing time.
  • When exporting to a CSV file, you can select a separator character. Make sure to select a character that can be handled by the target app you want to use.
  • Click on the Export button.

You can import files based on JSON or CSV format. Importing CSV requires macOS 12 or newer. Follow these steps to import data:

  • Select an entity in the sidebar.
  • Choose Import JSON or Import CSV in the Data menu.
  • An open file dialog will be presented, to select the file that must be imported.
  • When importing a JSON file, the import feature will include relationship data when present and correctly formatted within the file.
  • When importing a CSV file, you must select a separator character that is being used within the CSV file.
  • Click on the Import button.

The structure and formatting of the import file must be identical to the files exported by Core Data Lab:

  • Date values must be formatted as ISO 8601.
  • Data values must be encoded with Base64.
  • Relationship data must be added as an array related to the parent object, with the name of the relationship as key of the array data.

When importing CSV, make sure the file complies to these rules, in addition to the regular CSV rules:

  • The first row in a CSV file must contain the attribute names as defined in the Core Data model.
  • String type values must be enclosed by double quotes when the value contains new line or separator characters.
  • Null values must be represented as null.
  • Boolean type values must be represented as either true, false or null.

Entity metadata of a selected entity in the sidebar can be inspected via menu Data > Entity Description, or by simply double-clicking on the entity item in the sidebar.

Database metadata of the current Core Data SQLite database can be inspected via menu File > Store Metadata.

The settings of a project can be inspected via menu File > Project Settings. Or you can simply click on the status label located at the right side of the status bar in the middle of the toolbar.

The project settings dialog shows the full paths of the database and object model or related app, their reachability status and whether the combination is compatible.

In addition to this you can change the following settings:

  • Open as read-only: determines if the database must be opened in read-only mode or not.
  • Merge policy: determines the merge policy of the managed object context when editing data. Not available when the database is opened in read-only modus.
  • History tracking: if the database contains history tracking data, then you can enable NSPersistentHistoryTracking, which makes the database editable in Core Data Lab.

The following settings can be changed in the Preferences dialog, and apply to all projects:

General preferences

The File Access section shows access paths needed for the search forms and simulator browser. If needed you can change any path by clicking on the Change button.

  • Home directory: is being used by the Simulator browser.
  • App search directory: is being used by the App search form. This path also be changed in search form.
  • Database search directory: is being used by the Database search form. Can also be changed in the search form itself.

In the New Projects section you can change the default directory for saving new projects.

Files preferences
In the Database Extension section you can define which extensions will be supported for searching or opening database. To add support for extension-less databases, add a single point as extension.
If enabled, databases opened via one of the menu options or via Finder, will be opened as read-only. This setting does not effect databases that are being opened as part of a Core Data Lab project.
If enabled, only apps with a Core Data object model are selectable when using the file open dialog to select an app. This only works in the standard Application directory and the directory set as App search directory in the General section of the Core Data Lab Preferences.
Search preferences
In the App Search section you can fine tune settings that are used by the App search form:
  • Skip paths containing: this token field contains all paths segments that should be skipped when searching for an app for a selected database.
  • Skip hidden paths: when enabled, hidden paths will be skipped when searching for a matching app.
In the Database Search section you can fine tune settings that are used by the Database search form:
  • Skip paths containing: this token field contains all paths segments that should be skipped when searching for a database for a selected app or model.
  • Skip packages: when enabled, folders configured as packages will be skipped when searching for a matching database.
  • Skip hidden paths: when enabled, hidden paths will be skipped when searching for a matching database.
Colors preferences
This section lets you change the background colors that are used when tracking data changes.
Tables preferences
This section lets you change the alignment of numeric columns, and lets you set the default width of string and numeric columns.
This section lets you change the font size and styling of the table view grids, and whether tables should support multi-select.
Advanced preferences
Determines of cached Core Data object model data in a SQLite database may be used as object model in Core Data Lab.
When you run an iOS or iPadOS app in a simulator using Xcode, the paths to the app binary and app data changes each time you hit the run button. When you enable setting Auto repair simulator projects, the app and database paths are automatically corrected when you open the project. While the project is open, the paths remain valid because they are based on bookmarks.
Determines how tabbed detail windows are attached to an existing window:
  • Main document window: the tab is added to the document window.
  • First standalone window: the tab is added to the first standalone window. If there is no any standalone window, the tab is opened as a separate window.
  • Last standalone window: the tab is added to the last standalone window. If there is no any standalone window, the tab is opened as a separate window.