# Neo4J migrations

## When not recommended to use this migration style

- Neo4j DDL statements
- Minor data changes using specific record ids.
- Short running queries (less than 5 minutes)

For such type of migrations consider using [liquigraph deploy]( https://github.com/theorchard/database/blob/master/neo4j/README.md)

## How to create a migration

- Put your migration files under `/kafka-db-deploy/neo4j/build/changelog/{dml,ddl}` directory
- Only XML format is supported for migrations
- No special rollback sections/tags. To rollback a migration you will have 
to create a new migration with rollback queries manually.
- The changeset id must be unique across all changesets. Follow best practices below to ensure this.

## Best Practices

- Only one file per PR.
- Changeset id should match the file ('.xml' filetype excluded)
- If there are multiple changesets in a file, append the sequence number of the changeset
- Only one statement per changeset.
- Verify in `neo4j://dev-neo4j-cluster.dev.theorchard.io:7687` that the changeset can execute within the 5-minute Neo4j timeout.
- For changesets that don't import data from other storages (e.g. Snowflake, MySQL) and create 100s of nodes and edges, use [Neo4J migrations with liquigraph](https://github.com/theorchard/database/tree/master/neo4j) instead.
- Use [EXPLAIN](https://neo4j.com/docs/cypher-manual/current/execution-plans/) to verify the query plan does not include a [NodeByLabelScan](https://neo4j.com/docs/cypher-manual/current/execution-plans/operators/#query-plan-node-by-label-scan).

## Migration example

### No SQL-query is set inside precondition

Filename: another_migration_example.xml

```
<?xml version="1.0" encoding="UTF-8"?>
<changelog xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="file:/var/app/InputFileSchema.xsd">
    <changeset id="another_migration_example:1" author="ibolshakov">
        <cypherquery>
            <![CDATA[
                MERGE (n:Solid {text: 'example_text', id: 1}) RETURN n
            ]]>
        </cypherquery>
    </changeset>
</changelog>
``` 

## Neo4j Sink Connector Cypher Template

Cypher inside `<query>` tag will be executed in Neo4j

Changesets' `run-on-change="true"` and `run-always="true"` attributes are optional.


[Cypher template documentation](https://neo4j.com/labs/kafka/4.0/kafka-connect/#_cypher_template)


## Known limitations

- Changesets with CypherQuery containing lines with comments are not supported at the moment. Please remove any comments (i.e: lines starting with `//`) from the query before attempting a DB Deploy.