A conduit for accessing and performing operations on the data of an app container.
SDKs
- iOS 8.0+
- macOS 10.10+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 3.0+
Framework
- Cloud
Kit
Declaration
class CKDatabase : NSObject
Overview
An app container has a public database whose data is accessible to all users and a private database whose data is accessible only to the current user. A database object takes requests for data and applies them to the appropriate part of the container.
You do not create database objects yourself, nor should you subclass CKDatabase
. Your app’s CKContainer
objects provide the CKDatabase
objects you use to access the associated data. Use database objects as-is to perform operations on data.
The public database is always available, regardless of whether the device has an active iCloud account. When no iCloud account is available, your app may fetch records and perform queries on the public database, but it may not save changes. (Saving records to the public database requires an active iCloud account to identify the owner of those records.) Access to the private database always requires an active iCloud account on the device.
Note
Interactions with CKDatabase
objects occur at a quality of service level of NSQuality
by default. For information about quality of service, see Prioritize Work with Quality of Service Classes in Energy Efficiency Guide for iOS Apps and Prioritize Work at the Task Level in Energy Efficiency Guide for Mac Apps.
Interacting with Database Objects
You interact with database objects as follows:
Assign a database object to an operation object when you want to fetch, save, delete, and query the contents of the database. The database object tells the operation object where to get the data. (Calling the
add(_:)
method of the database assigns that database to the operation object implicitly.)Use a database object’s convenience methods to fetch, save, delete, and query the contents of the database directly. The convenience methods act on only one item at a time.
Using Databases with Operation Objects
For operation objects that descend from the CKDatabase
class, specify the database object to use when executing the operation.
If you execute operations on your own custom queue, specify the database explicitly by assigning the appropriate
CKDatabase
object to the operation object’s database property.If you do not have your own queue, execute the operation object against a database implicitly by calling its
add(_:)
method.
Executing Tasks Against a Database Directly
The CKDatabase
class offers convenience methods for accessing records, record zones, and subscriptions without an operation object. The convenience methods allow you to fetch, save, or delete a single item asynchronously and process the results on a background thread. There is also a convenience method to search for records in the database.