Document TransactionalEnforcer for atomic policy and business data updates

[Copilot]

Casbin's TransactionalEnforcer provides atomic coordination between policy operations and business database transactions, but was undocumented. Users deploying RBAC systems need to update user roles in their database and Casbin policies atomically to avoid inconsistency.

Changes

• TRANSACTION_GUIDE.md - Comprehensive documentation covering:

  • WithTransaction pattern for automatic commit/rollback
  • Two-phase commit protocol with conflict detection
  • TransactionalAdapter interface implementation
  • GORM adapter integration example

• examples/transaction/ - Working examples demonstrating:

  • Basic transactions with automatic rollback
  • User role management pattern
  • Batch policy operations

• README.md - Added transaction support section with usage snippet

Usage

enforcer, _ := casbin.NewTransactionalEnforcer("model.conf", transactionalAdapter)

err := enforcer.WithTransaction(ctx, func(tx *casbin.Transaction) error {
    // Database and Casbin operations in same transaction
    db.UpdateUserRole(userId, "admin")
    tx.AddGroupingPolicy(userId, "admin")
    return nil // Both commit atomically
})

Adapters must implement persist.TransactionalAdapter interface. Guide includes complete GORM implementation example.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>How to achieve transaction consistency between Casbin policy operations and other database operations?</issue_title>
<issue_description>Description
In our application, we need to update both business data and Casbin authorization policies atomically. For example, when changing a user's role:

Update the user's role in the business database

Update the corresponding Casbin grouping policy

Currently, these operations happen in separate transactions, risking data inconsistency if one succeeds and the other fails.

Questions:

What are the recommended patterns for ensuring transaction consistency between Casbin policies and business data?

Does Casbin provide built-in support for coordinating these operations within a single transaction?

Are there adapter-specific solutions (e.g., for Gorm, Xorm, or specific databases)?

Context:

We're using gorm-adapter

Database: PostgreSQL

Application framework: [specify framework, e.g., Go Gin, Spring Boot]

Any guidance or examples would be greatly appreciated!</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes How to achieve transaction consistency between Casbin policy operations and other database operations? #1702

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}