Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 21 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,44 +52,44 @@ session.close().await?;
engine.shutdown()?;
```

Insert, update, and delete rows by executing statements inside a transaction.
Insert, update, and delete rows through direct transaction methods.

```rust
use doradb_storage::{SelectKey, UpdateCol, Val};

let mut trx = session.begin_trx()?;

trx.exec(async |stmt| {
stmt.table_insert_mvcc(table_id, vec![Val::from(1i32), Val::from("alice")])
.await?;
Ok(())
})
.await?;
trx.table_insert_mvcc(table_id, vec![Val::from(1i32), Val::from("alice")])
.await?;

let key = SelectKey::new(0, vec![Val::from(1i32)]);
trx.exec(async |stmt| {
stmt.table_update_unique_mvcc(
let updated = trx
.table_update_unique_mvcc(
table_id,
&key,
key.index_no,
&key.vals,
vec![UpdateCol {
idx: 1,
val: Val::from("ada"),
}],
)
.await?;
Ok(())
})
.await?;
assert!(updated.is_updated());

trx.exec(async |stmt| {
stmt.table_delete_unique_mvcc(table_id, &key, false).await?;
Ok(())
})
.await?;
let deleted = trx
.table_delete_unique_mvcc(table_id, key.index_no, &key.vals)
.await?;
assert!(deleted.is_deleted());

trx.commit().await?;
```

DML validation is enabled by default. Call
`trx.disable_dml_validation(true)` only for input already proven against the
table metadata; the setting applies to subsequent direct and streaming
operations in that transaction. Call `disable_dml_validation(false)` to enable
validation again.

Scan rows, read one unique-key row, and scan matching rows through a secondary index.

```rust
Expand All @@ -98,30 +98,20 @@ use doradb_storage::{SelectKey, Val};
let mut trx = session.begin_trx()?;
let mut rows = Vec::new();

trx.exec(async |stmt| {
stmt.table_scan_mvcc(table_id, &[0, 1], |vals| {
trx.table_scan_mvcc(table_id, &[0, 1], |vals| {
rows.push(vals);
true
})
.await?;
Ok(())
})
.await?;

let id_key = SelectKey::new(0, vec![Val::from(1i32)]);
let _row = trx
.exec(async |stmt| {
stmt.table_lookup_unique_mvcc(table_id, &id_key, &[0, 1])
.await
})
.table_lookup_unique_mvcc(table_id, id_key.index_no, &id_key.vals, &[0, 1])
.await?;

let name_key = SelectKey::new(1, vec![Val::from("ada")]);
let _matching_rows = trx
.exec(async |stmt| {
stmt.table_index_scan_mvcc(table_id, &name_key, &[0, 1])
.await
})
.table_index_lookup_mvcc(table_id, name_key.index_no, &name_key.vals, &[0, 1])
.await?
.unwrap_rows();

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,11 @@ A public Transaction::exec callback cannot invoke two DML attempts through one S
## Notes (Optional)

Consume the public DML capability when an attempt begins, so admission or validation failure cannot be followed by a second DML in the same statement. Planning should decide whether multiple read-only operations before the single DML remain supported. One public DML call may still mutate many rows internally; the restriction is on public DML invocations, not physical row effects.

## Close Reason

- Type: implemented
- Detail: Implemented via docs/tasks/000274-retire-callback-statement-apis-and-complete-migration.md
- Closed By: backlog close
- Reference: User decision
- Closed At: 2026-08-20
11 changes: 6 additions & 5 deletions docs/error-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,8 +151,9 @@ Disclosure is approved only at one of these boundaries:
- a public Doradb method returning the public `Result` alias;
- an external trait whose signature is fixed to the public result;
- a constrained carrier's disclosure implementation; or
- the three callback-mutation helpers that must forward an arbitrary public
`Error` returned by `Statement::table_mutate_mvcc`'s caller.
- the three row-mutation adapters that must forward an arbitrary public
`Error` returned by a direct `Transaction` mutation method's caller-supplied
row-decision callback.

Reusable private helpers do not return public `Result` merely to make `?`
compile. Test helpers follow the same rule: test a typed producer as typed, and
Expand Down Expand Up @@ -299,10 +300,10 @@ The principal convergence owners are:
| value and rows | public decode/access adapters and fixed external traits |
| engine | public bootstrap, new-session admission, and shutdown facades |
| session | public table, checkpoint, retention, and transaction operations |
| transaction | public lock, statement execution, commit, and rollback |
| statement/stream | public DML and stream iteration methods |
| transaction | public lock, direct no-op/read/DML/stream construction, commit, and rollback |
| stream | public iteration over an already-constructed MVCC stream |
| log configuration | fixed `FromStr` adapter over typed validation |
| catalog/table | public semantic facades plus callback mutation error transport |
| catalog/table | public semantic facades plus row-decision callback error transport |
| recovery/startup | typed recovery helpers beneath public Engine bootstrap |

Lower buffer, file, log internals, index, table, purge, retention, recovery, and
Expand Down
10 changes: 5 additions & 5 deletions docs/lock-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -531,11 +531,11 @@ abandoned session:
-> release explicit session-owned logical locks
```

Public statement-future cancellation composes with the same terminal proof
boundary:
Public direct-operation future cancellation composes with the same terminal
proof boundary:

```text
drop callback and pending acquisition
drop owned operation future and pending acquisition
-> fold residual statement undo into transaction undo and discard statement redo
-> check the complete transaction core in as CleanupReady
-> worker rolls back transaction effects
Expand All @@ -544,8 +544,8 @@ drop callback and pending acquisition
-> consume ReleasedTransactionLocks at session rollback completion
```

The callback future is destroyed before its `StmtState`, so a queued waiter or
promoted-but-unobserved request is cancelled by its call-local pending guard
The owned operation future is destroyed before its `StmtState`, so a queued
waiter or promoted-but-unobserved request is cancelled by its call-local pending guard
before the core becomes cleanup-claimable. An accepted transaction claim is not
released inline; it remains attached to `TrxInner` until whole-transaction
rollback reaches the ordering above.
Expand Down
3 changes: 2 additions & 1 deletion docs/public-error-audit.csv
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ doradb-storage/src/table/index_mutate.rs,IndexMutator::mutate_index_candidate,1
doradb-storage/src/table/index_mutate.rs,IndexMutator::mutate_owned_hot_index_candidate,2
doradb-storage/src/table/index_mutate.rs,IndexMutator::unique_driver_key_changed,1
doradb-storage/src/table/index_mutate.rs,IndexMutator::update_owned_hot_row,5
doradb-storage/src/trx/interface.rs,Transaction::table_index_scan_mvcc_stream,1
doradb-storage/src/trx/mod.rs,Transaction::commit,2
doradb-storage/src/trx/mod.rs,Transaction::exec,2
doradb-storage/src/trx/mod.rs,Transaction::lock_table,2
Expand All @@ -62,5 +63,5 @@ doradb-storage/src/trx/stmt.rs,Statement::table_scan_mvcc,2
doradb-storage/src/trx/stmt.rs,Statement::table_update_unique_mvcc,5
doradb-storage/src/trx/stmt.rs,Statement::table_upsert_unique_mvcc,5
doradb-storage/src/trx/stream_stmt.rs,IndexScanMvccStream::next,2
doradb-storage/src/trx/stream_stmt.rs,StreamStmt::table_index_scan_mvcc,5
doradb-storage/src/trx/stream_stmt.rs,StreamStmtState::table_index_scan_mvcc_stream,4
doradb-storage/src/value.rs,ValKind::try_from,1
Loading
Loading