Scout Sync Engine Guide

The Scout Sync Engine is a robust synchronization system that manages bidirectional data flow between local SQLite storage and the remote Scout server. It handles hierarchical data relationships, batch operations, and provides resilient error handling.

Overview

The sync engine maintains a strict hierarchical sync order to preserve data integrity:

1. Sessions (parent entities)
2. Connectivity entries (children of sessions)
3. Events (children of sessions)
4. Operators (children of sessions)
5. Tags (children of events)
6. Artifacts (depend on sessions and devices)

This order ensures that parent entities are synced before their children, preventing foreign key constraint violations.

Health metrics are device-level and are not part of the sync engine hierarchy.

Key Features

• Batch Operations: Efficiently syncs multiple items in single requests
• Automatic ID Management: Handles local-to-remote ID mapping and relationship updates
• Partial Failure Recovery: Continues syncing other entities even if one type fails
• Configurable Batching: Control sync frequency and batch sizes

Local Model Versions

Every local table is keyed by its native_model version, so rows written by an older build sit in a separate table from the current one. Opening the database drains superseded event rows into the current table before the engine writes anything, keeping unsynced records visible across upgrades. A failed migration is logged rather than fatal: the engine still starts and the older rows stay on disk until the next attempt.