Upgrading Casbin (Go) from v2 to v3: A Complete Migration Guide

Back

If you're running Casbin v2 in production and wondering about the upgrade path to v3, this guide is for you. We'll cover everything you need to know about the transition, from understanding what changed to executing a safe production migration.

What Changed in v3?

The good news: v3 is primarily a module path change with full backward compatibility. The core authorization logic, APIs, and functionality remain unchanged. This was an intentional decision to minimize disruption while following Go's semantic versioning conventions.

The Main Change: Module Path

The only breaking change in v3 is the Go module path:

// v2
import "github.com/casbin/casbin/v2"

// v3
import "github.com/casbin/casbin/v3"

That's it. Your existing policies, models, and code logic don't need to change. The migration is mechanical: update import statements and your go.mod file.

Why Release v3?

You might wonder why release a new major version for just an import path change. The answer is semantic versioning. Go's module system uses the major version number in the import path (/v2, /v3, etc.). This allows multiple major versions to coexist in the same dependency tree, which is crucial for large applications with many dependencies.

By releasing v3, we've:

Aligned with Go's semantic import versioning
Enabled gradual migration in complex dependency graphs
Set the stage for future enhancements without breaking existing v2 users

What Stayed the Same?

Everything else. Seriously.

All APIs remain identical - Enforce(), AddPolicy(), GetAllRoles(), and every other method works exactly as before
Model and policy syntax unchanged - Your existing .conf model files and .csv policy files work without modification
Adapter interface unchanged - All existing adapters (PostgreSQL, MySQL, MongoDB, etc.) remain compatible
Performance characteristics - No performance regressions or improvements; it's the same engine
Middleware integrations - Your Gin, Echo, or other framework middleware continues to work

New Features in v3

Since the v3.0.0 release on December 9, 2025, several new features have been added:

v3.7.0+: Enhanced Logger Integration

You can now integrate custom loggers into Casbin's core enforcement and policy management operations, providing better observability:

enforcer.SetLogger(yourCustomLogger)

v3.8.0+: GetAllUsers() API

A new API to distinguish users from roles:

users := enforcer.GetAllUsers()

This is particularly useful in RBAC systems where you need to list actual users separately from role definitions.

v3.9.0+: Built-in Cycle Detection

The enforcer now includes automatic detection of cycles in role hierarchies, preventing infinite loops:

// Automatically detects and prevents circular role assignments
enforcer.AddGroupingPolicy("alice", "admin")
enforcer.AddGroupingPolicy("admin", "alice") // Will be detected as a cycle

v3.10.0+: Explain() API for AI-Powered Authorization Insights

The latest feature leverages LLM APIs to explain authorization decisions in natural language:

explanation := enforcer.Explain("alice", "read", "data1")
// Returns: "Alice has read permission on data1 because she has the 'reader' role..."

This is particularly valuable for debugging complex policies and helping non-technical stakeholders understand authorization decisions.

Migration Strategy

For New Projects

Simple: just use v3 from the start.

go get github.com/casbin/casbin/v3

import "github.com/casbin/casbin/v3"

For Existing v2 Projects

The migration involves three steps:

Step 1: Update Your go.mod

go get github.com/casbin/casbin/v3
go mod tidy

Step 2: Update Import Statements

Find and replace all Casbin imports across your codebase:

# Using sed on Unix/Linux/Mac
find . -type f -name '*.go' -exec sed -i 's|github.com/casbin/casbin/v2|github.com/casbin/casbin/v3|g' {} +

# Or manually in your editor
# Find: github.com/casbin/casbin/v2
# Replace: github.com/casbin/casbin/v3

Step 3: Update Adapter Imports (If Applicable)

If you're using an adapter, check if it has been updated for v3. Most popular adapters have v3 versions:

// Example: PostgreSQL Adapter
import "github.com/casbin/casbin-pg-adapter" // Check for v3 support

// Note: File Adapter is built-in and works with both v2 and v3

Check the adapter's repository for v3 compatibility. Most adapters work with both v2 and v3 since the adapter interface didn't change.

Rollback Plan

If you need to rollback:

Code level: Revert import changes (use version control)
Dependency level: go get github.com/casbin/casbin/v2@latest
Deploy: Use your standard deployment process to revert

The beauty of this migration is that rollback is trivial - just revert the import changes and redeploy.

Do I Need to Migrate My Policy Database?

No. Your existing policy data remains unchanged. The policies are stored as simple strings (subject, object, action, etc.) and have no dependency on the Casbin version.

Testing Your Migration

Automated Testing

Your existing tests should pass without modification:

func TestPolicyEnforcement(t *testing.T) {
    // This test works identically in v2 and v3
    e, _ := casbin.NewEnforcer("model.conf", "policy.csv")
    
    ok, _ := e.Enforce("alice", "data1", "read")
    if !ok {
        t.Error("Expected alice to have read access to data1")
    }
}

Integration Testing

Test your middleware integrations:

// Example with Gin
import (
    "github.com/casbin/casbin/v3"
    casbinmiddleware "github.com/casbin/gin-casbin/v3"
)

// Your middleware should work identically
router.Use(casbinmiddleware.NewAuthorizer(enforcer))

Load Testing

Run your standard load tests against the v3 build. Performance characteristics should be identical to v2.

Policy Verification

Compare policy evaluation across versions:

# Export policies from v2
# Load into v3
# Run test cases against both
# Compare results

If you see any differences, it's likely a bug - please report it!

Common Pitfalls

Pitfall 1: Mixed v2/v3 Dependencies

Problem: Some dependencies use Casbin v2, others use v3, causing conflicts.

Solution: This actually isn't a problem! Go's module system allows both v2 and v3 to coexist. They're treated as separate packages. However, for cleanliness, try to update all dependencies to v3 when possible.

Pitfall 2: Adapter Version Mismatch

Problem: Using a v2 adapter with Casbin v3 (or vice versa).

Solution: Check your adapter's documentation. Most adapters support both versions. If uncertain, test in development first.

Pitfall 3: Forgetting Internal Packages

Problem: Updated main application imports but forgot internal packages or tools.

Solution: Use go mod graph and go mod why to find all Casbin dependencies:

go mod graph | grep casbin

Pitfall 4: Custom Adapter Compilation Issues

Problem: Custom adapter won't compile after upgrade.

Solution: The adapter interface didn't change, so this suggests an import issue. Check that all Casbin imports in your adapter use v3:

import (
    "github.com/casbin/casbin/v3"
    "github.com/casbin/casbin/v3/persist"
)