Connect with a Galactus DB driver

Wiki / Clients and drivers

Galactus DB provides native drivers for C#, Rust, Java, Go, Node.js / TypeScript, C++ and Python. Each driver uses Bolt 4.4 directly, with no third-party runtime package dependencies. Version 0.1 is early access: source repositories are public on main; package-registry releases are not available yet.

Choose a language

The driver catalogue lists runtime requirements and installation options. Each repository documents its API, type mapping, spatial values and tests. Pin a reviewed commit for reproducible builds.

Connecting with a driver

Start the database. Applications on your host use bolt://127.0.0.1:7687; applications on the example Compose network use bolt://db:7687. Supply the configured database username and password separately from the URI. The examples below use username gdb and read GDB_PASSWORD from the application environment. This variable is an example convention; it does not set the database password or change GDB_INITIAL_PASSWORD on the server.

An empty or omitted database selects the server's configured home database. Supply an existing database name to select another. Driver constructors do not create databases. See configuration.

Python

Install from the public repository:

python -m pip install git+https://github.com/galactusdb/galactus-db-python-driver.git@main

import os
from galactus import Driver

with Driver("bolt://127.0.0.1:7687", "gdb", os.environ["GDB_PASSWORD"]) as driver:
    result = driver.execute_query("RETURN $name AS name", {"name": "Ada"})
    print(result.records[0]["name"])

Node.js / TypeScript

npm install github:galactusdb/galactus-db-node-driver#main

Save the following as an ESM module (.mjs, or use "type":"module" in package.json). TypeScript declarations are included.

import { Driver } from 'galactus-db-node-driver';

const driver = await Driver.connect('bolt://127.0.0.1:7687', {
  username: 'gdb', password: process.env.GDB_PASSWORD,
});
try {
  const result = await driver.executeQuery('RETURN $name AS name', { name: 'Ada' });
  console.log(result.records[0].name);
} finally {
  driver.close();
}

Use parameters for values rather than constructing Cypher from user input. Records are keyed by column name; use unique column aliases. Node returns integers as bigint and encodes number parameters as FLOAT; use 37n for an INTEGER.

Types and spatial values

Parameters support native scalars, bytes, lists and string-keyed maps. Results include typed nodes, relationships and paths. Temporal wrappers retain values that cannot be represented exactly by the language's native types.

Drivers decode the database's spatial envelope into Spatial objects for all seven geometry/geography shape families, XY/XYZ dimensions and typed empties. Binding a Spatial object sends its envelope; use spatial.fromMap($shape) to store it as a database spatial value. See spatial types.

Transactions and connection lifecycle

Queries autocommit unless the connection has an explicit transaction. Use begin/commit/rollback on the same driver, and close or dispose it after use. Closing an unfinished transaction rolls it back. See the executable example in transactions.

Version 0.1 owns one connection per driver and buffers results in memory. Use a separate driver for concurrent units of work and bound large queries with LIMIT or application pagination. Pooling, routing discovery, managed retries, lazy cursors and cancellation are not implemented. Only Node provides an async API.

Protocol, transport and database failures discard the connection. Open a new driver after failure. A lost connection during COMMIT can leave the outcome unknown; reconcile the write before retrying it.

Encryption and timeouts

Python, Node, Go, Java and C# support verified bolt+s:// through their runtime's TLS facilities. Rust and C++ require an external TLS tunnel in this dependency-free release. The database listener itself is plaintext, so encrypted connections need a TLS terminator. No driver silently falls back from TLS to plaintext.

Timeouts default to 30 seconds. Most drivers bound socket waits; Go applies an operation deadline. These are not query cancellation guarantees. Check the language Quickstart for timeout units and concurrency rules.

The Bolt server

The server speaks Bolt 4.4 with PackStream encoding. Basic authentication in HELLO is required before queries. It supports autocommit queries, explicit transactions, typed graph results, summary metadata, and RESET of a failed query state. Authentication failures close the connection.

The server also exposes a single-node routing table and Bolt over WebSocket for compatible clients. The native drivers use direct TCP connections and do not implement routing or WebSocket transport. Server protocol capabilities do not imply that every client implements them.

Read transactions may overlap but do not capture a repeatable-read snapshot. Statements observe committed live data after any conflicting writer completes. See concurrency.

Related articles

Explorer · Server configuration · Authentication · Compatibility