Module ac.simons.neo4j.migrations.core
Package ac.simons.neo4j.migrations.core

Class Migrations

java.lang.Object
ac.simons.neo4j.migrations.core.Migrations
public final class Migrations extends Object
Main entry to Neo4j Migrations
Since:
0.0.1
Author:
Michael J. Simons

  • Constructor Details

    • Migrations

      public Migrations(MigrationsConfig config, org.neo4j.driver.Driver driver)
      Creates a migrations instance ready to used with the given configuration over the connection defined by the driver.
      Parameters:
      config - The configuration to use
      driver - The connection

  • Method Details

    • clearCache

      public void clearCache()
      Clears the internal cache (discovered migrations and callbacks) which can be useful in certain testing scenarios.
      Since:
      2.2.0

    • getConnectionDetails

      public ConnectionDetails getConnectionDetails()
      Returns:
      Information about the connection when migrations are applied, validated and so on.
      Since:
      1.4.0
      See Also:

    • info

      public MigrationChain info()
      Returns information about the context, the database, all applied and all pending applications.
      Returns:
      The chain of migrations.
      Throws:
      org.neo4j.driver.exceptions.ServiceUnavailableException - in case the driver is not connected
      MigrationsException - for everything caused by failing migrations
      Since:
      0.0.4
      See Also:

    • info

      public MigrationChain info(MigrationChain.ChainBuilderMode mode)
      Returns information about the context, the database, all applied and all pending applications.
      Parameters:
      mode - Specify how the chain should be computed
      Returns:
      The chain of migrations.
      Throws:
      org.neo4j.driver.exceptions.ServiceUnavailableException - in case the driver is not connected
      MigrationsException - for everything caused by failing migrations
      Since:
      1.4.0

    • apply

      public Optional<MigrationVersion> apply()
      Applies all discovered Neo4j migrations. Migrations can either be classes implementing JavaBasedMigration or Cypher script migrations that are on the classpath or filesystem.
      Returns:
      The last applied migration (if any)
      Throws:
      org.neo4j.driver.exceptions.ServiceUnavailableException - in case the driver is not connected
      MigrationsException - for everything caused by failing migrations
      Since:
      0.0.1
      See Also:

    • apply

      public Optional<MigrationVersion> apply(boolean log)
      Applies all discovered Neo4j migrations. Migrations can either be classes implementing JavaBasedMigration or Cypher script migrations that are on the classpath or filesystem.

      The startup will be logged to ac.simons.neo4j.migrations.core.Migrations.Startup and can be individually disabled through that logger.

      Parameters:
      log - set to true to log connection details prior to applying the migrations
      Returns:
      The last applied migration (if any)
      Throws:
      org.neo4j.driver.exceptions.ServiceUnavailableException - in case the driver is not connected
      MigrationsException - for everything caused by failing migrations
      Since:
      1.12.0

    • apply

      public Counters apply(Refactoring... refactorings)
      Applies one or more refactorings to the target (not the schema) database without recording any metadata and also without acquiring the lock.
      Parameters:
      refactorings - the refactorings to apply
      Returns:
      summarized counters
      Since:
      1.13.0

    • apply

      public int apply(URL... resources)
      Applies one or more migrations to the target (not the schema) database without recording any metadata and also without acquiring the lock.
      Parameters:
      resources - One or more resources pointing to parsable migration data
      Returns:
      the number of migrations applied
      Since:
      1.13.0

    • clean

      public CleanResult clean(boolean all)
      Cleans the selected schema database. If there is no schema database selected, the operation uses the target database. If this isn't configured as either, the users home database will be used. Items te be removed include:
      1. Migration chains (those are the nodes containing information about the applied migrations
      2. Any log from this tool
      3. Any constraints created by this tool
      and will delete and drop them in that order. This is a destructive operation, so make sure not to apply it to your production database without thinking at least twice. It cannot be undone via Neo4j-Migrations.
      Parameters:
      all - Set to true to remove all constructs created by Neo4j-Migrations, set to false to remove all the migration chain for the selected or automatically determined target database.
      Returns:
      The result of cleaning the database.
      Throws:
      org.neo4j.driver.exceptions.ServiceUnavailableException - in case the driver is not connected
      MigrationsException - for everything caused due to schema objects not deletable
      Since:
      1.1.0

    • delete

      public DeleteResult delete(MigrationVersion version)
      Deletes the specific version from selected schema database. If there is no schema database selected, the operation uses the target database.. If this isn't configured as either, the users home database will be used. The migration will be removed from the migration chain without being prior resolved from the filesystem or classpath. This operation is useful for all scenarios in which you would like to delete specific migrations from your scripts which would otherwise lead to a MigrationsException indicating that more migrations have been applied than locally resolved.
      Parameters:
      version - the version that should be deleted, must not be null.
      Since:
      2.2.0

    • repair

      public RepairmentResult repair()
      This command repairs databases containing Neo4j-Migration chains. Those schema databases need to be repaired if the locally discovered migrations have diverged from the ones applied to the database. This can have several reasons: Local Cypher scripts have been edited after they have been recorded with this tool, thus their checksum doesn't match anymore, local scripts or classes have been deleted or scripts or classes have been inserted.

      The repairment will take the locally discovered set of migrations (both Cypher files and classes) as truth and proceed as follows:

      1. Check all the checksums (pairwise by migration version) and fix the recorded chain if necessary
      2. Check for missing local migrations and delete the missing ones in the database
      3. Check for inserted local migrations and create new chain entries with current time stamp
      The process does never run migrations, as there is no proper way of telling any newly found script has been manually run or not.

      This command will throw a MigrationsException if no local scripts or classes are discovered at all as that would lead to the deletion of all applied migrations. In case that is the desired outcome, please use clean(boolean) and optionally specify whether Neo4j-Migration required infrastructure (read constraints etc).

      Returns:
      The result of the repair process, containing detailed information about the outcome and the changed database content
      Since:
      2.2.0

    • validate

      public ValidationResult validate()
      Validates the database against the resolved migrations. A database is considered to be in a valid state when all resolved migrations have been applied (there are no more pending migrations). If a database is not yet fully migrated, it won't identify as ValidationResult.Outcome.VALID but it will indicate via ValidationResult.needsRepair() that it doesn't need repair. Applying the pending migrations via apply() will bring the database into a valid state. Most other outcomes not valid need to be manually fix. One radical fix is calling clean(boolean) with the same configuration.
      Returns:
      a validation result, with an outcome, a possible list of warnings and indicators if the database is in a valid state
      Since:
      1.2.0

    • getLocalCatalog

      public Catalog getLocalCatalog()
      Retrieves the local catalog, containing constraints and indexes.
      Returns:
      the local catalog
      Since:
      1.7.0

    • getDatabaseCatalog

      public Catalog getDatabaseCatalog()
      Retrieves the database catalog
      Returns:
      the database catalog
      Since:
      1.7.0

    • getUserAgent

      public static String getUserAgent()
      Returns:
      the user agent for Neo4j-Migrations (given in the form name/version).
      Since:
      1.2.1