GoFrame - A powerful framework for faster, easier, and more efficient project development

Version: 2.8.x(Latest)

Transaction Propagation is an advanced transaction management mechanism provided by the GoFrame ORM framework, used to control the behavior of nested transactions. In complex business scenarios, one transaction method may call other transaction methods, requiring clear definition of transaction propagation behavior to ensure data consistency and integrity.

Basic Introduction

Transaction propagation defines how a transaction method should behave when called by another transaction method. GoFrame ORM supports multiple transaction propagation behaviors, allowing developers to choose the appropriate propagation type based on business requirements.

GoFrame ORM supports the following transaction propagation types:

PropagationNested (default): If a transaction exists, creates a nested transaction (using savepoints); if no transaction exists, creates a new transaction.
PropagationRequired: If a transaction exists, joins that transaction; if no transaction exists, creates a new transaction.
PropagationSupports: If a transaction exists, joins that transaction; if no transaction exists, executes without a transaction.
PropagationRequiresNew: Creates a new transaction; if a transaction exists, suspends the current transaction.
PropagationNotSupported: Executes without a transaction; if a transaction exists, suspends the current transaction.
PropagationMandatory: If a transaction exists, joins that transaction; if no transaction exists, throws an exception.
PropagationNever: Executes without a transaction; if a transaction exists, throws an exception.

info

Note: To ensure compatibility with older versions of transaction processing, the default transaction propagation type in GoFrame ORM is PropagationNested, not PropagationRequired.

Advantages

Flexible Transaction Management: Choose different transaction propagation behaviors based on business requirements for more granular transaction control.
Improved Code Reusability: Service layer methods can define transaction behavior independently, without concern for whether the calling environment already has a transaction.
Reduced Transaction Conflicts: Through appropriate propagation behavior, reduce locking and conflicts caused by long transactions.
Enhanced Error Isolation: Using independent transactions (such as PropagationRequiresNew) can isolate error impacts and avoid entire transaction rollbacks.
Simplified Complex Business Logic: In complex business processes, different steps can use different transaction propagation strategies, making code clearer.

Application Scenarios

Service Composition: When one service method calls multiple other service methods, you can choose to share the same transaction or use independent transactions based on business requirements.
Logging: Business operations need to record logs, but log write failures should not affect the main business logic; PropagationRequiresNew can be used.
Batch Processing: In batch processing, you might want each item to use an independent transaction so that the failure of one item does not affect others.
Transaction Compensation: In distributed systems, different propagation behaviors can be used to implement transaction compensation mechanisms.
Nested Business Logic: Some steps in complex business logic may need to be treated as independent transaction units, using PropagationNested.

Usage Examples

Before starting the examples, let's create a table for testing:

CREATE TABLE IF NOT EXISTS `user` (
    id INT PRIMARY KEY,
    username VARCHAR(50)
);

tip

If you want to run the following examples step by step, you need to clear the user table data before running each new example.

PropagationNested (Nested Transaction, Default)

If a transaction exists, creates a nested transaction (using savepoints); if no transaction exists, creates a new transaction.

package main

import (
	_ "github.com/gogf/gf/contrib/drivers/mysql/v2"

	"context"
	"fmt"

	"github.com/gogf/gf/v2/database/gdb"
	"github.com/gogf/gf/v2/frame/g"
)

func main() {
	var (
		ctx = context.Background()
		db  = g.DB()
	)
	db.SetDebug(true)

	// Execute transaction
	err := db.Transaction(ctx, func(ctx context.Context, tx gdb.TX) error {
		// Insert data in the outer transaction
		_, err := tx.Insert("user", g.Map{
			"id":       1,
			"username": "outer_user",
		})
		if err != nil {
			return err
		}

		// Nested transaction - using PropagationNested to create a nested transaction (using savepoint)
		err = tx.Transaction(ctx, func(ctx context.Context, tx2 gdb.TX) error {
			// Insert data in the nested transaction
			_, err = tx2.Insert("user", g.Map{
				"id":       2,
				"username": "nested_user",
			})
			if err != nil {
				return err
			}

			// Simulate an error, causing the nested transaction to roll back to the savepoint
			return fmt.Errorf("nested transaction deliberately failed")
		})

		// Nested transaction failed, but outer transaction can continue
		fmt.Println("Nested transaction error:", err)

		// Continue inserting data in the outer transaction
		_, err = tx.Insert("user", g.Map{
			"id":       3,
			"username": "outer_after_nested",
		})
		// Outer transaction commits normally
		return nil
	})

	if err != nil {
		fmt.Println("Transaction execution failed:", err)
		return
	}

	// Query results
	result, err := db.Model("user").All()
	if err != nil {
		fmt.Println("Query failed:", err)
		return
	}

	// Data only contains records with id 1 and 3, not 2
	fmt.Println("Query results:", result)
}