feat: pg18 temporal indexes (references #117)

Author: tpetry

README.md

@@ -49,6 +49,7 @@ The minimal breaking changes of the past years are listed in the [breaking chang
         - [Storage Parameters](#storage-parameters-index)
         - [Functional Indexes / Column Options](#functional-indexes--column-options)
         - [Fulltext Indexes](#fulltext-indexes)
+        - [Temporal Indexes](#temporal-indexes)
     - [Domain Types](#domain-types)
     - [Table Options](#table-options)
         - [Unlogged](#unlogged)
@@ -587,6 +588,68 @@ Schema::table('book', function (Blueprint $table) {
 });
 ```
 
+#### Temporal Indexes
+
+Imagine you've built a shopping system and one day a customer complains that his order was sent to their old address, which is hundreds of miles away from the current one.
+The current data in the database also shows you the current address - so you made a mistake?
+But how was the address when the order was shipped?
+Have you logged the change in an audit table?
+Happy for you if you did, but querying the data is complicated...
+
+So PostgreSQL 18 added support for temporal database features:
+You can now version control your data with primary keys, unique keys and foreign keys that are only valid for a specific point in time:
+
+```php
+use Tpetry\PostgresqlEnhanced\Schema\Blueprint;
+use Tpetry\PostgresqlEnhanced\Support\Facades\Schema;
+
+Schema::createExtensionIfNotExists('btree_gist');
+Schema::create('addresses', function (Blueprint $table) {
+    $table->uuid('id');
+    $table->timestampTzRange('valid');
+    // ...
+
+    $table->primary(['id', 'valid WITHOUT OVERLAPS']);
+});
+Schema::create('orders', function (Blueprint $table) {
+    $table->uuid('id');
+    $table->uuid('address_id');
+    $table->text('reference_nr');
+    $table->timestampTzRange('valid');
+    // ...
+
+    $table->primary(['id', 'valid WITHOUT OVERLAPS']);
+    $table->unique(['reference_nr', 'valid WITHOUT OVERLAPS']);
+    $table->foreign(['address_id', 'PERIOD valid'])->references(['id', 'PERIOD valid'])->on('addresses');
+});
+
+Address::insert([
+    [
+        'id' => '7f8f1ee1-63fc-4472-8950-034aeb75da38',
+        'valid' => '["2000-01-01 00:00:00+00","2025-01-01 00:00:00+00")',
+    ],
+    [
+        'id' => '7f8f1ee1-63fc-4472-8950-034aeb75da38',
+        'valid' => '["2025-01-01 00:00:00+00",)',
+    ],
+]);
+Order::insert([
+    'id' => '93c7d2a9-41d9-4fba-9943-7c97c4420d59',
+    'address_id' => '7f8f1ee1-63fc-4472-8950-034aeb75da38',
+    'reference_nr' => '1234567890',
+    'valid' => '["2025-10-17 10:46:34+00",)',
+]);
+        
+Order::query()
+    ->join('addresses', 'addresses.id', 'orders.address_id')
+    ->where('addresses.valid', '@>', new Expression('LOWER(orders.valid)'))
+    ->whereKey('93c7d2a9-41d9-4fba-9943-7c97c4420d59');
+```
+
+> [!NOTE]
+> There is no Eloquent implementation for temporal features yet.
+> But a full implementation would replace Laravel's soft-deletes implementation.
+
 ### Domain Types
 
 A relational database like PostgreSQL provides a lot of data types you can choose from.

src/Schema/BlueprintIndex.php

@@ -88,10 +88,6 @@ public function uniqueIndex($columns, ?string $name = null, ?string $algorithm =
      */
     protected function createIndexName($type, array $columns): string
     {
-        if ('unique' === $type) {
-            return parent::createIndexName($type, $columns);
-        }
-
         $columns = array_map(function (string $column): string {
             // When the column has a structure like '(.+).*' it's an functional index. But it's not
             // easily possible to extract column names from a functional expression so the developer
@@ -112,9 +108,12 @@ protected function createIndexName($type, array $columns): string
             }
 
             // When index parameters are defined the space in the sql grammar is the separation character
-            // of the column and all params. So in case a space is available only the part before the first
-            // space character is declaring the column and will be used.
-            return Str::before($column, ' ');
+            // of the column and all params. So in case a space is available, special index behavior is
+            // defined and the real column name must be extracted.
+            return match (str_starts_with(strtolower($column), 'period ')) {
+                true => Str::after($column, ' '),
+                false => Str::before($column, ' '),
+            };
         }, $columns);
 
         return parent::createIndexName($type, $columns);

src/Schema/Grammars/GrammarForeignKey.php

@@ -4,7 +4,10 @@
 
 namespace Tpetry\PostgresqlEnhanced\Schema\Grammars;
 
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
+use Illuminate\Database\Query\Expression;
 use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Fluent;
 
 trait GrammarForeignKey
@@ -14,6 +17,22 @@ trait GrammarForeignKey
      */
     public function compileForeign(Blueprint $blueprint, Fluent $command): string
     {
+        foreach (['columns', 'references'] as $columnsKey) {
+            $command[$columnsKey] = array_map(function (string|Expression|ExpressionContract $column) {
+                if ($this->isExpression($column)) {
+                    return $column;
+                }
+
+                if (str_starts_with(strtolower($column), 'period ')) {
+                    $column = trim(substr($column, 7));
+
+                    return new Expression("PERIOD {$this->wrap($column)}");
+                }
+
+                return $column;
+            }, Arr::wrap($command[$columnsKey]));
+        }
+
         $sql = parent::compileForeign($blueprint, $command);
         if ($command->get('notEnforced')) {
             $sql .= ' not enforced';

src/Schema/Grammars/GrammarIndex.php

@@ -4,6 +4,8 @@
 
 namespace Tpetry\PostgresqlEnhanced\Schema\Grammars;
 
+use Illuminate\Contracts\Database\Query\Expression as ExpressionContract;
+use Illuminate\Database\Query\Expression;
 use Illuminate\Database\Schema\Blueprint;
 use Illuminate\Support\Fluent;
 use Tpetry\PostgresqlEnhanced\Support\Helpers\MigrationIndex;
@@ -73,15 +75,23 @@ public function compileFulltext(Blueprint $blueprint, Fluent $command): string
     {
         $command['algorithm'] ??= 'gin';
 
-        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, false);
+        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, 'index');
     }
 
     /**
      * Compile a plain index key command.
      */
     public function compileIndex(Blueprint $blueprint, Fluent $command): string
     {
-        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, false);
+        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, 'index');
+    }
+
+    /**
+     * Compile a primary key command.
+     */
+    public function compilePrimary(Blueprint $blueprint, Fluent $command): string
+    {
+        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, 'primary');
     }
 
     /**
@@ -91,14 +101,34 @@ public function compileSpatialIndex(Blueprint $blueprint, Fluent $command): stri
     {
         $command['algorithm'] = 'gist';
 
-        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, false);
+        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, 'index');
+    }
+
+    /**
+     * Compile a unique key command.
+     *
+     * @return string|string[]
+     */
+    public function compileUnique(Blueprint $blueprint, Fluent $command): mixed
+    {
+        $command['columns'] = array_map(function (string|Expression|ExpressionContract $column) {
+            if ($this->isExpression($column)) {
+                return $column;
+            }
+
+            $parts = explode(' ', $column, 2);
+
+            return new Expression(trim(\sprintf('%s %s', $this->wrap($parts[0]), $parts[1] ?? '')));
+        }, $command['columns']);
+
+        return parent::compileUnique($blueprint, $command);
     }
 
     /**
      * Compile a unique key command.
      */
     public function compileUnique2(Blueprint $blueprint, Fluent $command): string
     {
-        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, true);
+        return (new MigrationIndex())->compileCommand($this, $blueprint->getTable(), $command, 'unique');
     }
 }

src/Schema/Timescale/CaggBlueprint.php

@@ -83,7 +83,7 @@ public function index(string|array $columns, ?string $name = null, ?string $algo
         /** @var \Tpetry\PostgresqlEnhanced\Schema\IndexDefinition $fluent */
         $fluent = $migration->createCommand('index', $name ?: $migration->createName('index', '', $this->table, $columns), $columns, $algorithm);
 
-        $this->commands[] = fn (Connection $connection, Grammar $grammar) => [(new MigrationIndex())->compileCommand($grammar, $this->table, $fluent, false)];
+        $this->commands[] = fn (Connection $connection, Grammar $grammar) => [(new MigrationIndex())->compileCommand($grammar, $this->table, $fluent, 'index')];
 
         return $fluent;
     }

src/Support/Helpers/MigrationIndex.php

@@ -18,7 +18,10 @@
  */
 class MigrationIndex
 {
-    public function compileCommand(Grammar $grammar, string $table, Fluent $command, bool $unique): string
+    /**
+     * @param 'index'|'primary'|'unique' $type
+     */
+    public function compileCommand(Grammar $grammar, string $table, Fluent $command, string $type): string
     {
         // If the index is partial index using a closure a dummy query builder is provided to the closure. The query is
         // then transformed to a static query and the select part is removed to only keep the condition.
@@ -72,20 +75,27 @@ public function compileCommand(Grammar $grammar, string $table, Fluent $command,
             $columns = ['('.implode(' || ', $columns).')'];
         }
 
-        $index = [
-            $unique ? 'create unique index' : 'create index',
-            $command['concurrently'] ? 'concurrently' : null,
-            $command['ifNotExists'] ? 'if not exists' : null,
-            $grammar->wrap($command['index']),
-            'on',
-            $grammar->wrapTable($table),
-            $command['algorithm'] ? "using {$command['algorithm']}" : null,
-            '('.implode(', ', $columns).')',
-            $command['include'] ? 'include ('.implode(',', $grammar->wrapArray(Arr::wrap($command['include']))).')' : null,
-            $command['nullsNotDistinct'] ? 'nulls not distinct' : null,
-            $command['with'] ? "with ({$command['with']})" : null,
-            $command['where'] ? "where {$command['where']}" : null,
-        ];
+        $index = match ($type) {
+            'index', 'unique' => [
+                'unique' === $type ? 'create unique index' : 'create index',
+                $command['concurrently'] ? 'concurrently' : null,
+                $command['ifNotExists'] ? 'if not exists' : null,
+                $grammar->wrap($command['index']),
+                'on',
+                $grammar->wrapTable($table),
+                $command['algorithm'] ? "using {$command['algorithm']}" : null,
+                '('.implode(', ', $columns).')',
+                $command['include'] ? 'include ('.implode(',', $grammar->wrapArray(Arr::wrap($command['include']))).')' : null,
+                $command['nullsNotDistinct'] ? 'nulls not distinct' : null,
+                $command['with'] ? "with ({$command['with']})" : null,
+                $command['where'] ? "where {$command['where']}" : null,
+            ],
+            'primary' => [
+                'alter table',
+                $grammar->wrapTable($table),
+                'add primary key ('.implode(', ', $columns).')',
+            ],
+        };
         $sql = implode(' ', array_filter($index, fn (?string $part) => filled($part)));
 
         return $sql;
@@ -104,6 +114,7 @@ public function createName(string $type, string $prefix, string $table, array $c
             true => substr_replace("{$table}.{$prefix}", strrpos($table, '.'), 1),
             false => $prefix.$table,
         };
+        $columns = array_map(fn (string $column) => Str::before($column, ' '), $columns);
 
         $index = strtolower($table.'_'.implode('_', $columns).'_'.$type);
 

tests/Migration/ForeignKeyTest.php

@@ -44,4 +44,22 @@ public function testNotEnforcedTrue(): void
         });
         $this->assertEquals(['alter table "test_861910" add constraint "test_861910_col_422395_foreign" foreign key ("col_422395") references "test_940615" ("col_422395") not enforced'], array_column($queries, 'query'));
     }
+
+    public function testPeriod(): void
+    {
+        if (Comparator::lessThan($this->getConnection()->serverVersion(), '18')) {
+            $this->markTestSkipped('Foreign key PERIOD is first supported with PostgreSQL 18.');
+        }
+
+        Schema::createExtensionIfNotExists('btree_gist');
+        $this->getConnection()->statement('CREATE TABLE test_668671 (col_975277 bigint, valid tstzrange, PRIMARY KEY (col_975277, valid WITHOUT OVERLAPS))');
+        $this->getConnection()->statement('CREATE TABLE test_178855 (col_975277 bigint, valid tstzrange, PRIMARY KEY (col_975277, valid WITHOUT OVERLAPS))');
+
+        $queries = $this->withQueryLog(function (): void {
+            Schema::table('test_178855', function (Blueprint $table): void {
+                $table->foreign(['col_975277', 'PERIOD valid'])->references(['col_975277', 'PERIOD valid'])->on('test_668671');
+            });
+        });
+        $this->assertEquals(['alter table "test_178855" add constraint "test_178855_col_975277_valid_foreign" foreign key ("col_975277", PERIOD "valid") references "test_668671" ("col_975277", PERIOD "valid")'], array_column($queries, 'query'));
+    }
 }

tests/Migration/IndexOptionsTest.php

@@ -695,6 +695,63 @@ public function testWithIndexByName(): void
         $this->assertEquals(['create index "index_477176" on "test_533609" ("col_889546") with (fillfactor = 80)'], array_column($queries, 'query'));
     }
 
+    public function testWithoutOverlapsPrimary(): void
+    {
+        if (Comparator::lessThan($this->getConnection()->serverVersion(), '18')) {
+            $this->markTestSkipped('WITHOUT OVERLAPS is first supported with PostgreSQL 18.');
+        }
+
+        Schema::createExtensionIfNotExists('btree_gist');
+        Schema::create('test_897145', function (Blueprint $table): void {
+            $table->string('col_301428');
+            $table->timestampTzRange('col_734356');
+        });
+        $queries = $this->withQueryLog(function (): void {
+            Schema::table('test_897145', function (Blueprint $table): void {
+                $table->primary(['col_301428', 'col_734356 WITHOUT OVERLAPS']);
+            });
+        });
+        $this->assertEquals(['alter table "test_897145" add primary key ("col_301428", "col_734356" WITHOUT OVERLAPS)'], array_column($queries, 'query'));
+    }
+
+    public function testWithoutOverlapsUniqueByColumn(): void
+    {
+        if (Comparator::lessThan($this->getConnection()->serverVersion(), '18')) {
+            $this->markTestSkipped('WITHOUT OVERLAPS is first supported with PostgreSQL 18.');
+        }
+
+        Schema::createExtensionIfNotExists('btree_gist');
+        Schema::create('test_849793', function (Blueprint $table): void {
+            $table->string('col_376999');
+            $table->timestampTzRange('col_513975');
+        });
+        $queries = $this->withQueryLog(function (): void {
+            Schema::table('test_849793', function (Blueprint $table): void {
+                $table->unique(['col_376999', 'col_513975 WITHOUT OVERLAPS']);
+            });
+        });
+        $this->assertEquals(['alter table "test_849793" add constraint "test_849793_col_376999_col_513975_unique" unique ("col_376999", "col_513975" WITHOUT OVERLAPS)'], array_column($queries, 'query'));
+    }
+
+    public function testWithoutOverlapsUniqueByName(): void
+    {
+        if (Comparator::lessThan($this->getConnection()->serverVersion(), '18')) {
+            $this->markTestSkipped('WITHOUT OVERLAPS is first supported with PostgreSQL 18.');
+        }
+
+        Schema::createExtensionIfNotExists('btree_gist');
+        Schema::create('test_224202', function (Blueprint $table): void {
+            $table->string('col_405091');
+            $table->timestampTzRange('col_427625');
+        });
+        $queries = $this->withQueryLog(function (): void {
+            Schema::table('test_224202', function (Blueprint $table): void {
+                $table->unique(['col_405091', 'col_427625 WITHOUT OVERLAPS'], 'index_142173');
+            });
+        });
+        $this->assertEquals(['alter table "test_224202" add constraint "index_142173" unique ("col_405091", "col_427625" WITHOUT OVERLAPS)'], array_column($queries, 'query'));
+    }
+
     public function testWithRawIndex(): void
     {
         if (Comparator::lessThan($this->app->version(), '7.7.0')) {