Migration Notes

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

2026-07-14 migration snapshot

The following historical baseline was checked on 2026-07-14. Do not use its dependency pins for a new workspace; use Latest Versions and the manifest emitted by the current generator:

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

Use this table to understand the recorded migration, not as a current compatibility matrix. It is not proof that every target and provider combination is executable today.

Area	Detect old behavior	Migration recorded in this snapshot	Verification / rollback
Maven generation	Hard-coded target-specific goals or a plugin older than 1.1.1.	Pin plugin 1.1.1, 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 July 2026 java-lib-core output had SQLite-coordinate and internalSet/internalGet alignment blockers; do not apply that conclusion to a newer generator without a clean replay.

See Latest Versions for the current numbers and Verification Evidence Archive 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. Request current model-aware Assist for exact 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);

Both values must be non-empty before executeForXxx or execute_for_xxx. They may appear in either order and need not be adjacent; filtering, selection, ordering, pagination, and relation selection can be composed between them.

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.