Connect with a Galactus DB driver
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
| Language | Repository and Quickstart |
|---|---|
| C# | C# driver |
| Rust | Rust driver |
| Java | Java driver |
| Go | Go driver |
| Node.js / TypeScript | Node driver |
| C++ | C++ driver |
| Python | Python 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.
| Address | What it is | Needs |
|---|---|---|
bolt://host:7687 | Bolt over plain TCP | Nothing; refused once TLS is required |
bolt+s://host:7687 | Bolt over TLS, certificate verified | GDB_TLS_CERT and GDB_TLS_KEY on the server (from 1.1.0) |
bolt+ssc://host:7687 | Bolt over TLS, certificate not verified (self-signed) | The same; a client that offers this scheme |
ws://host:7687 | Bolt over WebSocket, for browser-based clients | Nothing |
wss://host:7687 | Bolt over WebSocket over TLS | The TLS certificate (from 1.1.0) |
neo4j://host:7687 | A routing driver; it is given a single-node routing table | A driver that asks for routing |
- Encrypted and plaintext together. With a certificate configured,
plaintext is refused.
GDB_TLS_REQUIRED=falseaccepts 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.4keeps every connection on 4.4. - Signing in. Basic authentication: in
HELLOup to Bolt 5.0, and withLOGONfrom Bolt 5.1, whereLOGOFFdrops 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 withGDB_NEO4J_AGENT=truefor it. - Native Galactus drivers.
bolt://and verifiedbolt+s://, on Bolt 5.0–5.4 or 4.4. They connect directly, without WebSocket or routing. - Explorer.
bolt://,bolt+s://(setGDB_EXPLORER_CA_FILEfor a private certificate authority) orbolt+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.
Related articles
Explorer · Server configuration · Authentication · Compatibility