Neo4j-python-migrations

This exiting release - again **without** breaking changes - brings two important features:

1. Migrating `BTREE` indexes to "future" indexes
Neo4j 5 will drop the support for `BTREE` indexes. Those indexes must be replaced by `RANGE`, `POINT` or `TEXT` before a store upgrade is attempted. Neo4j 4.4 already "supports" `RANGE` and `POINT` for creating indexes (albeit they are not used in planning right now).
Neo4j-Migrations offers two new refactorings for that: `migrate.createFutureIndexes` which will create future indexes in parallel to old ones and `migrate.replaceBTreeIndexes` to replace old indexes with new ones prior to upgrade
2. Running refactorings or even whole migrations standalone without storing or requiring metadata

How does that look like? Users have 3 options:
1. Define the new refactoring in a proper catalog based migrations (not going to reiterate that here)
2. Build the refactoring via its api and use the new api on `Migrations` to apply it
java
Migrations migrations = new Migrations(MigrationsConfig.defaultConfig(), driver);

// Create equivalent future indexes with the suffix `_new` in parallel
Counters counters = migrations.apply(
MigrateBTreeIndexes.createFutureIndexes("_new")
);

// or drop the old ones and create new ones
counters = migrations.apply(
MigrateBTreeIndexes.replaceBTreeIndexes()
);


or

3. Define a "fake" migration containing only the refactoring and run it via the CLI
First store the following as `V000__Migrate_indexes.xml` (or any other conform name you prefer):

xml
<?xml version="1.0" encoding="UTF-8"?>
<migration xmlns="https://michael-simons.github.io/neo4j-migrations">
<refactor type="migrate.replaceBTreeIndexes">
<parameters>
<parameter name="typeMapping">
<mapping>
<name>index_on_location</name>
<type>POINT</type>
</mapping>
</parameter>
</parameters>
</refactor>
</migration>


And run via:


./bin/neo4j-migrations -uneo4j -psecret run --migration file:./V000__Migrate_indexes.xml


Of course all variants allow to specify the type of replacement index per index / constraint and also excluding or explicitly including indexes and constraints to be migrated. The [documentation covers all the details](https://michael-simons.github.io/neo4j-migrations/main/#migratingbtreeindexestofutureindexes).

Thanks to SergeyPlatonov for the ideas to explicitly run single migrations from the CLI.

🚀 Features
- de0cc6f Provide refactorings for migrating BTREE indexes to future indexes. (667)
- 1609fa0 Add the ability to run migrations and refactorings directly without recording them. (668)

📝 Documentation
- 62a6870 Add JavaDocs where missing.

🧹 Housekeeping
- eba3cda Bump quarkus-neo4j.version from 1.5.0 to 1.6.0
- 430fbb6 Bump spring-boot.version from 2.7.3 to 2.7.4 (658)
- 322045b Bump byte-buddy.version from 1.12.16 to 1.12.17 (659)
- afe7a36 Bump quarkus.version from 2.12.2.Final to 2.13.0.Final (660)
- 0f2b47e Bump checkstyle from 10.3.3 to 10.3.4 (661)
- d0385a5 Bump native-maven-plugin from 0.9.13 to 0.9.14 (662)
- b59ea26 Bump spring-data-neo4j from 6.3.2 to 6.3.3 (663)
- 2dbe2c5 Bump asciidoctorj from 2.5.5 to 2.5.6 (664)
- a3f6497 Bump junit-bom from 5.9.0 to 5.9.1 (665)

🛠 Build
- 5bd4483 Ignore files with literal `.extension` during license check.
- a6dde98 Make sure constraints are really gone before running more tests.
- bf56ba8 Improve testing performance.

There has been no breaking changes in this release, but we have added some methods and moved things around that haven't been public before to improve your life in case you should use this library on the module path.

🚀 Features
- ad76526 Log connection details during Spring and Quarkus startup. (655)
- f6f6ef9 Try to detect invalid use of enterprise constraints against community edition. (654)

🐛 Bug Fixes
- 08ec086 Add braces to single property node key constraints statements for elder versions. (653)
- 7a949bd Add several missing JMS requirements and necessities to public API. (646)

📝 Documentation
- 871c36b add SaschaPeukert as a contributor (649)

🧹 Housekeeping
- a8e0586 Bump maven-jar-plugin from 3.2.2 to 3.3.0 (651)
- 637815a Bump maven-shade-plugin from 3.3.0 to 3.4.0 (652)
- 8758ae4 Bump quarkus.version from 2.12.1.Final to 2.12.2.Final (650)

This release contains the second Java annotation processor I wrote and I am very excited about it: You can point this tool from within Javac to entities annotated with [Neo4j-OGM](https://github.com/neo4j/neo4j-ogm) OR [Spring Data Neo4j 6](https://github.com/spring-projects/spring-data-neo4j) annotations and it will produce catalog files containing the indexes and constraints that can be derived by the annotated classes.

All indexes and constraints of the Neo4j-OGM auto index manager and all SDN6 annotations are supported. The annotation processor does not ship the dependencies itself, so one possible invocation looks like this:


javac -proc:only \
-processorpath neo4j-migrations-1.11.0.jar:neo4j-migrations-annotation-processor-api-1.11.0.jar:neo4j-migrations-annotation-processor-1.11.0.jar \
-Aorg.neo4j.migrations.catalog_generator.output_dir=output \
-Aorg.neo4j.migrations.catalog_generator.default_catalog_name=V01__Create_OGM_schema.xml \
-cp neo4j-ogm-core-3.2.37.jar \
path/to/annotated/entities/*


Please have a look at ["Annotation processing"](https://michael-simons.github.io/neo4j-migrations/current/#appendix_annotation) in the manual how to run this for SDN6 and possible ways to integrate it into your build.

One possible output - outlining just some of the constraints - will look like this

xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<migration xmlns="https://michael-simons.github.io/neo4j-migrations">
<!-- This file was generated by Neo4j-Migrations at 2022-09-21T21:21:00+01:00. -->
<catalog>
<indexes>
<index name="my_entities_ogm_singleindexentity_login_property" type="property">
<label>Entity</label>
<properties>
<property>login</property>
</properties>
</index>
<index name="my_entities_ogm_relpropertyindextentity_description_property" type="property">
<type>RELPROPERTYINDEXTENTITY</type>
<properties>
<property>description</property>
</properties>
</index>
<index name="my_entities_ogm_compositeindexentity_name_age_property" type="property">
<label>EntityWithCompositeIndex</label>
<properties>
<property>name</property>
<property>age</property>
</properties>
</index>
</indexes>
<constraints>
<constraint name="my_entities_ogm_entitywithassignedid_id_unique" type="unique">
<label>EntityWithAssignedId</label>
<properties>
<property>id</property>
</properties>
</constraint>
<constraint name="my_entities_ogm_nodepropertyexistenceconstraintentity_login_exists" type="exists">
<label>Entity</label>
<properties>
<property>login</property>
</properties>
</constraint>
<constraint name="my_entities_ogm_relpropertyexistenceconstraintentity_description_exists" type="exists">
<type>REL</type>
<properties>
<property>description</property>
</properties>
</constraint>
<constraint name="my_entities_ogm_nodekeyconstraintentity_name_age_key" type="key">
<label>Entity</label>
<properties>
<property>name</property>
<property>age</property>
</properties>
</constraint>
</constraints>
</catalog>
<apply/>
</migration>


This catalog can than be added to your CI/CD or application setup as described in the [manual](https://michael-simons.github.io/neo4j-migrations/current/#concepts_catalog). We do not recommend regenerating it every time in the build as that will break the chain of migrations once you change entities. This might be seen as an inconvenience but we are convinced that a half-automated process here is better than the auto index manager of old that might surprises you with it's upgrade mechanism.

This also the first release that that will ship with Linux ARM64 ootb.

While we did bump the minor version, there are **no** breaking changes.

🚀 Features
- 771124c Add annotation processor for Neo4j-OGM and SDN6 entities. (618)

🐛 Bug Fixes
- f8b1da9 Improve quotation papttern. (616)

🔄️ Refactorings
- 9c58ec5 Use Cypher-DSL schema name support for sanitizing names. (620)

📝 Documentation
- fb4ca38 add fbiville as a contributor for ideas (638)
- e8a71cd add ali-ince as a contributor for userTesting (637)
- 59fea88 add atomfrede as a contributor for ideas (636)
- 1b52cf9 add katya-dovgalets as a contributor for code (635)
- 6791e62 add corneil as a contributor for bug (634)
- d141781 add marianozunino as a contributor for ideas (633)
- fd4b41c add aalmiray as a contributor for code, plugin, ideas, mentoring (632)
- a11f2fc add Dcanzano as a contributor for userTesting, bug (631)
- 3b02732 add Hosch250 as a contributor for userTesting, bug (630)
- 832f503 add injectives as a contributor for code, userTesting (629)
- 1807f29 add SeanKilleen as a contributor for doc (628)
- 22cf9b7 add ali-ince as a contributor for bug (627)
- 1fadb5d add michael-simons as a contributor for maintenance (626)
- 2062be5 add michael-simons as a contributor for code, doc (625)
- 4aebc75 add meistermeier as a contributor for doc (624)
- 99b9f60 add bsideup as a contributor for review (623)
- e5e89ce add meistermeier as a contributor for code (622)
- 897be21 Update local changelog.

🧹 Housekeeping
- 1a7b7b3 Bump neo4j-harness from 4.4.10 to 4.4.11 (642)
- 91266e4 Bump error_prone_annotations from 2.12.1 to 2.15.0 (643)
- 2af5eaa Bump byte-buddy.version from 1.12.14 to 1.12.16 (644)
- 4e1bf2f Bump checker-qual from 3.24.0 to 3.25.0 (641)
- 8ef853e Bump mockito.version from 4.7.0 to 4.8.0 (639)
- c2b6c6f Bump quarkus-neo4j.version from 1.4.1 to 1.5.0
- a3ade49 Bump quarkus.version from 2.12.0.Final to 2.12.1.Final
- e783d4d Bump japicmp-maven-plugin from 0.15.7 to 0.16.0 (617)
- dde32a3 Bump quarkus.version from 2.11.2.Final to 2.12.0.Final (611)

🛠 Build
- 165bcb8 Add linux-aarch_64 to the release pipeline. (645)
- d8d1dfe Add all-contributors bot.

📝 Documentation
- b93d9be Use correct heading level.
- 491b793 Improve intro to naming conventions.

🧹 Housekeeping
- 95fdff1 Bump quarkus-neo4j.version from 1.4.0 to 1.4.1
- 3a2c08a Bump quarkus.version from 2.11.2.Final to 2.11.3.Final
- 0f8b5d8 Bump checkstyle from 10.3.2 to 10.3.3 (615)
- 621db9e Bump maven-checkstyle-plugin from 3.1.2 to 3.2.0 (614)
- 3a31f05 Bump byte-buddy.version from 1.12.13 to 1.12.14 (613)
- d30cd1a Bump jreleaser-maven-plugin from 1.1.0 to 1.2.0 (612)

There's an exiting new feature in this release: Predefined database refactorings, such as "rename the label `Movie` into `Film`" or "normalise all properties that have the values `ja`, `yes` and `y` and all of `nein`, `no`, `vielleicht` into a boolean `true` respectively `false`". Those refactorings are largely modeled after [apoc.refactor](https://neo4j.com/labs/apoc/4.4/overview/apoc.refactor/) but *do not* require APOC to be installed and run into pure Cypher. They even do support batching in Neo4j 4.4 or higher.

Some inspiration has been taken from fbiville's post about [Graph Refactoring: The Hard Way](https://medium.com/neo4j/graph-refactoring-the-hard-way-5762067ead46) for the general initiative and the `Merge.nodes` refactoring. Thanks for that, Florent!

The refactorings of this project here are in [`ac.simons.neo4j.migrations.core.refactorings`](https://github.com/michael-simons/neo4j-migrations/tree/main/neo4j-migrations-core/src/main/java/ac/simons/neo4j/migrations/core/refactorings) and can actually be used without the migrations itself, a connected Neo4j driver instance will be enough to use them. We will maybe extract them into a separate module or even separate library in a new org at a later stage. Until than, they will be part of the publicly maintained API here. Have a look at the document how to use them in catalogs or standalone (full example [here](https://michael-simons.github.io/neo4j-migrations/current/#concepts_migrations_catalog-based) and a list of [predefined refactorings](https://michael-simons.github.io/neo4j-migrations/current/#appendix_refactorings)).

This feature does not have *any* breaking changes to the core, so 1.10.0 is a drop-in replacement of 1.9 and depending if you are using it in Spring Boot or Quarkus and your versions there, for 1.8 or 1.7, too.

🚀 Features
- cbd1075 Add refactoring `Normalize.asBoolean`. (606)
- 2ec53be Add support for running predefined refactorings. (605)

🐛 Bug Fixes
- 36459cc Escape escaped Unicode 0060 (backtick) proper. (607)

🔄️ Refactorings
- 794238f Don't double escape already escaped backticks. (604)

📝 Documentation
- 7ea2bd8 Add JavaDoc where required.
- ff0a922 Update local changelog.

🧹 Housekeeping
- 2a1ca61 Bump spring-boot.version from 2.7.2 to 2.7.3 (610)


Contributors
We'd like to thank the following people for their contributions:
- meistermeier

🐛 Bug Fixes
- a99b33f Add missing type `property` to allowed index types.

🧹 Housekeeping
- 127996f Bump maven-javadoc-plugin from 3.4.0 to 3.4.1 (600)
- 75191a9 Bump neo4j-harness from 4.4.9 to 4.4.10 (601)
- 538ccd1 Bump maven-project-info-reports-plugin from 3.4.0 to 3.4.1 (602)
- 8c6ad22 Bump mockito.version from 4.6.1 to 4.7.0 (603)
- 123acdd Bump maven-site-plugin from 3.12.0 to 3.12.1 (599)
- 2c91338 Bump byte-buddy.version from 1.12.12 to 1.12.13 (598)
- 7ec3a03 Bump objenesis from 3.2 to 3.3 (597)
- 2c5ebeb Bump quarkus.version from 2.11.1.Final to 2.11.2.Final (596)

🛠 Build
- d736df7 Use `quarkus-extension-maven-plugin` instead of `quarkus-bootstrap-maven-plugin`.