# Connect with a Galactus DB driver

[Wiki](../README.md) / [Clients and drivers](README.md)

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](https://github.com/galactusdb/galactus-db-csharp-driver#quickstart) |
| Rust | [Rust driver](https://github.com/galactusdb/galactus-db-rust-driver#quickstart) |
| Java | [Java driver](https://github.com/galactusdb/galactus-db-java-driver#quickstart) |
| Go | [Go driver](https://github.com/galactusdb/galactus-db-go-driver#quickstart) |
| Node.js / TypeScript | [Node driver](https://github.com/galactusdb/galactus-db-node-driver#quickstart) |
| C++ | [C++ driver](https://github.com/galactusdb/galactus-db-cpp-driver#quickstart) |
| Python | [Python driver](https://github.com/galactusdb/galactus-db-python-driver#quickstart) |

The [driver catalogue](https://galactusdb.com/product/drivers) 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=false` accepts both on the same port
  while you move clients across. See
  [encrypted connections](../operations/authentication.md#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](../getting-started/quickstart.md). 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](../operations/configuration.md).

### Python

Install from the public repository:

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

```python
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

```sh
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.

```js
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](../types/spatial-shapes.md#formats-validation-and-drivers).

## 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](../operations/transactions.md).

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](../operations/authentication.md#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](../operations/transactions.md#time-limits). 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](../operations/transactions.md#snapshot-reads).

## Related articles

[Explorer](../explorer/README.md) · [Server configuration](../operations/configuration.md) · [Authentication](../operations/authentication.md) · [Compatibility](../reference/compatibility.md)
