feat(migration): USING modifier for column type changes

Author: tpetry

README.md

@@ -40,6 +40,7 @@ composer require tpetry/laravel-postgresql-enhanced
     - [Column Options](#column-options)
         - [Compression](#compression)
         - [Initial](#initial)
+        - [Using](#using)
     - [Column Types](#column-types)
         - [Arrays](#arrays)
         - [Ranges](#ranges)
@@ -644,6 +645,24 @@ Schema::table('users', function (Blueprint $table): void {
 });
 ```
 
+#### Using
+
+PostgreSQL forbids some data type changes in migrations when they violate the type system.
+You can't, e.g., change a `varchar` column storing one email address into a `jsonb` array storing multiple email addresses, as PostgreSQL doesn't know how to convert between these types automatically.
+You would get this error:
+
+```
+SQLSTATE[42804]: Datatype mismatch: 7 ERROR:  column "email" cannot be cast automatically to type jsonb
+```
+
+You can specify an expression how the current value has to be transformed to the new type with the `using()` modifier:
+
+```php
+Schema::table('users', function (Blueprint $table): void {
+    $table->jsonb('email')->using('jsonb_build_array(email)')->change();
+});
+```
+
 ### Column Types
 
 #### Arrays

src/Query/Grammar.php

@@ -33,7 +33,7 @@ class Grammar extends PostgresGrammar
     /**
      * Compile a delete statement into SQL.
      *
-     * @param \Tpetry\PostgresqlEnhanced\Query\Builder $query
+     * @param Builder $query
      */
     public function compileDelete(BaseBuilder $query): string
     {
@@ -43,7 +43,7 @@ public function compileDelete(BaseBuilder $query): string
     /**
      * Compile an insert statement into SQL.
      *
-     * @param \Tpetry\PostgresqlEnhanced\Query\Builder $query
+     * @param Builder $query
      */
     public function compileInsert(BaseBuilder $query, array $values): string
     {
@@ -53,7 +53,7 @@ public function compileInsert(BaseBuilder $query, array $values): string
     /**
      * Compile an insert statement using a subquery into SQL.
      *
-     * @param \Tpetry\PostgresqlEnhanced\Query\Builder $query
+     * @param Builder $query
      */
     public function compileInsertUsing(BaseBuilder $query, array $columns, string $sql): string
     {
@@ -63,7 +63,7 @@ public function compileInsertUsing(BaseBuilder $query, array $columns, string $s
     /**
      * Compile a select query into SQL.
      *
-     * @param \Tpetry\PostgresqlEnhanced\Query\Builder $query
+     * @param Builder $query
      */
     public function compileSelect(BaseBuilder $query): string
     {
@@ -73,7 +73,7 @@ public function compileSelect(BaseBuilder $query): string
     /**
      * Compile an update statement into SQL.
      *
-     * @param \Tpetry\PostgresqlEnhanced\Query\Builder $query
+     * @param Builder $query
      */
     public function compileUpdate(BaseBuilder $query, array $values): string
     {
@@ -83,7 +83,7 @@ public function compileUpdate(BaseBuilder $query, array $values): string
     /**
      * Compile an update from statement into SQL.
      *
-     * @param \Tpetry\PostgresqlEnhanced\Query\Builder $query
+     * @param Builder $query
      */
     public function compileUpdateFrom(BaseBuilder $query, $values): string
     {

src/Schema/Grammars/GrammarTypes.php

@@ -7,14 +7,40 @@
 use Illuminate\Database\Connection;
 use Illuminate\Database\Schema\Blueprint as BaseBlueprint;
 use Illuminate\Support\Fluent;
+use Illuminate\Support\Str;
 use Tpetry\PostgresqlEnhanced\Schema\Blueprint;
 
 trait GrammarTypes
 {
-    public function compileChange(BaseBlueprint $blueprint, Fluent $command, Connection $connection)
+    /**
+     * Compile a change column command into a series of SQL statements.
+     */
+    public function compileChange(BaseBlueprint $blueprint, Fluent $command, Connection $connection): array
     {
-        $queries = parent::compileChange($blueprint, $command, $connection);
+        $queries = [];
+
+        // The table prefix is accessed differently based on Laravel version. In old version the $prefix was public,
+        // while with new ones the $blueprint->prefix() method should be used. The issue is solved by invading the
+        // object and getting the property directly.
+        $prefix = (fn () => $this->prefix)->call($blueprint);
+
         foreach ($blueprint->getChangedColumns() as $changedColumn) {
+            $blueprintColumn = new BaseBlueprint($blueprint->getTable(), null, $prefix);
+            $blueprintColumn->addColumn($changedColumn['type'], $changedColumn['name'], $changedColumn->toArray());
+
+            foreach (parent::compileChange($blueprintColumn, $command, $connection) as $sql) {
+                if (filled($changedColumn['using']) && Str::is('ALTER TABLE * ALTER * TYPE *', $sql)) {
+                    $using = match ($connection->getSchemaGrammar()->isExpression($changedColumn['using'])) {
+                        true => $connection->getSchemaGrammar()->getValue($changedColumn['using']),
+                        false => $changedColumn['using'],
+                    };
+
+                    $queries[] = "{$sql} USING {$using}";
+                } else {
+                    $queries[] = $sql;
+                }
+            }
+
             if (filled($changedColumn['compression'])) {
                 $queries[] = sprintf(
                     'ALTER TABLE %s ALTER %s SET COMPRESSION %s',

src/Support/Phpstan/SchemaColumnDefinitionExtension.php

@@ -4,6 +4,7 @@
 
 namespace Tpetry\PostgresqlEnhanced\Support\Phpstan;
 
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
 use Illuminate\Database\Schema\ColumnDefinition;
 use PHPStan\Reflection\ClassReflection;
 use PHPStan\Reflection\FunctionVariant;
@@ -19,13 +20,14 @@
 class SchemaColumnDefinitionExtension implements MethodsClassReflectionExtension
 {
     /**
-     * @param 'initial'|'compression' $methodName
+     * @param 'compression'|'initial'|'using' $methodName
      */
     public function getMethod(ClassReflection $classReflection, string $methodName): MethodReflection
     {
         return match ($methodName) {
             'initial' => $this->getInitialMethod($classReflection),
             'compression' => $this->getCompressionMethod($classReflection),
+            'using' => $this->getUsingMethod($classReflection),
         };
     }
 
@@ -35,7 +37,7 @@ public function hasMethod(ClassReflection $classReflection, string $methodName):
             return false;
         }
 
-        return \in_array($methodName, ['compression', 'initial']);
+        return \in_array($methodName, ['compression', 'initial', 'using']);
     }
 
     private function getCompressionMethod(ClassReflection $classReflection): MethodReflection
@@ -65,4 +67,20 @@ classReflection: $classReflection,
             ],
         );
     }
+
+    private function getUsingMethod(ClassReflection $classReflection): MethodReflection
+    {
+        $parametersExpression = [new ReflectedParameter('expression', new ObjectType(ExpressionContract::class))];
+        $parametersString = [new ReflectedParameter('expression', new StringType())];
+        $returnType = new ObjectType(ColumnDefinition::class);
+
+        return new ReflectedMethod(
+            classReflection: $classReflection,
+            name: 'using',
+            variants: [
+                new FunctionVariant(TemplateTypeMap::createEmpty(), null, $parametersExpression, false, $returnType),
+                new FunctionVariant(TemplateTypeMap::createEmpty(), null, $parametersString, false, $returnType),
+            ],
+        );
+    }
 }

tests/Migration/TypesTest.php

@@ -5,6 +5,7 @@
 namespace Tpetry\PostgresqlEnhanced\Tests\Migration;
 
 use Closure;
+use Illuminate\Database\Query\Expression;
 use Tpetry\PostgresqlEnhanced\Schema\Blueprint;
 use Tpetry\PostgresqlEnhanced\Support\Facades\Schema;
 use Tpetry\PostgresqlEnhanced\Tests\TestCase;
@@ -64,6 +65,28 @@ public function testColumnModifierCompressionIsSupported(): void
         $this->assertEquals('ALTER TABLE "test" ALTER "col" SET COMPRESSION "lz4"', $queries[1]['query'] ?? null);
     }
 
+    public function testColumnModifierUsingIsSupported(): void
+    {
+        $queries = $this->runMigrations(
+            fnCreate: fn (Blueprint $table) => $table->string('col'),
+            fnChange: fn (Blueprint $table) => $table->json('col')->using('json_build_array(col)')->change(),
+        );
+
+        $this->assertEquals('create table "test" ("col" varchar(255) not null)', $queries[0]['query'] ?? null);
+        $this->assertEquals('ALTER TABLE test ALTER col TYPE JSON USING json_build_array(col)', $queries[1]['query'] ?? null);
+    }
+
+    public function testColumnModifierWithExpressionUsingIsSupported(): void
+    {
+        $queries = $this->runMigrations(
+            fnCreate: fn (Blueprint $table) => $table->string('col'),
+            fnChange: fn (Blueprint $table) => $table->json('col')->using(new Expression('json_build_array(col)'))->change(),
+        );
+
+        $this->assertEquals('create table "test" ("col" varchar(255) not null)', $queries[0]['query'] ?? null);
+        $this->assertEquals('ALTER TABLE test ALTER col TYPE JSON USING json_build_array(col)', $queries[1]['query'] ?? null);
+    }
+
     public function testDateMultiRangeTypeIsSupported(): void
     {
         $queries = $this->runMigrations(