README

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

内容

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

兼容性

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

PHP 7.4-8.0
OpenSearch 2.x
Laravel 6.x-9.x

安装

可以通过 Composer 安装此库

composer require friendsofcat/opensearch-migrations

如果您想使用 Lumen 框架与 OpenSearch Migrations 结合使用，请查看本指南。

配置

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

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

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

建议同时发布 OpenSearch Migrations 设置

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 Migrations 如何加载它们

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

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

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

迁移状态

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

php artisan opensearch:migrate:status

零停机迁移

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

故障排除

如果您看到以下消息之一，请遵循说明

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

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

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

friendsofcat / opensearch-migrations

维护者

详细信息