| workspace_connector_sync_log_id | string, UUID, 🔒 system | ✅ Yes | unique; generated by gen_random_uuid() at INSERT | — | Public stable identifier for this sync log row. Used in all API responses; the internal pk is never exposed. |
| status | string (ConnectorSyncStatusEnum) | ✅ Yes | DEFAULT ‘scheduled’; non-nullable; one of the four enum values | scheduled, in_progress, success, error | Current execution state of the sync run. Starts as SCHEDULED (or IN_PROGRESS when created by the service), transitions to SUCCESS or ERROR once the connector run completes. The sync orchestrator is the only writer. |
| trigger_type | string (SyncTriggerTypeEnum), nullable | ⚪ No | nullable; one of the three enum values when present | cloud_task, manual, oauth_callback | How the sync run was initiated. CLOUD_TASK = scheduled Cloud Tasks queue; MANUAL = user-initiated via UI or API; OAUTH_CALLBACK = triggered immediately after a successful OAuth authorization flow. |
| cloud_task_id | string, VARCHAR(255), nullable | ⚪ No | nullable; max 255 chars (cast from TEXT in Migration20260407100000) | — | The fully-qualified Cloud Tasks task name associated with this sync run when trigger_type is CLOUD_TASK. Null for manual and OAuth-callback triggers. Used for deduplication and traceability in the task queue. |
| started_at | datetime, nullable | ⚪ No | nullable; set by the orchestrator when actual processing begins (not at row creation for SCHEDULED status) | — | Timestamp when the sync run transitioned from SCHEDULED to IN_PROGRESS and connector API calls began. Null if the run was never picked up (e.g. task enqueued but not yet dispatched). |
| completed_at | datetime, nullable | ⚪ No | nullable; set atomically with duration_ms and the terminal status (SUCCESS or ERROR) | — | Timestamp when the sync run reached a terminal state. Null while the run is SCHEDULED or IN_PROGRESS. |
| duration_ms | integer, nullable | ⚪ No | nullable; integer; computed as completed_at - started_at in milliseconds by the repository markSuccess/markError helpers | — | Wall-clock duration of the sync run in milliseconds. Null when started_at is null (run never began) or while still in progress. Derived at finalisation time, not stored as a trigger. |
| error | string, TEXT, nullable | ⚪ No | nullable; no length limit; populated only when status = error | — | Human-readable error message or stringified exception captured when the sync run terminates with an ERROR status. Null on success. Used by the monitoring layer and displayed in the connector-status dashboard. |
| metadata | jsonb, nullable | ⚪ No | nullable; free-form JSONB object; no fixed schema enforced at the DB level | — | Provider-specific sync context written at completion. Common keys include records_synced, pages_fetched, connector_slug, and billing-related counts. Not queried by the platform for logic — observability and debugging only. |
| created_at | datetime, 🔒 system | ✅ Yes | set once on INSERT via MikroORM onCreate lifecycle hook; never updated | — | Row creation timestamp. Corresponds to when the sync was enqueued or initiated, which may precede started_at by a few seconds for CLOUD_TASK triggers. |
| updated_at | datetime, 🔒 system | ✅ Yes | set on INSERT and on every UPDATE via MikroORM onCreate/onUpdate lifecycle hooks | — | Last modification timestamp. Advances each time the sync orchestrator patches status, started_at, completed_at, duration_ms, error, or metadata. |
| deleted_at | datetime, nullable | ⚪ No | nullable; soft-delete convention; all queries must filter deleted_at IS NULL | — | Soft-delete timestamp. Null for active log rows. When set, the log is logically removed but retained for audit purposes. |
