Versioning and migrations
Semver guarantees, database migration policy, and safe upgrades.
Product versioning
ChatAI uses Semantic Versioning. The canonical version lives in the repository root VERSION file and is mirrored in:
- OpenAPI
info.version - Git tags (
v1.1.0, …) - GitHub Releases, whose notes come from
CHANGELOG.md
| Component | Versioning |
|---|---|
| Self-hosted app (Docker image) | Tracks product semver |
@nightzeros/chatai-widget-core, @nightzeros/chatai-widget, @nightzeros/chatai-react, @nightzeros/chatai-sdk | Published together at the product version |
| Database schema | Forward-only Drizzle migrations; no down migrations |
| REST API | /api/v1 stays backward compatible within major version 1; see API stability |
Features labelled preview, currently Voice, are usable in production but their configuration and behavior may change in a minor release. Changes are always noted in the changelog.
Database migration guarantees
Migrations live in packages/database/migrations/ and apply automatically on Docker boot via migrate.mjs.
| Guarantee | Detail |
|---|---|
| Forward-only | Each release adds numbered SQL files; we do not ship down migrations |
| Additive for released tables | Minor and patch releases only add tables, columns, enum values and indexes to tables that shipped in an earlier release. Each release's notes list any data changes |
| Breaking DDL | Reserved for major releases with explicit upgrade notes |
| Legacy bootstrap | Pre-journal Docker installs are baselined before applying pending migrations |
| CI verification | pnpm test:migrations applies all migrations on a fresh Postgres |
Before upgrading
- Back up Postgres and uploads — see Backup and upgrades.
- Read the release notes for migration-specific steps. For 1.0 → 1.1, see Upgrading to 1.1.
- Pull or rebuild and restart so the entrypoint runs
migrate.mjs.
Embedding dimension constraint
The schema uses vector(1536). Switching to a model with a different dimension requires re-embedding all documents — surfaced in the dashboard when changing embedding providers.
Package semver (npm)
The four @nightzeros/chatai-* packages are released together with the same version. Breaking changes to the public API or the widget embed contract only happen in a new major version; minor releases add features (such as the Voice APIs in 1.1.0) and patch releases are bugfix-only. Install matching versions of widget-core, widget and react.