Merge pull request #480 from tidesdb/reference-docs-updates

update ffi library references to align with their current versions

Author: guycipher

public/analysis-tidesql-v4-3-0-mariadb-v11-8-6-tpc-c/iibench-results-2026-04-23/bench_batch_sweep.py

@@ -81,7 +81,7 @@ def start_mariadbd():
 
 
 def patch_header(bulk_ops, idx_batch):
-    """Rewrite the two batch constants in ha_tidesdb.h. Idempotent — always starts
+    """Rewrite the two batch constants in ha_tidesdb.h. Idempotent - always starts
     from the pristine header backup."""
     with open(HEADER_BAK) as f:
         src = f.read()

src/content/docs/reference/cplusplus.md

@@ -231,6 +231,18 @@ txn.del(cf, "key");
 txn.commit();
 ```
 
+#### Single Delete
+
+`singleDelete` emits a single-delete tombstone. When the tombstone meets exactly one prior put for the same key during compaction, both records are dropped, so the tombstone does not persist past its matching put. Use it only when the caller guarantees at most one put precedes the delete; otherwise prefer `del`.
+
+```cpp
+auto cf = db.getColumnFamily("my_cf");
+
+auto txn = db.beginTransaction();
+txn.singleDelete(cf, "key");
+txn.commit();
+```
+
 #### Multi-Operation Transactions
 
 ```cpp
@@ -1093,7 +1105,7 @@ Use `ObjectStoreConfig::defaultConfig()` for sensible defaults, then override fi
 
 ### Per-CF Object Store Tuning
 
-Column family configurations include three object store tuning fields.
+Column family configurations include two object store tuning fields.
 
 - `objectLazyCompaction` · 1 to compact less aggressively for remote storage (default: 0)
 - `objectPrefetchCompaction` · 1 to download all inputs before compaction merge (default: 1)

src/content/docs/reference/csharp.md

@@ -19,6 +19,14 @@ You **must** have the TidesDB shared C library installed on your system. You can
 
 ### Installation
 
+Install the package from NuGet:
+
+```bash
+dotnet add package TidesDB
+```
+
+Or build from source:
+
 ```bash
 git clone https://github.com/tidesdb/tidesdb-cs.git
 cd tidesdb-cs
@@ -326,6 +334,26 @@ txn.Delete(cf, Encoding.UTF8.GetBytes("key"));
 txn.Commit();
 ```
 
+#### Single-Delete
+
+`Transaction.SingleDelete` writes a tombstone with the same read semantics as `Delete`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key.
+
+```csharp
+var cf = db.GetColumnFamily("my_cf")!;
+
+using var txn = db.BeginTransaction();
+
+txn.SingleDelete(cf, Encoding.UTF8.GetBytes("key"));
+
+txn.Commit();
+```
+
+When in doubt, prefer `Transaction.Delete`.
+
 #### Multi-Operation Transactions
 
 ```csharp
@@ -1236,6 +1264,7 @@ using TidesDB;
 // -- ColumnFamily.UpdateRuntimeConfig(ColumnFamilyConfig config, bool persistToDisk)
 // -- ColumnFamily.Purge()
 // -- ColumnFamily.SyncWal()
+// -- Transaction.SingleDelete(ColumnFamily cf, ReadOnlySpan<byte> key)
 // -- Iterator.KeyValue()
 
 // Enums

src/content/docs/reference/go.md

@@ -408,6 +408,39 @@ if err != nil {
 }
 ```
 
+#### Single-Delete
+
+`SingleDelete` writes a tombstone with the same read semantics as `Delete`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key.
+
+```go
+cf, err := db.GetColumnFamily("my_cf")
+if err != nil {
+    log.Fatal(err)
+}
+
+txn, err := db.BeginTxn()
+if err != nil {
+    log.Fatal(err)
+}
+defer txn.Free()
+
+err = txn.SingleDelete(cf, []byte("key"))
+if err != nil {
+    log.Fatal(err)
+}
+
+err = txn.Commit()
+if err != nil {
+    log.Fatal(err)
+}
+```
+
+Returns `nil` on success or a non-nil error on failure. When in doubt, prefer `Delete`.
+
 #### Multi-Operation Transactions
 
 ```go
@@ -1807,4 +1840,7 @@ go test -v -run TestCfConfigIni
 
 # Run error code readonly test
 go test -v -run TestErrorCodeReadonly
+
+# Run single-delete transaction test
+go test -v -run TestTransactionSingleDelete
 ```

src/content/docs/reference/java.md

@@ -192,6 +192,25 @@ try (Transaction txn = db.beginTransaction()) {
 }
 ```
 
+#### Single-Delete
+
+`txn.singleDelete` writes a tombstone with the same read semantics as `txn.delete`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key.
+
+```java
+ColumnFamily cf = db.getColumnFamily("my_cf");
+
+try (Transaction txn = db.beginTransaction()) {
+    txn.singleDelete(cf, "key".getBytes());
+    txn.commit();
+}
+```
+
+When in doubt, prefer `txn.delete`.
+
 #### Transaction Rollback
 
 ```java
@@ -748,7 +767,7 @@ try (TidesDB db = TidesDB.open(config)) {
 
 ### Per-CF Object Store Tuning
 
-Column family configurations include three object store tuning fields:
+Column family configurations include two object store tuning fields:
 
 ```java
 ColumnFamilyConfig cfConfig = ColumnFamilyConfig.builder()

src/content/docs/reference/lua.md

@@ -270,6 +270,27 @@ txn:commit()
 txn:free()
 ```
 
+#### Single-Delete
+
+`txn:single_delete(cf, key)` writes a tombstone with the same read semantics as `txn:delete`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key.
+
+```lua
+local cf = db:get_column_family("my_cf")
+
+local txn = db:begin_txn()
+
+txn:single_delete(cf, "mykey")
+
+txn:commit()
+txn:free()
+```
+
+When in doubt, prefer `txn:delete`.
+
 #### Multi-Operation Transactions
 
 ```lua
@@ -1401,6 +1422,7 @@ lua test_tidesdb.lua
 | `txn:put(cf, key, value, ttl)` | Put a key-value pair |
 | `txn:get(cf, key)` | Get a value by key |
 | `txn:delete(cf, key)` | Delete a key |
+| `txn:single_delete(cf, key)` | Delete a key with at-most-one-put promise (see Single-Delete) |
 | `txn:commit()` | Commit the transaction |
 | `txn:rollback()` | Rollback the transaction |
 | `txn:reset(isolation)` | Reset transaction for reuse with new isolation level |

src/content/docs/reference/python.md

@@ -202,6 +202,24 @@ with db.begin_txn() as txn:
     txn.commit()
 ```
 
+### Single-Delete
+
+`single_delete` writes a tombstone with the same read semantics as `delete`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key.
+
+```python
+cf = db.get_column_family("my_cf")
+
+with db.begin_txn() as txn:
+    txn.single_delete(cf, b"mykey")
+    txn.commit()
+```
+
+When in doubt, prefer `delete`.
+
 ### Transaction Reset
 
 `reset()` resets a committed or aborted transaction for reuse with a new isolation level. This avoids the overhead of freeing and reallocating transaction resources in hot loops.

src/content/docs/reference/rust.md

@@ -40,7 +40,7 @@ The easiest way to add TidesDB to your project is via [crates.io](https://crates
 
 ```toml
 [dependencies]
-tidesdb = "0.6"
+tidesdb = "0.7"
 ```
 
 Or using `cargo add`:
@@ -65,22 +65,22 @@ Each crate release defaults to a specific TidesDB C library version. You can sel
 
 ```toml
 [dependencies]
-# Uses the default version (currently v9.0.6)
-tidesdb = "0.6"
+# Uses the default version (currently v9.1.0)
+tidesdb = "0.7"
 
 # Pin to a specific TidesDB version
-tidesdb = { version = "0.6", default-features = false, features = ["v9_0_5"] }
+tidesdb = { version = "0.7", default-features = false, features = ["v9_0_5"] }
 ```
 
-Only one version feature can be enabled at a time. The version feature (e.g., `v9_0_6`) maps directly to the TidesDB C library release tag (e.g., `v9.0.6`).
+Only one version feature can be enabled at a time. The version feature (e.g., `v9_1_0`) maps directly to the TidesDB C library release tag (e.g., `v9.1.0`).
 
 ### Object Store Support
 
 To enable S3 object store support, enable the `objectstore` feature:
 
 ```toml
 [dependencies]
-tidesdb = { version = "0.6", features = ["objectstore"] }
+tidesdb = { version = "0.7", features = ["objectstore"] }
 ```
 
 This requires additional dependencies:
@@ -369,6 +369,41 @@ fn main() -> tidesdb::Result<()> {
 }
 ```
 
+#### Single-Delete
+
+`Transaction::single_delete` writes a tombstone with the same read semantics as `Transaction::delete`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key. When in doubt, prefer `Transaction::delete`.
+
+Requires tidesdb >= 9.1.0 (the `v9_1_0` Cargo feature, enabled by default in `tidesdb` 0.7).
+
+```rust
+use tidesdb::{TidesDB, Config, ColumnFamilyConfig};
+
+fn main() -> tidesdb::Result<()> {
+    let db = TidesDB::open(Config::new("./mydb"))?;
+    db.create_column_family("my_cf", ColumnFamilyConfig::default())?;
+
+    let cf = db.get_column_family("my_cf")?;
+
+    let mut txn = db.begin_transaction()?;
+    txn.single_delete(&cf, b"key")?;
+    txn.commit()?;
+
+    Ok(())
+}
+```
+
+Signature:
+
+```rust
+pub fn single_delete(&self, cf: &ColumnFamily, key: &[u8]) -> Result<()>;
+```
+
+Returns `Ok(())` on success or an `Error` on failure.
+
 #### Multi-Operation Transactions
 
 ```rust

src/content/docs/reference/tidesql.md

@@ -208,20 +208,20 @@ The engine supports Index Condition Pushdown for secondary index scans. When the
 
 ### Multi-Range Read (MRR)
 
-The engine implements a custom MRR path for point-lookup batches such as `WHERE col IN (v1, v2, ..., vN)` on a primary or full-key unique index. When every range the optimizer hands the engine is a full-key point equality (`UNIQUE_RANGE | EQ_RANGE`) and there are at least two ranges, the engine buffers them, converts each key into comparable bytes, and sorts by those bytes so the LSM sees a monotone stream of seeks — much friendlier to the block cache and the merge-heap than N scattered seeks in user-supplied order. Primary-key lookups bypass the iterator entirely via `fetch_row_by_pk`; secondary-index lookups reuse a single cached iterator and do one seek per entry. Ranges whose rows have been deleted concurrently are silently skipped.
+The engine implements a custom MRR path for point-lookup batches such as `WHERE col IN (v1, v2, ..., vN)` on a primary or full-key unique index. When every range the optimizer hands the engine is a full-key point equality (`UNIQUE_RANGE | EQ_RANGE`) and there are at least two ranges, the engine buffers them, converts each key into comparable bytes, and sorts by those bytes so the LSM sees a monotone stream of seeks - much friendlier to the block cache and the merge-heap than N scattered seeks in user-supplied order. Primary-key lookups bypass the iterator entirely via `fetch_row_by_pk`; secondary-index lookups reuse a single cached iterator and do one seek per entry. Ranges whose rows have been deleted concurrently are silently skipped.
 
 The engine deliberately declines MRR in three cases, falling back to the base handler's default implementation:
 
-- Single-range scans (`count < 2`) — MRR has no sorting win for one key, and the eq_ref path is where pessimistic row locking engages.
-- Non-point ranges — true `BETWEEN`/`<`/`>` scans stay on `read_range_first`.
-- Partitioned tables — `ha_partition` already dispatches MRR across children using its own DS-MRR logic.
+- Single-range scans (`count < 2`) - MRR has no sorting win for one key, and the eq_ref path is where pessimistic row locking engages.
+- Non-point ranges - true `BETWEEN`/`<`/`>` scans stay on `read_range_first`.
+- Partitioned tables - `ha_partition` already dispatches MRR across children using its own DS-MRR logic.
 
 
 ## Auto-Increment
 
 Auto-increment works in a similar way to InnoDB. The engine calls MariaDB's built-in `update_auto_increment()` mechanism during `write_row()`. Rather than calling `index_last()` on every INSERT (which would create and destroy a TidesDB merge-heap iterator each time), the engine maintains an in-memory atomic counter on the shared table descriptor. The counter is seeded once at table open time by seeking to the last key in the primary key column family, and is atomically incremented via a CAS loop on each INSERT - making auto-increment assignment O(1). When a user inserts an explicit value larger than the current counter, `write_row()` bumps the counter to match.
 
-`TRUNCATE TABLE` and `ALTER TABLE ... AUTO_INCREMENT=N` both reset the counter via the engine's `reset_auto_increment` handler hook — the next generated ID equals `N` (or `1` after a bare `TRUNCATE`). This applies to both user-defined AUTO_INCREMENT columns and hidden-PK tables.
+`TRUNCATE TABLE` and `ALTER TABLE ... AUTO_INCREMENT=N` both reset the counter via the engine's `reset_auto_increment` handler hook - the next generated ID equals `N` (or `1` after a bare `TRUNCATE`). This applies to both user-defined AUTO_INCREMENT columns and hidden-PK tables.
 
 ```sql
 CREATE TABLE tickets (

src/content/docs/reference/typescript.md

@@ -23,6 +23,10 @@ You **must** have the TidesDB shared C library installed on your system.  You ca
 npm install git+https://github.com/tidesdb/tidesdb-node.git
 ```
 
+```bash
+npm i @tidesdb/tidesdb
+```
+
 Or clone and install locally:
 
 ```bash
@@ -208,6 +212,27 @@ txn.commit();
 txn.free();
 ```
 
+#### Single-Delete
+
+`txn.singleDelete()` writes a tombstone with the same read semantics as `txn.delete()`, but carries a caller-provided promise that lets compaction drop the put and the tombstone together as soon as both appear in the same merge input, rather than carrying the tombstone forward until it reaches the largest active level.
+
+Between any two single-deletes on the same key, and between the start of the key's history and its first single-delete, the key has been put **at most once**. The engine does not and cannot verify this at runtime; violating the contract can leave older puts visible after the single-delete and is a bug in the caller.
+
+This is the right choice for workloads that insert each key exactly once and then delete it exactly once (classic insert-benchmark patterns, secondary-index entries on columns that are never updated, log-style tables with scheduled purges). It is **not** safe for tables that issue repeated updates to the same key.
+
+```typescript
+const cf = db.getColumnFamily('my_cf');
+
+const txn = db.beginTransaction();
+
+txn.singleDelete(cf, Buffer.from('key'));
+
+txn.commit();
+txn.free();
+```
+
+When in doubt, prefer `txn.delete()`.
+
 #### Multi-Operation Transactions
 
 ```typescript