README

Laravel的Elastic Migrations允许您轻松修改和共享应用程序环境中的索引模式。

内容

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

兼容性

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

PHP 8.2
Elasticsearch 8.x
Laravel 11.x

如果您的项目使用较旧的Laravel（或PHP）版本，请检查此包的先前主要版本。

安装

该库可以通过Composer安装

composer require babenkoivan/elastic-migrations

如果您想使用Lumen框架与Elastic Migrations一起使用，请查看此指南。

配置

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

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

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

建议发布Elastic Migrations设置

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

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

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

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

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

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

php artisan migrate

编写迁移

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

// create a migration file with "create_my_index.php" name in the default directory
php artisan elastic: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 elastic:make:migration /my_path/create_my_index.php

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

您可以使用Elastic\Migrations\Facades\Index外观来执行对Elasticsearch索引的基本操作

创建索引

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

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');

多个连接

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

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

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

运行迁移

您可以运行所有迁移

php artisan elastic:migrate

或者运行特定的一个

// execute a migration located in one of the registered paths
php artisan elastic: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 elastic:migrate /my_path/2018_12_01_081000_create_my_index.php

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

php artisan elastic:migrate --force

回滚迁移

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

php artisan elastic:migrate:rollback

或者回滚特定的一个

// rollback a migration located in one of the registered paths
php artisan elastic: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 elastic:migrate:rollback /my_path/2018_12_01_081000_create_my_index

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

php artisan elastic:migrate:reset

重新开始

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

php artisan elastic:migrate:refresh

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

php artisan elastic:migrate:fresh

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

迁移状态

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

php artisan elastic:migrate:status

您还可以仅显示挂起的迁移

php artisan elastic:migrate:status --pending

零停机时间迁移

在不中断服务的情况下更改索引映射不是一件简单的事情，并且可能因项目而异。Elastic Migrations 库不自带此功能，但您可以通过遵循此指南在您的项目中实现它。

故障排除

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

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

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

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

babenkoivan / elastic-migrations

维护者

详情