Migration Notes

Status: Migration-family index. Version-specific instructions must be validated against the target release before use.

Adopting the Current Baseline

The current baseline was last checked on 2026-07-14:

• Generator Server 20260710.110004;
• teaql-java 1.525-RELEASE;
• teaql-rs 4.1.1;
• TeaQL Maven plugin 1.1.0;
• cargo-teaql 2.0.8.

Use this table when moving from an earlier or unrecorded installation. It is a migration checklist, not proof that every target and provider combination is executable.

Area	Detect old behavior	Current migration	Verification / rollback
Maven generation	Hard-coded target-specific goals or a plugin older than 1.1.0.	Pin plugin 1.1.0, run list-services, then call generate with -Dservice=<live-target>.	Preserve the old plugin declaration; evaluate and diff an unchanged model before replacing generated output.
Cargo generation	cargo teaql eval, a generic generate word, or a client older than 2.0.8.	Pin cargo-teaql 2.0.8, use evaluate, and invoke the target returned by services directly.	Preserve the installed version/lock evidence; generate into a new directory and run the target tests.
Rust workspace	Older SQLx-centered provider dependencies or historical provider crate names.	Regenerate with the current target and use the emitted TeaQL 4.1.1 runtime/provider dependencies.	Verify schema, queries, transactions, mutations, and database behavior; restore the previous dependency/workspace snapshot on failure.
Java workspace	Generated runtime dependencies older than 1.525-RELEASE or handwritten calls to internal dispatch methods.	Regenerate rather than editing generated code, then review the emitted Java 21, framework, runtime, and provider dependencies.	The current java-lib-core output has known SQLite-coordinate and internalSet/internalGet alignment blockers; do not promote it until a clean build and execution pass.

See Latest Versions for the current numbers and Verification Evidence for the dated commands and observed blockers.

Known Migration Families

Generated Query Prefix Changes

Historical Rust release material describes a query-filter prefix migration from which_* to with_*.

Migration procedure:

1. Regenerate with the target generator.
2. Read the generated request source for exact current method names.
3. Replace handwritten callers; do not add compatibility methods to generated files.
4. Compile and exercise affected filters.

Do not apply this rename mechanically to Java or to a release that does not emit those methods.

Repository-Level Persistence to Entity Audit Chains

Historical Rust material describes removal of manual repository/guard patterns in favor of entity persistence carrying explicit audit intent.

Current target shape:

entity.audit_as("Describe the business change").save(&ctx).await?;

Verify the generated entity and runtime version before migrating. Review graph transaction behavior and emitted audit events, not only compilation.

Mandatory Query Intent

Current Java and Rust guidance requires operation comment and business purpose before query execution:

Q.orders()
    .comment("Query orders")
    .purpose("Render the order list")
    .executeForList(ctx);

Place filtering, selection, ordering, and pagination before the intent phase. Finish each query chain with .comment(...).purpose(...), so purpose is the method immediately before executeForXxx or execute_for_xxx.

Rust SQLx Provider Removal

Current architecture material says TeaQL Rust uses narrower provider crates:

• teaql-provider-postgres;
• teaql-provider-mysql;
• teaql-provider-sqlite.

An upgrade from an SQLx-centered workspace must be treated as a provider and runtime-assembly migration:

1. Generate or inspect the target workspace's provider dependencies.
2. Replace direct SQLx/provider assembly with the target TeaQL provider setup.
3. Revalidate transactions, row decoding, connection behavior, and streaming.
4. Remove direct SQLx assumptions from handwritten TeaQL integration code.

Exact crate versions must come from the target generator/release, not an older blog example.

Java Modular Runtime Boundary

Current Java architecture documents a modular runtime and public API boundary. Applications should use generated entities, Q, E, UserContext, documented runtime contracts, and supported framework modules.

If an older application imports repository or internal implementation packages:

1. Identify imports outside documented public APIs.
2. Replace them with public runtime contracts or extension points.
3. Regenerate against the target runtime.
4. Compile with the target module boundaries enabled.
5. Verify runtime resolution and framework integration.

Java Toolchain and Spring Boot Baseline

Historical release material describes a move to Java 21 and Spring Boot 4.1 for a generated target. This is not yet a universal support statement for every TeaQL Java artifact.

Before adopting that baseline:

• verify the selected generator target;
• inspect the emitted pom.xml or build file;
• confirm the TeaQL runtime artifact versions;
• confirm framework availability and database-driver compatibility;
• run the Java golden path on Java 21.

Required Shape for Version-Specific Notes

Future entries must state:

Field	Requirement
From / to	Exact component versions or release lines.
Applies to	Java, Rust, generator, provider, model, or operations.
Breaking behavior	User-visible or generated-contract change.
Detection	Search, compiler error, report, config, or runtime symptom.
Migration	Ordered smallest credible changes.
Verification	Commands and observable success evidence.
Rollback	Code, generated output, schema, and data considerations.

See Upgrade Guide for the complete workflow.