Upgrading from 1.0.0-rc.1 to 1.5.1
1.0.0-rc.1 is the only ruprizzle version published before 1.5.1, so every existing
user upgrades along this path. It is a large jump: the whole v1.1–v1.5 feature line lands
at once (see What's new in v1.1–v1.5).
Most applications need no code changes. If your code uses the generated client and the query builders, bump the versions, build, and you are done. The breaking changes below affect code that goes underneath the generated client: matching on diagnostic or IR enums, building IR or query-manifest structs by hand, or calling the internal modules that generated code uses.
Why this happened: rc.1 was a release candidate, and Stability
allows breaking changes before the first stable release. cargo-semver-checks counts
these as major. They are accepted once, for this upgrade only, and each one is listed
here with the compiler error you will see and the fix. From 1.5.1 on, normal semver
applies.
Contents
- Before you upgrade: pin exactly
- Upgrade in five steps
- Am I affected?
- What stays compatible (verified)
- Breaking changes and how to fix them
- Compiler error lookup
- Rolling back
1. Before you upgrade: pin exactly
To Cargo, the requirement ruprizzle = "1.0.0-rc.1" means >=1.0.0-rc.1, <2.0.0.
That range includes 1.5.1, so a routine cargo update would upgrade you without
asking. If you are not ready, pin the exact version now:
[dependencies]
ruprizzle = "=1.0.0-rc.1"
ruprizzle-migrate = "=1.0.0-rc.1" # only if you depend on it
Remove the = when you decide to upgrade.
2. Upgrade in five steps
Step 1 — bump every ruprizzle crate together. All workspace crates and the CLI share
one version (Versioning). Mixing 1.0.0-rc.1 and 1.5.1 crates in one
build is not supported.
[dependencies]
ruprizzle = "1.5.1"
ruprizzle-migrate = "1.5.1" # only if you depend on it
cargo install ruprizzle-cli --version 1.5.1 --locked
ruprizzle --version # should print 1.5.1
cargo update -p ruprizzle
Step 2 — build. cargo build --all-targets. If it compiles, skip to step 4. If not,
look up the error in section 6.
Step 3 — fix what the compiler reports using section 5. Every fix is mechanical, and none changes runtime behaviour.
Step 4 — regenerate the client. ruprizzle generate. This is recommended but not
required, because a client generated by rc.1 still compiles against 1.5.1
(section 4). Regenerating gives you the codegen fixes and
the generated API for new schema features such as @deletedAt and PostGIS types.
Commit the regenerated files on their own so the diff is easy to review.
Step 5 — check migrations before deploying.
ruprizzle migrate status
ruprizzle migrate dev --name upgrade_check # against a development database
Your existing migrations/.ruprizzle/snapshot.ruprizzle loads unchanged. If you have not
edited your schema, expect no new migration. If migrate dev proposes one anyway, read
the generated SQL before applying it, and report it as a bug.
3. Am I affected?
| Your code… | Affected? | Go to |
|---|---|---|
Uses the generated Db client, repos and query builders | No | — |
Has migrations created with rc.1 | No (loads unchanged) | 4 |
Has ruprizzle check query-manifest JSON files | No (loads unchanged) | 4 |
matches on SchemaError, DialectError or QueryCheckError | Maybe | 5.1 |
matches on ScalarType, RustType, FilterNode or ArrayFilterOp | Yes, if exhaustive | 5.2 |
Casts ArrayFilterOp to an integer (op as u8) | Yes | 5.3 |
Builds FieldAttrs, IndexDef, QueryEntry, QueryManifest or QueryCheckError::UnknownTable by hand | Yes | 5.4 |
Imports from ruprizzle::compile, ::decode, ::counting or ::nested | Still compiles | 5.5 |
4. What stays compatible (verified)
These were tested for 1.5.1, not assumed:
- Generated clients. The
rc.1code generator's committed output for five schemas (blog,ecommerce,m2m,saas-tenant,minimal) builds unchanged against the1.5.1runtime. - Migration snapshots.
rc.1snapshots have nois_created_at/is_deleted_atkeys, and1.5.1loads them asfalse. The regression test issnapshot_from_1_0_0_rc_1_without_new_field_attrs_still_loadsincrates/core/tests/ir_roundtrip.rs. (An unpublished1.5.0source build failed here withmissing field `is_created_at`. If you ever built1.5.0from git, move to1.5.1.) - Query manifests. Every field added to
QueryManifestandQueryEntryhas a serde default (versiondefaults to1), sorc.1manifest JSON parses unchanged. - Hidden internals. No function or struct in
compile,decodeorcountingchanged its signature. Items were only added.
5. Breaking changes and how to fix them
5.1 Diagnostic errors are #[non_exhaustive]
Affects: ruprizzle_core::SchemaError, ruprizzle_dialect::DialectError,
ruprizzle_check::QueryCheckError.
Why: new validation rules and dialects add variants. With #[non_exhaustive], future
additions will not break your build again.
Error: error[E0004]: non-exhaustive patterns: _ not covered
#![allow(unused)] fn main() { // before (rc.1) match err { SchemaError::Syntax { .. } => report_syntax(&err), SchemaError::UnknownType { .. } => report_type(&err), // ...every other variant listed } // after (1.5.1) match err { SchemaError::Syntax { .. } => report_syntax(&err), SchemaError::UnknownType { .. } => report_type(&err), _ => report_generic(&err), // required; also catches variants added later } }
These types implement miette::Diagnostic / std::error::Error. If you only display
them, use {err} or the diagnostic renderer and skip the match.
5.2 New enum variants
| Enum | Crate | New variants | Feature |
|---|---|---|---|
ScalarType | ruprizzle-core | Point, Polygon, MultiPolygon, LineString | PostGIS |
RustType | ruprizzle-dialect | Point, Polygon, MultiPolygon, LineString | PostGIS |
FilterNode | ruprizzle | FullTextMatch { .. }, Spatial { .. } | full-text search, PostGIS |
ArrayFilterOp | ruprizzle | Has, IsEmpty, IsNotEmpty | array filters |
Error: error[E0004]: non-exhaustive patterns: ScalarType::Point, … not covered
Fix: handle the new variants. The compiler lists every missing one.
#![allow(unused)] fn main() { // after (1.5.1) let sql_kind = match scalar { ScalarType::String => "text", // ...existing arms unchanged... ScalarType::Point | ScalarType::Polygon | ScalarType::MultiPolygon | ScalarType::LineString => "geometry", }; }
These four enums are still exhaustive in 1.5.1. Listing the variants keeps the compiler
checking your code. A _ => arm also compiles, but then you get no warning when a variant
you should handle is added.
5.3 ArrayFilterOp discriminants changed
Has was added as the first variant, so Contains, ContainedBy and Overlaps moved
from 0, 1, 2 to 1, 2, 3. ArrayFilterOp has no #[repr], so its numeric value was
never a stable contract.
Affects you only if you wrote op as u8 (or any integer cast), stored or sent that
number, or compared it with a constant. Nothing fails to compile. The number is just
wrong.
Fix: match on the variant instead of using its number:
#![allow(unused)] fn main() { fn op_code(op: ArrayFilterOp) -> &'static str { match op { ArrayFilterOp::Has => "has", ArrayFilterOp::Contains => "contains", ArrayFilterOp::ContainedBy => "contained_by", ArrayFilterOp::Overlaps => "overlaps", ArrayFilterOp::IsEmpty => "is_empty", ArrayFilterOp::IsNotEmpty => "is_not_empty", } } }
If you stored integers produced by rc.1, map 0 → Contains, 1 → ContainedBy,
2 → Overlaps when you read them back.
5.4 New struct fields
Error: error[E0063]: missing fields …in initializer of…``
(or error[E0027]: pattern does not mention fields … when destructuring).
| Struct | New fields | Fix |
|---|---|---|
ruprizzle_core::ir::FieldAttrs | is_created_at: bool, is_deleted_at: bool | end the literal with ..Default::default() |
ruprizzle_core::ir::IndexDef | index_type: Option<IndexType> | add index_type: None (same behaviour as rc.1) |
ruprizzle_check::QueryManifest | version: u32 | add version: 1 |
ruprizzle_check::QueryEntry | id, params, result_columns, location | add id: None, params: Vec::new(), result_columns: Vec::new(), location: None |
QueryCheckError::UnknownTable | suggestion, location | when building: suggestion: None, location: None; when matching: add .. |
#![allow(unused)] fn main() { // FieldAttrs: `..Default::default()` protects you from future fields as well let attrs = FieldAttrs { is_id: true, ..Default::default() }; // IndexDef let index = IndexDef { db_name, targets, where_clause, span, index_type: None, }; // QueryManifest / QueryEntry: or skip the literals and deserialize JSON, // which fills in every default for you let manifest: QueryManifest = serde_json::from_str(&json)?; // matching a struct variant if let QueryCheckError::UnknownTable { table, .. } = &e { /* ... */ } }
The added fields default to "feature not used" (false, None, empty), so behaviour
stays the same as rc.1.
5.5 Internal modules are hidden from docs
ruprizzle::compile, ruprizzle::decode, ruprizzle::counting and ruprizzle::nested
are now #[doc(hidden)]. Your code still compiles. Paths and signatures are
unchanged. These modules no longer appear on docs.rs, because they exist for generated
code and are not covered by semver (Stability).
Move to the crate-root re-exports, which are covered:
#![allow(unused)] fn main() { // before use ruprizzle::compile::{CompiledSql, select, insert, insert_many, update, delete}; use ruprizzle::counting::CountingExecutor; // after use ruprizzle::{CompiledSql, CountingExecutor, delete, insert, insert_many, select, update}; }
dialect_for_pool and the Nested* writers are also re-exported from the root. For
anything with no root re-export (the decode::* helpers, compile::count,
compile::exists, compile::upsert and similar), use the generated repo and query
builder methods. Those items may change in a minor release.
6. Compiler error lookup
| You see | Section |
|---|---|
E0004 non-exhaustive patterns on SchemaError / DialectError / QueryCheckError | 5.1 |
E0004 on ScalarType / RustType / FilterNode / ArrayFilterOp | 5.2 |
E0063 missing fields in a struct literal | 5.4 |
E0027 pattern does not mention fields suggestion, location | 5.4 |
| No error, but array-filter codes are wrong at runtime | 5.3 |
missing field `is_created_at` from ruprizzle migrate | You are on a 1.5.0 source build. Use 1.5.1 (4) |
Two versions of ruprizzle-core in cargo tree -d | Bump every ruprizzle crate together (step 1) |
Anything else that breaks when moving from rc.1 to 1.5.1 is not documented here and is
a bug in this guide. Please open an issue with the error message.
7. Rolling back
Go back to "=1.0.0-rc.1" in Cargo.toml, run
cargo install ruprizzle-cli --version 1.0.0-rc.1 --locked, and restore your generated
client from version control. Migrations applied while on 1.5.1 stay applied. Check
whether any of them use a 1.5-only feature (soft-delete columns, PostGIS types, GIN/GiST
indexes) before rolling back a database that rc.1 code will read.