Metadata-Version: 2.4
Name: smbdb
Version: 0.1.0.dev3
Summary: An embedded relational database designed for direct SMB storage
Author: SMBDB contributors
License: Apache-2.0
Project-URL: Documentation, https://github.com/smbdb/smbdb
Project-URL: Source, https://github.com/smbdb/smbdb
Keywords: database,embedded,smb,storage
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: smbprotocol<2,>=1.15
Requires-Dist: zstandard<1,>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"

# 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.

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

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

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

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

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

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