Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

  1. Before you upgrade: pin exactly
  2. Upgrade in five steps
  3. Am I affected?
  4. What stays compatible (verified)
  5. Breaking changes and how to fix them
  6. Compiler error lookup
  7. 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 buildersNo—
Has migrations created with rc.1No (loads unchanged)4
Has ruprizzle check query-manifest JSON filesNo (loads unchanged)4
matches on SchemaError, DialectError or QueryCheckErrorMaybe5.1
matches on ScalarType, RustType, FilterNode or ArrayFilterOpYes, if exhaustive5.2
Casts ArrayFilterOp to an integer (op as u8)Yes5.3
Builds FieldAttrs, IndexDef, QueryEntry, QueryManifest or QueryCheckError::UnknownTable by handYes5.4
Imports from ruprizzle::compile, ::decode, ::counting or ::nestedStill compiles5.5

4. What stays compatible (verified)

These were tested for 1.5.1, not assumed:

  • Generated clients. The rc.1 code generator's committed output for five schemas (blog, ecommerce, m2m, saas-tenant, minimal) builds unchanged against the 1.5.1 runtime.
  • Migration snapshots. rc.1 snapshots have no is_created_at / is_deleted_at keys, and 1.5.1 loads them as false. The regression test is snapshot_from_1_0_0_rc_1_without_new_field_attrs_still_loads in crates/core/tests/ir_roundtrip.rs. (An unpublished 1.5.0 source build failed here with missing field `is_created_at` . If you ever built 1.5.0 from git, move to 1.5.1.)
  • Query manifests. Every field added to QueryManifest and QueryEntry has a serde default (version defaults to 1), so rc.1 manifest JSON parses unchanged.
  • Hidden internals. No function or struct in compile, decode or counting changed 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

EnumCrateNew variantsFeature
ScalarTyperuprizzle-corePoint, Polygon, MultiPolygon, LineStringPostGIS
RustTyperuprizzle-dialectPoint, Polygon, MultiPolygon, LineStringPostGIS
FilterNoderuprizzleFullTextMatch { .. }, Spatial { .. }full-text search, PostGIS
ArrayFilterOpruprizzleHas, IsEmpty, IsNotEmptyarray 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).

StructNew fieldsFix
ruprizzle_core::ir::FieldAttrsis_created_at: bool, is_deleted_at: boolend the literal with ..Default::default()
ruprizzle_core::ir::IndexDefindex_type: Option<IndexType>add index_type: None (same behaviour as rc.1)
ruprizzle_check::QueryManifestversion: u32add version: 1
ruprizzle_check::QueryEntryid, params, result_columns, locationadd id: None, params: Vec::new(), result_columns: Vec::new(), location: None
QueryCheckError::UnknownTablesuggestion, locationwhen 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 seeSection
E0004 non-exhaustive patterns on SchemaError / DialectError / QueryCheckError5.1
E0004 on ScalarType / RustType / FilterNode / ArrayFilterOp5.2
E0063 missing fields in a struct literal5.4
E0027 pattern does not mention fields suggestion, location5.4
No error, but array-filter codes are wrong at runtime5.3
missing field `is_created_at` from ruprizzle migrateYou are on a 1.5.0 source build. Use 1.5.1 (4)
Two versions of ruprizzle-core in cargo tree -dBump 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.