Backup & Recovery

Coincert provides multiple layers of data protection to ensure your financial data is never lost. From automatic safety snapshots to full data exports, you have complete control over your data’s safety.

Overview

Backups (Database Snapshots)

Backups create a point-in-time copy of your entire SwiftData database. Unlike exports, backups capture the raw database file and can be restored instantly without re-importing.

How Backups Work

Coincert uses SQLite’s VACUUM INTO command to create a clean, self-contained copy of the database while the app is running. This means:

• No data loss during backup — the app continues working normally while the snapshot is created.
• Complete capture — every account, transaction, budget, tag, category, debt plan, BNPL loan, rename rule, and learned pattern is included.
• Standalone files — each backup is a single database file with no dependencies on WAL or SHM journal files.

Creating a Backup

1. Navigate to Settings > Data > Backups.
2. Tap Create Backup Now.
3. Enter a label to identify this backup (e.g., “Before cleanup”, “Pre-import”, “Weekly backup”).
4. Tap Create.

The backup appears in the Snapshots list with its label, date, time, and file size.

Viewing Backups

The Backups screen lists all snapshots sorted newest first. Each entry shows:

• Label — the name you gave the backup
• Date and time — when the backup was created
• Size — the file size of the database snapshot

Restoring from a Backup

Restoring replaces your entire current database with the backup’s contents.

1. On the Backups screen, swipe left on the snapshot you want to restore (or long-press for the context menu).
2. Tap Restore.
3. Read the confirmation dialog carefully — restoring will replace ALL current data.
4. Tap Restore “[label]” to confirm.

What happens during restore:

1. A safety backup of your current data is automatically created (labeled “Auto-backup before restore”).
2. The current database files are removed.
3. The snapshot is copied into place as the new live database.
4. Harmony Sync state is reset so iCloud data will be re-fetched on next sync.
5. You are prompted to restart the app.

Important: You must restart the app after restoring. The SwiftData ModelContainer holds an open connection to the database file and cannot be swapped at runtime.

Deleting a Backup

Swipe left on a snapshot and tap Delete, or use the context menu. Deleted backups cannot be recovered.

Where Backups Are Stored

Backups are stored locally on your device in the App Group container:

Group Containers/group.com.coincert.app/
  Library/Application Support/
    Backups/
      2026-02-16_14-30-00/
        default.store       — database snapshot
        metadata.json       — label, date, size

Backups are NOT synced to iCloud. They exist only on the device where they were created. If you need a portable backup that can be transferred between devices, use the Full Backup export instead.

Auto-Backup

Coincert automatically creates a backup snapshot before any operation that could cause data loss. You do not need to do anything — this happens transparently.

When Auto-Backups Are Created

Auto-backups appear in the Backups list alongside your manual backups. You can restore from them the same way.

Auto-Backup Limits

Auto-backups are not automatically pruned. If you frequently reset sync or delete data, you may accumulate backups over time. Review and delete old backups periodically from the Backups screen.

Full Backup Export (JSON Dump)

The Full Backup export creates a portable file containing all your data in structured JSON format. Unlike database snapshots, this file can be read by other tools and transferred between devices.

What Is Exported

The Full Backup exports all 26 data types:

How to Export

1. Navigate to the Export screen (Dashboard toolbar or Settings > Data > Export).
2. Select Full Backup from the format picker.
3. Tap Export.
4. Choose where to save the file via the system share sheet.

File Format

The export produces a .coincert file (which is a renamed .zip archive). Inside it:

Coincert-Backup-2026-02-16.coincert
├── metadata.json           — app version, export date, format version
├── accounts.json           — all accounts
├── transactions.json       — all transactions
├── categories.json         — all categories
├── budgets.json            — all budgets
├── tags.json               — all tags
├── split_items.json        — all split items
├── recurring_rules.json    — all recurring rules
├── debt_plans.json         — all debt payoff plans
├── debt_items.json         — all debt items
├── bnpl_loans.json         — all BNPL loans
├── learned_rules.json      — all Auto-Tune rules
├── ... (one file per type)
└── conflict_logs.json      — sync conflict history

Each JSON file contains an array of records. Encrypted fields (amounts, payees, names) are exported in plaintext since the file lives on your local device. Fields are prefixed with _enc_ to indicate they are normally encrypted in iCloud.

Metadata

The metadata.json file contains:

{
  "appVersion": "0.8.1",
  "buildNumber": "95",
  "exportDate": "2026-02-16T14:30:00Z",
  "format": "coincert-json-v1"
}

Full Backup vs Database Snapshot

Fresh Start (TestFlight Only)

Fresh Start is a TestFlight-only feature that simulates a brand-new device experience. It is useful for testing the onboarding flow, initial sync behavior, and new-user experience without uninstalling the app.

How to Use Fresh Start

1. Navigate to Settings > Backstage (only visible in TestFlight and debug builds).
2. Toggle on Fresh Start on Next Launch.
3. Close and reopen the app.

What Happens on Launch

When the Fresh Start flag is set, the following sequence runs on the next app launch:

1. Auto-backup — a snapshot is created (labeled “Auto: before fresh start”) so you can recover your data.
2. Wipe local data — all SwiftData records are deleted from the local database.
3. Reset sync state — the Harmony Sync change token is cleared, pending changes are discarded, and sync status resets to idle.
4. Clear the flag — the Fresh Start toggle is turned off so it only runs once.
5. Normal initialization — the app starts as if on a new device. CKSyncEngine detects the existing CloudKit zone and begins downloading your data from iCloud.

Recovery

Since an auto-backup is created before the wipe, you can always restore your previous state:

1. Wait for iCloud sync to complete (your data should reappear from the cloud).
2. If anything is missing, go to Settings > Data > Backups and restore the “Auto: before fresh start” backup.

Availability

Fresh Start only appears in Backstage, which is visible in:

• TestFlight builds — for beta testers
• Debug builds — for development

It does not appear in App Store release builds.

Recovery Scenarios

”I accidentally deleted data”

1. Go to Settings > Data > Backups.
2. Find the most recent backup (or the auto-backup labeled “Auto: before nuclear delete”).
3. Restore from it and restart the app.

”Sync brought in bad data from another device”

1. Go to Settings > Data > Backups.
2. Restore from a backup created before the sync issue.
3. After restarting, go to Harmony Sync and use Push All Data to iCloud to overwrite iCloud with your restored data.

”I want to move my data to a new device”

1. On the old device, ensure Harmony Sync shows “Up to date”.
2. Optionally, create a Full Backup export as an extra safety net.
3. Install Coincert on the new device and sign in with the same iCloud account.
4. Harmony Sync will automatically download all your data.

”I want an offline archive of all my data”

1. Go to the Export screen.
2. Select Full Backup format.
3. Export and save the .coincert file to Files, iCloud Drive, or an external drive.

”Sync keeps failing after a reset”

1. Check if an auto-backup was created before the reset.
2. If Harmony Sync shows errors, check the Troubleshooting section in Harmony Sync.
3. If the sync zone was deleted, Coincert will automatically recreate it (up to 3 times per 24 hours to prevent loops).

Platform Differences