Neo4j connection

Connect a task to a Neo4j graph database (the Neo4jHook) over a managed Leoflow Connection. The database name lives in the Schema field.

URI shape

neo4j://<login>:<password>@<host>:<port>/<database>

The control plane builds this URI from the Connection's fields. Reserved characters in the password (e.g. @, :, /) are percent-escaped by the URI builder; Neo4jHook un-escapes them back. The reserved-character round-trip is pinned by TestNeo4jConnectionURIShapeIntegration (in internal/storage/).

Fields the UI asks for

Field	Required	Notes
Conn Id	yes	e.g. neo4j_target. Exported as AIRFLOW_CONN_NEO4J_TARGET (uppercased).
Conn Type	yes	neo4j.
Host	yes	DNS name or IP of the Bolt endpoint.
Schema	optional	The database name (defaults to neo4j).
Login	yes	The Neo4j user.
Password	yes	Stored encrypted at rest (ADR 0019).
Port	optional	Defaults to 7687 (Bolt).
Extra	optional	JSON — e.g. {"encrypted":true} to force TLS. Encrypted at rest.

Example DAG

The provider import must live inside the task body — a top-level provider import fails compilation in the parser sidecar.

from datetime import datetime
from airflow.decorators import dag, task


@dag(schedule=None, start_date=datetime(2024, 1, 1), catchup=False)
def neo4j_smoke():
    @task
    def query():
        from airflow.providers.neo4j.hooks.neo4j import Neo4jHook

        hook = Neo4jHook(conn_id="neo4j_target")
        rows = hook.run("RETURN 1 AS ok")
        print("neo4j up:", rows)

    query()


neo4j_smoke()

# leoflow.yaml
name: neo4j_smoke
schedule: null
image:
  python: "3.11"
  requirements:
    - apache-airflow-providers-neo4j
connectors: [neo4j]

Security notes

• Secrets in logs: never print() the URI itself — it carries the password. Log host + port + database only.
• TLS in transit: set {"encrypted":true} in Extra to force a TLS Bolt connection.
• gRPC channel (agent ↔ control plane): Connections are only served over an authenticated channel (see #58 + ADR 0021).

Related

• ADR 0019 — secret encryption at rest.
• ADR 0021 — agent secret delivery (AIRFLOW_CONN_<CONN_ID>).

• 142 — connector cookbook umbrella.