Advanced CoreData: debug and query the underlying SQLite data

Photo by Tobias Fischer on Unsplash

Maybe you have an app that handles complex data, maybe you are taking over an app developed by someone else. Either way, trying to debug CoreData issues in your app can sometimes feel like a guessing-game.

But if you suspect some sort of data-related issue, you have several tools at your disposal:

• You can enable the SQL debugging flag to get more insight into what’s happening
• You can use a 3rd party SQLite GUI to get visual overview of how your database and its contents look like (for iOS in Simulator or for macOS apps)

Let’s take a look at these in detail…

Enable SQL debugging

Unless you configured it otherwise, CoreData will use an SQLite database to store your app’s data. Any CRUD operations you perform through the CoreData API will be converted to SQL statements and will run on this database.

But by default Xcode will not give us any info about what is actually happening under the hood. This is where SQL debugging comes to the rescue — to enable it:

1. Open Product > Scheme > Edit Scheme > Run > Arguments
2. Add -com.apple.CoreData.SQLDebug 1 argument in "Arguments Passed on launch"

Enable CoreData’s SQL Debugging feature

Once enabled, you’ll get a lot of helpful information — everything from SQL queries, to fetch times, etc. (so you may also want to remember to turn it off once you’re done debugging :)).

Log output with SQL Debugging on

Open and query the SQLite database

If you are running your app in Simulator (or on your Mac or a macOS app), you can open up the database with an SQLite client to get more insight into what data is stored there.

Among the many SQL debugging log messages (once enabled — see above) you should also see something like this:

CoreData: annotation: Connecting to sqlite database file at “/Users/****/Library/Developer/CoreSimulator/Devices/****/data/Containers/Shared/AppGroup/****/AppName.sqlite”

…of course the actual path will vary widely, depending on the specific setup. But nevertheless you can use this path to open the SQLite file in your favorite client.

I would recommend a GUI, either the free DB Browser for SQLite or a commercial one like JetBrain’s DataGrip or Navicat for SQLite.

Next, open up the SQLite file based on the path shown in your client.

Tip: with DB Browser for SQLite installed, you can simply issue an open command in Terminal to quickly open the file:
open /Copied/Full/Path/To/AppName.sqlite

Now you can browse the structure, data, and execute SQL commands as you wish:

Yeah, this GUI won’t win any design awards, but it does the job and it’s free…

Modifying your database

Of course you can also issue UPDATE statements (or use the GUI) to edit the underlying data.

Tip: depending on the client you’ll likely need to separately save the database (“Write Changes” in DB Browser)

While good for testing certain situations, externally modifying the SQLite database (especially when it comes to schema/structural changes) can lead to unexpected behavior in your app. Tread carefully!