README

使用这个 Symfony bundle，您可以在 Couchbase 数据库中生成和执行迁移。它的工作方式类似于 Doctrine Migrations。

• 生成空白迁移，并填充它们以创建新的索引或更新/删除文档。
• 它检查已经执行和尚未执行的迁移。
• 可通过 Symfony 命令使用。

先决条件

• PHP 8.3 或更高版本，并安装 Couchbase 扩展

安装和设置

通过 composer 安装该 bundle。

composer require bowlofsoup/couchbase-migrations-bundle

将 bundle 添加到您的 AppKernel.php 文件。

$bundles = [
    ...
    new \BowlOfSoup\CouchbaseMigrationsBundle\CouchbaseMigrationsBundle()
    ...
];

在您的 app 目录中创建一个 CouchbaseMigrations 目录。这将包含所有生成的空白迁移。

$ mkdir CouchbaseMigrations

添加 config/packages/couchbase_migrations_bundle.yaml。

couchbase_migrations:
    host: '%env(COUCHBASE_MIGRATIONS_HOST)%'
    user: '%env(COUCHBASE_MIGRATIONS_USER)%'
    password: '%env(COUCHBASE_MIGRATIONS_PASSWORD)%'
    bucket_migrations: '%env(COUCHBASE_MIGRATIONS_BUCKET_MIGRATIONS)%'
    bucket_default: '%env(COUCHBASE_MIGRATIONS_DEFAULT_BUCKET)%'

可选：如果您不是使用标准端口，也可以配置端口号。

couchbase_migrations:
    port: '%env(COUCHBASE_MIGRATIONS_PORT)%'

在您的 .env 文件中，定义上述值

COUCHBASE_MIGRATIONS_HOST="127.0.0.1"
COUCHBASE_MIGRATIONS_USER="couchbase_user"
COUCHBASE_MIGRATIONS_PASSWORD="couchbase_password"
COUCHBASE_MIGRATIONS_BUCKET_MIGRATIONS="default"
COUCHBASE_MIGRATIONS_DEFAULT_BUCKET="default"

• bucket_migrations 必须包含您想要存储已执行迁移的 bucket。不是强制性的，但此时必须可以访问名为 migrations 的 bucket。
• bucket_default 必须包含您的默认 bucket。如果您没有默认 bucket，请使用 %couchbase_migrations.bucket_migrations% 作为选项。

使用方法

生成迁移

bin/console couchbase:migrations:generate

这将为您在 CouchbaseMigrations/ 中生成一个空白迁移文件以填充。

迁移所有

bin/console couchbase:migrations:migrate

这将执行所有尚未完成的迁移。

配置的 bucket（配置文件中的 bucket_migrations）将包含一个文档（migrations::versions），其中包含已迁移的内容。

执行单个迁移

bin/console couchbase:migrations:execute VERSION_NUMBER [--no-verbose] [--down]

这将执行给定的版本（CouchbaseMigrations/ 中的文件）。用您想要执行的版本（文件的 日期时间部分）替换 VERSION_NUMBER。您可以无限期地执行一个版本：将不会被跟踪。

清除 bucket 中的所有数据（除迁移外）

bin/console couchbase:migrations:flush-data BUCKET_NAME

清除 bucket 中的所有数据，如果启用了该 bucket 的清除功能，则除迁移版本文档外。用您想要清除数据的 bucket 名称替换 BUCKET_NAME。默认为配置的 bucket。

如果您想重置 bucket 中的所有数据，但又不想丢失迁移，这将很有用。

创建一个 bucket

bin/console couchbase:migrations:create-bucket [BUCKET_NAME] [--index]

创建一个 bucket，可选名称（采用默认配置）和可选创建主索引。

删除一个 bucket

bin/console couchbase:migrations:remove-bucket [BUCKET_NAME]

创建一个 bucket，可选名称（采用默认配置）。

如何编写迁移

当您生成迁移时，打开文件并使用 up 函数。示例

public function up()
{
    // Use only if you want to select a different bucket than the one configured.
    $this->selectBucket('some-other-bucket-name');

    $this->bucketRepository->query(
        'CREATE INDEX `i_someindexname` ON `bucketname`(`propertyname`) WHERE (`someotherpropertyname` = "propertycontent")'
    );
}

或

public function up()
{
    // Use only if you want to select a different bucket than the one configured.
    $bucket = $this->selectBucket('some-other-bucket-name');

    $result = $bucket->get('some-document-key');
    $documentContent = $result->value;

    $bucket->insert('some-other-document-key', $documentContent);
}

降级也支持 execute 命令，只需在迁移中添加一个 down() 方法。

public function down()
{
    $this->bucketRepository->query(
        'the opposite of the up() query'
    );
}

所以

• 可以使用 $this->bucketRepository 来简化对 bucket 的查询（如命名参数）。
• 您还可以直接使用 $this->selectBucket() 的返回值对 bucket 执行操作。

注意：由 selectBucket() 返回的 Bucket 和由 $bucket->get() 返回的结果都是向后兼容的小类，以避免破坏使用此 bundle 的先前版本定义的旧迁移。如果您需要实际的 Couchbase Bucket，您可以使用 $bucket->getBucket()，如果您需要实际的 Couchbase 结果，您可以通过调用 $result->getResult() 获取。

如何作为独立应用程序使用

您可以使用这个包作为独立应用程序，因此，不要在 Symfony 安装中使用它。这也非常适合开发。

• 检查这个仓库，并在 src 目录下创建一个 app 目录。
• 创建一个 src/CouchbaseMigrations 目录。
• 创建一个包含配置参数的 src/app/parameters.yml 文件。

在 src/app/parameters.yml 文件中填充以下内容：

parameters:
  kernel.project_dir:

  couchbase_bucket:

  couchbase_migrations.bucket_migrations:
  couchbase_migrations.host:
  couchbase_migrations.user:
  couchbase_migrations.password:

• kernel.project_dir 选项必须包含 src 目录的完整路径。
• 有关选项的更多信息，请参阅“安装和设置”。

贡献

您非常欢迎fork这个仓库，进行更改并创建一个 pull request。

• 创建一个问题，并说明您想要做出的更改。
• 在您的提交信息中，引用这个问题。
• 在提交代码更改之前，请确保运行 vendor/bin/php-cs-fixer fix。这将使更改后的代码符合编码标准。

升级到 2.x

当您从 1.0 版本升级时，您需要做两件事

• 根据上述信息更新配置
• 移动迁移的路径。在新的 Symfony 版本中，app/ 目录已不存在，CouchbaseMigrations 文件夹现在应在您的项目根目录下