SMBDB

SMBDB is an early-stage embedded relational database engine designed for safe, selective access to databases stored on SMB shares. This repository currently contains the project foundation, local and direct SMB storage backends, a versioned database format, immutable column segments, pruning, and adaptive block compression, an initial SQL frontend, and immutable primary-key indexes.

Requires Python 3.11 or newer. See docs/architecture.md and docs/storage-format.md for the current design.

import smbdb

db = smbdb.create("/tmp/company.smbdb")
db.close()

db = smbdb.connect("/tmp/company.smbdb")
print(db.info())
db.close()

If creation was interrupted before CURRENT was published, resume only that generation-zero directory explicitly:

db = smbdb.create("company.smbdb", recover_incomplete=True)

The equivalent CLI option is smbdb create company.smbdb --recover-incomplete. SMBDB refuses this recovery when newer manifests or transaction history exist.

The same SQL API works with a local path or an smb:// URL:

db = smbdb.create("/tmp/company.smbdb")
db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)")
db.execute("INSERT INTO users (id, name) VALUES (?, ?)", [1, "Adam"])
print(db.execute("SELECT name FROM users WHERE id = ?", [1]).fetchall())
db.close()

Direct SMB does not require a mount or a server-side SMBDB process:

db = smbdb.create(
    "smb://fileserver/share/company.smbdb",
    username="user",
    password="secret",
)
db.close()

Long-running remote workloads can configure maintenance, lease heartbeat, and the non-authoritative local immutable cache:

db = smbdb.connect(
    "smb://fileserver/share/company.smbdb",
    username="user",
    password="secret",
    auto_maintenance=True,
    optimize_segment_threshold=32,
    vacuum_pack_threshold=16,
    lease_heartbeat_interval=300,
    immutable_cache=True,
    cache_directory="/fast-local-disk/smbdb-cache",
    cache_size_limit=1024**3,
)
print(db.storage_stats()["io"])

Development checks:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest
.venv/bin/ruff check .
.venv/bin/mypy src/smbdb