trysharpen / versionna

Sharpen Versionna is a PHP migration system to manage versioning of Manticoresearch. It includes a CLI tool to keep your Manticore index schemas and your data on sync.

versionna

Manticoresearch migration tool. Keep updated your index schemas up to date using an executable CLI script or integrate it programmatically in your application code.

Table of contents

• versionna
• Table of contents
  • project progress and roadmap
  • Installation
  • Usage
    • Create migration
      • CLI
      • programmatically
    • Apply migrations
      • CLI
      • programmatically
    • Rollback migration
      • CLI
      • programmatically
    • List migrations applied history
      • CLI
      • programmatically
    • List pending migrations
      • CLI
      • programmatically

project progress and roadmap

• Add CI pipeline
  • Add PHP versions supported
    • 8.0
    • 8.1
    • 8.2
  • PhpStan
  • PHPUnit run tests
• Pre-commit linter and tests checks
  • Add Grumphp
    • PHPStan
    • PHPUnit
• Add a logger implementation
• Add docker-compose stack files for testing and development
• Add code documentation
• Write a complete README file explaining all
• Add unit and integration tests
• Add command line interface feature
  • Add cli application metadata such as name, description, etc.
  • Created structure of the CLI application
• Executable script (bin/versionna)
• Add commands
  • list
  • make:config
  • make:migration
  • migration:list:pending
  • migration:list:migrated
  • migrate
  • rollback
  • rollback with --steps
  • fresh
  • refresh
  • refresh with --steps
  • reset
  • status
  • help
• Add drivers to support multiple DBs engines dialects
  • Add driver for SQLite
  • Add driver for MySQL
  • Add driver for PostgreSQL
• Create a Laravel package
• Create a Symfony package

Installation

composer require sharpen/versionna

Usage

First of all, you need to install the package.

composer require sharpen/versionna

After been installed, you need to create a directory. That directory will contain the migration files sorted by creation date.

You have two different ways to use this package:

• programmatically
• CLI

You can create your own integration with versionna using the programmatically way as you can see in hte examples directory in this repository.

In each section of these documentation you will see both: programmatically and CLI version to create, migrate, rollback, list applied and pending migrations.

Create migration

CLI

To create a migration file you have to use the make:migration and the class name (the migration class name that extends Migration class) using snake_case_style. This class name should be a descriptive name. It's better a long name for two reasons:

• to better understand what the migration does
• and for avoid duplicated class names

./vendor/bin/versionna make:migration -c config.php create_products_index

programmatically

<?php

use Sharpen\Versionna\MigrationCreator;

$configuration = require 'config.php';

$migrationName = 'create_users_index';
$description = 'users initial definition of the rt index';
$migrationCreator = new MigrationCreator(
    $configuration['migrations_path'],
    $migrationName,
    $description,
);

$migrationCreator->create();

echo 'Migration created successfully';

Apply migrations

CLI

There are two available commands for apply pending migrations using the Command Line Interface

./vendor/bin/versionna migrate -c config.php

./vendor/bin/versionna migrate:up -c config.php

programmatically

<?php

use Sharpen\Versionna\Manticore\ManticoreConnection;
use Sharpen\Versionna\MigrationDirector;
use Sharpen\Versionna\Storage\DatabaseConfiguration;
use Sharpen\Versionna\Storage\DatabaseConnection;
use Sharpen\Versionna\Storage\MigrationTable;

$configuration = require 'config.php';

$dbConnection = new DatabaseConnection(
    DatabaseConfiguration::fromArray(
        $configuration['connections']['mysql']
    )
);

$manticoreConnection = new ManticoreConnection(
    $configuration['manticore_connection']['host'],
    $configuration['manticore_connection']['port'],
);

$migrationTable = new MigrationTable(
    $dbConnection,
    $configuration['table_prefix'],
    $configuration['migration_table'],
);

$director = new MigrationDirector();

$director
    ->dbConnection($dbConnection)
    ->manticoreConnection($manticoreConnection)
    ->migrationsPath($configuration['migrations_path'])
    ->migrationTable($migrationTable);

if (! $migrationTable->exists()) {
    echo 'Migration table doesn\'t exist';
    exit(1);
} elseif (! $director->hasPendingMigrations()) {
    echo 'No pending migrations';

    exit(0);
}

try {
    $director->migrate();
} catch (Exception $exception) {
    echo $exception->getMessage();

    exit(1);
}

echo 'Applied all migrations';

Rollback migration

CLI

There are two available commands to rollback applied migrations using the Command Line Interface

./vendor/bin/versionna rollback -c config.php

./vendor/bin/versionna migrate:down -c config.php

programmatically

<?php

use Sharpen\Versionna\Manticore\ManticoreConnection;
use Sharpen\Versionna\MigrationDirector;
use Sharpen\Versionna\Storage\DatabaseConfiguration;
use Sharpen\Versionna\Storage\DatabaseConnection;
use Sharpen\Versionna\Storage\MigrationTable;

$configuration = require 'config.php';

$dbConnection = new DatabaseConnection(
  DatabaseConfiguration::fromArray(
    $configuration['connections']['mysql']
  ),
);

$manticoreConnection = new ManticoreConnection(
  $configuration['manticore_connection']['host'],
  $configuration['manticore_connection']['port'],
);

$migrationTable = new MigrationTable(
  $dbConnection,
  $configuration['table_prefix'],
  $configuration['migration_table']
);

$director = new MigrationDirector();
$director
  ->dbConnection($dbConnection)
  ->manticoreConnection($manticoreConnection)
  ->migrationsPath($configuration['migrations_path'])
  ->migrationTable($migrationTable);

$steps = 1;

$director->undoMigrations($steps);

List migrations applied history

CLI

For list pending migrations using the Command Line tool

./vendor/bin/versionna migration:list:pending -c config.php

programmatically

<?php

$configuration = require 'config.php';

$dbConnection = new DatabaseConnection(
    DatabaseConfiguration::fromArray(
        $configuration['connections']['mysql']
    )
);

$migrationTable = new MigrationTable(
    $dbConnection,
    $configuration['table_prefix'],
    $configuration['migration_table']
);

$ascending = false;

$migrations = $migrationTable->getAll($ascending);

if ($migrations) {
    $migrationsDone = array_map(
        function ($migration) {
            return $migration->toArray();
        },
        $migrations,
    );

    var_dump($migrationsDone);
} else {
    echo 'The migration table is empty';
}

List pending migrations

CLI

For list pending migrations using the Command Line tool

./vendor/bin/versionna migration:list:pending -c config.php

programmatically

<?php

use Sharpen\Versionna\Manticore\ManticoreConnection;
use Sharpen\Versionna\MigrationDirector;
use Sharpen\Versionna\Storage\DatabaseConfiguration;
use Sharpen\Versionna\Storage\DatabaseConnection;
use Sharpen\Versionna\Storage\MigrationTable;

$dbConnection = new DatabaseConnection(
    DatabaseConfiguration::fromArray(
        $configuration['connections'][$connection]
    )
);

$manticoreConnection = new ManticoreConnection(
    $configuration['manticore_connection']['host'],
    $configuration['manticore_connection']['port'],
);

$migrationTable = new MigrationTable(
    $dbConnection,
    $configuration['table_prefix'],
    $configuration['migration_table']
);

$director = new MigrationDirector();

$director
    ->dbConnection($dbConnection)
    ->manticoreConnection($manticoreConnection)
    ->migrationsPath($configuration['migrations_path'])
    ->migrationTable($migrationTable);

$pendingMigrations = $director->getPendingMigrations();

if (count($pendingMigrations) > 0) {
    array_map(
        function ($migration) {
            return ['name' => $migration];
        },
        array_values(array_keys($pendingMigrations)),
    );
} else {
    echo 'ManticoreSearch is up to date! no pending migrations';
}

versionna's Issues

manticoresoftware/manticoresearch-php support for > v1.8

Hello,

I've noticed that your package needs exactly the v1.8 of manticoresoftware/manticoresearch-php.
It is an issue for my case, because I use the v2.2...

I inform you that I'm using PHP 7.4, so I'm using the v0.1 of your dependency.

Would it be possible to upgrade its version's requirements for after v1.8 ?
Especially because the v1.8 was released one year ago (January 2022)...

Thank you very much.