Migration checklist

This is the on-the-day checklist that complements the per-source migration guide. Use it as a copy-paste into your launch ticket.

Before you start

• You have read the per-source guide (database, Algolia, Elasticsearch, Meilisearch, Typesense).
• You have an AACsearch organization, project, and at least one API key created — see API keys.
• Your schema is defined and reviewed (field names, types, query_by candidates, filter_by candidates, sort_by candidates).
• You have decided your tenant model: single index or per-tenant index. See Tenant isolation.
• You have decided your cutover model: dark-launch or rollback window. See Migration overview.
• You have at least 100 queries from your existing analytics to use as the validation sample.

Dry run

Do this in a staging project at least 48 hours before cutover.

• Create the AACsearch index in staging with the chosen schema.
• Run the export from the source system — measure how long it takes for the full corpus.
• Run the import into AACsearch — measure the ingest lag and the time to flush completely.
• Check searchIndex.getHealth.driftPercent is < 5 %.
• Run the 100-query validation. Categorize identical / mostly-same / drift.
• Triage drift cases: fix in schema (most common), in query_by_weights, or as curations.
• Run the dry-run again after fixes — drift count should drop.
• Document the time the full import took (you need this for the real cutover).

Validation

After the staging dry run, before flipping production traffic:

• Doc count check: source count(*) matches searchIndex.getHealth.actualDocCount.
• All 100 sample queries return results (none should be unexpectedly empty).
• Top-5 hits for at least 80 % of queries are stable across re-runs (no random ordering).
• Facet counts on a sample query match between staging and the source system within ±1 %.
• Filter queries (price < X, category = Y) return the same documents as the source.
• Sort queries (createdAt:desc) return documents in the same order as the source.
• Negative test for tenant isolation: mint a scoped token for tenant A, search for a known tenant-B document, confirm zero hits. See Tenant isolation.
• Empty query (no q) returns expected facets without crashing.
• Unicode query (accented characters in a Western alphabet, Cyrillic, CJK) returns expected results.
• Very long query (>500 chars) returns gracefully (no 5xx).
• Query with operators ("phrase match", -excluded) behaves as documented.

Pre-cutover

In the 24 hours before cutover:

• Schedule the cutover for a low-traffic window (your business will know when).
• Inform stakeholders: engineering, support, ops, customer-success. Status update sent.
• If you have a status page on your side, draft the maintenance notice (do not publish yet).
• Verify rollback path: confirm the old system can serve traffic if you flip back.
• Verify your monitoring is connected — see Monitoring. The four signals must alert your team.
• On-call rotation is staffed for the cutover window + 4 hours after.
• Final import from source into production AACsearch index. (If you're doing a delta sync, this is the last full sync before delta starts.)
• Verify doc count check on production matches.

Cutover

The window itself.

• T-0: Confirm everyone is at the keyboard. Status page notice published.
• T-0+0 min: Run a final delta sync from source to AACsearch (if applicable).
• T-0+5 min: Confirm AACsearch doc count matches source.
• T-0+5 min: Flip the feature flag / config that routes search to AACsearch.
• T-0+10 min: Run the 100-query validation against production.
• T-0+15 min: Check the four monitoring signals — all green.
• T-0+15 min: Check Sentry / error tracker for any new error class.
• T-0+30 min: Capture a baseline latencyMs from production telemetry. Compare to source system.
• T-0+60 min: Status page back to operational. Internal notice sent.

If any step fails, see Rollback below.

After cutover

• First hour: dedicated on-call review of search analytics — zero-result rate, click-through.
• First 4 hours: keep the old system reading. Compare top results for a sample of live queries.
• First 24 hours: review alerts. Tune thresholds if any are noisy.
• First 7 days: keep the old system warm (no further writes). Be ready to flip back.
• Day 7: decommission the old system. Remove the rollback flag from the application.
• Day 14: post-migration review meeting. What worked, what didn't, what to fix.

Rollback

If during or immediately after cutover the migration is clearly bad (broken results, errors > 0.1 %, latency 2x baseline), flip back:

• Flip the feature flag / config to route search back to the old system. This should take seconds.
• Verify the old system is serving traffic and results look correct.
• Investigate the AACsearch issue offline — do not retry the cutover until the root cause is known.
• Communicate: status page updated, internal notice sent, incident retrospective scheduled.

What "good" looks like at day 7

• Zero-result rate is similar to (or lower than) the old system.
• Click-through rate on top-3 results is similar or better.
• p95 search latency is at or under your old system.
• No new patterns in user feedback ("search feels different" without specifics is OK; "search can't find the product I sold yesterday" is not).
• The four monitoring signals have been steady-green for 96+ hours.

If those are green, decommission the old system on schedule. If anything is yellow at day 7, extend the rollback window — don't decommission a fallback you might still need.

See also

• Migration overview
• Per-source guides
• Operations — monitoring
• Tenant isolation