Python Client

The GalaxDB Python client provides PyO3 bindings for both embedded mode (no server required) and server mode (connects to a running galaxdb-server over the PostgreSQL wire protocol).

Installation

bash

pip install galaxdb-client

The package includes pre-built wheels for Python 3.9+ on Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64).

Embedded Mode

Embedded mode opens a GalaxDB database directly in the Python process — no server required. This is similar to SQLite's embedded mode.

Python

import galaxdb

# Open or create a database
db = galaxdb.Database("./mydata")

# Execute SQL
db.execute("CREATE TABLE users (id INT PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO users (id, name) VALUES (1, 'Alice')")

# SELECT returns list of dicts
rows = db.execute("SELECT * FROM users")
for row in rows:
    print(row)  # {'id': '1', 'name': 'Alice'}

# INSERT/UPDATE/DELETE returns int (row count)
count = db.execute("DELETE FROM users WHERE id = 1")
print(count)  # 1

# DDL returns str
result = db.execute("DROP TABLE users")
print(result)  # "OK"

Server Mode

Server mode connects to a running galaxdb-server over the PostgreSQL wire protocol. The connection string uses libpq DSN format.

Python

import galaxdb

# Connect to server
conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")

# Same API as embedded mode
conn.execute("CREATE TABLE t (id INT PRIMARY KEY, name TEXT)")
rows = conn.execute("SELECT * FROM t")

# Check connection state
print(conn.is_open)  # True

# Close connection
conn.close()
print(conn.is_open)  # False

API Overview

Method / Property	Mode	Returns
galaxdb.Database(path)	Embedded	Database instance
galaxdb.connect(dsn)	Server	Connection instance
db.execute(sql)	Both	list[dict] \| int \| str
db.path	Embedded	str
db.table_count	Embedded	int
db.table_exists(name)	Embedded	bool
db.training_dataset(tag)	Embedded	str (Lance path)
db.create_training_snapshot(name, seed)	Embedded	int (timestamp)
conn.is_open	Server	bool
conn.close()	Server	None

ANALYZE

Embedded Mode