Connect with a Galactus DB driver

Wiki / Clients and drivers

Galactus DB provides open source drivers, under Apache-2.0, for C#, Rust, Java, Go, Node.js / TypeScript, C++ and Python. Version 0.2 speaks Bolt 5.0 to 5.4 with a Bolt 4.4 fallback, verifies TLS in every language and keeps the default builds free of third-party packages. Install from the public repositories on main.

Choose a language

LanguageRepository and Quickstart
C#C# driver
RustRust driver
JavaJava driver
GoGo driver
Node.js / TypeScriptNode driver
C++C++ driver
PythonPython driver

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.

Ways to connect

Everything below is served on the one Bolt port (7687 by default). The server recognises each kind of connection from its first bytes, so nothing is configured per mode except the TLS certificate.

AddressWhat it isNeeds
bolt://host:7687Bolt over plain TCPNothing; refused once TLS is required
bolt+s://host:7687Bolt over TLS, certificate verifiedGDB_TLS_CERT and GDB_TLS_KEY on the server (from 1.1.0)
bolt+ssc://host:7687Bolt over TLS, certificate not verified (self-signed)The same; a client that offers this scheme
ws://host:7687Bolt over WebSocket, for browser-based clientsNothing
wss://host:7687Bolt over WebSocket over TLSThe TLS certificate (from 1.1.0)
neo4j://host:7687A routing driver; it is given a single-node routing tableA driver that asks for routing
  • Encrypted and plaintext together. With a certificate configured, plaintext is refused. GDB_TLS_REQUIRED=false accepts both on the same port while you move clients across. See encrypted connections.
  • Protocol versions. Bolt 4.4 and, from 1.1.0, Bolt 5.0 to 5.4. The server picks the newest version the client offers; GDB_BOLT_MAX_VERSION=4.4 keeps every connection on 4.4.
  • Signing in. Basic authentication: in HELLO up to Bolt 5.0, and with LOGON from Bolt 5.1, where LOGOFF drops the identity without closing the connection. A connection must authenticate within 30 seconds.
  • Official Neo4j drivers. They connect with the schemes above. The Python driver refuses a server whose agent does not begin Neo4j/, so start the database with GDB_NEO4J_AGENT=true for it.
  • Native Galactus drivers. bolt:// and verified bolt+s://, on Bolt 5.0–5.4 or 4.4. They connect directly, without WebSocket or routing.
  • Explorer. bolt://, bolt+s:// (set GDB_EXPLORER_CA_FILE for a private certificate authority) or bolt+ssc://.
  • Connection limit. 1,024 connections at once by default (GDB_MAX_CONNECTIONS).

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.

Each driver owns one connection and buffers results in memory. Use a separate driver for each concurrent unit of work, and bound large queries with LIMIT or application pagination. Node provides an async API.

After a database error, the driver sends RESET and stays usable; an open transaction is closed and the error carries its Galactus code, classification and a retryable flag for transient errors. Protocol and transport failures discard the connection, so open a new driver. A lost connection during COMMIT can leave the outcome unknown; reconcile the write before retrying it.

Encryption and timeouts

Every driver supports verified bolt+s://, trusting the platform's certificate store or a PEM file you supply (the trusted certificates option, for a private CA or a self-signed development server). Python, Node, Go, Java and C# use their runtime's TLS. Rust needs the tls cargo feature (rustls) and C++ the CMake option GALACTUS_WITH_TLS (SChannel on Windows, OpenSSL elsewhere); their default builds reject bolt+s:// with an error naming the setting. The database terminates TLS itself once a certificate is configured (see encrypted connections); without one the listener is plaintext. 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 and 5.0–5.4 with PackStream encoding and picks the newest version a client offers; the native drivers offer 4.4. Basic authentication is required before queries. The official Neo4j Python driver refuses any server whose agent does not begin Neo4j/; start the database with GDB_NEO4J_AGENT=true to use it. PULL honours the requested row count, and tx_timeout sets a time limit. It supports autocommit queries, explicit transactions, typed graph results, summary metadata, and RESET of a failed query state. Authentication failures close the connection.

Every error code is a Galactus.* code in the four-part shape drivers parse, such as Galactus.ClientError.Statement.SyntaxError, so drivers still classify client, transient and database errors. With GDB_NEO4J_AGENT=true the server sends the Neo4j spelling (Neo.ClientError.Statement.SyntaxError) of the codes the Neo4j drivers turn into specific exceptions, such as AuthError and CypherSyntaxError, so applications that catch those keep working.

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. From version 1.6.1 each one reads a single snapshot from BEGIN to COMMIT and never waits for a writer. See snapshot reads.

Explorer · Server configuration · Authentication · Compatibility

Planning a deployment? Review compatibility and licence setup for your instance.