User Guide

A walkthrough of Titan Command from an operator's seat — what you'll actually see and click. For how the system works under the hood, see the Architecture page.

Roles

• Admin — everything, including deleting configurations and clearing destination data.
• Operator — day-to-day work: create/edit configurations, run migrations, manage Auto Sync, run the copy/repair tools.
• Viewer — read-only: browse history and progress, but most action buttons are hidden or disabled.

Your role and username appear top-right in the navbar, with a color-coded badge (Admin = red, Operator = blue, Viewer = gray).

Logging in

Sign in with your email and password, then enter the 6-digit code from your authenticator app. Sessions renew themselves silently while you're active — you won't be asked to re-authenticate mid-task, but a long period of inactivity (or a revoked account) will sign you out and send you back to the login page.

First-time setup

If no database configuration is active yet, the Home page shows a warning banner with a "Create Configuration Now" button. A configuration is a named pair of connections — source (QDB) and destination (QDG) — with host, port, database name, username, and password for each side. On the Create page, use "Test Source Connection" / "Test Destination Connection" before saving to confirm the credentials actually work. Once saved, go to the Configuration list and click Set Active — the active configuration drives the migration wizard, Auto Sync, and every tool in the app.

Running a migration

The wizard is five steps, always reachable via Migrate → New Migration in the navbar.

Step 1 — Table Selection

A searchable, sortable checklist of every source table with its row count. Use Select All / Deselect All, or check tables individually — a live counter shows how many tables and total rows you've selected. Next stays disabled until you've picked at least one table.

Step 2 — Schema Import

Upload an Excel file describing source→destination column mappings. If one was already saved for this configuration, you'll see a green banner and a one-click "Use Saved Schema & Continue" button instead of needing to re-upload. A side panel shows which of your selected tables are mapped in the file and which will fall back to a 1:1 (same-name) mapping.

Step 3 — Review Mappings

One card per selected table. Tables found in the Excel file show their column mappings in an editable table — tick Include to keep a column, edit Destination Column to rename it (renamed columns get a highlighted border with a "renamed from X" note). Tables not found in the file are marked "1:1 auto-mapping" and need no action. Watch for typos in destination column names — a mismatch here causes an "Unknown column" error during the actual run.

Step 4 — Relationship Config

Four tabs:

• Migration Order — the order tables will be migrated in (parents before children). Use the up/down arrows to override it if needed; a warning appears if a circular dependency is detected.
• Custom FK — manually link a destination column to a parent table/column, for relationships the tool couldn't detect automatically.
• Detected FK — read-only list of foreign keys found on the real source database.
• Column Config — per table, tick Skip Copy to leave a column out, or Drop Column to exclude it from the destination entirely (a confirmation dialog lists everything you're about to permanently exclude before it takes effect; primary/foreign key columns can't be dropped).

Step 5 — Configure & Run

Choose a Run Mode: Insert (the normal path — copy new records) or Patch FK Values (only updates NULL foreign keys on rows already migrated in a previous run; no new inserts). For each table you can set a custom ORDER BY, a day-by-day chunking column (for very large date-ranged tables), and a filter — either a quick preset (All rows / Latest 100–5000 / First 100) or your own WHERE clause, with a Test button to preview the resulting row count before running. If a table has prior migration history, you'll see how many rows were already copied, and can Reset that table's history alone if you need to re-run it from scratch (this risks duplicate rows unless you also clear the destination table). Click Start Migration (labeled Patch FK Values in Patch mode) to begin.

Progress

A live dashboard: an overall progress bar (tables completed / elapsed time), a sub-progress bar for the table currently running, five stat tiles (success rows, skipped rows, errors, status, speed), a per-table status table, and a scrolling activity log. A red Stop button cancels the run; once it finishes, View Results and Home buttons appear.

Results

Success/failure summary, four stat tiles (duration, tables completed, rows copied, errors), and a full per-table breakdown. If anything errored, an expandable Error Log shows exactly which rows failed and why. Below that are four follow-up tools:

• Sync ID Mappings to Destination — pushes the local SQLite ID mappings for this run into the destination's own config_id_mappings table (needed so later migrations/sync runs can resolve foreign keys against rows migrated in this session).
• Reset Migration History — clear history for selected tables, or everything, if you need a clean re-run.
• Backfill NULL Foreign Keys — a two-step flow: Find Matches searches for manually-added destination rows using natural-key matching, then takes you to a review page where you confirm or reject each candidate match before Run Backfill Now actually applies them.
• Repair Boolean Columns — one-click fix for a known historical issue where boolean flag columns from the source ended up stuck at 0 in the destination.

Migration History

Migrate → Migration History lists every session. Six stat cards double as filters (Total, Draft, Ready, Running, Completed, Failed) — click one to filter the list, and use the sort controls to reorder it. Each row links to whatever makes sense for its status: Progress if it's running, Results if it's finished, Edit if it's still a draft awaiting setup, or Delete for drafts you no longer need.

Auto Sync (recurring jobs)

Reachable via Tools → Auto Sync. This is for tables you want kept up to date automatically rather than migrated once.

• Create a job — name it, pick a configuration, choose which tables to include and their interval (minutes between runs).
• Enable/disable — a toggle switch on the job list; runs stop firing when disabled.
• Run Now — triggers an immediate run outside the schedule. The button waits until the new run actually has a session before reloading the page, so you don't briefly see stale info from the previous run.
• View Progress / View Last Run Results — while a job is running this links into the same Progress page the wizard uses; once idle it links to Results instead. There's no separate Auto-Sync-specific progress page.
• Preview — see a job's column mappings and detected foreign keys without actually running it.
• Delete — removes the job and its table configuration.

The navbar also shows a live Sync status badge (top-right, refreshing every 30 seconds) that turns amber/red if any job is currently syncing or has errored.

Barrier Trials / Sectional copy

Two dedicated tools, reachable from their own navbar dropdowns, each following the same shape as the main wizard but for one fixed source→destination table set: Preview your Excel mapping → Start the copy → watch Progress. Each also has its own Auto Sync tab (same enable/interval/Run Now pattern as the general Auto Sync feature, just scoped to that one table set) and a Clear Data option (Admin only) to truncate the destination tables and start over.

Discipline Repair

A standalone admin/operator tool (navbar: Discipline Repair) that fixes jockey/trainer rows that got copied without their discipline (thoroughbred/harness/greyhound) set correctly — it recovers the right value by checking which race/run rows still reference them. Click Start, then watch it work on the same kind of Progress page as everything else.

Meeting Compare

Meeting Compare in the navbar lets you look up a meeting by its source or destination ID and see a side-by-side comparison. Click through to a meeting's races, and from a race into its runners, to spot-check that a specific piece of data actually migrated correctly.

Where things live in the navbar

• Migrate — New Migration (wizard) · Migration History
• Tools — Auto Sync (SQL Query and Backup are shown but not yet available)
• Meeting Compare — standalone link
• Sectional / Barrier Trials — each with Copy and Auto Sync sub-items
• Discipline Repair — standalone link
• Configuration — manage source/destination connection profiles
• Verification Report — opens an external reporting tool in a new tab

Top-right: live Sync status badge, your username with role badge, and Logout.