Upgrade Guide

TeaQL upgrades are regeneration exercises, not dependency-number edits alone. The safe unit of change includes the model, generator, generated output, runtime, providers, configuration, and handwritten API callers.

1. Capture the Current Baseline

Before changing versions, record:

• model revision;
• generator or client version;
• Maven plugin or cargo-teaql version;
• generated runtime dependencies;
• Java and Maven or Rust toolchain versions;
• framework and database/provider versions;
• exact generation command and working directory;
• current build/test result;
• schema-management mode;
• production audit, logging, tenancy, and authorization settings.

If a client does not expose a version command, preserve its installation source, lockfile/plugin declaration, help output, and generated dependency set.

2. Read Release and Migration Evidence

Check, in this order:

1. Compatibility Matrix.
2. Migration Notes.
3. The target component's release notes.
4. Generator-emitted dependency and workspace changes.

Historical blog posts provide context but may contain old dependency names or commands. Use current client output and maintained reference pages as the operational authority.

3. Upgrade in an Isolated Change

Do not mix a framework upgrade with unrelated domain-model features. A focused upgrade makes generated diffs, runtime failures, and rollback decisions reviewable.

Recommended order:

1. Update the generator/client or plugin declaration.
2. Evaluate the unchanged model.
3. Regenerate from the unchanged model.
4. Review generated and dependency diffs.
5. Align runtime and provider dependencies with generator output.
6. Update handwritten callers and configuration.
7. Build and run tests.
8. Only then introduce new model features.

4. Review the Regeneration Diff

Area	Upgrade question
Entity API	Were accessors, update methods, status methods, or traits/interfaces renamed?
Query API	Did filters, selections, relations, intent phases, or terminal execution change?
Mutation API	Did audit requirements, graph planning, transaction behavior, or save signatures change?
Layout	Did generated packages, crates, modules, or extension locations move?
Dependencies	Were runtime versions, features, providers, or framework integrations changed?
Schema	Are changes additive, destructive, provider-specific, or permission-sensitive?
Operations	Did defaults for logging, audit, schema, connection, or runtime policy change?

Large unexplained generated diffs are a stop condition.

5. Verify in Layers

Run the smallest checks first:

1. Model evaluation.
2. Generation.
3. Compile/build.
4. Unit tests for handwritten domain behavior.
5. Provider-backed integration tests.
6. One query carrying comment and purpose.
7. One mutation carrying audit intent.
8. Relation loading and transaction rollback tests.
9. Schema dry run or controlled schema verification.
10. Application smoke test with production-like configuration.

6. Production Review

Before deployment, explicitly review:

• tenant and permission boundaries;
• audit identity and intent records;
• sensitive-field masking and log payloads;
• database privileges and schema behavior;
• transaction guarantees of the selected provider;
• connection, timeout, and retry behavior;
• backward compatibility of HTTP/event payloads;
• rollback artifacts and database constraints.

7. Rollback Strategy

Prepare rollback before deployment:

• preserve the previous generator/client and dependency lock state;
• retain the previously generated workspace or reproducible generation inputs;
• avoid destructive schema changes without a separate database rollback plan;
• identify data written in a new format that older runtimes cannot read;
• keep deployment configuration versioned;
• define the smoke test that decides whether rollback is necessary.

Rolling back code does not automatically roll back schema or data.

Upgrade Evidence Record

Attach this record to the change:

Source version(s):
Target version(s):
Model revision:
Generator command:
Generated diff reviewed by:
Toolchain/framework/provider versions:
Evaluation result:
Build/test result:
Query verification:
Mutation/audit verification:
Schema verification:
Known limitations:
Rollback plan: