Skip to main content

​
Quickstart Guide

This guide will walk you through freezing your first SwiftData schema with FreezeRay.

​
Prerequisites

  • Xcode 15.0+
  • Swift 5.9+
  • iOS 17+ or macOS 14+ project with SwiftData
  • Git repository (for tracking fixtures)
  • npm (for CLI installation)
  • Apple Silicon Mac (Intel users must build from source)

​
Install CLI

Install the FreezeRay CLI via npm: 
npm install -g @trinsicventures/freezeray
Verify installation: 
freezeray --version
The CLI automatically adds the FreezeRay Swift package to your project when you run freezeray init.

​
Initialize Your Project

Navigate to your Xcode project directory and run: 
cd YourProject
freezeray init
This will:
  • Add FreezeRay package dependency to your Package.swift
  • Create the FreezeRay/ directory structure
  • Set up .gitignore rules (if needed)

​
Annotate Your Schema

Add @FreezeSchema to your schema definition: 
import SwiftData
import FreezeRay

@FreezeSchema(version: "1.0.0")
enum AppSchemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)

    static var models: [any PersistentModel.Type] {
        [User.self]
    }

    @Model
    final class User {
        var name: String
        var email: String

        init(name: String, email: String) {
            self.name = name
            self.email = email
        }
    }
}

​
Freeze Your Schema

Run the freeze command: 
freezeray freeze 1.0.0
This will:
  1. Build your project
  2. Run tests in iOS Simulator
  3. Extract schema fixtures to FreezeRay/Fixtures/1.0.0/
  4. Generate validation tests in FreezeRay/Tests/

​
Verify the Freeze

Check that fixtures were created: 
ls FreezeRay/Fixtures/1.0.0/
You should see:
  • App-1_0_0.sqlite - SQLite database with schema
  • schema-1_0_0.json - JSON representation
  • export_metadata.txt - Metadata about the freeze

​
Commit the Fixtures

Commit the generated files to your repository: 
git add FreezeRay/
git commit -m "Freeze schema v1.0.0"
Always commit fixtures to your repository. They serve as the source of truth for schema validation.

​
Run Tests

The generated tests run automatically with your test suite: 
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 15'
The tests will:
  • Verify the schema hasn’t drifted from the frozen version
  • Validate that all models match the fixtures

​
Next Steps

Learn Core Concepts

Understand how FreezeRay works under the hood

Test Migrations

Learn how to test schema migrations between versions

CI Integration

Set up FreezeRay in your CI pipeline

CLI Reference

Explore all CLI commands and options