Deprecate SchemaDiff::toSql() and SchemaDiff::toSaveSql()

[morozov]

Q	A
Type	deprecation

1. Similar to TableDiff::getName() (Deprecate not passing $fromColumn to TableDiff #5678), implementing the SQL-related methods makes the diff (which is a value object) depend on the infrastructure. It should be the other way around.
2. Being able to discard all DROP statements from the generated schema migration SQL is a poor-man solution to dealing with the objects not owned by the DBAL. It has the following downsides:
   1. The DBAL still can choke during introspection of those objects (e.g. Schema introspection on Oracle is failing when user is 'system' #4470, AbstractSchemaManager#_getPortableTableColumnList() cannot process functional indexes defined in MySQL #5306).
   2. The objects that are owned by the DBAL still need to be dropped manually.
3. The toSaveSql() method and the corresponding $saveMode parameter names make absolute no sense.
4. Neither the DBAL nor Migrations use SchemaDiff::toSaveSql(). This method is absolutely untested, and I'm not talking about a unit test that confirms that the flag is respected. I'm talking about the integration testing of the scenarios for which the method was implemented in the first place.

Instead of using SchemaDiff::toSaveSql() for discarding schema changes in 3rd-party database objects (if that's the case), it is recommended to use asset filtering.

[derrabus]

Shall we add tests that call the new getAlterSchemaSQL() method?

[morozov]

We can migrate more code to use the new API. It will make both the new and the deprecated API covered by existing tests.

[greg0ire]

Neither the ORM nor Migrations use SchemaDiff::toSaveSql()

That does not seem to be accurate: https://github.com/doctrine/orm/blob/5f4b76b88fe2682af2c1d7580719dd1b9193db65/lib/Doctrine/ORM/Tools/SchemaTool.php#L950

What should be done here?

[morozov]

Sorry, I meant DBAL instead of ORM. I knew that the ORM uses it. The ORM should deprecate not passing the --complete flag to the schema tool. This flag will be not supported with DBAL 4.