| name | add-synced-table |
| description | Walk through adding a new table to the open-mSupply server and wiring it into sync. Use when the user wants to "add a new table and make it sync", "make a table sync over v7", "integrate a table that already syncs in v5/v6 but isn't processed yet", or otherwise add/sync a server table. It loads sync-context, then follows the annotated reference guides (repository + migration, changelog, sync-style classification, legacy v5/v6 translation, V7 integration) with worked code, and ends with the verification commands. Trigger whenever a new synced table needs to be added on the server. |
| argument-hint | [v7 | v5v6 | <table-name>] |
Add a new table to the open-mSupply server and make it sync.
Arguments: $ARGUMENTS (optional — v7 for a brand-new V7-only table, v5v6 for a table that already syncs in central mSupply and needs integrating + V7, and/or the table name. If omitted, ask which scenario applies.)
Step 0: Load sync context first
Run the sync-context skill (or read its docs) before touching any code. Sync is one of the most consequential surfaces in the repo — bugs corrupt data on real sites. The reference guides below assume that context.
Step 1: Pick the scenario
There are two cases, and they share most of their work. Decide which applies (ask the user if unclear):
Scenario B is a superset of A (same repository layer + V7 bits) plus the legacy SyncTranslation. Both guides use a fictional widget table with full code for every file that changes.
Step 2: Work through the guide
Each guide has a TL;DR checklist table at the top, then a step-per-section walkthrough with the exact file paths and code. The layers, in order:
- Repository + migration —
CREATE TABLE (incl. the Postgres ALTER TYPE changelog_table_name ADD VALUE), the *_row.rs row struct + repository + Upsert/Delete impls, db_diesel/mod.rs wiring.
- Changelog — add the
ChangelogTableName variant, the generate_changelog impl (store-scoped RowOrId vs central id-string flavour), the sync_style.rs classification (authoring / distribution / transport: V5|V6|V5_V6), and the Row enum + fetch_rows_for_table arm in batch_query.rs (the V7 push path).
- Legacy v5/v6 translation (scenario B only) — a
SyncTranslation in service/src/sync/translations/, registered in all_translators(), with a test-data fixture. Note: table_name() must match central exactly; pull_dependencies() references the dependency translation's own table_name() (e.g. vec![StoreTranslation.table_name()]), not a string literal.
- V7 sync —
INTEGRATION_ORDER (FK order), serde.rs serialize/deserialize arms, and the translate_delete arm (if the table supports hard deletes).
- Re-sync for existing v7 sites (only if v7 sites already exist) — if the table is new in v7 (or you're turning on v7 coverage for an existing v5/v6 table) and sites are already running v7, their v7 pull cursor was seeded from the v6 position and will never re-pull the table's historic rows. Add a migration that seeds a
sync_request for the table so the sync_request_runner backfills it (from cursor 0) on the next tick. Use the shared helpers in repository/src/migrations/helpers.rs: guard with pull_has_started(connection) (skip fresh installs) then call seed_sync_request_for_table(connection, ChangelogTableName::Widget). Precedent: repository/src/migrations/v3_00_00/seed_sync_request_user_tables.rs. The guides cover the full migration file.
Lean on the compiler and the guards: the Row enum and the serde.rs / batch_query.rs matches are non-exhaustive on purpose, so a missing arm is a hard compile error; the integration_order_is_up_to_date test catches order/completeness/FK problems.
The sync_request mechanism (auxiliary/special sync, temporary cursor, reference_id-scoped buffer isolation) is specified in the Store re-syncs and Re-sync after a v7 migration sections of docs/content/docs/sync/v7/_index.md. Read those before touching auxiliary-sync code.
Step 3: Verify
From server/ (always cargo nextest run, never cargo test — see AGENT.md):
cd server
cargo nextest run integration_order
cargo nextest run sync_v7
cargo nextest run sync
cargo build --features postgres
Conventions reminder
- Prefer explaining what you'd change and confirming before editing non-trivial sync code, especially anything affecting the changelog row shape, sync-style classification, transport filters, or translator opt-ins.
- After changing
sync_style.rs, generate_changelog.rs, or translator opt-ins, regenerate the plain-English doc via the sync-styles-doc skill.
