Run any Skill in Manus with one click

code-quality

Stars11

Forks1

UpdatedJuly 24, 2026 at 09:53

VelociDB code conventions - error handling, module boundaries, the experimental-modules policy, locking style, and documentation expectations. Use when writing or reviewing any VelociDB code, deciding where new code lives, or cleaning up warnings.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

niklabh

niklabh/velocidb

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	code-quality
description	VelociDB code conventions - error handling, module boundaries, the experimental-modules policy, locking style, and documentation expectations. Use when writing or reviewing any VelociDB code, deciding where new code lives, or cleaning up warnings.

Code Quality Conventions

Active path vs experimental modules

The SQL engine uses ONLY: storage, btree, parser, executor, transaction, types, wal, vector, cdc, async_api.

mvcc, async_io, lockfree, simd, btree_optimized, crdt, cloud_vfs, hybrid_storage, pmem are experimental: exported for visibility, not wired in. Do not add dependencies from active-path modules to experimental ones, and do not "fix" experimental-module warnings as part of unrelated changes. If a feature graduates, say so explicitly in src/lib.rs and the README.

Error handling

Library code returns crate::types::Result<T> (VelociError). Pick the matching variant: ParseError, ConstraintViolation, NotFound, Corruption (on-disk invariant broken), TransactionError, TypeMismatch, StorageError, Busy.
No unwrap()/expect() on the active path except for logically infallible cases with a justifying message (e.g. expect("group active after begin_group")). Tests and the REPL binary may unwrap freely.
Error strings include the offending identifier: "Table '{}' not found".

Locking style

parking_lot RwLock/Mutex everywhere; locks are NOT reentrant.
Keep guard scopes minimal: clone schema/rows out, drop the guard, then compute. Comment the release point when non-obvious (// schema lock released).
Document lock ordering when a function takes more than one lock (see the header of src/transaction.rs).

Style

Module-level //! docs stating purpose; /// docs with # Example on public Database methods (they compile as doctests — keep them building).
Comments explain invariants and non-obvious "why", never restate the code.
On-disk formats and thresholds are named constants (PAGE_SIZE, BTREE_ORDER, PARALLEL_THRESHOLD, DEFAULT_CDC_CAPACITY).
New feature = update README ("What works today" / "Limitations") and CHANGELOG in the same change. Known limitations are documented, not hidden.
src/main.rs builds against the velocidb library crate — never re-add mod declarations there.

Warnings

Do not introduce new warnings in active-path modules; cargo check --all-targets output for files you touched should be clean. Pre-existing experimental-module warnings stay as-is.

More from this repository

same repository

async-io-model

niklabh/velocidb

How VelociDB's async API and parallel query execution work - the tokio spawn_blocking model in src/async_api.rs and the rayon thresholds in the executor. Use when modifying async_api.rs, adding async methods, tuning parallelism, or debugging blocked runtimes, stalled futures, or async test hangs.

2026-07-2411

cdc

niklabh/velocidb

VelociDB Change Data Capture - the in-memory change log in src/cdc.rs and its executor hooks. Use when modifying cdc.rs, adding CDC hooks to new write paths, changing ChangeEvent fields, or debugging missing/duplicate/out-of-order change events.

2026-07-2411

testing

niklabh/velocidb

How to run and write VelociDB tests - test suite layout, commands, and patterns for unit, integration, crash-recovery, property-based, and async tests. Use when adding features, fixing bugs, writing new tests, or deciding which suites must pass before a change is done.

2026-07-2411

vector-search

niklabh/velocidb

VelociDB vector search implementation - F32_BLOB(n)/VECTOR(n) columns, vector32 literals, distance functions, and exact parallel KNN. Use when modifying src/vector.rs, adding distance metrics, extending vector SQL syntax, or debugging dimension-mismatch, KNN-ordering, or vector-parsing issues.

2026-07-2411

debugging

niklabh/velocidb

Debugging VelociDB - REPL-based reproduction, tracing, inspecting db/WAL files, and a map of common failure modes to their causes. Use when investigating bugs, corruption errors, deadlocks/hangs, wrong query results, or data that disappears after reopen.

2026-07-2411

sql-parser

niklabh/velocidb

Extending VelociDB's regex-based SQL parser in src/parser.rs - statement dispatch, quote/paren-aware splitting helpers, value parsing, and known fragility. Use when adding SQL syntax, new statements or operators, changing WHERE/ORDER BY/VALUES parsing, or debugging "Invalid ... syntax" / mis-split errors.

2026-07-2411

name	code-quality
description	VelociDB code conventions - error handling, module boundaries, the experimental-modules policy, locking style, and documentation expectations. Use when writing or reviewing any VelociDB code, deciding where new code lives, or cleaning up warnings.

Code Quality Conventions

Active path vs experimental modules

The SQL engine uses ONLY: storage, btree, parser, executor, transaction, types, wal, vector, cdc, async_api.

Error handling

Library code returns crate::types::Result<T> (VelociError). Pick the matching variant: ParseError, ConstraintViolation, NotFound, Corruption (on-disk invariant broken), TransactionError, TypeMismatch, StorageError, Busy.
No unwrap()/expect() on the active path except for logically infallible cases with a justifying message (e.g. expect("group active after begin_group")). Tests and the REPL binary may unwrap freely.
Error strings include the offending identifier: "Table '{}' not found".

Locking style

parking_lot RwLock/Mutex everywhere; locks are NOT reentrant.
Keep guard scopes minimal: clone schema/rows out, drop the guard, then compute. Comment the release point when non-obvious (// schema lock released).
Document lock ordering when a function takes more than one lock (see the header of src/transaction.rs).

Style

Module-level //! docs stating purpose; /// docs with # Example on public Database methods (they compile as doctests — keep them building).
Comments explain invariants and non-obvious "why", never restate the code.
On-disk formats and thresholds are named constants (PAGE_SIZE, BTREE_ORDER, PARALLEL_THRESHOLD, DEFAULT_CDC_CAPACITY).
New feature = update README ("What works today" / "Limitations") and CHANGELOG in the same change. Known limitations are documented, not hidden.
src/main.rs builds against the velocidb library crate — never re-add mod declarations there.

Warnings

Do not introduce new warnings in active-path modules; cargo check --all-targets output for files you touched should be clean. Pre-existing experimental-module warnings stay as-is.