falkordblite

Embedded FalkorDB for Node.js/TypeScript. Zero-config graph database that runs locally (redis-server + FalkorDB module) and connects over a Unix socket.

Quick start

import { FalkorDB } from 'falkordblite';

const db = await FalkorDB.open();
await db.selectGraph('quickstart').query('RETURN 1');
await db.close();

Installation

npm install falkordblite

The package automatically installs pre-built Redis + FalkorDB binaries for your platform. No system dependencies required.

If you also want to connect to remote servers, install the upstream client:

npm install falkordb

Examples

See the examples/ directory:

• basic.ts - minimal usage
• persistence.ts - durable data with a path
• multiple-graphs.ts - isolated graphs in one DB
• migration.ts - 1-line change to remote
• graphrag-example.ts - use with GraphRAG tooling

API reference

FalkorDB.open(options?)

Create a new embedded FalkorDB instance. This resolves binaries, generates a redis.conf, starts a local redis-server process, and connects a falkordb client.

Returns: Promise<FalkorDB>

FalkorDB instance methods

• selectGraph(graphId: string): Graph
• list(): Promise<string[]>
• info(section?: string): Promise<unknown> (Redis INFO output)
• configGet(configKey: string): Promise<unknown>
• configSet(configKey: string, value: number | string): Promise<void>
• close(): Promise<void>

FalkorDB getters

• socketPath: string - Unix socket path for the embedded server
• pid: number | undefined - redis-server PID
• isRunning: boolean - whether the server is still alive

Graph API (from falkordb)

selectGraph() returns the exact Graph type from the falkordb package, so all graph methods (query, roQuery, delete, copy, explain, profile, slowLog, constraints, indexes, etc.) work the same. See the upstream client docs for details.

Advanced exports

The package also exports internal building blocks for advanced usage:

• ConfigGenerator, ServerManager, BinaryManager
• registerServer, unregisterServer

These are not required for normal usage but can help with custom embedding.

Configuration options

| Option | Type | Default | Description | | --- | --- | --- | --- | | path | string | temp dir | Data directory for persistence. If set, periodic snapshots are enabled. | | redisServerPath | string | auto | Custom redis-server binary path. | | modulePath | string | auto | Custom FalkorDB module (.so) path. | | maxMemory | string | unset | Redis maxmemory, e.g. "256mb". | | logLevel | 'debug' \| 'verbose' \| 'notice' \| 'warning' | unset | Redis log level. | | logFile | string | stdout | Redis log file path. | | timeout | number | 10000 | Startup timeout in milliseconds. | | additionalConfig | Record<string, string> | none | Extra redis.conf key/value pairs. | | falkordbVersion | string | v4.16.3 | FalkorDB module release tag to download. | | inheritStdio | boolean | false | Pipe redis-server stdout/stderr to the parent. |

Tip: use additionalConfig to set a TCP port (for external tools) by adding { port: '6379' }.

Migration guide (embedded -> remote)

Your graph code stays the same. Only the import and connection line changes:

// Embedded
import { FalkorDB } from 'falkordblite';
const db = await FalkorDB.open();

// Remote (falkordb-ts)
import { FalkorDB } from 'falkordb';
const db = await FalkorDB.connect({
  socket: { host: '127.0.0.1', port: 6379 },
});

Platform support

| Platform | Status | | --- | --- | | Linux x64 | ✅ Fully supported (binaries included) | | macOS arm64 | ✅ Fully supported (binaries included) | | macOS x64 | Use system redis-server + custom module path | | Windows | Use WSL2 or a remote server |

Troubleshooting

See TROUBLESHOOTING.md for common issues and fixes.

Contributing

Contributions are welcome. Please open an issue for major changes, and ensure npm run lint && npm test && npm run build passes before submitting a PR.

License

MIT. See LICENSE.