Embedded Mode (galaxdb.Database)

galaxdb.Database opens a GalaxDB database directly in the Python process. No server required — similar to SQLite. The database is stored in a directory on disk.

Opening a Database

Python

import galaxdb

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

# The path is created if it doesn't exist
db = galaxdb.Database("/var/lib/myapp/db")

# Inspect the database
print(db)  # Database(path='./mydata', tables=0)
print(db.path)  # './mydata'

Note

galaxdb.Database is not thread-safe. For concurrent access, use server mode (galaxdb.connect) which handles concurrent connections safely.

execute()

db.execute(sql) executes a SQL statement and returns a result based on the statement type:

SELECT / SHOW: returns list[dict[str, str]] — one dict per row
INSERT / UPDATE / DELETE: returns int — number of rows affected
DDL (CREATE, DROP, ANALYZE, etc.): returns str — status message

Python

import galaxdb

db = galaxdb.Database("./data")

# DDL — returns str
result = db.execute("CREATE TABLE docs (id INT PRIMARY KEY, body TEXT)")
print(result)  # "OK"

# INSERT — returns int
count = db.execute("INSERT INTO docs (id, body) VALUES (1, 'hello world')")
print(count)  # 1

# SELECT — returns list of dicts
rows = db.execute("SELECT * FROM docs")
print(rows)  # [{'id': '1', 'body': 'hello world'}]

# Empty SELECT — returns empty list
rows = db.execute("SELECT * FROM docs WHERE id = 999")
print(rows)  # []

# UPDATE — returns int
count = db.execute("UPDATE docs SET body = 'updated' WHERE id = 1")
print(count)  # 1

# DELETE — returns int
count = db.execute("DELETE FROM docs WHERE id = 1")
print(count)  # 1

Note

All values in the returned dicts are strings. Cast them as needed:int(row['id']), float(row['price']).

Properties

Python

import galaxdb

db = galaxdb.Database("./data")
db.execute("CREATE TABLE t1 (id INT PRIMARY KEY)")
db.execute("CREATE TABLE t2 (id INT PRIMARY KEY)")

# Path to the database directory
print(db.path)  # './data'

# Number of tables
print(db.table_count)  # 2

Table Methods

Python

import galaxdb

db = galaxdb.Database("./data")
db.execute("CREATE TABLE users (id INT PRIMARY KEY, name TEXT)")

# Check if a table exists
print(db.table_exists("users"))   # True
print(db.table_exists("orders"))  # False

Examples

Complete workflow

Python

import galaxdb

db = galaxdb.Database("./knowledge-base")

# Create table with embeddings
db.execute("""
    CREATE TABLE IF NOT EXISTS docs (
        id   INT PRIMARY KEY,
        body TEXT EMBEDDING MODEL 'sentence-transformers/all-MiniLM-L6-v2' DIM 384
    )
""")

# Insert documents
documents = [
    (1, "Python is a high-level programming language"),
    (2, "Rust is a systems programming language focused on safety"),
    (3, "Machine learning uses statistical methods to learn from data"),
    (4, "Deep learning uses neural networks with many layers"),
    (5, "Vector databases store and search high-dimensional embeddings"),
]
for doc_id, text in documents:
    db.execute(f"INSERT INTO docs (id, body) VALUES ({doc_id}, '{text}')")

# Semantic search
results = db.execute(
    "SELECT id, body FROM docs WHERE SEMANTIC_MATCH(body, 'AI and neural networks', 0.4)"
)
print(f"Found {len(results)} results:")
for row in results:
    print(f"  [{row['id']}] {row['body']}")

Error handling

Python

import galaxdb

db = galaxdb.Database("./data")

try:
    db.execute("SELECT * FROM nonexistent_table")
except RuntimeError as e:
    print(f"Error: {e}")  # Error: table 'nonexistent_table' not found

try:
    db.execute("INSERT INTO docs (id, body) VALUES (1, 'duplicate')")
    db.execute("INSERT INTO docs (id, body) VALUES (1, 'duplicate')")  # primary key conflict
except RuntimeError as e:
    print(f"Error: {e}")  # Error: primary key constraint violation

Overview

Server Mode