Server Mode (galaxdb.connect)

galaxdb.connect connects to a running galaxdb-server over the PostgreSQL wire protocol. Use this for production deployments where multiple clients need concurrent access.

Connecting

Python

import galaxdb

# Connect using libpq DSN format
conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")

# All connection parameters
conn = galaxdb.connect(
    "host=db.example.com port=5433 user=galaxdb dbname=galaxdb sslmode=disable"
)

Connection string parameters:

Parameter	Default	Description
host	localhost	Server hostname or IP
port	5433	Wire protocol port
dbname	galaxdb	Database name (ignored, single-db)
user	galaxdb	Username (ignored, no auth yet)
sslmode	disable	SSL mode (disable required currently)

Note

GalaxDB currently reports N (no SSL) on the SSLRequest handshake. Use sslmode=disable in the connection string.

execute()

Same API as embedded mode — returns list[dict] for SELECT, int for DML, str for DDL.

Python

import galaxdb

conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")

# DDL
conn.execute("CREATE TABLE docs (id INT PRIMARY KEY, body TEXT)")

# INSERT
count = conn.execute("INSERT INTO docs (id, body) VALUES (1, 'hello')")
print(count)  # 1

# SELECT
rows = conn.execute("SELECT * FROM docs")
print(rows)  # [{'id': '1', 'body': 'hello'}]

# Semantic search (requires server started with --sidecar --model)
results = conn.execute(
    "SELECT id, body FROM docs WHERE SEMANTIC_MATCH(body, 'greeting', 0.4)"
)

Connection Properties

Python

import galaxdb

conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")

# Check if connection is open
print(conn.is_open)  # True

# String representation
print(conn)  # Connection(dsn='host=localhost port=5433 ...', state=open)

Closing

Python

import galaxdb

conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")

# Execute queries...
conn.execute("SELECT 1")

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

# Further calls raise RuntimeError
try:
    conn.execute("SELECT 1")
except RuntimeError as e:
    print(e)  # connection is closed

Examples

Context manager pattern

Python

import galaxdb
from contextlib import contextmanager

@contextmanager
def get_connection():
    conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")
    try:
        yield conn
    finally:
        conn.close()

with get_connection() as conn:
    rows = conn.execute("SELECT * FROM docs")
    print(rows)

RAG application

Python

import galaxdb

conn = galaxdb.connect("host=localhost port=5433 dbname=galaxdb sslmode=disable")

def search_knowledge_base(query: str, threshold: float = 0.4) -> list[dict]:
    """Search the knowledge base for documents similar to query."""
    results = conn.execute(f"""
        SELECT id, title, content
        FROM knowledge
        WHERE SEMANTIC_MATCH(content, '{query}', {threshold})
        LIMIT 5
    """)
    return results

def add_document(doc_id: int, title: str, content: str) -> None:
    """Add a document to the knowledge base."""
    conn.execute(f"""
        INSERT INTO knowledge (id, title, content)
        VALUES ({doc_id}, '{title}', '{content}')
    """)

# Usage
add_document(1, "Python Guide", "Python is a high-level programming language")
results = search_knowledge_base("programming languages")
for r in results:
    print(f"[{r['id']}] {r['title']}: {r['content'][:60]}...")

psycopg2 alternative

Python

# You can also use psycopg2 directly (standard PostgreSQL client)
import psycopg2

conn = psycopg2.connect(
    host="localhost",
    port=5433,
    dbname="galaxdb",
    sslmode="disable"
)
cur = conn.cursor()

cur.execute("SELECT id, body FROM docs WHERE SEMANTIC_MATCH(body, %s, %s)", 
            ("machine learning", 0.4))
rows = cur.fetchall()
for row in rows:
    print(row)

conn.close()

Embedded Mode

Training API