README

Laravel 的 OpenSearch 迁移允许您轻松地在应用程序的不同环境中修改和共享索引模式。

内容

兼容性
安装
配置
编写迁移
运行迁移
撤销迁移
重新开始
迁移状态
零停机时间迁移
故障排除

兼容性

当前版本的 OpenSearch 迁移已与以下配置进行了测试

PHP 7.4-8.x
OpenSearch 2.x
Laravel 6.x-10.x

安装

您可以通过 Composer 安装此库

composer require haridarshan/opensearch-migrations

如果您想使用 Lumen 框架的 OpenSearch 迁移，请查看此指南。

配置

OpenSearch 迁移使用 haridarshan/opensearch-client 作为依赖项。要更改客户端设置，您需要首先发布配置文件

php artisan vendor:publish --provider="OpenSearch\Laravel\Client\ServiceProvider"

在新建的 config/opensearch.client.php 文件中，您可以定义默认连接名称，并使用配置哈希描述多个连接。有关更多详细信息，请参阅opensearch-client 文档。

建议同时发布 OpenSearch 迁移设置

php artisan vendor:publish --provider="OpenSearch\Migrations\ServiceProvider"

这将创建 config/opensearch.migrations.php 文件，允许您配置以下选项

storage.default_path - 迁移文件的默认位置
database.table - 存储已执行迁移名称的表名
database.connection - 您希望使用的数据库连接
prefixes.index - 您索引的前缀
prefixes.alias - 您别名的前缀

如果您将一些迁移文件存储在默认路径之外，并希望它们被包可见，您可以使用 registerPaths 方法通知 OpenSearch 迁移如何加载它们

class MyAppServiceProvider extends Illuminate\Support\ServiceProvider
{
    public function boot()
    {
        resolve(MigrationStorage::class)->registerPaths([
            '/my_app/opensearch/migrations1',
            '/my_app/opensearch/migrations2',
        ]);
    }
}

最后，不要忘记运行 Laravel 数据库迁移以创建 OpenSearch 迁移表

php artisan migrate

编写迁移

您可以使用 Artisan 控制台命令轻松创建新的迁移文件

// create a migration file with "create_my_index.php" name in the default directory
php artisan opensearch:make:migration create_my_index

// create a migration file with "create_my_index.php" name in "/my_path" directory 
// note, that you need to specify the full path to the file in this case
php artisan opensearch:make:migration /my_path/create_my_index.php

每个迁移都有两个方法： up 和 down。 up 用于更改索引模式，down 用于撤销该操作。

您可以使用 OpenSearch\Migrations\Facades\Index 门面在 OpenSearch 索引上执行基本操作

创建索引

您可以使用默认设置创建索引

Index::create('my-index');

您可以使用修饰符来配置映射和设置

Index::create('my-index', function (Mapping $mapping, Settings $settings) {
    // to add a new field to the mapping use method name as a field type (in Camel Case), 
    // first argument as a field name and optional second argument for additional field parameters  
    $mapping->text('title', ['boost' => 2]);
    $mapping->float('price');

    // you can define a dynamic template as follows
    $mapping->dynamicTemplate('my_template_name', [
        'match_mapping_type' => 'long',
        'mapping' => [
            'type' => 'integer',
        ],
    ]);
    
    // you can also change the index settings and the analysis configuration
    $settings->index([
         'number_of_replicas' => 2,
         'refresh_interval' => -1
    ]);
    
    $settings->analysis([
        'analyzer' => [
            'title' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'    
            ]
        ]
    ]);
});

您还可以使用 createRaw 方法

$mapping = [
    'properties' => [
        'title' => [
            'type' => 'text'
        ]
    ]
];

$settings = [
    'number_of_replicas' => 2
];

Index::createRaw('my-index', $mapping, $settings);

最后，如果索引不存在，则可以创建索引

// you can use a modifier as shown above
Index::createIfNotExists('my-index', $modifier);
// or you can use raw mapping and settings 
Index::createIfNotExistsRaw('my-index', $mapping, $settings);

更新映射

您可以使用修饰符来调整映射

Index::putMapping('my-index', function (Mapping $mapping) {
    $mapping->text('title', ['boost' => 2]);
    $mapping->float('price');
});

或者，您可以使用以下方式的 putMappingRaw 方法

Index::putMappingRaw('my-index', [
    'properties' => [
        'title' => [
            'type' => 'text',
            'boost' => 2
        ],
        'price' => [
            'price' => 'float'
        ]      
    ]   
]);

更新设置

您可以使用修饰符来更改索引配置

Index::putSettings('my-index', function (Settings $settings) {
    $settings->index([
         'number_of_replicas' => 2,
         'refresh_interval' => -1
    ]);
});

使用 putSettingsRaw 方法可以实现相同的结果

Index::putSettingsRaw('my-index', [
    'index' => [
        'number_of_replicas' => 2,
        'refresh_interval' => -1
    ]
]);

在关闭索引上可以更新分析设置。 pushSettings 方法关闭索引，更新配置，然后再次打开索引

Index::pushSettings('my-index', function (Settings $settings) {
    $settings->analysis([
        'analyzer' => [
            'title' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'
            ]
        ]
    ]);
});

使用 pushSettingsRaw 方法也可以实现相同的效果

Index::pushSettingsRaw('my-index', [
    'analysis' => [
        'analyzer' => [
            'title' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'
            ]
        ]
    ]
]);

删除索引

您可以无条件删除索引

Index::drop('my-index');

或者仅当索引存在时删除它

Index::dropIfExists('my-index');

创建别名

您可以使用可选的筛选查询创建别名

Index::putAlias('my-index', 'my-alias', [
    'is_write_index' => true,
    'filter' => [
        'term' => [
            'user_id' => 1,
        ],
    ],
]);

删除别名

您可以通过名称删除别名

Index::deleteAlias('my-index', 'my-alias');

多个连接

您可以在客户端配置文件中配置多个连接到OpenSearch，然后为每个操作使用不同的连接

Index::connection('my-connection')->drop('my-index');

最后，您可以在迁移构造函数中注入OpenSearch\Client并执行客户端支持的所有操作。

运行迁移

您可以选择运行所有迁移

php artisan opensearch:migrate

或者运行特定的一个

// execute a migration located in one of the registered paths
php artisan opensearch:migrate 2018_12_01_081000_create_my_index

// execute a migration located in "/my_path" directory
// note, that you need to specify the full path to the file in this case
php artisan opensearch:migrate /my_path/2018_12_01_081000_create_my_index.php

如果您想在生产环境中执行迁移，请使用--force选项

php artisan opensearch:migrate --force

撤销迁移

您可以选择回滚最后一次执行的迁移

php artisan opensearch:migrate:rollback

或者回滚特定的一个

// rollback a migration located in one of the registered paths
php artisan opensearch:migrate:rollback 2018_12_01_081000_create_my_index

// rollback a migration located in "/my_path" directory
// note, that you need to specify the full path to the file in this case
php artisan opensearch:migrate:rollback /my_path/2018_12_01_081000_create_my_index

如果您想回滚所有之前迁移的文件，请使用opensearch:migrate:reset命令

php artisan opensearch:migrate:reset

重新开始

有时您可能只想从头开始，回滚所有更改并重新应用

php artisan opensearch:migrate:refresh

或者您也可以删除所有现有索引并重新运行迁移

php artisan opensearch:migrate:fresh

注意此命令使用通配符删除索引。这需要将action.destructive_requires_name设置为false。

迁移状态

您可以使用opensearch:migrate:rollback命令（最后一批）始终检查哪些文件已经迁移以及哪些可以回滚

php artisan opensearch:migrate:status

您还可以只显示待处理的迁移

php artisan opensearch:migrate:status --pending

零停机时间迁移

在不中断服务的情况下更改索引映射不是一个简单的过程，并且可能因项目而异。OpenSearch迁移库不包含此功能，但您可以通过遵循此指南在项目中实现此功能。

故障排除

如果您看到以下消息之一，请按照说明操作

迁移表尚未创建 - 运行php artisan migrate命令
迁移目录尚未创建 - 使用opensearch:make:migration命令创建迁移文件或手动创建migrations目录

如果某个命令未按预期工作，请尝试发布配置

php artisan vendor:publish --provider="OpenSearch\Migrations\ServiceProvider"

haridarshan / opensearch-migrations

维护者

详细信息