Cloud Database Basics
Please make sure you know about and have already configured your
SKYContainer before you proceed.
You can follow the steps in Setup Skygear to set it up.
The Record Class
SKYRecord is the data storage unit in Skygear.
SKYRecordmust have a type.
SKYRecordobject is like a dictionary with keys and values; keys will be mapped to database column names, and values will be stored appropriately based on the data type. Please refer to Data Type for more information.
SKYRecordwill be owned by the currently logged in user.
SKYRecordobject has a unique
id(a string combination of record type and uuid is used).
recordType, which describes the type of data this record holds.
SKYRecordhas reserved keys that cannot be used, such as
recordType. Please refer to Reserved Columns section for more.
A record can store whatever values that are JSON-serializable. Possible values include strings, numbers, booleans, dates, and several other custom types that Skygear supports.
SKYDatabase is the central hub of data storage in
SKYKit. The main responsibility of database is to store
You will be provided with a private and a public database.
- Everything in the private database is truly private, regardless of what access control entity you set to the record. In other words, each user has his own private database, and only himself have access to it.
- Record saved at public database is by default public. Only the owner of the record can modify the record. Even without logging in, records in the public database can be queried (but not updated). To control the access, you may set different access control entity to the record. However, only logged in user can do write operation on databases
- The database objects can be accessed with
[[SKYContainer defaultContainer] publicCloudDatabase]and
[[SKYContainer defaultContainer] privateCloudDatabase].
Head to Access Control to read more about it.
Creating a record
Let's imagine we are writing a To-Do app with Skygear. When user creates an to-do item, we want to save that item on server. We probably will save that to-do item like this:
There are couples of things we have done here:
- First we created a
todorecord and assigned some attributes to it. you can use the
subscript operator as shown above, or the
setObject:forKey:method. Your app automatically creates this Class when you first use it.
- We fetched the container of our app, and took a reference to the private database of the current user. So when you save a record, you're saving the record to the private database of the current user.
- We actually saved the
todorecord and registered a block to be executed after the action is done. When you have successfully saved a record, there are several fields automatically filled in for you, such as
SKYRecordwill be returned and you can make use of the block to add additional logic which will run after the save completes.
You can also save multiple
SKYRecords at once:
Reading a record
recordID we could also fetch the record from a database:
In Objective-C, to get the values out of the
SKYRecord, you can use the
 subscript operator as shown above, or the
NSString *title = [record objectForKey: @"title"]; NSNumber *order = [record objectForKey: @"order"]; NSNumber *done = [record objectForKey: @"done"];
You can construct a
SKYQuery object by providing a
recordType. You can configure the
SKYQuery by mutating its state. Read the Query section to learn more.
Updating a record
Now let's return to our to-do item example. This is how you save a
After you have successfully saved the
SKYRecord, the server will return an updated
SKYRecord. Your console should look like this:
2015-09-22 16:16:37.893 todoapp[89631:1349388] saved todo with recordID = <SKYRecordID: 0x7ff93ac37940; recordType = todo, recordName = 369067DC-BDBC-49D5-A6A2-D83061D83BFC>
As you can see, the returned
SKYRecord now has a
recordID property on your saved todo
SKYRecord is a unique
recordID which identifies the record in a database.
recordID you can modify the record later on. Say if
you have to mark this todo as done:
Note that the data in the returned record in the completion block may be
different from the originally saved record. This is because additional
fields maybe applied on the server side when the record is saved (e.g. the updated
modificationDate). You may want to inspect the returned record for any changes applied on the server side.
Deleting a record
Deleting a record requires its
If you are to delete records in batch, you could also use the
You can also delete multiple records at once:
For each record type stored in the database, a table with the same name as the record type is created. For example, if your record type is called
note, there is a table called
note in the database. Each row in the table corresponds to one record.
For each record table there exists two types of columns, those that are reserved by Skygear and those that are user-defined. Reserved columns contain metadata of a record, such as record ID, record owner and creation time. Names of reserved columns are prefixed with underscore (
It is possible to manipulate data in record tables directly. However, one should exercise cautions when modifying data directly in record tables.
Each record table contains the following reserved columns:
|Column Name||Object Attribute||Description|
You can retrieve the values from the object by accessing its properties:
Please head to Database Schema to read more about Reserved Columns, Record Tables and Reserved Tables.
Local Storage (Offline)
Record storage relies on Query
SKYContainerDelegate to your controller.