Releases and compatibility

Ridu uses one version across its Go module, project-local CLI, npm packages, and official plugins. Keep them on the same release line. Mixing versions can fail during generation, plugin registration, or startup.

Supported matrix

PostgreSQL-compatible services must provide the PostgreSQL behavior Ridu depends on, including transaction semantics, migration locks, concurrent indexes, and TLS. Test a managed service before using it in production.

MongoDB support does not extend to Atlas, DocumentDB, Cosmos DB, standalone servers, other versions or topologies, or other operating systems and architectures. Follow the supported setup in MongoDB.

Versioning rules

Before v1.0.0, a release may change a public contract. Upgrade one project at a time and read its release notes before updating. Only the latest pre-1 release is supported.

From v1.0.0, breaking changes to public Go, CLI, REST, SDK, and extension contracts require a major version. Additions use a minor version and compatible fixes use a patch version.

Contracts fail mismatches early

Ridu checks related versions during generation and startup:

Fix the package versions and regenerate. Do not copy generated files from another project or bypass plugin checks.

What counts as public

Compatibility covers documented exported Go packages, CLI commands, REST and protocol contracts, published TypeScript packages, generated application contracts, and documented plugin interfaces.

Go internal/ packages, .ridu/ intermediates, unexported symbols, and generated implementation details are not customization surfaces. Change the executable config and regenerate instead of editing generated output.

Upgrade a project

Read the release notes, then upgrade the project as one unit:

1. Update @riducms/cli to the target version.
2. Update the Go module, framework npm packages, and official plugins to the same release line.
3. Run ridu generate and review the generated changes.
4. Create and review a migration when the model changed.
5. Run ridu check, ridu migrate verify, and the application’s tests.
6. Rehearse the deployment on a recent restored backup.

Set the version once so the CLI and Go module cannot drift:

TARGET_VERSION="X.Y.Z"
npm install --save-dev --save-exact "@riducms/cli@$TARGET_VERSION"
go get "github.com/riducms/ridu@v$TARGET_VERSION"
npm run ridu -- generate

TARGET_VERSION="X.Y.Z"
bun add --dev --exact "@riducms/cli@$TARGET_VERSION"
go get "github.com/riducms/ridu@v$TARGET_VERSION"
bun run ridu -- generate

TARGET_VERSION="X.Y.Z"
pnpm add --save-dev --save-exact --workspace-root "@riducms/cli@$TARGET_VERSION"
go get "github.com/riducms/ridu@v$TARGET_VERSION"
pnpm run ridu generate

TARGET_VERSION="X.Y.Z"
yarn add --dev --exact --ignore-workspace-root-check "@riducms/cli@$TARGET_VERSION"
go get "github.com/riducms/ridu@v$TARGET_VERSION"
yarn run ridu generate

Never edit an applied migration. Add a forward migration to correct it.

Verify an installation

Check that the project resolves one Ridu version across its tools:

ridu version
go list -m github.com/riducms/ridu

Then run ridu doctor to find a mismatched CLI, Go module, package, project file, or generated contract.

Before production

Before sending traffic to an upgraded application:

• run ridu migrate verify against restored data;
• restore the database and upload storage together and test representative media;
• confirm database transport, credentials, topology, and timeouts;
• monitor /healthz, /readyz, request errors, tasks, latency, and storage health;
• exercise authentication, writes, access-controlled reads, uploads, drafts, and rollback on a canary; and
• record who approves the traffic switch and who can roll it back.

See Production, Security, Migrations, and Troubleshooting for the complete operational paths.