Skip to main content

Transactions

Manage ACID transactions using ekoDB's REST API with support for multiple isolation levels, savepoints, and full rollback capabilities.

Architecture & Concepts

For detailed information about transactions architecture, isolation levels, and best practices, see the Transactions Architecture Reference.

REST API Transaction Considerations

When using the REST API directly (without client libraries), be aware of these important limitations:

  1. Manual Transaction ID Management - You must track and include the transaction_id with every operation within a transaction
  2. Connection Stateless - REST is stateless; transaction state is maintained server-side with timeout expiration
  3. No Automatic Rollback - If your client crashes, the transaction will remain pending until timeout (default: 5 minutes)
  4. Network Failures - A failed commit response doesn't guarantee the commit failed; use idempotency keys for critical operations

Recommendation: Use the official client libraries which handle transaction lifecycle automatically.

Isolation Levels​

ekoDB supports four standard SQL isolation levels:

  • ReadUncommitted - Highest performance, dirty reads allowed
  • ReadCommitted (default) - Good balance of performance and consistency
  • RepeatableRead - Consistent reads within transaction
  • Serializable - Highest consistency, full MVCC

Begin Transaction​

Start a new transaction with optional isolation level and timeout.

let tx_id = client.begin_transaction(Some(TransactionOptions {
    isolation_level: IsolationLevel::Serializable,
    timeout_seconds: Some(600),
})).await?;

println!("{}", tx_id); // 'tx-abc-123'
Working Examples

Prefer a client library? See examples in Rust, Python, TypeScript, Go, or Kotlin

Want to use the REST API directly? See examples in JavaScript, Python, Go, or Rust

Parameters:

  • isolation_level (optional) - ReadUncommitted, ReadCommitted, RepeatableRead, Serializable
  • timeout_seconds (optional) - Default: 300 (5 minutes)

Commit Transaction​

Commit all operations within the transaction.

client.commit_transaction(&tx_id).await?;

Rollback Transaction​

Rollback all operations and abort the transaction.

client.rollback_transaction(&tx_id).await?;

Create Savepoint​

Create a savepoint for partial rollback within a transaction.

client.create_savepoint(&tx_id, "checkpoint1").await?;

Rollback to Savepoint​

Rollback to a specific savepoint, undoing operations after it.

client.rollback_to_savepoint(&tx_id, "checkpoint1").await?;

Release Savepoint​

Remove a savepoint that's no longer needed.

client.release_savepoint(&tx_id, "checkpoint1").await?;

Get Transaction Status​

Check the current status of a transaction.

let status = client.get_transaction_status(&tx_id).await?;

println!("{:?}", status);

List Active Transactions​

List all currently active transactions.

const transactions = await client.listActiveTransactions();

console.log(transactions);
/*
[
  { transaction_id: 'tx-abc-123', isolation_level: 'Serializable', created_at: 1699814400 },
  { transaction_id: 'tx-def-456', isolation_level: 'ReadCommitted', created_at: 1699814500 }
]
*/

Complete Example​

Here's a complete example of a multi-step transaction with savepoints:

# 1. Begin transaction
curl -X POST https://{EKODB_API_URL}/api/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"isolation_level": "Serializable", "timeout_seconds": 600}'
# Response: {"transaction_id": "tx-001"}

# 2. Create initial savepoint
curl -X POST https://{EKODB_API_URL}/api/transactions/tx-001/savepoints \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"name": "start"}'

# 3. Debit source account
curl -X PUT https://{EKODB_API_URL}/api/update/accounts/ACC001 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"balance": 900}'

# 4. Create savepoint after debit
curl -X POST https://{EKODB_API_URL}/api/transactions/tx-001/savepoints \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"name": "after_debit"}'

# 5. Credit destination account
curl -X PUT https://{EKODB_API_URL}/api/update/accounts/ACC002 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{"balance": 1100}'

# 6. If credit fails, rollback to after_debit
# curl -X POST https://{EKODB_API_URL}/api/transactions/tx-001/savepoints/after_debit/rollback \
#   -H "Authorization: Bearer {YOUR_API_TOKEN}"
# Then retry credit operation...

# 7. Commit transaction
curl -X POST https://{EKODB_API_URL}/api/transactions/tx-001/commit \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

Best Practices​

Choose Appropriate Isolation Level​

Use CaseRecommended LevelWhy
Analytics/ReportingReadUncommittedPerformance over consistency
General CRUDReadCommittedGood balance
Financial CalculationsRepeatableReadConsistent reads
Banking/CriticalSerializableMaximum safety

Use Savepoints for Multi-Stage Operations​

Savepoints allow partial rollback without aborting the entire transaction:

# Create savepoint before risky operation
POST /api/transactions/{id}/savepoints
{"name": "before_risky_op"}

# Perform risky operation
PUT /api/update/...

# If operation fails, rollback to savepoint
POST /api/transactions/{id}/savepoints/before_risky_op/rollback

# Retry or continue with alternative approach

Set Appropriate Timeouts​

// Short transaction (1 minute)
{"timeout_seconds": 60}

// Long-running workflow (30 minutes)
{"timeout_seconds": 1800}

// Critical operation (5 minutes, default)
{"timeout_seconds": 300}

Handle Errors Gracefully​

Always implement proper error handling with rollback:

# Begin transaction
curl -X POST .../api/transactions ...
# -> {"transaction_id": "tx-001"}

# Try operations
if operation_fails; then
  # Rollback on error
  curl -X POST .../api/transactions/tx-001/rollback ...
else
  # Commit on success
  curl -X POST .../api/transactions/tx-001/commit ...
fi

Monitor Active Transactions​

Track and debug active transactions:

# List all active transactions
GET /api/transactions

# Check specific transaction status
GET /api/transactions/{id}

# Useful for:
# - Debugging stuck transactions
# - Monitoring long-running operations
# - Identifying transaction bottlenecks

Use Cases​

Financial Transfers​

Multi-account updates with atomicity guarantees:

# Begin transaction
POST /api/transactions
{"isolation_level": "Serializable"}

# Debit source
PUT /api/update/accounts/{from_id}
{"$decrement": {"balance": 100}}

# Credit destination  
PUT /api/update/accounts/{to_id}
{"$increment": {"balance": 100}}

# Commit both or rollback both
POST /api/transactions/{id}/commit

E-Commerce Orders​

Order creation with inventory reservation:

# Begin transaction
POST /api/transactions
{"isolation_level": "RepeatableRead"}

# Create savepoint before inventory check
POST /api/transactions/{id}/savepoints
{"name": "before_inventory"}

# Reserve inventory
PUT /api/update/inventory/{product_id}
{"$decrement": {"stock": 1}}

# If insufficient stock, rollback to savepoint
# Otherwise create order
POST /api/insert/orders
{...}

# Commit transaction
POST /api/transactions/{id}/commit

Batch Processing​

Process multiple records with error recovery:

# Begin transaction
POST /api/transactions

# Process records in batches
for batch in batches:
  # Create savepoint before batch
  POST /api/transactions/{id}/savepoints
  {"name": "batch_{i}"}
  
  # Process batch
  POST /api/batch/insert/...
  
  # If batch fails, rollback and continue
  if error:
    POST /api/transactions/{id}/savepoints/batch_{i}/rollback
    continue

# Commit all successful batches
POST /api/transactions/{id}/commit

Example Code​

Direct HTTP/REST API Examples​

Raw HTTP examples demonstrating the REST API directly:

Client Library Examples​

Production-ready examples using official client libraries: