Add sync API for transactional client #517

odecode · 2026-01-16T10:59:55Z

For issue #289 a synchronous API for transactional client.

I have programmed a fair bit but new to OSS and Rust. I consulted AI heavily for this to try and get an understanding of what this part of the project is about and how it works, but I tried using it a teacher rather than just "vibe coding".

Summary by CodeRabbit

New Features
- Added synchronous transaction and snapshot APIs providing blocking access alongside the existing async interfaces.
Bug Fixes
- Runtime validation now surfaces a clear user-facing error when attempting to use the sync APIs from within an active async runtime.
Tests
- Added extensive integration tests covering sync client behavior, transactions, snapshots, scans, and edge cases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

ti-chi-bot · 2026-01-16T10:59:59Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign niedhui for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ti-chi-bot · 2026-01-16T11:00:06Z

Welcome @odecode!

It looks like this is your first PR to tikv/client-rust 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to tikv/client-rust. 😃

Copilot

Pull request overview

This PR adds a synchronous API wrapper for the TiKV transactional client to address issue #289. The implementation provides blocking alternatives to the existing async transaction APIs.

Changes:

Introduced SyncTransactionClient, SyncTransaction, and SyncSnapshot structs that wrap their async counterparts
Each sync type contains an Arc-wrapped Tokio runtime and uses block_on to execute async operations synchronously
Added comprehensive integration tests mirroring the async test patterns

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/transaction/sync_client.rs	New synchronous client wrapper providing blocking transaction operations
src/transaction/sync_transaction.rs	Synchronous transaction wrapper that blocks on async transaction methods
src/transaction/sync_snapshot.rs	Synchronous snapshot wrapper for read-only operations
src/transaction/mod.rs	Module declarations for new sync components
src/lib.rs	Public API exports for sync types
tests/sync_transaction_tests.rs	Comprehensive integration tests covering all sync APIs
tests/common/mod.rs	Added `init_sync()` helper for synchronous test setup

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/transaction/sync_client.rs

tests/common/mod.rs

src/transaction/sync_client.rs

…th block_on. Signed-off-by: Otto Westerlund <[email protected]>

Signed-off-by: Otto Westerlund <[email protected]>

odecode · 2026-01-17T09:30:46Z

Thank you for the review comments, I have made changes according to the comments

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/transaction/sync_client.rs

tests/sync_transaction_tests.rs

src/transaction/sync_client.rs

Signed-off-by: Otto Westerlund <[email protected]>

odecode · 2026-01-18T09:23:32Z

I have made changes requested by the review comments

Signed-off-by: Otto Westerlund <[email protected]>

odecode · 2026-01-19T04:46:43Z

Thank you for your patience so far! I have made the review's suggested change.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

odecode · 2026-01-19T13:30:52Z

Copilot left no new comments. Are some actions required by me for the "tide" pending check?

src/transaction/sync_client.rs

tests/sync_transaction_tests.rs

tests/common/mod.rs

Signed-off-by: Otto Westerlund <[email protected]>

… usage limitation Signed-off-by: Otto Westerlund <[email protected]>

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests/common/mod.rs

src/transaction/sync_client.rs

tests/sync_transaction_tests.rs

Signed-off-by: Otto Westerlund <[email protected]>

odecode · 2026-01-20T11:03:11Z

Is it possible for me to request review from Copilot myself? Then I could address all its concerns and not bother you on every iteration.

EDIT: I figured out that I can ask Copilot to review uncommitted changes in my code editor, I will do that for the next round of changes if Copilot or you request more improvements

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/transaction/sync_snapshot.rs

tests/sync_transaction_tests.rs

src/transaction/sync_client.rs

src/transaction/sync_transaction.rs

src/transaction/sync_snapshot.rs

Signed-off-by: Otto Westerlund <[email protected]>

coderabbitai · 2026-01-28T09:55:48Z

📝 Walkthrough

Walkthrough

Adds a synchronous transaction API: new types SyncTransactionClient, SyncTransaction, SyncSnapshot, a NestedRuntimeError variant, synchronous test helper, and extensive integration tests. The sync types wrap existing async components and block on their futures via an internal Tokio runtime.

Changes

Cohort / File(s)	Summary
Error Handling `src/common/errors.rs`	Added `NestedRuntimeError(String)` to the public `Error` enum with user-facing message about not using `SyncTransactionClient` inside a Tokio async runtime.
Crate Re-exports `src/lib.rs`, `src/transaction/mod.rs`	Publicly re-exported `SyncSnapshot`, `SyncTransaction`, and `SyncTransactionClient`; added module declarations for sync implementations.
Sync Client Implementation `src/transaction/sync_client.rs`	New `SyncTransactionClient` wrapping async client + Tokio runtime; implements `new`, `new_with_config`, nested-runtime detection (`check_nested_runtime`), `safe_block_on`, sync transactional entry points (begin_*, snapshot, current_timestamp, gc, cleanup_locks, unsafe_destroy_range, cfg-gated scan_locks), `Clone`, and unit tests for nested-runtime behavior.
Sync Snapshot Implementation `src/transaction/sync_snapshot.rs`	New `SyncSnapshot` wrapping async `Snapshot` with blocking accessors (get, key_exists, batch_get, scan, scan_keys, scan_reverse, scan_keys_reverse) using runtime.
Sync Transaction Implementation `src/transaction/sync_transaction.rs`	New `SyncTransaction` wrapping async `Transaction`; provides blocking transactional API (get, get_for_update, key_exists, batch ops, scans, put/insert/delete, batch_mutate, lock_keys, commit, rollback, send_heart_beat) delegating via `safe_block_on`.
Test Infrastructure `tests/common/mod.rs`	Added `init_sync()` helper to initialize test infra synchronously with a dedicated single-thread Tokio runtime (panics if called from async contexts).
Integration Test Suite `tests/sync_transaction_tests.rs`	Added extensive integration tests for sync client: nested-runtime checks, timestamp retrieval, optimistic/pessimistic flows, CRUD, batch operations, snapshot semantics, scans, locking, heartbeat, cloning, and edge cases.

Sequence Diagram(s)

sequenceDiagram
    participant U as User Code
    participant SC as SyncTransactionClient
    participant RT as check_nested_runtime()
    participant SB as safe_block_on()
    participant TRT as Tokio Runtime
    participant AC as Async TransactionClient

    U->>SC: call sync method (e.g., begin_optimistic())
    SC->>RT: check_nested_runtime()
    alt nested runtime detected
        RT-->>SC: Err(NestedRuntimeError)
        SC-->>U: return Err(NestedRuntimeError)
    else no nested runtime
        RT-->>SC: Ok(())
        SC->>SB: wrap async_op into future
        SB->>TRT: block_on(future)
        TRT->>AC: execute async operation
        AC-->>TRT: result
        TRT-->>SB: unblock with result
        SB-->>SC: Result<T>
        SC-->>U: return Result<T>
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 I hop between async and sync today,
I check runtimes lest I stray,
I block with care, I wrap and send,
Transactions safe from end to end,
A rabbit's cheer for syncs that play!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add sync API for transactional client' is a concise, specific summary that accurately describes the main objective of the pull request, which is to add synchronous API wrappers for the TiKV transactional client.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

odecode · 2026-01-28T09:56:45Z

added extra test coverage for the sync snapshot public api surface, and error handling to prevent panic when sync client is called from within an async runtime.

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/transaction/sync_snapshot.rs`:
- Around line 18-70: SyncSnapshot methods call self.runtime.block_on(...)
directly which will panic if invoked inside an active Tokio runtime; add a
private helper on SyncSnapshot (e.g., safe_block_on_snapshot) that mirrors
sync_client::safe_block_on by checking
tokio::runtime::Handle::try_current().is_ok() and returning
Err(Error::NestedRuntimeError) when a current runtime exists, otherwise invoking
self.runtime.block_on; replace direct self.runtime.block_on(...) calls in the
public methods get, key_exists, batch_get, scan, scan_keys, scan_reverse, and
scan_keys_reverse to use this helper so nested runtime usage is guarded.

In `@src/transaction/sync_transaction.rs`:
- Around line 20-126: All SyncTransaction and SyncSnapshot methods currently
call self.runtime.block_on(...) and can panic if invoked inside an existing
Tokio runtime; make the existing check_nested_runtime/safe_block_on helpers
accessible (move to a shared module or change to pub(crate)), then replace every
direct self.runtime.block_on(self.inner.<method>(...)) call in SyncTransaction
and SyncSnapshot (e.g., get, get_for_update, key_exists, batch_get,
batch_get_for_update, scan, scan_keys, scan_reverse, scan_keys_reverse, put,
insert, delete, batch_mutate, lock_keys, commit, rollback, send_heart_beat) with
the safe helper usage (run the nested-runtime check and call safe_block_on
around the inner async call) so callers get a NestedRuntimeError instead of a
panic.

src/transaction/sync_snapshot.rs

src/transaction/sync_transaction.rs

Signed-off-by: Otto Westerlund <[email protected]>

ti-chi-bot bot added contribution This PR is from a community contributor. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. first-time-contributor Indicates that the PR was contributed by an external member and is a first-time contributor. labels Jan 16, 2026

ti-chi-bot bot added the dco-signoff: no Indicates the PR's author has not signed dco. label Jan 16, 2026

odecode force-pushed the sync-api-txclient branch from f90bd47 to 20f8737 Compare January 16, 2026 11:17

ti-chi-bot bot added dco-signoff: yes Indicates the PR's author has signed the dco. and removed dco-signoff: no Indicates the PR's author has not signed dco. labels Jan 16, 2026

pingyu requested a review from Copilot January 17, 2026 01:49

Copilot started reviewing on behalf of pingyu January 17, 2026 01:50 View session

Copilot AI reviewed Jan 17, 2026

View reviewed changes

ti-chi-bot bot added dco-signoff: no Indicates the PR's author has not signed dco. and removed dco-signoff: yes Indicates the PR's author has signed the dco. labels Jan 17, 2026

Travel Planner Developer and others added 6 commits January 17, 2026 11:28

Synchronous version of Transaction Client. Async functions wrapped wi…

a24cb10

…th block_on. Signed-off-by: Otto Westerlund <[email protected]>

sync transaction and snapshot, tests, runtime handling for sync_client

fda1e85

Signed-off-by: Otto Westerlund <[email protected]>

Add comments and sign-off-by message

9d2f1a1

Signed-off-by: Otto Westerlund <[email protected]>

change .expect to ? operator for better error handling

83498cf

Signed-off-by: Otto Westerlund <[email protected]>

add documentation to sync_client public API

d720774

Signed-off-by: Otto Westerlund <[email protected]>

add better documentation about snapshot

2fad975

Signed-off-by: Otto Westerlund <[email protected]>

odecode force-pushed the sync-api-txclient branch from 80170a7 to 2fad975 Compare January 17, 2026 09:29

ti-chi-bot bot added dco-signoff: yes Indicates the PR's author has signed the dco. and removed dco-signoff: no Indicates the PR's author has not signed dco. labels Jan 17, 2026

pingyu requested a review from Copilot January 18, 2026 03:49

Copilot started reviewing on behalf of pingyu January 18, 2026 03:50 View session

Copilot AI reviewed Jan 18, 2026

View reviewed changes

src/transaction/sync_client.rs Outdated Show resolved Hide resolved

tests/sync_transaction_tests.rs Show resolved Hide resolved

src/transaction/sync_client.rs Outdated Show resolved Hide resolved

odecode added 2 commits January 18, 2026 10:39

remove trailing whitespace

a6403de

Signed-off-by: Otto Westerlund <[email protected]>

change tokio runtime method, add scan feature tests

63c94d1

Signed-off-by: Otto Westerlund <[email protected]>

init_sync change according to pr comment, cargo fmt

55bf7a3

Signed-off-by: Otto Westerlund <[email protected]>

pingyu requested a review from Copilot January 19, 2026 12:16

Copilot started reviewing on behalf of pingyu January 19, 2026 12:16 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

pingyu reviewed Jan 20, 2026

View reviewed changes

src/transaction/sync_client.rs Outdated Show resolved Hide resolved

src/transaction/sync_client.rs Outdated Show resolved Hide resolved

tests/sync_transaction_tests.rs Outdated Show resolved Hide resolved

tests/common/mod.rs Show resolved Hide resolved

odecode added 4 commits January 20, 2026 08:19

multi thread scheduler for new_with_config

9235466

Signed-off-by: Otto Westerlund <[email protected]>

cleanup docstrings

cc0f119

Signed-off-by: Otto Westerlund <[email protected]>

rename test cases sync_txn -> txn_sync

b5b389c

Signed-off-by: Otto Westerlund <[email protected]>

change init_sync according to review suggestion and add comment about…

00dc279

… usage limitation Signed-off-by: Otto Westerlund <[email protected]>

odecode requested a review from pingyu January 20, 2026 06:35

pingyu requested a review from Copilot January 20, 2026 09:36

Copilot started reviewing on behalf of pingyu January 20, 2026 09:37 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

tests/common/mod.rs Outdated Show resolved Hide resolved

src/transaction/sync_client.rs Outdated Show resolved Hide resolved

src/transaction/sync_client.rs Outdated Show resolved Hide resolved

tests/sync_transaction_tests.rs Show resolved Hide resolved

odecode added 3 commits January 20, 2026 12:54

remove trailing whitespace

b3ea3fa

Signed-off-by: Otto Westerlund <[email protected]>

tests for sync_transaction wrapper functions

920f004

Signed-off-by: Otto Westerlund <[email protected]>

Merge branch 'master' into sync-api-txclient

2fa5375

pingyu requested a review from Copilot January 24, 2026 03:09

Copilot started reviewing on behalf of pingyu January 24, 2026 03:10 View session

Copilot AI reviewed Jan 24, 2026

View reviewed changes

odecode added 4 commits January 28, 2026 11:33

code review fixes

b5fe3b1

Signed-off-by: Otto Westerlund <[email protected]>

remove trailing whitespace

4807831

Signed-off-by: Otto Westerlund <[email protected]>

Merge branch 'master' into sync-api-txclient

d07e80f

fix compilation error

2f6c85f

Signed-off-by: Otto Westerlund <[email protected]>

coderabbitai bot reviewed Jan 28, 2026

View reviewed changes

src/transaction/sync_snapshot.rs Outdated Show resolved Hide resolved

src/transaction/sync_transaction.rs Show resolved Hide resolved

error handling to sync_snapshot and sync_transaction to prevent panics

d625c21

Signed-off-by: Otto Westerlund <[email protected]>

Add sync API for transactional client #517

Are you sure you want to change the base?

Add sync API for transactional client #517

Uh oh!

Conversation

odecode commented Jan 16, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

ti-chi-bot bot commented Jan 16, 2026

Uh oh!

ti-chi-bot bot commented Jan 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

odecode commented Jan 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

odecode commented Jan 18, 2026

Uh oh!

odecode commented Jan 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

odecode commented Jan 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

odecode commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Poem

Uh oh!

odecode commented Jan 28, 2026

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

odecode commented Jan 16, 2026 •

edited by coderabbitai bot

Loading

odecode commented Jan 20, 2026 •

edited

Loading

coderabbitai bot commented Jan 28, 2026 •

edited

Loading