Deprecate not specifying charset

UPGRADE.md

@@ -8,7 +8,18 @@ awareness about deprecated code.
 
 # Upgrade to 3.4
 
-# Deprecated `AbstractPlatform` schema introspection methods
+## Deprecated omitting the charset when using MySQL
+
+Omitting the charset when using MySQL results in the deprecated `utf8` MySQL
+charset being used. Configure it explicitly when creating a table:
+```php
+use Doctrine\DBAL\Schema\Table;
+
+$table = new Table('a_table', [new Column('a_column', Type::getType('string'))]);
+$table->addOption('charset', 'utf8mb4');
+```
+
+## Deprecated `AbstractPlatform` schema introspection methods
 
 The following schema introspection methods have been deprecated:
 
@@ -19,22 +30,22 @@ The following schema introspection methods have been deprecated:
 
 The queries used for schema introspection are an internal implementation detail of the DBAL.
 
-# Deprecated `collate` option for MySQL
+## Deprecated `collate` option for MySQL
 
 This undocumented option is deprecated in favor of `collation`.
 
-# Deprecated `AbstractPlatform::getListTableConstraintsSQL()`
+## Deprecated `AbstractPlatform::getListTableConstraintsSQL()`
 
 This method is unused by the DBAL since 2.0.
 
-# Deprecated `Type::getName()`
+## Deprecated `Type::getName()`
 
 This will method is not useful for the DBAL anymore, and will be removed in 4.0.
 As a consequence, depending on the name of a type being `json` for `jsonb` to
 be used for the Postgres platform is deprecated in favor of extending
 `Doctrine\DBAL\Types\JsonType`.
 
-# Deprecated `AbstractPlatform::getColumnComment()` and `AbstractPlatform::getDoctrineTypeComment()`
+## Deprecated `AbstractPlatform::getColumnComment()` and `AbstractPlatform::getDoctrineTypeComment()`
 
 DBAL no longer needs column comments to ensure proper diffing. Note that both
 methods should probably have been marked as internal as these comments were an

src/Platforms/AbstractMySQLPlatform.php

@@ -460,6 +460,11 @@ private function buildTableOptions(array $options): string
 
         // Charset
         if (! isset($options['charset'])) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5278',
+                'Omitting the charset option is deprecated, be explicit about it instead. We recommend using "utf8b4"'
+            );
             $options['charset'] = 'utf8';
         }
 

tests/Platforms/MySQLPlatformTest.php

@@ -4,8 +4,10 @@
 
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\MySQLPlatform;
+use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\TransactionIsolationLevel;
+use Doctrine\DBAL\Types\Type;
 use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use InvalidArgumentException;
 
@@ -54,4 +56,11 @@ public function testCollateOptionIsStillSupportedButDeprecated(): void
             $this->platform->getCreateTableSQL($table)[0]
         );
     }
+
+    public function testOmittingTheCharsetIsDeprecated(): void
+    {
+        $table = new Table('a_table', [new Column('a_column', Type::getType('string'))]);
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/5278');
+        $this->platform->getCreateTableSQL($table);
+    }
 }