Version: 1.1.0

Transactions and Write Management

DB plugin provides a robust transaction system for managing write operations. Transactions ensure data consistency, enable batch operations, and provide validation before any data reaches the database.

Transaction Lifecycle

Basic Transaction Pattern

beginWrites / commitWrites / endWrites

1Database db = Database.Static.getDefault();
2
3db.beginWrites();
4try {
5    // Make changes
6    article1.save();
7    article2.save();
8    author.save();
9
10    // Commit changes
11    db.commitWrites();
12
13} finally {
14    // Always clean up
15    db.endWrites();
16}

What Happens

beginWrites() - Starts a transaction, increments depth counter
save() - Buffers the write, doesn't touch the database yet
commitWrites() - Validates all buffered writes, then writes them atomically
endWrites() - Decrements depth counter, cleans up resources

Why Use Transactions

1// Without transaction - NOT atomic
2article.save();  // Might succeed
3author.save();   // Might fail
4// Now you have inconsistent data!
5
6// With transaction - atomic
7db.beginWrites();
8try {
9    article.save();
10    author.save();
11    db.commitWrites();  // Both succeed or both fail
12} finally {
13    db.endWrites();
14}

Nested Transactions

DB plugin supports nested transactions using a depth counter:

1Database db = Database.Static.getDefault();
2
3db.beginWrites();  // Depth 1
4try {
5    article.save();
6
7    db.beginWrites();  // Depth 2 (nested)
8    try {
9        author.save();
10        db.commitWrites();  // Commits only at depth 1
11    } finally {
12        db.endWrites();  // Back to depth 1
13    }
14
15    db.commitWrites();  // Actually commits everything
16} finally {
17    db.endWrites();  // Depth 0
18}

How Nesting Works

beginWrites() increments a counter
endWrites() decrements it
commitWrites() only writes when counter reaches 0
Allows method composition without worrying about transaction state

1public void saveArticleWithAuthor(Article article, Author author) {
2    // This method doesn't know if it's called within a transaction
3    db.beginWrites();
4    try {
5        article.save();
6        author.save();
7        db.commitWrites();
8    } finally {
9        db.endWrites();
10    }
11}
12
13// Called standalone - commits immediately
14saveArticleWithAuthor(article, author);
15
16// Called within transaction - commits with outer transaction
17db.beginWrites();
18try {
19    saveArticleWithAuthor(article1, author1);
20    saveArticleWithAuthor(article2, author2);
21    db.commitWrites();  // All 4 objects committed together
22} finally {
23    db.endWrites();
24}

Commit Strategies

commitWrites - Immediate Consistency

Commits changes immediately with strong consistency guarantees:

1db.beginWrites();
2try {
3    article.save();
4    db.commitWrites();
5    // Data is immediately visible to other transactions
6} finally {
7    db.endWrites();
8}

Use when:

You need immediate read-after-write consistency
Other processes depend on this data immediately
Working with critical data (financial, inventory, etc.)

commitWritesEventually - Eventual Consistency

Commits changes for eventual consistency, allowing for optimization:

1db.beginWrites();
2try {
3    article.save();
4    db.commitWritesEventually();
5    // Data will be visible soon, but maybe not immediately
6} finally {
7    db.endWrites();
8}

Use when:

Eventual consistency is acceptable
Performance is critical
Working with caching or replication systems
Bulk imports or batch operations

The database implementation may:

Batch writes together
Delay replication
Optimize index updates
Trade immediate consistency for throughput

Isolated Writes

Create an isolated write session that doesn't interact with the main transaction:

1// Main transaction
2db.beginWrites();
3try {
4    article.save();
5
6    // Isolated session
7    db.beginIsolatedWrites();
8    try {
9        // This saves independently
10        auditLog.save();
11        db.commitWrites();
12    } finally {
13        db.endWrites();
14    }
15
16    // Main transaction continues
17    db.commitWrites();
18} finally {
19    db.endWrites();
20}

Use cases:

Audit logging that should succeed even if main transaction fails
Separate concerns (e.g., metrics, analytics)
Writing to different databases

Write Buffering and Validation

The Validation Phase

All validation happens before any database writes:

1db.beginWrites();
2try {
3    // These are buffered
4    article1.save();
5    article2.save();
6    article3.save();
7
8    // This triggers validation of ALL three
9    db.commitWrites();
10
11    // If any validation fails, NONE are written
12} catch (ValidationException e) {
13    // Handle validation errors for all objects
14    Map<Object, Map<ObjectField, List<Throwable>>> errors = e.getAllErrors();
15} finally {
16    db.endWrites();
17}

Validation Order

Annotation validation - @Required, @Maximum, etc.
beforeSave() hooks - Custom pre-save logic
onValidate() hooks - Custom validation logic
afterValidate() hooks - Post-validation logic
Database write - Only if all validation passes
afterSave() hooks - Post-save logic

Example: Custom Validation

1public class Article extends Record {
2
3    @Required
4    private String title;
5
6    @Required
7    private String content;
8
9    @Override
10    protected void beforeSave() {
11        // Normalize data before validation
12        if (title != null) {
13            title = title.trim();
14        }
15    }
16
17    @Override
18    protected void onValidate() {
19        // Custom validation logic
20        if (content != null && content.length() < 100) {
21            getState().addError(
22                getState().getField("content"),
23                new IllegalArgumentException("Content must be at least 100 characters")
24            );
25        }
26
27        if (title != null && title.toLowerCase().contains("spam")) {
28            getState().addError(
29                getState().getField("title"),
30                new IllegalArgumentException("Title contains forbidden words")
31            );
32        }
33    }
34
35    @Override
36    protected void afterSave() {
37        // Post-save logic (cache invalidation, notifications, etc.)
38        System.out.println("Article saved: " + getLabel());
39    }
40}

Error Handling

Handling ValidationException

1db.beginWrites();
2try {
3    article.save();
4    db.commitWrites();
5
6} catch (ValidationException e) {
7    // Get all validation errors
8    Map<Object, Map<ObjectField, List<Throwable>>> allErrors = e.getAllErrors();
9
10    for (Map.Entry<Object, Map<ObjectField, List<Throwable>>> entry : allErrors.entrySet()) {
11        Object object = entry.getKey();
12        Map<ObjectField, List<Throwable>> fieldErrors = entry.getValue();
13
14        System.out.println("Errors in " + object.getClass().getSimpleName() + ":");
15
16        for (Map.Entry<ObjectField, List<Throwable>> fieldEntry : fieldErrors.entrySet()) {
17            String fieldName = fieldEntry.getKey().getInternalName();
18            for (Throwable error : fieldEntry.getValue()) {
19                System.out.println("  " + fieldName + ": " + error.getMessage());
20            }
21        }
22    }
23
24} catch (DatabaseException e) {
25    // Handle database errors (connection, constraint violations, etc.)
26    logger.error("Database error", e);
27    throw e;
28
29} finally {
30    db.endWrites();
31}

Handling Database Errors

1db.beginWrites();
2try {
3    article.save();
4    db.commitWrites();
5
6} catch (DatabaseException e) {
7    // Check for specific error types
8    if (e.getCause() instanceof SQLException) {
9        SQLException sqlEx = (SQLException) e.getCause();
10
11        // Unique constraint violation
12        if (sqlEx.getErrorCode() == 1062) {  // MySQL duplicate entry
13            throw new DuplicateException("Article already exists", e);
14        }
15
16        // Deadlock
17        if (sqlEx.getErrorCode() == 1213) {  // MySQL deadlock
18            // Retry logic
19            return retryOperation();
20        }
21    }
22
23    throw e;
24
25} finally {
26    db.endWrites();
27}

Automatic Retry

DB plugin automatically retries certain recoverable errors:

1// This is handled automatically by AbstractDatabase
2db.beginWrites();
3try {
4    article.save();
5    db.commitWrites();  // Will retry on transient errors
6} finally {
7    db.endWrites();
8}

Automatically retried errors:

Connection timeouts
Deadlocks
Transient network failures
Lock wait timeouts

Uses exponential backoff with configurable max attempts.

Batch Operations

Efficient Batch Writes

1public void importArticles(List<ArticleData> dataList) {
2    Database db = Database.Static.getDefault();
3
4    db.beginWrites();
5    try {
6        for (ArticleData data : dataList) {
7            Article article = new Article();
8            article.setTitle(data.getTitle());
9            article.setContent(data.getContent());
10            article.setAuthor(data.getAuthor());
11            article.save();  // Buffered, not written yet
12        }
13
14        // All articles validated and written in one batch
15        db.commitWrites();
16
17        System.out.println("Imported " + dataList.size() + " articles");
18
19    } catch (ValidationException e) {
20        System.err.println("Import failed due to validation errors");
21        // None of the articles are saved
22        throw e;
23
24    } finally {
25        db.endWrites();
26    }
27}

Batch with Progress Tracking

1public void importWithProgress(List<ArticleData> dataList) {
2    Database db = Database.Static.getDefault();
3    int batchSize = 100;
4    int processed = 0;
5
6    for (int i = 0; i < dataList.size(); i += batchSize) {
7        int end = Math.min(i + batchSize, dataList.size());
8        List<ArticleData> batch = dataList.subList(i, end);
9
10        db.beginWrites();
11        try {
12            for (ArticleData data : batch) {
13                Article article = new Article();
14                // ... populate article
15                article.save();
16            }
17
18            db.commitWrites();
19            processed += batch.size();
20            System.out.println("Processed " + processed + " / " + dataList.size());
21
22        } catch (Exception e) {
23            System.err.println("Batch failed at index " + i);
24            throw e;
25
26        } finally {
27            db.endWrites();
28        }
29    }
30}

Parallel Batch Processing

1public void parallelImport(List<ArticleData> dataList) throws InterruptedException {
2    int numThreads = Runtime.getRuntime().availableProcessors();
3    ExecutorService executor = Executors.newFixedThreadPool(numThreads);
4    int batchSize = 100;
5
6    List<Future<?>> futures = new ArrayList<>();
7
8    for (int i = 0; i < dataList.size(); i += batchSize) {
9        int start = i;
10        int end = Math.min(i + batchSize, dataList.size());
11
12        Future<?> future = executor.submit(() -> {
13            List<ArticleData> batch = dataList.subList(start, end);
14            Database db = Database.Static.getDefault();
15
16            db.beginWrites();
17            try {
18                for (ArticleData data : batch) {
19                    Article article = new Article();
20                    // ... populate article
21                    article.save();
22                }
23                db.commitWrites();
24            } finally {
25                db.endWrites();
26            }
27        });
28
29        futures.add(future);
30    }
31
32    // Wait for all batches to complete
33    for (Future<?> future : futures) {
34        try {
35            future.get();
36        } catch (ExecutionException e) {
37            System.err.println("Batch failed: " + e.getCause().getMessage());
38        }
39    }
40
41    executor.shutdown();
42}

Distributed Locks

For unique constraint enforcement across distributed systems:

1public class Article extends Record {
2
3    @Indexed
4    @Unique
5    private String slug;
6
7    @Override
8    protected void beforeSave() {
9        // DB plugin automatically acquires a distributed lock
10        // for unique fields during save
11    }
12}

Transaction Patterns

Unit of Work Pattern

1public class ArticleService {
2
3    public void publishArticle(UUID articleId) {
4        Database db = Database.Static.getDefault();
5
6        db.beginWrites();
7        try {
8            Article article = Query.from(Article.class)
9                .where("_id = ?", articleId)
10                .first();
11
12            if (article == null) {
13                throw new IllegalArgumentException("Article not found");
14            }
15
16            // Make multiple related changes
17            article.setPublishDate(db.now());
18            article.setStatus("published");
19            article.save();
20
21            // Update author stats
22            Author author = article.getAuthor();
23            author.incrementPublishedCount();
24            author.save();
25
26            // Create activity log
27            ActivityLog log = new ActivityLog();
28            log.setType("article_published");
29            log.setArticle(article);
30            log.setTimestamp(db.now());
31            log.save();
32
33            // All changes committed together
34            db.commitWrites();
35
36        } finally {
37            db.endWrites();
38        }
39    }
40}

Saga Pattern (Compensating Transactions)

1public class OrderService {
2
3    public void placeOrder(Order order) {
4        Database db = Database.Static.getDefault();
5        boolean inventoryReserved = false;
6        boolean paymentProcessed = false;
7
8        try {
9            db.beginWrites();
10
11            // Step 1: Reserve inventory
12            reserveInventory(order);
13            inventoryReserved = true;
14
15            // Step 2: Process payment
16            processPayment(order);
17            paymentProcessed = true;
18
19            // Step 3: Create order
20            order.setStatus("confirmed");
21            order.save();
22
23            db.commitWrites();
24
25        } catch (Exception e) {
26            // Compensating actions
27            if (paymentProcessed) {
28                refundPayment(order);
29            }
30            if (inventoryReserved) {
31                releaseInventory(order);
32            }
33            throw e;
34
35        } finally {
36            db.endWrites();
37        }
38    }
39}

Optimistic Locking

1public class Article extends Record {
2
3    @Indexed
4    private int version;
5
6    public void updateWithOptimisticLock(String newTitle) {
7        Database db = Database.Static.getDefault();
8
9        db.beginWrites();
10        try {
11            // Load current version
12            Article current = Query.from(Article.class)
13                .where("_id = ?", this.getId())
14                .first();
15
16            if (current.getVersion() != this.version) {
17                throw new ConcurrentModificationException(
18                    "Article was modified by another transaction"
19                );
20            }
21
22            // Update with new version
23            this.setTitle(newTitle);
24            this.setVersion(this.version + 1);
25            this.save();
26
27            db.commitWrites();
28
29        } finally {
30            db.endWrites();
31        }
32    }
33}

Performance Optimization

Batch vs. Individual Commits

1// Slow - many small transactions
2for (Article article : articles) {
3    db.beginWrites();
4    try {
5        article.save();
6        db.commitWrites();
7    } finally {
8        db.endWrites();
9    }
10}
11
12// Fast - one large transaction
13db.beginWrites();
14try {
15    for (Article article : articles) {
16        article.save();
17    }
18    db.commitWrites();
19} finally {
20    db.endWrites();
21}

Eventual Consistency for Bulk Operations

1// Use eventual consistency for better performance
2db.beginWrites();
3try {
4    for (Article article : articles) {
5        article.save();
6    }
7    db.commitWritesEventually();  // Faster than commitWrites()
8} finally {
9    db.endWrites();
10}

Skip Validation for Trusted Data

1// Import from trusted source - skip validation
2db.beginWrites();
3try {
4    for (ArticleData data : trustedData) {
5        Article article = convertToArticle(data);
6        db.saveUnsafely(article.getState());  // No validation
7    }
8    db.commitWrites();
9} finally {
10    db.endWrites();
11}

Best Practices

1. Always Use try-finally

1// Good
2db.beginWrites();
3try {
4    article.save();
5    db.commitWrites();
6} finally {
7    db.endWrites();
8}
9
10// Bad - endWrites() might not be called
11db.beginWrites();
12article.save();
13db.commitWrites();
14db.endWrites();

2. Keep Transactions Short

1// Good - short transaction
2db.beginWrites();
3try {
4    article.save();
5    db.commitWrites();
6} finally {
7    db.endWrites();
8}
9
10// Bad - long transaction holding locks
11db.beginWrites();
12try {
13    article.save();
14    sendEmail(article);  // External I/O
15    updateSearchIndex(article);  // Slow operation
16    db.commitWrites();
17} finally {
18    db.endWrites();
19}

3. Use Appropriate Commit Strategy

1// Critical data - immediate consistency
2db.beginWrites();
3try {
4    payment.save();
5    db.commitWrites();  // Must be immediately visible
6} finally {
7    db.endWrites();
8}
9
10// Non-critical data - eventual consistency
11db.beginWrites();
12try {
13    viewCount.save();
14    db.commitWritesEventually();  // Performance > consistency
15} finally {
16    db.endWrites();
17}

4. Don't Catch and Ignore Exceptions

1// Bad - hides errors
2db.beginWrites();
3try {
4    article.save();
5    db.commitWrites();
6} catch (Exception e) {
7    // Ignored!
8} finally {
9    db.endWrites();
10}
11
12// Good - handle or propagate
13db.beginWrites();
14try {
15    article.save();
16    db.commitWrites();
17} catch (ValidationException e) {
18    logger.error("Validation failed: {}", e.getMessage());
19    throw e;
20} finally {
21    db.endWrites();
22}

Transaction Lifecycle​

Basic Transaction Pattern​

beginWrites / commitWrites / endWrites​

What Happens​

Why Use Transactions​

Nested Transactions​

How Nesting Works​

Commit Strategies​

commitWrites - Immediate Consistency​

commitWritesEventually - Eventual Consistency​

Isolated Writes​

Write Buffering and Validation​

The Validation Phase​

Validation Order​

Example: Custom Validation​

Error Handling​

Handling ValidationException​

Handling Database Errors​

Automatic Retry​

Batch Operations​

Efficient Batch Writes​

Batch with Progress Tracking​

Parallel Batch Processing​

Distributed Locks​

Transaction Patterns​

Unit of Work Pattern​

Saga Pattern (Compensating Transactions)​

Optimistic Locking​

Performance Optimization​

Batch vs. Individual Commits​

Eventual Consistency for Bulk Operations​

Skip Validation for Trusted Data​

Best Practices​

1. Always Use try-finally​

2. Keep Transactions Short​

3. Use Appropriate Commit Strategy​

4. Don't Catch and Ignore Exceptions​