mdb-changelog-runner 0.1.2

Lightweight Liquibase-style XML changelog executor for Neo4j/MDB updates

mdb-changelog-runner

Lightweight Python execution for Liquibase-style Neo4j/MDB changelog XML.

This package parses ordered <changeSet> entries and executes their <neo4j:cypher> queries in a single Neo4j transaction. It does not require Java, the JDK, Liquibase, or the Liquibase Neo4j extension at runtime.

Install

uv add mdb-changelog-runner

For local development:

uv sync
uv run pytest

XML format

Existing Liquibase Neo4j changelogs are supported:

<databaseChangeLog
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xmlns:neo4j="http://www.liquibase.org/xml/ns/dbchangelog-ext"
  xmlns:mdb="https://cbiit.github.io/mdb/changelog">
  <changeSet id="1" author="NWM">
    <neo4j:cypher>CREATE (n:test {handle:'TEST'})</neo4j:cypher>
  </changeSet>
</databaseChangeLog>

Parameterized Cypher can use MDB JSON params:

<changeSet id="2" author="NWM">
  <neo4j:cypher>
    MERGE (n:term {handle: $handle, value: $value})
  </neo4j:cypher>
  <mdb:params>{"handle": "C123", "value": "Example"}</mdb:params>
</changeSet>

Usage

import logging

from neo4j import GraphDatabase
from mdb_changelog_runner import ChangelogExecutor

driver = GraphDatabase.driver(uri, auth=(user, password))
logger = logging.getLogger("mdb_changelog_runner")

executor = ChangelogExecutor(driver, logger=logger)
result = executor.execute(
    "local_changelog.xml",
    "s3://my-bucket/path/local_changelog.xml",
)

print(result.changesets_executed)

execute() opens a session when given a Neo4j driver. It can also accept an already-open session-like object that provides begin_transaction().

Behavior

• Each <changeSet> must have an id, author, and <neo4j:cypher> element.
• Changesets run in XML order.
• All changesets run inside one transaction.
• If any changeset fails, the transaction is rolled back and ChangelogExecutionError is raised.
• dry_run=True parses the changelog and returns a summary without executing Cypher.
• No _changelog metadata node is created by this package yet.