Learn · The plan as a document
The five symbols, and what each one costs
A plan speaks in five glyphs. Four of them are cheap and one of them is not, and telling them apart at speed is the whole skill.
Five, not four
Every line in a plan's gutter is one of five things. + creates something that did not exist. ~ changes something in place. - destroys something. <= reads a data source. And -/+ destroys something and then creates it again.
Four of those are cheap. The fifth is the one this whole site exists for, and it is the one that looks most like the others: a -/+ is two characters wider than a ~, in the same column, in the same colour family, in a document that is four hundred lines long.
There is a sixth form, +/-, which is the same destruction with the order reversed. It is covered in the replacement track, and it is the only good news in this list.
In-place is genuinely free
A ~ line means the provider has an API call that changes the attribute on the object that already exists. Nothing is destroyed, nothing downstream notices, and the resource keeps its id.
That is worth stating plainly because the instinct in a code review is to worry about the biggest-looking number. Resizing a production database from db.r6g.large to db.r6g.2xlarge is a ~ line: RDS modifies the instance, fails over, and the endpoint does not change.
- instance_class = "db.r6g.large"+ instance_class = "db.r6g.2xlarge"
Watch: Which glyph the block gets, and whether the endpoint row changes at all.
aws_db_instance.instance_class — Not ForceNew in the real provider either — RDS resizes with ModifyDBInstance. The scariest-looking line in most plans is a modify and a failover.
The one that is not
A -/+ means the provider has no API call for the change, so the only way to honour it is to build a new object and throw the old one away. Everything that referenced the old one has to be pointed at the new one, its computed values are all different, and for a database it means the data is gone unless a snapshot happens to exist.
Nothing about the edit tells you which you are getting. The decision was made years ago by whoever wrote the provider, based on which API calls the service happens to expose, and it is recorded in the schema as a flag called ForceNew.
Before you run it
The master user on a production database is being renamed from app to orders_app, to match a new naming convention. What does the plan say?
- username = "app"+ username = "orders_app"
Watch: The glyph, the comment above the block, and the clause on the username row.
aws_db_instance.username — ForceNew in the real provider, for the same reason: there is no ModifyDBInstance parameter that renames the master user.
The plan
The same service every claim above was made about. Nothing here is graded — load whatever you like, or change nothing and read what the configuration already produces.
Plan: 0 to add, 0 to change, 0 to destroy.
Nothing in this plan is destroyed.