Using `executeStatement()` in `up()`/`down()` methods?

[mpdude]

In a code review, I spotted someone doing $this->connection->executeStatement() in an up() method. They claim "it works".

My suspicion is that this is just by coincidence, because of the acutal changes made in this particular case, but not generally safe.

I would assume that addSql batches the statements for execution, for dumping to a file or skipping it in a --dry-run – and that would not be possible with direct executeStatement().

The documentation does not address this and I would like to clarify it.

• May I use direct executeStatement() or executeQuery() in up(), down(), postUp() or postDown()?
• May/shall I use addSql() in postUp() or postDown()?
• Are postUp() / postDown() only called when the migrations has actually been executed, i. e. not in a dry-run?
• What should I be aware of when mixing addSql and other statements?

[stof]

"it works", but it won't respect dry-run mode or dump-sql mode. And it also means those are executed before any query added in addSql.

• May/shall I use addSql() in postUp() or postDown()?

no. Those methods are called after the added queries are executed, so adding new ones would not execute them. The documentation states when addSql can be used: https://www.doctrine-project.org/projects/doctrine-migrations/en/3.9/reference/migration-classes.html#addsql

• Are postUp() / postDown() only called when the migrations has actually been executed, i. e. not in a dry-run?

no. those methods are also called in dry-run mode:

migrations/src/Version/DbalExecutor.php

Line 166 in d0c644b

$migration->{'post' . ucfirst($direction)}($toSchema);

• What should I be aware of when mixing addSql and other statements?

addSql registers SQL queries that will be executed after the end of your up/down method (mutating the Schema object will add the queries from its schema diff after your added queries)

[mpdude]

So, what is the best/recommended way to write migrations that depend on actual database contents?

For example, query for and iterate over a result set and execute an update statement for every row with a value that needs to be computed in PHP.

If I use addSql for these queries, will the preparation (selection) and execution phase be executed in the same transaction?