Add a way to fully initialize the CloudKit Development schema

[W1W1-M]

Hello,

Before promoting the CloudKit schema from Development to Production, it's hard to be sure every column has a field. Core Data offers NSPersistentCloudKitContainer.initializeCloudKitSchema(options:) for this; SwiftData apps can use it through a temporary Core Data container. SQLiteData has nothing equivalent yet. In smaller apps this is generally not a problem because everything can be easily/quickly tested and then gets synced without too much worry. As apps become bigger and more complexe there is more risk of a field not being synced a least once before dev schema is promoted to production.

Why testing one record per table isn't enough

CloudKit Development only creates a field when a record is saved with a non-nil value for it. When a column is nil, CKRecord.removeValue(forKey:at:) (CloudKit+StructuredQueries.swift) writes only the sqlitedata_icloud_userModificationTime_<column> companion. It never writes the value field, or <column>_hash for BLOB columns. So a record type can exist in Development while some optional columns have no field. After deploying, the first save in Production that sets one of those columns fails. Uploading a blank record per table wouldn't help, because a blank record leaves every optional column nil.

In my app, estimatedValueCurrencyCode, latitude/longitude, and a couple of optional BLOBs were never set during testing. I only noticed because I went looking.

Why the library is the right place for this

The placeholder values have to produce the same CloudKit field types that real saves produce. For example, a Date stored as TEXT becomes a timestamp field, and UUID, Bool and BLOB columns each have their own encoding. App code can only get this right by inserting real rows through the models. I do that today with a DEBUG helper that inserts one fully populated row per table, sends, then deletes. It has to be updated by hand whenever a column is added. SQLiteData already knows each table's writableColumns and their bindings, so it could do this generically.

Possible shape

• try await syncEngine.initializeCloudKitSchema(), DEBUG / Development only. For each synced table it would upload a record with every field set (assets included), then delete it. Optionally it would also create and delete a share, so cloudkit.share exists for apps that use sharing.
• A dry-run or print option that lists the record types and fields SQLiteData expects, so developers can diff it against xcrun cktool export-schema.

Thanks for any feedback and also considering this!

PS : written by me with the help of Claude

[mbrandonw]

Hey @W1W1-M, thanks for bringing this up. I have actually attempted this tool in the past but got mired in some details. We definitely should try it again. A few questions:

• Optionally it would also create and delete a share, so cloudkit.share exists for apps that use sharing.

This is the first I've heard of needing to prime shares in CloudKit. What does this accomplish?

xcrun cktool export-schema

This is also the first time I've heard of this tool. Do you have any example of what the output looks like?

[W1W1-M]

Hey @W1W1-M, thanks for bringing this up. I have actually attempted this tool in the past but got mired in some details. We definitely should try it again. A few questions:

Ah interesting, sorry if this turns into a rabbit hole 😄

• Optionally it would also create and delete a share, so cloudkit.share exists for apps that use sharing.

This is the first I've heard of needing to prime shares in CloudKit. What does this accomplish?

Yes, this might be overkill, doesn't need priming and could be part of other tests dedicated to making sure iCloud sharing works in your app. From what I understand a cloudKit.share record type does get created if sharing is correctly setup, so it could potentially be checked on if your approach things from a database point of view. I agree this is probably out of scope for this discussion.

xcrun cktool export-schema

This is also the first time I've heard of this tool. Do you have any example of what the output looks like?

I found this here: https://developer.apple.com/icloud/ck-tool/
I believe using this cktool export-schema is pretty much the same as doing Export Schema from the CloudKit web dashboard. Here is an extract of the .ckdb file obtained from export schema for one of my apps:

DEFINE SCHEMA

    RECORD TYPE Users (
        "___createTime" TIMESTAMP,
        "___createdBy"  REFERENCE,
        "___etag"       STRING,
        "___modTime"    TIMESTAMP,
        "___modifiedBy" REFERENCE,
        "___recordID"   REFERENCE,
        roles           LIST<INT64>,
        GRANT WRITE TO "_creator",
        GRANT READ TO "_world"
    );

    RECORD TYPE brands (
        "___createTime"                                     TIMESTAMP,
        "___createdBy"                                      REFERENCE,
        "___etag"                                           STRING,
        "___modTime"                                        TIMESTAMP,
        "___modifiedBy"                                     REFERENCE,
        "___recordID"                                       REFERENCE,
        dateArchived                                        ENCRYPTED TIMESTAMP,
        dateCreated                                         ENCRYPTED TIMESTAMP,
        dateModified                                        ENCRYPTED TIMESTAMP,
        description                                         ENCRYPTED STRING,
        id                                                  ENCRYPTED STRING,
        label                                               ENCRYPTED STRING,
        sqlitedata_icloud_userModificationTime              ENCRYPTED INT64,
        sqlitedata_icloud_userModificationTime_dateArchived ENCRYPTED INT64,
        sqlitedata_icloud_userModificationTime_dateCreated  ENCRYPTED INT64,
        sqlitedata_icloud_userModificationTime_dateModified ENCRYPTED INT64,
        sqlitedata_icloud_userModificationTime_description  ENCRYPTED INT64,
        sqlitedata_icloud_userModificationTime_id           ENCRYPTED INT64,
        sqlitedata_icloud_userModificationTime_label        ENCRYPTED INT64,
        GRANT WRITE TO "_creator",
        GRANT CREATE TO "_icloud",
        GRANT READ TO "_world"
    );

    RECORD TYPE "cloudkit.share" (
        "___createTime"               TIMESTAMP,
        "___createdBy"                REFERENCE,
        "___etag"                     STRING,
        "___modTime"                  TIMESTAMP,
        "___modifiedBy"               REFERENCE,
        "___recordID"                 REFERENCE,
        "cloudkit.thumbnailImageData" BYTES,
        "cloudkit.title"              STRING,
        "cloudkit.type"               STRING,
        GRANT WRITE TO "_creator",
        GRANT CREATE TO "_icloud",
        GRANT READ TO "_world"
    );

Users and cloudkit.share are system generated record types. brands is a record type for one of my business objects.

I'm happy to help move things forward, test, etc.