Neo4j Migrationsを使ったNeo4jグラフスキーマの移行

原文(投稿日：2021/12/28)へのリンク

Neo4j Labsは、Neo4j Migrationsをリリースした。これはデータベース移行およびリファクタリングツールで、リレーショナルデータベースのバージョン管理を提供する。Neo4j Migrationsは、FlywayDBにインスピレーションを受けており、Neo4j Javaドライバと、クラスパス上の移行を検出するために使用されるClassGraphからなる。

このツールは、GitHubリリースページからCLIバイナリをダウンロードして、neo4j-migrationsコマンドを介してCLIとして使用できる。バイナリは、WindowsとUnixライクなオペレーティングシステムの両方に対して入手できる。HomebrewはmacOSのインストールを提供している。

brew install michael-simons/homebrew-neo4j-migrations/neo4j-migrations

JVMベースのバージョンもダウンロードできる。これは、--package引数を使ってJavaベースの移行をサポートする唯一のバージョンだ。

Neo4j Migrationsには、Neo4jに移行するか、あるいは、他の変更を適用する2つのオプションがある。Cypherベースの移行は、Cypherステートメントとして記述される。「;」は各ステートメントを区切るものである。classpath:neo4j/migrations内の.cypherファイルは自動的に検出され、各ファイルは1回のトランザクションで実行される。クラスパスまたはファイルシステム上の他のロケーションは、次のように指定できる。

MigrationsConfig configLookingAtDifferentPlaces = MigrationsConfig.builder()

    .withLocationsToScan(
        "classpath:[custompath]", 
        "file:/[custompath]" 
    ).build();

あるいは、Javaベースの移行を使用することもできる。これにより、Javaロジックを使って、JavaBasedMigrationインターフェイスを実装することにより、データベース内のあらゆる変更ができるため、柔軟性が向上する。

import ac.simons.neo4j.migrations.core.JavaBasedMigration;
import ac.simons.neo4j.migrations.core.MigrationContext;

import org.neo4j.driver.Driver;
import org.neo4j.driver.Session;

public class CustomMigration implements JavaBasedMigration {

    @Override
    public void apply(MigrationContext context) {
        try (Session session = context.getSession()) { 
            …
        }
    }
}

CLIを使わずにビルドを介してデータベースの移行をトリガーするMavenプラグインを使うことができる。その場合、次のような構成となる。

<plugin>
    <groupId>eu.michael-simons.neo4j</groupId>
    <artifactId>neo4j-migrations-maven-plugin</artifactId>
    <version>[version]</version>
    <executions>
        <execution>
            <id>migrate</id>
            <goals>
                <goal>migrate</goal>
            </goals>
            <configuration>
                <user>[username]</user>
                <password>[password]</password>
                <address>[address]</address>
                <verbose>true</verbose>
            </configuration>
        </execution>
    </executions>
</plugin>

プラグインは、neo4j/migrations内の移行を自動的に検出する。他のディレクトリは次のように指定できる。

<locationsToScan>  
   <locationToScan>file://${project.build.outputDirectory}/[custom-path]</locationToScan>
</locationsToScan>

または、Spring Bootスターターを使って、依存関係を構成することで移行をトリガーすることもできる。

<dependency>
    <groupId>eu.michael-simons.neo4j</groupId>
    <artifactId>neo4j-migrations-spring-boot-starter</artifactId>
    <version>[version]</version>
</dependency>

スターターはNeo4j Javaドライバを使用する。これは、Spring Boot2.4以降を使うと、直接構成される。スターターは、デフォルトではJavaベースの移行をスキャンせず、Cypherステートメントのデフォルトディレクトリとしてclasspath:neo4j/migrationsを使用する。スターターを構成するには、次のようなさまざまなプロパティを使用できる。

spring.neo4j.authentication.username=[username]
spring.neo4j.authentication.password=[location]
spring.neo4j.uri=[uri]

# To configure additional locations with migrations
org.neo4j.migrations.packages-to-scan=location1, location2

Spring Bootは、@DataNeo4jTestアノテーションを使ったNeo4jテストをサポートする。次のような構成とすることで移行と共に使用できる。

@Testcontainers(disabledWithoutDocker = true)
@DataNeo4jTest
@ImportAutoConfiguration(MigrationsAutoConfiguration.class)
public class CustomTest {

    @Container
    private static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:4.2")
        .withReuse(TestcontainersConfiguration.getInstance().environmentSupportsReuse()); 
    @DynamicPropertySource
    static void neo4jProperties(DynamicPropertyRegistry registry) { 
        registry.add("spring.neo4j.uri", neo4j::getBoltUrl);
        registry.add("spring.neo4j.authentication.username", () -> "neo4j");
        registry.add("spring.neo4j.authentication.password", neo4j::getAdminPassword);
    }

    @Test
    void yourTest(@Autowired Driver driver) {
        …
    }
}

Sebastian Daschner氏は、彼のブログと併せて提供されるビデオで、どのようにしてCLIでinitコンテナを使ってKubernetesにおけるNeo4jグラフスキーマを移行するかを説明している。

すべてのドキュメントがGitHubから入手でき、そこには全構成オプションが含まれる。いくつかのサンプルプロジェクトも含まれている。