# Snowflake to Neo4J migrations


## How to create a migration

- Put your migration files under `/kafka-db-deploy/snowflake-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

## Migration examples

### Precondition with SQL-query is set

Filename: 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="migration_example:1" 
        author="ibolshakov"
        neo4j-server="music-graph" 
        run-always="true"
    >
        <precondition>
            <sqlquery>
                <![CDATA[
                    SELECT EXAMPLE_ID, EXAMPLE_TEXT FROM example_table
                ]]>
            </sqlquery>
        </precondition>
        <cypherquery>
            <![CDATA[
                MERGE (n:Solid {text: event.EXAMPLE_TEXT, id: event.EXAMPLE_ID}) RETURN n
            ]]>
        </cypherquery>
    </changeset>
    <changeset 
        id="migration_example:2" 
        author="ibolshakov"
        neo4j-server="music-graph" 
        run-on-change="true"
    >
        <precondition>
            <sqlquery>
                <![CDATA[
                    SELECT EXAMPLE_ID, EXAMPLE_TEXT FROM example_table
                ]]>
            </sqlquery>
        </precondition>
        <cypherquery>
            <![CDATA[
                MERGE (n:Solid {text: event.EXAMPLE_TEXT, id: event.EXAMPLE_ID}) RETURN n
            ]]>
        </cypherquery>
    </changeset>
</changelog>
``` 

## Neo4j Sink Connector Cypher Template

The SQL inside `<sqlquery>` tag of `<precondition>` will be executed in Snowflake.
Cypher template inside `<query>` tag will be executed for each row with column names
passed as variable names with the `event.` prefix.
Choose the target Neo4j server by setting the `neo4j-server` attribute of the `<changeset>` tag. Available options are "music-graph" and "nr-graph".

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.