@graphium/cli

English · 한국어

Graph-native OGM with multiple graph DB backends

Explicit persistence model — no Proxy magic, no N+1 footguns

@graphium/cli is the graphium command-line tool for managing entity schemas and database migrations.

What's new in 0.4

• graphium migrate:diff (Phase 4.1) — emits a reviewable {timestamp}-auto-diff.cypher file by comparing decorator metadata against the live database schema.
  • --allow-destructive flag enables DROP/MODIFY statements; without it those entries are commented out and the command exits with code 1 so CI catches them.
  • Production gate: when NODE_ENV=production, --allow-destructive requires an explicit GRAPHIUM_ALLOW_DESTRUCTIVE_PROD=true env opt-in (otherwise throws ConfigurationError).
  • Currently wired for the neo4j backend; other backends throw NotImplementedError in 0.4.

Install

pnpm add -D @graphium/cli

Or install globally:

pnpm add -g @graphium/cli

Setup

graphium init

Creates a graphium.config.ts file in the current directory. For Memgraph:

graphium init memgraph

Example generated config:

import type { GraphiumConfig } from '@graphium/cli'

const config: GraphiumConfig = {
  backend: 'neo4j',
  connection: 'env',
  entities: ['./src/entities/**/*.ts'],
  migrationsPath: './migrations',
}

export default config

Commands

| Command | Description | | -------------------------------- | ---------------------------------------------------------------------------- | | graphium init | Create graphium.config.ts (Neo4j) | | graphium init memgraph | Create graphium.config.ts (Memgraph) | | graphium migrate:create <name> | Create a new migration file | | graphium migrate:up | Run all pending migrations | | graphium migrate:down [steps] | Revert migrations (default: 1) | | graphium migrate:status | Show migration status | | graphium migrate:preview | Preview pending migration statements | | graphium migrate:diff | Emit schema diff between entities and live DB (--allow-destructive opt-in) | | graphium schema:validate | Validate entity decorator metadata | | graphium schema:inspect | List registered entities and relationships | | graphium --version | Print the CLI version |

Entity Loading

Entities are loaded at runtime via jiti so TypeScript entity files are imported directly without a separate compile step. Glob patterns in entities are resolved with tinyglobby.

Connection

Set connection: 'env' in the config to read connection details from environment variables. For Neo4j: NEO4J_PASSWORD is required; NEO4J_USERNAME defaults to neo4j. For Memgraph: set both MEMGRAPH_USERNAME and MEMGRAPH_PASSWORD.

Peer Dependencies

@graphium/neo4j and @graphium/memgraph are optional peer dependencies. Install the one that matches the backend value in your config.