Rethinkdb
@shrug/rethinkdbv2026.07.18.5
Security Notice
This extension includes AI agent skills that can modify AI assistant behavior. Review the skill files before installing.
01README
Manage a RethinkDB instance/cluster over ReQL (rethinkdb-ts driver, no REST API): ping/health, Rule-6 fan-out sync of cluster/servers/databases/tables/issues, per-table snapshot, an idempotent declarative provision entrypoint plus create/delete of databases/tables/indexes and reconfigure, and a per-table JSON backup export. Also ships a single-document atomic-CAS distributed lock (provisionLockTable/acquireLock/releaseLock/extendLock/inspectLock/forceRelease) and a verifyDatastore probe. Mutations are confirm-gated and audited on both success and failure.
02Release Notes
Initial publish. Management model for RethinkDB over ReQL. Test drive: 8/8 steps PASS against rethinkdb:2.4. Quality 14/14.
03Models
@shrug/rethinkdbv2026.07.18.5rethinkdb.ts
fn ping()
Reachability + auth pre-flight: r.now() round-trip and server version. Writes a `health` resource. Read-only.
fn sync()
Rule-6 fan-out: ONE execution snapshots cluster/servers/databases/tables/issues into separate resources from the rethinkdb system tables. Read-only.
fn getTable(db: string, table: string)
Snapshot one table's config + status + secondary-index status into a `table` resource. Read-only.
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| table | string | Table name |
fn backup(db: string, table: string)
Per-table JSON export (§7 v1): drain the table's cursor and write a `backup` resource with the full documentCount + byte size and the document array bounded to MAX_BACKUP_BYTES (sampleTruncated when the export exceeds the cap). Non-destructive read export, so it is NOT confirm-gated, but it DOES write an `attempt` audit on both the success and failure paths. Does NOT perform the cluster `rethinkdb dump` (deferred — needs the separate Python CLI).
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| table | string | Table name to export |
fn provision()
PRIMARY ENTRYPOINT. Idempotently ensure the given databases/tables/indexes exist (create-if-absent; indexWait on new indexes). Never drops anything. Gated behind confirm:true; audits on both paths and writes a `provisionResult` summary.
fn createDatabase(name: string, confirm: boolean)
Create a database. Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| name | string | Database name |
| confirm | boolean | Must be true to apply |
fn deleteDatabase(name: string, confirm: boolean)
Drop a database. Verifies existence first (no-op-with-note if absent). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| name | string | Database name |
| confirm | boolean | Must be true to apply |
fn createTable(db: string, name: string, primaryKey?: string, shards?: number, replicas?: number, durability?: enum, confirm: boolean)
Create a table (optional primaryKey/shards/replicas/durability). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| name | string | Table name |
| primaryKey? | string | Primary key field (default id) |
| shards? | number | |
| replicas? | number | |
| durability? | enum | |
| confirm | boolean | Must be true to apply |
fn deleteTable(db: string, name: string, confirm: boolean)
Drop a table. Verifies existence first (no-op-with-note if absent). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| name | string | Table name |
| confirm | boolean | Must be true to apply |
fn createIndex(db: string, table: string, name: string, confirm: boolean)
Create a secondary index (kind = simple|compound|multi|geo) and indexWait for it. Compound accepts optional fields (else the name is the single field). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| table | string | Table name |
| name | string | Index name |
| confirm | boolean | Must be true to apply |
fn deleteIndex(db: string, table: string, name: string, confirm: boolean)
Drop a secondary index. Verifies existence first (no-op-with-note if absent). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| table | string | Table name |
| name | string | Index name |
| confirm | boolean | Must be true to apply |
fn reconfigure(db: string, shards: number, replicas: number, confirm: boolean)
Reshard/re-replicate a table (if `table` given) or a whole database's tables via .reconfigure({shards, replicas}). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| db | string | Database name |
| shards | number | Number of shards |
| replicas | number | Number of replicas |
| confirm | boolean | Must be true to apply |
fn provisionLockTable(confirm: boolean)
Create the distributed-lock table (create-if-absent, primaryKey `id`) out-of-band. This is the SANCTIONED setup path: run it once, single-threaded — never let contending acquireLock callers create it lazily (RethinkDB 2.4 does NOT enforce table-name uniqueness under concurrent tableCreate, which yields duplicate tables and `Table is ambiguous`). Gated behind confirm:true; audited on both paths.
| Argument | Type | Description |
|---|---|---|
| confirm | boolean | Must be true to apply |
fn acquireLock(lockKey: string, tableName: string)
OPERATIONAL (not confirm-gated). Acquire a distributed lock via a single atomic CAS replace: wins a free OR stale (expired) document, retrying with jittered backoff up to maxWaitMs. Assumes the lock table already exists (run provisionLockTable first). On a WIN, writes the authoritative `lock[lockKey]` resource with acquired:true + the ownership nonce (use it to release/extend). On a LOSS/timeout, records the miss under `lock[${lockKey}:miss:<short-nonce>]` so it never clobbers the current holder
| Argument | Type | Description |
|---|---|---|
| lockKey | string | Lock key (== lock document primary key) |
| tableName | string | Lock table name |
fn releaseLock(lockKey: string, nonce: string, tableName: string)
OPERATIONAL, NONCE-GATED. Release a lock via a single atomic compare-and-delete: frees the document only when its stored nonce matches (a stale nonce must NOT free another holder's lock). Writes a `lock` resource with the released outcome. Assumes the lock table exists (run provisionLockTable/acquireLock first); if the table is absent this propagates the raw ReQL error rather than swallowing it.
| Argument | Type | Description |
|---|---|---|
| lockKey | string | Lock key |
| nonce | string | Ownership nonce from acquireLock |
| tableName | string | Lock table name |
fn extendLock(lockKey: string, nonce: string, tableName: string)
OPERATIONAL, NONCE-GATED TTL heartbeat. Extend a held lock's expiry via a single atomic replace gated on the nonce (a taken-over lock cannot be resurrected). Writes a `lock` resource with the extended outcome and the new expiresAt (re-fetched to confirm when returnChanges is empty). Assumes the lock table exists (run provisionLockTable/acquireLock first); if the table is absent this propagates the raw ReQL error rather than swallowing it.
| Argument | Type | Description |
|---|---|---|
| lockKey | string | Lock key |
| nonce | string | Ownership nonce from acquireLock |
| tableName | string | Lock table name |
fn inspectLock(lockKey: string, tableName: string)
READ. Snapshot the current lock document (or its absence) into a `lock` resource; outcome is true when a live (unexpired) lock is present. Read-only. Assumes the lock table exists (run provisionLockTable/acquireLock first); if the table is absent this propagates the raw ReQL error rather than swallowing it.
| Argument | Type | Description |
|---|---|---|
| lockKey | string | Lock key |
| tableName | string | Lock table name |
fn forceRelease(lockKey: string, tableName: string, confirm: boolean)
CONFIRM-GATED + NONCE-GATED destructive override. Force-free a lock via a single atomic compare-and-delete, but ONLY when expectedNonce matches the stored nonce (so it still cannot silently steal another live holder's lock). Gated behind confirm:true; audited on both paths, and writes a `lock` resource with the freed outcome.
| Argument | Type | Description |
|---|---|---|
| lockKey | string | Lock key |
| tableName | string | Lock table name |
| confirm | boolean | Must be true to apply |
fn verifyDatastore()
Datastore reachability/latency probe: an r.now() round-trip plus a check that the lock table is present. Writes a `datastoreHealth` resource; never throws (healthy=false with a scrubbed error on failure). Read-only.
Resources
health(30d)— Reachability/health snapshot: round-trip latency and server version
cluster(infinite)— Snapshot of rethinkdb.cluster_config
servers(infinite)— Snapshot of all servers (server_status joined with server_config)
databases(infinite)— Snapshot of all databases (rethinkdb.db_config)
tables(infinite)— Snapshot of all tables (table_config joined with table_status)
issues(30d)— Snapshot of rethinkdb.current_issues
table(infinite)— Snapshot of one table: config + status + secondary-index status
provisionResult(infinite)— Summary of an idempotent provision apply (created/existing/skipped counts)
attempt(infinite)— Audit record of a mutation attempt (request + result/error + timestamp). Written on both success and failure.
backup(90d)— Per-table JSON export snapshot (driver cursor→JSON, §7 v1). Records the full documentCount and byte size; stores the document array bounded to MAX_BACKUP_BYTES (sampleTruncated=true when the full export exceeded the cap). Non-destructive read export — NOT the cluster `rethinkdb dump`.
lock(1h)— Outcome of a distributed-lock operation on a swamp_lock document. The authoritative holder is the `lock[lockKey]` instance (written only by the winning acquire or the owner's release/extend/forceRelease); a losing acquire records a `${lockKey}:miss:<short-nonce>` instance instead. Carries holder/nonce/expiry and the acquire/release/extend/inspect/forceRelease outcome.
datastoreHealth(30d)— RethinkDB datastore reachability/latency probe (r.now() round-trip + lock-table presence).
04Reports
@shrug/rethinkdb-replica-healthmodel
rethinkdb_replica_health.ts
Derive under-replicated / not-ready tables and current cluster issues from the latest sync snapshot; render as markdown plus machine-readable JSON.
rethinkdbreplicationhealth
05Skills
rethinkdb1 file
06Stats
A
100 / 100
Downloads
1
Archive size
116.2 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
07Platforms
08Labels