Technical Note TN2241

Migrating to CloudKit

This document covers information on how to migrate data to CloudKit.

What can I migrate?
How do I migrate?
What will it cost?
Migrating public non-user content
Migrating user-specific content
Document Revision History


CloudKit powers some of the most popular apps in iOS and OS X. It is designed to help you get started on your app quickly and scale with you as your user base grows.

Before reading this document make sure to read the CloudKit Quick Start and Designing for CloudKit as they walk through core concepts and how to get set up.

What can I migrate?

Some of the high-level features that CloudKit provides are:

How do I migrate?

In order to migrate data into CloudKit, there are two main points to consider:

Table 1  Public and Private Data

public data

private data


Public DB, server-side migration



Private DB, client-side migration

Private DB, client-side migration

In the case of public non-user-specific data, you can use a server-side application to migrate the data, but in the case of private user-specific data you will need to migrate that data from your client application (iOS, OS X, or web). To understand more about why, make sure to read about public and private databases.

What will it cost?

Any data stored in a user's private database counts against their personal iCloud quota whereas data stored in your container's public database counts towards your container's public usage. CloudKit provides up to 1TB of public storage and data transfer that scales with the number of users you have and to find out more, visit iCloud for Developers page.

Migrating public non-user content

To migrate public data that doesn't need to be attached to any specific user, the easiest path is probably to build a server-side application that migrates the data. Here is the recommended approach:

  1. Use the CloudKit Dashboard to:

    1. Configure your schema to support the type of data you will be storing.

    2. Set up a Server-to-Server Key to allow your application to write data into the public database.

  2. Build a node.js application using CloudKit.js that does the following (likely in batches):

    1. Read the public data from your existing data source.

    2. Write that data into CloudKit.

Migrating user-specific content

As mentioned above, you won't be able to migrate user-specific data using a server-side application and instead will need to do so after a user has logged in to your client application (iOS, OS X, or web).


When a user uses your client application to write data to CloudKit it is marked as written by that user. This is often important for controlling who can read and write specific records. On top of this, CloudKit provides you the ability to store a user's private data into their private database so that no other users can access it.

To take advantage of both of these things, your user will need to be signed in with their Apple ID. You can read more about how to do this in the native API, the web services API, and CloudKit.js. On iOS and OS X, once a user is signed in to their Apple ID, they are automatically authenticated so you won't need to prompt them to sign into your app. Because you are migrating a user's data from an existing data source, it's likely that they will also need to be simultaneously logged in with your existing authentication service.

Organizing data in custom zones

When storing data in a user's private database, you have the option of storing related data in a custom zone, giving you the ability to later ask the server for the set of changes in that zone since a certain point in time. To read more, see the CKRecordZone and CKFetchRecordChangesOperation documentation, but consider using zones when migrating your data.

Writing the data to CloudKit

The CloudKit APIs provide various ways to write data and we recommend that you consider the following mechanisms:

  1. Native API

  2. Web Services API

  3. CloudKit.js

    CloudKit.js is a JavaScript wrapper around the web services API.

Document Revision History


New document that covers information on how to migrate your data to CloudKit.