Upgrading
Read this page before every minor bump. Breaking changes land only on minor releases, and every one has a section in MIGRATING.md on GitHub, which stays the full, canonical history. This page summarizes the recent ones.
0.34.x → 0.35.0
Section titled “0.34.x → 0.35.0”0.35.0 changes no Stack code: the Dart API, synth output and every provider pin stay as they were. It changes how the terradart command behaves in CI and scripts.
- Raise every TerraDart constraint to
^0.35.0by hand, then rundart pub upgrade, anddart pub global activate terradart_clifor the new command. - Pass
--auto-approvewhere nobody can answer. Without a terminal — or with--no-input,CI, or in an AI agent’s shell —terradart applyandterradart destroystop beforeinitwith exit code 3 instead of starting the engine. A script that pipedyesinto them passes--auto-approveinstead. - Check exit codes against the new table. A failed engine step exits 12 (the engine’s own code is
error.engineExitCodeunder--json), a failed entry point 10, an unknown--env65. A script that tested$? -eq 1tests$? -ne 0, or readserror.codefrom--json. See JSON and exit codes. - Optional: install the agent skill.
terradart skill installwrites the TerraDart Agent Skill of the CLI’s release into the project;terradart skill status --checkkeeps it current in CI. See Let an AI agent do it.
0.33.x → 0.34.0
Section titled “0.33.x → 0.34.0”0.34.0 changes no Stack code: the Dart API, synth output and every provider pin stay as they were.
- Raise every TerraDart constraint to
^0.34.0by hand, then rundart pub upgrade, anddart pub global activate terradart_clifor the new command. - Optional: name a default environment. Passing a
defaultEnvmember torunEnvironmentsletsterradart planrun without--env;TERRADART_ENVoverrides it. See Environments. - Appwrite Stacks run on Terraform. The
terradartcommand now picks theterraformonPATHfor a Stack that usesterradart_appwrite, and stops beforeinitwhen there is none or OpenTofu is asked for. - A state another engine wrote now needs an answer. When
.terradart/engines.jsonhas no record (a fresh clone, or right after a migration),plan,applyanddestroyread the state first. If the engine the command picked by itself is not the one that wrote the state, they ask on a terminal. Without a terminal they stop with exit code 64; pass--engine, or set theengineof theterradartsection inpubspec.yaml, in CI.
0.32.x → 0.33.0
Section titled “0.32.x → 0.33.0”0.33.0 adds the terradart command (terradart_cli) and changes no Stack code: the provider packages keep their Dart API, no provider pin moves, and synth output is unchanged.
-
Raise every TerraDart constraint to
^0.33.0by hand, then rundart pub upgrade:dependencies:terradart_core: ^0.33.0terradart_google: ^0.33.0# and ^0.33.0 for terradart_google_beta, terradart_aws,# terradart_cloudflare, terradart_appwrite or terradart_time -
Switch to the command.
dart pub global activate terradart_cli, thenterradart applyreplacesdart run bin/infra.dart,cd tf-out,terraform initandterraform apply, and writes the define file a client reads its outputs from. An existingbin/infra.dartkeeps working; callingrunStackorrunEnvironmentsfrom it lets the command select an environment with--env <name>. See The terradart command. -
terradart-migrateusers: runterradart migratewith the same flags.terradart-migratestill runs, prints that it is deprecated, and goes away in a later release. -
Maintainers only:
dart pub global activate terradart_codegennow installsterradart-codegen(terradart-codegen wrap ...), becauseterradartis the user command. Deactivate and reactivateterradart_codegenbefore activatingterradart_cli;dart run terradart_codegen:terradartis unchanged.
0.31.x → 0.32.0
Section titled “0.31.x → 0.32.0”0.32.0 makes every argument take what it means — an attribute getter, an enum member, a variable handle, a provider instance, the blocks a resource depends on — so most of the upgrade is deleting wrappers. It breaks the Dart API of every package, not your Terraform: no provider pin moves, and synthesized JSON changes only where a typed reference now emits the attribute the provider expects, an IAM adjunct now carries its parent’s project / location, or an explicit false lifecycle flag is now written.
Upgrade steps
Section titled “Upgrade steps”-
Raise every TerraDart constraint to
^0.32.0by hand, then rundart pub upgrade. The Dart SDK minimum stays 3.10:dependencies:terradart_core: ^0.32.0terradart_google: ^0.32.0# and ^0.32.0 for terradart_google_beta, terradart_aws,# terradart_cloudflare, terradart_appwrite or terradart_time -
Drop
import 'package:terradart_core/terradart_core.dart';where a file imports a provider barrel: every barrel re-exports it. -
Fix the compile errors with the upgrade guide in MIGRATING.md, which lists the groups in order of how many stacks they touch, each with a before / after table.
-
Read
terradart planbefore you apply. A few typed references emit a different attribute than the one a stack passed (the list);.ref.pinned('id')keeps the old one. -
terradart-migrateusers:dart pub global activate terradart_migrateinstalls 0.32.0, which writes the new API.
The common changes
Section titled “The common changes”| Before (0.31) | After (0.32) |
|---|---|
GooglePubsubTopic(localName: 'orders', ...) | GooglePubsubTopic('orders', ...) |
topic.nameRef, labels: .ref(topic.labels) | topic.name, and the getter itself (the orders-dlq labels below) |
routingMode: .literal(.regional) | the member itself (the network’s routing mode below) |
addVariable('region', const TfVariable(type: 'string')), then TfArg.variable('region') | final region = variable<String>('region');, then the handle itself (the service’s location below) |
dependsOn: [ResourceDependency(api)], addData(...) | the resource itself (the service’s dependsOn below), add(...) |
provider: 'google.eu' | the handle addProvider returns for a GoogleProvider with the eu alias (the EU topic’s provider below) |
setBackend(...), TfTimeouts(create: '30m') | the backend of the super(...) call, and a Duration per TfTimeouts operation (the service’s timeouts below) |
Apis.enable(this, barrels: [Barrels.cloudRun]) | enableApis([.cloudRun]) |
member: .ref(sa.iamMember), member: .literal('user:a@example.com') | the account’s principal, or .user('a@example.com') (the two topic IAM members below) |
name: .ref(api.nameRef), location: ... on an IAM member | the parent’s ref (the service IAM member below) |
password: .literal('...') on a sensitive argument | a variable or an expression; Sensitive<T> has no .literal |
ignoreChanges: ['client'] | .of([...]) (the service’s lifecycle below) |
on StateError / on SensitiveLiteralError around synth() | on SynthException, or stack.validate() |
Together:
import 'package:terradart_google/cloud_run.dart';import 'package:terradart_google/compute.dart';import 'package:terradart_google/iam.dart';import 'package:terradart_google/provider.dart';import 'package:terradart_google/pubsub.dart';
final class PublisherStack extends Stack { PublisherStack({required String projectId}) : super( providers: [GoogleProvider(project: projectId)], backend: const GcsBackend(bucket: 'my-tf-state', prefix: 'publisher'), ) { final region = variable<String>('region'); final eu = addProvider(GoogleProvider(alias: 'eu', region: 'europe-west1')); final topic = add( GooglePubsubTopic( 'orders', name: .literal('orders'), labels: .literal({'team': 'orders'}), ), ); add( GooglePubsubTopic( 'orders-dlq', name: .literal('orders-dlq'), labels: topic.labels, // was .ref(topic.labels) ), ); add( GooglePubsubTopic( 'orders-eu', name: .literal('orders-eu'), provider: eu, // was 'google.eu' ), ); final publisher = add( GoogleServiceAccount('publisher', accountId: .literal('orders-publisher')), ); add( GooglePubsubTopicIamMember( 'publish', topic: topic.ref, // was name: .ref(topic.nameRef) role: .literal('roles/pubsub.publisher'), member: publisher.principal, // was .ref(publisher.iamMember) ), ); add( GooglePubsubTopicIamMember( 'view', topic: topic.ref, role: .literal('roles/pubsub.viewer'), member: .user('a@example.com'), // was .literal('user:a@example.com') ), ); final vpc = add( GoogleComputeNetwork( 'vpc', name: .literal('orders-vpc'), routingMode: .regional, // was .literal(.regional) ), ); final api = add( GoogleCloudRunV2Service( 'api', name: .literal('orders-api'), location: region, // was TfArg.variable('region') template: CloudRunV2ServiceTemplate( containers: [ .new(image: .literal('us-docker.pkg.dev/cloudrun/container/hello')), ], ), dependsOn: [vpc], timeouts: const TfTimeouts(create: Duration(minutes: 30)), lifecycle: .new(ignoreChanges: .of(['client'])), // was ['client'] ), ); add( GoogleCloudRunV2ServiceIamMember( 'invoke', service: api.ref, // was name: .ref(api.nameRef), location: ... role: .literal('roles/run.invoker'), member: publisher.principal, ), ); addOutput('orders_topic_id', topic.id); }}New in 0.32.0 and not breaking: typed outputs in Flutter and web clients (addDartDefineOutput), and provider aliases in migrated child modules.
Older releases
Section titled “Older releases”Every earlier breaking change — sealed arguments, typed references, typed nested helpers and short type names in 0.31.0, TfArg.expression and provider aliases in 0.28.0, sealed exactly-one slots in 0.12.12, typed enums in 0.12.10, and more — is documented in MIGRATING.md.
Next steps
Section titled “Next steps”- Status & versioning — alpha expectations and change policy
- Examples — every quickstart is on the current API