Add zero-downtime index deployments

Author: stevebauman

README.md

@@ -25,15 +25,15 @@ Publish the OpenSearch client configuration:
 php artisan vendor:publish --provider="DirectoryTree\OpenSearchClient\OpenSearchClientServiceProvider"
 ```
 
-Publish the migration configuration:
+Publish the migration and deployment configuration:
 
 ```bash
 php artisan vendor:publish --provider="DirectoryTree\OpenSearchMigrations\OpenSearchMigrationsServiceProvider"
 ```
 
 ## Configuration
 
-The migration configuration is published to `config/opensearch-migrations.php`:
+Migration history and index naming are configured in `config/opensearch-migrations.php`:
 
 ```php
 'table' => env('OPENSEARCH_MIGRATIONS_TABLE', 'opensearch_migrations'),
@@ -47,6 +47,17 @@ The migration configuration is published to `config/opensearch-migrations.php`:
 'alias_name_prefix' => env('OPENSEARCH_MIGRATIONS_ALIAS_NAME_PREFIX', env('SCOUT_PREFIX', '')),
 ```
 
+Deployment storage is configured separately in `config/opensearch-deployments.php`:
+
+```php
+'table' => env('OPENSEARCH_DEPLOYMENTS_TABLE', 'opensearch_deployments'),
+
+'connection' => env(
+    'OPENSEARCH_DEPLOYMENTS_CONNECTION',
+    env('OPENSEARCH_MIGRATIONS_CONNECTION')
+),
+```
+
 ## Creating Migrations
 
 Create a migration:
@@ -124,6 +135,74 @@ Show migration status:
 php artisan opensearch:migrate:status
 ```
 
+## Zero-Downtime Index Deployments
+
+The deployer creates versioned physical indexes and tracks their lifecycle in the `opensearch_deployments` table. Applications remain responsible for backfilling and validating candidate documents.
+
+First, create a stable alias for the index in a migration:
+
+```php
+Index::putAlias('posts', 'posts_search');
+```
+
+Start a deployment with the latest mapping and settings:
+
+```php
+use DirectoryTree\OpenSearchAdapter\Indices\Mapping;
+use DirectoryTree\OpenSearchAdapter\Indices\Settings;
+use DirectoryTree\OpenSearchMigrations\Deployer;
+
+$deployer = app(Deployer::class);
+
+$deployment = $deployer->start(
+    name: 'posts',
+    alias: 'posts_search',
+    configure: function (Mapping $mapping, Settings $settings) {
+        $mapping->text('title');
+        $mapping->text('body');
+    },
+);
+```
+
+The returned deployment exposes the physical candidate index for backfilling:
+
+```php
+$deployment->candidateIndex;
+```
+
+While backfilling, send live writes and deletions to every deployment write index:
+
+```php
+$deployment->writeIndexes();
+```
+
+After application-specific validation succeeds, mark the candidate ready and atomically move the alias:
+
+```php
+$deployer->markReady('posts');
+$deployer->cutover('posts');
+```
+
+Cancel and delete a candidate that should not be promoted:
+
+```php
+$deployer->cancel('posts');
+```
+
+The previous index remains in the deployment's write indexes during the rollback window:
+
+```php
+$deployer->rollback('posts');
+```
+
+Once the new index is verified in production, delete the previous physical index and complete the deployment:
+
+```php
+$deployer->retire('posts');
+```
+
+`opensearch:migrate:fresh` deletes all deployment records because it drops all physical indexes. Migration reset and refresh commands refuse to run while managed deployments exist.
+
 ## Credits
 
 This package builds on a lot of the foundation and prior work from [Ivan Babenko](https://github.com/babenkoivan) and his Elasticsearch Laravel ecosystem packages.

config/opensearch-deployments.php

@@ -0,0 +1,29 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Deployment Table
+    |--------------------------------------------------------------------------
+    |
+    | This table stores the state of versioned OpenSearch index deployments.
+    |
+    */
+
+    'table' => env('OPENSEARCH_DEPLOYMENTS_TABLE', 'opensearch_deployments'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Database Connection
+    |--------------------------------------------------------------------------
+    |
+    | This connection stores OpenSearch deployment state. When null, the
+    | application's default database connection will be used.
+    |
+    */
+
+    'connection' => env(
+        'OPENSEARCH_DEPLOYMENTS_CONNECTION',
+        env('OPENSEARCH_MIGRATIONS_CONNECTION')
+    ),
+];

src/Console/FreshCommand.php

@@ -4,6 +4,7 @@
 
 use DirectoryTree\OpenSearchMigrations\IndexManagerInterface;
 use DirectoryTree\OpenSearchMigrations\Migrator;
+use DirectoryTree\OpenSearchMigrations\Repositories\DeploymentRepository;
 use DirectoryTree\OpenSearchMigrations\Repositories\MigrationRepository;
 use Illuminate\Console\Command;
 use Illuminate\Console\ConfirmableTrait;
@@ -33,6 +34,7 @@ public function handle(
         Migrator $migrator,
         IndexManagerInterface $index,
         MigrationRepository $migrations,
+        DeploymentRepository $deployments,
     ): int {
         $migrator->setOutput($this->output);
 
@@ -41,10 +43,12 @@ public function handle(
         }
 
         $migrator->prepare();
+        $deployments->prepare();
 
         $index->drop('*');
 
         $migrations->deleteAll();
+        $deployments->deleteAll();
 
         $migrator->migrateAll();
 

src/Console/RefreshCommand.php

@@ -3,6 +3,7 @@
 namespace DirectoryTree\OpenSearchMigrations\Console;
 
 use DirectoryTree\OpenSearchMigrations\Migrator;
+use DirectoryTree\OpenSearchMigrations\Repositories\DeploymentRepository;
 use Illuminate\Console\Command;
 use Illuminate\Console\ConfirmableTrait;
 
@@ -31,7 +32,7 @@ class RefreshCommand extends Command
     /**
      * Execute the console command.
      */
-    public function handle(Migrator $migrator): int
+    public function handle(Migrator $migrator, DeploymentRepository $deployments): int
     {
         $migrator->setOutput($this->output);
 
@@ -40,6 +41,13 @@ public function handle(Migrator $migrator): int
         }
 
         $migrator->prepare();
+        $deployments->prepare();
+
+        if ($deployments->exists()) {
+            $this->components->error('Managed indexes cannot be refreshed. Use opensearch:migrate:fresh to discard them.');
+
+            return static::FAILURE;
+        }
 
         $migrator->rollbackAll();
         $migrator->migrateAll();

src/Console/ResetCommand.php

@@ -3,6 +3,7 @@
 namespace DirectoryTree\OpenSearchMigrations\Console;
 
 use DirectoryTree\OpenSearchMigrations\Migrator;
+use DirectoryTree\OpenSearchMigrations\Repositories\DeploymentRepository;
 use Illuminate\Console\Command;
 use Illuminate\Console\ConfirmableTrait;
 
@@ -31,7 +32,7 @@ class ResetCommand extends Command
     /**
      * Execute the console command.
      */
-    public function handle(Migrator $migrator): int
+    public function handle(Migrator $migrator, DeploymentRepository $deployments): int
     {
         $migrator->setOutput($this->output);
 
@@ -40,6 +41,13 @@ public function handle(Migrator $migrator): int
         }
 
         $migrator->prepare();
+        $deployments->prepare();
+
+        if ($deployments->exists()) {
+            $this->components->error('Managed indexes cannot be reset. Use opensearch:migrate:fresh to discard them.');
+
+            return static::FAILURE;
+        }
 
         $migrator->rollbackAll();