feat(migration): timescale support (resolves #103)

Author: tpetry

.github/workflows/phpunit.yml

@@ -76,7 +76,7 @@ jobs:
 
     services:
       postgres:
-        image: ankane/pgvector
+        image: timescale/timescaledb-ha:pg17
         env:
           POSTGRES_PASSWORD: postgres
         ports:

README.md

@@ -83,7 +83,8 @@ The minimal breaking changes of the past years are listed in the [breaking chang
     - [Refresh Data on Save](#refresh-data-on-save)
     - [Date Formats](#date-formats)
 - [Expressions](#expressions)
-
+- [Supported Extensions](#supported-extensions)
+    - [Timescale](#timescale)
 ## IDE Autocomplete
 
 Laravel provides many extension capabilities, making it hard for IDEs to do proper autocomplete.
@@ -1338,6 +1339,93 @@ Schema::create('comments', function (Blueprint $table) {
 });        
 ```
 
+# Supported Extensions
+
+You can use any extension with this PostgreSQL you like but some have received a deeper Laravel integration.
+
+## Timescale
+
+Timescale is fantastic and has many features.
+Therefore, it is impossible to explain everything here; consult their docs about the different features this extension provides.
+Here's a list of supported features and an example showcasing its usage:
+
+| Feature               | Actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Hypertable            | `new CreateHypertable(string $column, string\|int $interval, string $partitionFunction = null)`<br/>`new ChangeChunkTimeInterval(string\|int $interval)`                                                                                                                                                                                                                                                                                                                            |
+| Chunk Skipping        | `new EnableChunkSkipping(string $column)`<br/>`new DisableChunkSkipping(string $column)`                                                                                                                                                                                                                                                                                                                                                                                            |
+| Compression           | `new EnableCompression(string\|array $orderBy = null, string\|array $segmentBy = null)`<br/> `new DisableCompression()`<br/>`new CreateCompressionPolicy(string\|int $compressAfter)`<br/>`new DropCompressionPolicy()`<br/>`new CompressChunks(DateTimeInterface\|string\|int $olderThan = null, DateTimeInterface\|string\|int $newerThan = null)`<br/>`new DecompressChunks(DateTimeInterface\|string\|int $olderThan = null, DateTimeInterface\|string\|int $newerThan = null)` |
+| Reordering            | `new CreateReorderPolicy(string $index)`<br/>`new CreateReorderPolicyByIndex(...$columns)`<br/>`new CreateReorderPolicyByUnique(...$columns)`<br/>`new DropReorderPolicy()`<br/>`new ReorderChunks(DateTimeInterface\|string\|int $olderThan = null, DateTimeInterface\|string\|int $newerThan = null)`                                                                                                                                                                             |
+| Data Retention        | `new CreateRetentionPolicy(string\|int $dropAfter)`<br/>`new DropRetentionPolicy()`<br/>`new DropChunks(DateTimeInterface\|string\|int $olderThan = null, DateTimeInterface\|string\|int $newerThan = null)`                                                                                                                                                                                                                                                                        |
+| Tiered Storage        | `new CreateTieringPolicy(string\|int $dropAfter)`<br/>`new DropTieringPolicy()`<br/>`new TierChunks(DateTimeInterface\|string\|int $olderThan = null, DateTimeInterface\|string\|int $newerThan = null)`<br/>`new UntierChunks(DateTimeInterface\|string\|int $olderThan = null, DateTimeInterface\|string\|int $newerThan = null)`                                                                                                                                                 |
+| Continuous Aggregates | `new CreateRefreshPolicy(string $interval, string\|int\|null $start, string\|int\|null $end)`<br/>`new DropRefreshPolicy()`<br/>`new RefreshData(DateTimeInterface\|int\|null $start, DateTimeInterface\|int\|null $end)`                                                                                                                                                                                                                                                           |
+
+```php
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Migrations\Migration;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\CreateCompressionPolicy;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\CreateHypertable;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\CreateRefreshPolicy;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\CreateReorderPolicyByIndex;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\CreateRetentionPolicy;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\EnableChunkSkipping;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\EnableCompression;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\CaggBlueprint;
+use Tpetry\PostgresqlEnhanced\Support\Facades\Schema;
+use Tpetry\PostgresqlEnhanced\Schema\Blueprint;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::createExtensionIfNotExists('timescaledb');
+
+        Schema::create('visits', function (Blueprint $table) {
+            $table->identity();
+            $table->bigInteger('website_id');
+            $table->text('url');
+            $table->float('duration');
+            $table->timestampTz('created_at')->nullable();
+
+            $table->primary(['id', 'created_at']);
+            $table->index(['website_id', 'created_at']);
+
+            $table->timescale(
+                new CreateHypertable('created_at', '1 day'),
+                new CreateReorderPolicyByIndex('website_id', 'created_at'),
+                new EnableCompression(segmentBy: 'website_id'),
+                new CreateCompressionPolicy('3 days'),
+                new CreateRetentionPolicy('1 year'),
+                new EnableChunkSkipping('id'),
+            );
+        });
+
+        Schema::continuousAggregate('visits_agg', function(CaggBlueprint $table) {
+            $table->as("
+                SELECT
+                    time_bucket('1 hour', created_at) AS bucket,
+                    website_id,
+                    url,
+                    SUM(duration) AS duration
+                FROM visits
+                GROUP BY bucket, website_id, url
+            ");
+            $table->realtime();
+            $table->index(['website_id','url']);
+
+            $table->timescale(
+                new CreateRefreshPolicy('5 minutes', '1 days', '2 hours'),
+                new EnableCompression(),
+                new CreateCompressionPolicy('2 days'),
+            );
+        });
+    }
+};
+```
+
+> [!WARNING]
+> Indexes are not automatically created when creating hypertables or continuous aggregates.
+> You have to create them manually.
+
 # Breaking Changes
 
 * **2.0.0**

src/Schema/BlueprintTable.php

@@ -5,9 +5,22 @@
 namespace Tpetry\PostgresqlEnhanced\Schema;
 
 use Illuminate\Support\Fluent;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\Action;
 
 trait BlueprintTable
 {
+    /**
+     * Set timescale hypertable options.
+     *
+     * @param Action ...$actions
+     */
+    public function timescale(...$actions): void
+    {
+        foreach ($actions as $action) {
+            $this->addCommand('timescale', ['action' => $action]);
+        }
+    }
+
     /**
      * Set a table to be (un)logged.
      */

src/Schema/BuilderView.php

@@ -4,11 +4,22 @@
 
 namespace Tpetry\PostgresqlEnhanced\Schema;
 
+use Closure;
 use Illuminate\Database\Query\Builder as QueryBuilder;
+use Tpetry\PostgresqlEnhanced\Schema\Timescale\CaggBlueprint;
 use Tpetry\PostgresqlEnhanced\Support\Helpers\Query;
 
 trait BuilderView
 {
+    /**
+     * Create/Modify a continuous aggregate on the schema.
+     */
+    public function continuousAggregate($table, Closure $callback): void
+    {
+        $blueprint = new CaggBlueprint($table, $callback);
+        $blueprint->build($this->getConnection(), $this->getConnection()->getSchemaGrammar());
+    }
+
     /**
      * Create a materialized view on the schema.
      */
@@ -74,6 +85,22 @@ public function createViewOrReplace(string $name, QueryBuilder|string $query, ar
         $this->getConnection()->statement("create or replace view {$name} as {$query}");
     }
 
+    /**
+     * Drop continuous aggregates from the schema.
+     */
+    public function dropContinuousAggregate(string ...$name): void
+    {
+        $this->dropMaterializedView(...$name);
+    }
+
+    /**
+     * Drop continuous aggregates from the schema if they exist.
+     */
+    public function dropContinuousAggregateIfExists(string ...$name): void
+    {
+        $this->dropMaterializedViewIfExists(...$name);
+    }
+
     /**
      * Drop materialized views from the schema.
      */

src/Schema/Grammars/Grammar.php

@@ -12,6 +12,7 @@ class Grammar extends PostgresGrammar
     use GrammarBackportEscape;
     use GrammarIndex;
     use GrammarTable;
+    use GrammarTimescale;
     use GrammarTrigger;
     use GrammarTypes;
 

src/Schema/Grammars/GrammarIndex.php

@@ -146,10 +146,7 @@ private function genericCompileCreateIndex(Blueprint $blueprint, Fluent $command
 
             // In case index parameters are provided the column needs to escaped correctly and the rest is provided
             // exactly as provided.
-            $parts = explode(' ', $column, 2);
-            $column = trim(\sprintf('%s %s', $this->wrap($parts[0]), $parts[1] ?? ''));
-
-            return $column;
+            return $this->columnizeWithSuffix([$column]);
         }, $command['columns']);
 
         // A fulltext index needs special handling to wrap the columns into to_tsvector calls.

src/Schema/Grammars/GrammarTimescale.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\PostgresqlEnhanced\Schema\Grammars;
+
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Fluent;
+
+trait GrammarTimescale
+{
+    /**
+     * Compile a timescale action command.
+     */
+    public function compileTimescale(Blueprint $blueprint, Fluent $command): array
+    {
+        /** @var \Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions\Action $action */
+        $action = $command->get('action');
+
+        return $action->getValue($this, $blueprint->getTable());
+    }
+}

src/Schema/Timescale/Actions/Action.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions;
+
+use Tpetry\PostgresqlEnhanced\Schema\Grammars\Grammar;
+
+/**
+ * @internal
+ */
+interface Action
+{
+    public function getValue(Grammar $grammar, string $table): array;
+}

src/Schema/Timescale/Actions/ChangeChunkTimeInterval.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions;
+
+use Tpetry\PostgresqlEnhanced\Schema\Grammars\Grammar;
+
+class ChangeChunkTimeInterval implements Action
+{
+    public function __construct(
+        private string|int $interval,
+    ) {
+    }
+
+    public function getValue(Grammar $grammar, string $table): array
+    {
+        return match (is_numeric($this->interval)) {
+            true => ["select set_chunk_time_interval({$grammar->escape($table)}, {$this->interval})"],
+            false => ["select set_chunk_time_interval({$grammar->escape($table)}, interval '{$this->interval}')"],
+        };
+    }
+}

src/Schema/Timescale/Actions/CompressChunks.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tpetry\PostgresqlEnhanced\Schema\Timescale\Actions;
+
+use Tpetry\PostgresqlEnhanced\Schema\Grammars\Grammar;
+
+class CompressChunks extends ShowChunks
+{
+    public function getValue(Grammar $grammar, string $table): array
+    {
+        return ["select compress_chunk(c) from {$this->getShowChunksCall($grammar, $table)} c"];
+    }
+}