MongrelDB logo

MongrelDB Kit

The application-facing persistence layer for MongrelDB - schema-aware query builder, migrations, relational constraints, and stable semantics across TypeScript, Rust, Python, and CLI surfaces.

crates.io npm PyPI

Packages And Tools

Surface Package / crate Install or run
TypeScript @visorcraft/mongreldb-kit npm install @visorcraft/mongreldb-kit @visorcraft/mongreldb
Rust mongreldb-kit cargo add mongreldb-kit
Python mongreldb-kit pip install mongreldb-kit
CLI mongreldb-kit-cli (mongreldb-kit binary) cargo run -p mongreldb-kit-cli -- --help

What It Provides

  • Schema helpers for typed tables, stable table/column ids, defaults, indexes, checks, unique constraints, and foreign keys. Full type set: int64, float64, bool, text, bytes (BLOB), timestamp, date, date64, time64, interval, decimal128, UUID, JSON, and array columns.
  • Synchronous TypeScript CRUD/query builder with predicates, ordering, projections, aggregates, joins, subqueries, CTEs, batch inserts, updates, and deletes.
  • Rust and Python APIs backed by the same Rust core and verified with cross-language conformance fixtures.
  • Migration runner with content-addressed checksums, stored schema catalog, table renames, and SQL views.
  • Embedded SQL surface (sql / sqlArrow / sqlRows) with recursive CTEs, window functions, CREATE TABLE AS SELECT, materialized views, multi-statement execution, and a mongreldb_fts_rank relevance-scoring UDF.
  • Storage tuning (spill thresholds, compaction zstd, result-cache sizing, index build policy), trigger config, and per-table introspection (run count, page-cache stats, memtable/cache lengths).
  • BinarySign and full-f32 Dense ANN schema options, plus durable online create/replace index jobs with status, cancellation, resume, and wait APIs in Rust, TypeScript, and Python.
  • Non-blocking async I/O variants (putAsync / queryAsync / countAsync / …) and WriteBuffer micro-batching for high-throughput ingest (TypeScript).
  • Engine-side trigger management plus SQL-backed virtual/external table helpers.
  • Extended SQL Function helpers for JSON, date/time, aggregate, and math-style SQL calls.
  • User/role/credentials management with optional storage-layer enforcement: Argon2id-hashed catalog users, roles, GRANT/REVOKE table-level permissions, daemon HTTP Basic + Bearer auth, and opt-in require_auth credential enforcement (credentialed open/create constructors, enable_auth/disable_auth, offline recovery) - exposed through every language API, the embedded SQL surface, and the CLI (user / role / auth subcommands).
  • Relational constraint enforcement on top of MongrelDB transactions: not-null, type/range/string validation, unique/composite unique, foreign keys, and cascade/set-null/restrict deletes.
  • Multi-process file locking, replication, and change-data-capture via the daemon.

Documentation

History retention and time-travel reads

Both the embedded KitDatabase and the daemon client RemoteDatabase expose history-retention controls:

// TypeScript
db.setHistoryRetentionEpochs(100);   // embedded: number argument
remote.setHistoryRetentionEpochs(100n); // remote: bigint argument
console.log(db.historyRetentionEpochs());     // bigint
console.log(remote.historyRetentionEpochs()); // bigint
console.log(db.earliestRetainedEpoch());      // bigint

# Python (embedded)
db.set_history_retention_epochs(100)
print(db.history_retention_epochs())  # int
print(db.earliest_retained_epoch())   # int

# Python (remote)
remote.set_history_retention_epochs(100)
print(remote.history_retention_epochs())
print(remote.earliest_retained_epoch())

Set retention before writing the data you want to time-travel back to. Embedded databases initially keep only the latest epoch. The daemon defaults to 1024 epochs unless MONGRELDB_HISTORY_RETENTION_EPOCHS overrides it. Increasing retention later cannot restore history that has already been removed. Read past snapshots with db.rowsAtEpoch('table', epoch) (embedded) or SELECT ... AS OF EPOCH <epoch> (embedded SQL and the daemon).

Quick Example

Minimal TypeScript schema and CRUD flow:

TypeScript

import {
  KitDatabase,
  Schema,
  table,
  int,
  text,
  sequenceDefault,
  unique,
  eq
} from '@visorcraft/mongreldb-kit';

const users = table('users', {
  columns: [
    int('id', { primaryKey: true, default: sequenceDefault('users_id_seq') }),
    text('email', { nullable: false }),
    text('name', { nullable: true })
  ],
  primaryKey: 'id',
  unique: [unique(['email'], { name: 'users_email_uq' })]
});

const schema = new Schema([users]);
const db = KitDatabase.openSync('./app-data', schema);

db.migrateSync(schema, [
  {
    version: 1,
    name: 'initial',
    up({ ensureTable }) {
      ensureTable(users);
    }
  }
]);

const alice = db.insertInto(users)
  .values({ email: 'alice@example.com', name: 'Alice' })
  .executeSync();

const [row] = db.selectFrom(users)
  .where(eq(users.id, alice.id))
  .executeSync();

console.log(row);
db.close();

See the language docs for complete runnable examples in TypeScript, Rust, and Python.

Development Notes

  • TypeScript requires Node.js 22+ and the native @visorcraft/mongreldb peer dependency.
  • A MongrelDB database path is a data directory, not a single database file.
  • In this mono-repo checkout, the TypeScript package loads the native addon from the sibling MongrelDB repo. Build crates/mongreldb-node there with npm run build in release mode before benchmarking; stale debug .node builds make bulk paths much slower.

Building and testing

# Rust
rtk cargo check --workspace
rtk cargo test --workspace

# TypeScript
cd packages/kit
rtk npm ci
rtk npm run build
rtk npm run check
rtk npm test

# Python
cd python/mongreldb_kit
rtk python -m venv .venv
rtk .venv/bin/pip install maturin
rtk maturin develop
rtk .venv/bin/pytest ../../python/tests ../../tests/conformance/python

# CLI
rtk cargo run -p mongreldb-kit-cli -- --help

Related tools

  • Mongrel — Commercial multi-system workbench with native MongrelDB support.
  • MongrelDB Viewer — Free, open-source MongrelDB GUI and MCP server.

License

MIT OR Apache-2.0

Project links

Data verified by PyPI on Aug 11, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for visorcraft from gravatar.com visorcraft

Credits

Author: Visorcraft

GitHub Statistics

Data verified by PyPI on Aug 11, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License, MIT License (MIT OR Apache-2.0)

Requires

Python >=3.10

Tags

mongreldb database storage embedded-database columnar ffi

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mongreldb_kit-0.64.16-cp310-abi3-win_amd64.whl (49.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (54.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (56.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

mongreldb_kit-0.64.16-cp310-abi3-macosx_11_0_arm64.whl (49.1 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

mongreldb_kit-0.64.16-cp310-abi3-macosx_10_12_x86_64.whl (51.1 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file mongreldb_kit-0.64.16-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for mongreldb_kit-0.64.16-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 45383d56c0f65d8bd77b86a3bfa28a1ae099186ba9d2341b5bb242c3cd9891e2
MD5 773fb8b48cdfb4b3c92f12046c92b169
BLAKE2b-256 b55fc826e4a31ec2bedd486aa24e1aaad1d1c37d57a6ab7835e8707a0919c0ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for mongreldb_kit-0.64.16-cp310-abi3-win_amd64.whl:

Publisher: release.yml on visorcraft/MongrelDB-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d3b7986626dc0adbb2929c6f33c9953742265a743b7413384e0bbf35a730106a
MD5 b3a28b00496affa46265841b4734ed6b
BLAKE2b-256 b0c3a6b74c694c65517da8de8704880d56d6bfdd0f032d0f7171653c10b593a9

See more details on using hashes here.

Provenance

The following attestation bundles were made for mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on visorcraft/MongrelDB-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 05157945337645c2af64a647436aa890450699ec1ef8ab0bdfda7596cb230cd8
MD5 019cb6c95cf6e1507bedfe57c7540390
BLAKE2b-256 b3f6dca747beda8bf770093e195d17f25c3d53e31080c3584251bee3a336c2cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for mongreldb_kit-0.64.16-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on visorcraft/MongrelDB-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mongreldb_kit-0.64.16-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mongreldb_kit-0.64.16-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ac5313a0a7f4e8ffcd661c63e03ecbc6388f7893dd27016fc3fd689152e23ca8
MD5 2caed59bff39ed2bfe4f07d50b07ef5a
BLAKE2b-256 08f5eb28da36f37853348eacae72f38c77d385a62585c86dbd2aac38d32b7564

See more details on using hashes here.

Provenance

The following attestation bundles were made for mongreldb_kit-0.64.16-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on visorcraft/MongrelDB-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mongreldb_kit-0.64.16-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for mongreldb_kit-0.64.16-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a82b319543ff3b59de449a47c1b6508970a4ed95fa776270a1dd25434e87e21a
MD5 b572b4b51026eaa1950a7f289f8e4164
BLAKE2b-256 1d0df18f28851071df2d34aefb051722bbf8042dcbd73b5af72b237273bc925f

See more details on using hashes here.

Provenance

The following attestation bundles were made for mongreldb_kit-0.64.16-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on visorcraft/MongrelDB-Kit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page