OntoL Deployment Guide: Multi-Graph Database Backend Switching with Memgraph & Neo4j

1. Overview

OntoL's query layer generates standard openCypher statements, enabling the storage backend to be swapped among multiple graph databases. This document describes the standard deployment process, configuration for each backend, switching procedures, and verification methods.

1.1 Architecture Layers

Application Layer (Business Systems)
    |
Query Layer (OntoL: Ontology Parsing / DSL Rule Compilation → Standard Cypher)
    |
Adapter Layer (Backend Drivers: Memgraph / Neo4j / Other openCypher-Compatible Libraries)
    |
Storage Layer (Graph Database Instances)

Design principles:

The query layer produces only standard Cypher, with no dependency on proprietary SDKs.

The adapter layer handles connection management and dialect differences (index syntax, procedure calls, etc.).

Ontology data (schema, rules, instances) is written through the adapter layer via the same standard channel.

1.2 Supported Backends and Version Matrix

Memgraph – version ≥ x.y [to be confirmed]; deployment modes: single instance / primary-replica; default backend.

Neo4j – version ≥ x.y [to be confirmed]; deployment modes: single instance / cluster; openCypher compatible.

Other – [to be confirmed]; requires openCypher compatibility and transaction support.

2. Prerequisites

Operating system: Linux x86_64 (CentOS 7+/Ubuntu 20.04+) or Docker 20.10+.

CPU/Memory: minimum 4C8G, production recommended 8C32G+ (adjust per instance scale).

Disk: SSD, estimated by ontology size, reserve 2× redundancy.

Network: application server must reach graph database ports (Memgraph 7687, Neo4j 7687/7474).

Offline environments: pre-download Docker images and driver packages (see 2.1).

2.1 Offline Environment Preparation

In an online environment, run docker save to package the required images, transfer to the target environment, then run docker load:

# Example (image names per actual release)
docker save -o ontoll-images.tar ontoll/engine:x.y memgraph/memgraph:x.y neo4j:x.y
docker load -i ontoll-images.tar

3. Installation and Initial Configuration

3.1 Configuration File

Main configuration file config/backend.yaml:

backend:
  type: memgraph          # memgraph | neo4j | <other>
  dsn: bolt://127.0.0.1:7687
  username: ontoll
  password: ${DB_PASSWORD}  # inject via environment variable
  pool:
    max_size: 20
    idle_timeout: 300s
  # Backend feature toggles: dialect compensation, batch write size, etc.
  dialect:
    batch_size: 1000          # [to be confirmed] recommended per backend
    use_apoc: false           # Neo4j-specific extension, default off

3.2 Backend One: Memgraph (Default)

docker run -d --name memgraph \
  -p 7687:7687 -p 7444:7444 \
  -v mg_data:/var/lib/memgraph \
  memgraph/memgraph:x.y

Initialization (creating dedicated account and indexes) is performed automatically on first OntoL startup; no manual schema creation required.

3.3 Backend Two: Neo4j

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=ontoll/${DB_PASSWORD} \
  -v neo4j_data:/data \
  neo4j:x.y

Notes:

Neo4j disables some CALL db.* procedures by default; the adapter layer provides compatibility, no extra configuration needed.

If APOC extension is enabled ( use_apoc: true), the APOC JAR must be mounted. This mode is non-standard and requires regression verification before switching backends.

3.4 Starting OntoL

docker run -d --name ontoll \
  -v $(pwd)/config:/etc/ontoll \
  -e DB_PASSWORD=*** \
  -p 8080:8080 \
  ontoll/engine:x.y [to be confirmed]

When the startup log shows backend connected: <type>, the backend connection is successful.

4. Backend Switching Process

4.1 Pre-Switch Checks

Target backend version is within the support matrix (see 1.2).

Target backend empty instance is available, disk and memory meet requirements.

Confirm no proprietary extensions of the source backend are used (e.g., APOC, Mage modules). Export query inventory via ontoll admin export-queries for verification [command name to be confirmed].

4.2 Switching Steps

On the source backend, perform a full export:

ontoll admin export --output ./ontology-backup.json

The export contains ontology schema, DSL rules, instance data, and index definitions.

Modify

config/backend.yaml

type

and dsn to point to the target backend.

Start OntoL and run import:

ontoll admin import --input ./ontology-backup.json

Execute verification per 4.3.

4.3 Post-Switch Verification Checklist

Connection & Authentication – Method: startup log / health check endpoint; Pass: backend connected appears.

Schema Consistency – Method: ontoll admin verify-schema [to be confirmed]; Pass: class/property/constraint counts match source.

Inference Correctness – Method: run benchmark rule set (smoke cases shipped with product); Pass: results match source item by item.

Query Performance Baseline – Method: run benchmark query set and record latency; Pass: within expected range on target backend [baseline values to be confirmed].

Transaction & Concurrency – Method: concurrent write smoke test; Pass: no deadlocks, no dirty reads.

If any check fails, roll back by reverting backend.yaml to the source backend and restart (OntoL holds no local state; all state resides in the graph store).

5. Operations

Backup : Backup target is the graph database itself (Memgraph snapshots / Neo4j dump); OntoL has no independent state to back up.

Monitoring : Monitor graph DB process, port 7687, disk usage; OntoL exposes /healthz and /metrics.

Capacity Planning : Hard constraint is the underlying graph store's memory limit – Memgraph open-source edition is limited to single-machine memory; exceeding it requires migration to a distributed backend.

Upgrade : Upgrade graph database first, then OntoL; order cannot be reversed; perform full export backup before upgrade.

6. Known Limitations

Switching supports only the standard Cypher channel; proprietary extensions (APOC/Mage) prevent direct switching.

Performance characteristics differ across backends; after switching, performance baselines must be rebuilt – old baselines must not be reused for capacity commitments.

Transaction isolation levels vary between backends; strong-consistency scenarios (cross-system long-running processes) must be re-evaluated against the target backend's semantics.

7. FAQ

Q: Does switching backends require downtime?

Yes, the switch window requires downtime (export → switch → import → verify). Zero-downtime would need dual-write or incremental sync, not provided in the current version.

Q: Why is Memgraph open-source the default backend?

See Section 6 and capacity planning; for ultra-large scale, directly evaluate a distributed backend.

Q: Is Neo4j cluster mode supported?

Routing to a cluster is supported; failover is handled by the Neo4j driver layer; OntoL itself has no cluster-awareness logic.