Docs

Upgrading

Order

  1. Read the release notes for new environment variables and breaking changes.
  2. Migrate the database (npm run db:migrate with the direct URL, or let the build/auto-migrate do it). Migrations are additive within a major version, so the running old API keeps working.
  3. Deploy the API.
  4. Deploy the dashboard (it talks to the API through the versioned /v1 contract).
  5. Check GET /v1/health, the dashboard's Status page and npm run migrate -w @3x/api -- --check.

Sites and the SDK

  • Script tag …/v1/s/x3.js always serves the SDK bundled with the API – sites get updates with the API deploy. Pin a version with x3@1.2.3.js if you need to control the rollout.
  • npm users update @3x-engine/sdk themselves. The ingest protocol is versioned (v in each batch), and the API accepts older SDK versions of the same major.
  • Lazy plugin files are versioned with the core script; a mismatching plugin refuses to install instead of misbehaving.

Rollback

  • Code: redeploy the previous API/dashboard build.
  • Database: migrations are not reversed automatically. Within a major version an older API ignores new columns and tables, so a code rollback is enough. Restore a backup only for data errors.

Relevance rules and channels

Upgrades never re-score existing sessions silently. When a release changes the default relevance model or channel rules, projects keep their pinned version until an admin switches it in Settings → Relevance (re-scoring runs in the background) – reports stay comparable.