Edit

Policy Storage

In Casbin, the policy storage is implemented as an adapter (aka middleware for Casbin). A Casbin user can use an adapter to load policy rules from a storage (aka LoadPolicy()), or save policy rules to it (aka SavePolicy()). To keep light-weight, we don't put adapter code in the main library.

All supported adapters can be found here.

Here are some things you need to know:

1. If casbin.NewEnforcer() is called with an explicit or implicit adapter, the policy will be loaded automatically.
2. You can call e.LoadPolicy() to reload the policy rules from the storage.
3. If the adapter does not support the Auto-Save feature, The policy rules cannot be automatically saved back to the storage when you add or remove policies. You can to call SavePolicy() manually to save all policy rules.

Examples

Here we provide several examples:

File adapter (built-in)

Below shows how to initialize an enforcer from the built-in file adapter:

import "github.com/casbin/casbin"

e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")

This is the same with:

import (
    "github.com/casbin/casbin"
    "github.com/casbin/casbin/file-adapter"
)

a := fileadapter.NewAdapter("examples/basic_policy.csv")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

MySQL adapter

Below shows how to initialize an enforcer from MySQL database. it connects to a MySQL DB on 127.0.0.1:3306 with root and blank password.

import (
    "github.com/casbin/casbin"
    "github.com/casbin/mysql-adapter"
)

a := mysqladapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

Use your own storage adapter

You can use your own adapter like below:

import (
    "github.com/casbin/casbin"
    "github.com/your-username/your-repo"
)

a := yourpackage.NewAdapter(params)
e := casbin.NewEnforcer("examples/basic_model.conf", a)

Load/Save at run-time

You may also want to reload the model, reload the policy or save the policy after initialization:

// Reload the model from the model CONF file.
e.LoadModel()

// Reload the policy from file/database.
e.LoadPolicy()

// Save the current policy (usually after changed with Casbin API) back to file/database.
e.SavePolicy()

Supported adapters

In Casbin, the policy storage is implemented as an adapter (aka middleware for Casbin). To keep light-weight, we don't put adapter code in the main library. A complete list of Casbin adapters is provided as below.

Note: Any 3rd-party contribution on a new adapter is welcomed, please inform us and we will put it in this list:)

Adapter	Type	Author	Description
File Adapter (built-in)	File	Casbin	Persistence for .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)	File	@faceless-saint	Persistence for .CSV (Comma-Separated Values) files with policy subset loading support
Xorm Adapter	ORM	Casbin	MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
Gorm Adapter	ORM	Casbin	MySQL, PostgreSQL, Sqlite3, SQL Server are supported by Gorm
Beego ORM Adapter	ORM	Casbin	MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
MongoDB Adapter	NoSQL	Casbin	Persistence for MongoDB
Cassandra Adapter	NoSQL	Casbin	Persistence for Apache Cassandra DB
Consul Adapter	KV store	@ankitm123	Persistence for HashiCorp Consul
Redis Adapter	KV store	Casbin	Persistence for Redis
Etcd Adapter	KV store	Casbin	Persistence for etcd
Protobuf Adapter	Stream	Casbin	Persistence for Google Protocol Buffers
JSON Adapter	String	Casbin	Persistence for JSON
String Adapter	String	@qiangmzsx	Persistence for String
RQLite Adapter	SQL	EDOMO Systems	Persistence for RQLite
PostgreSQL Adapter	SQL	Going	Persistence for PostgreSQL
RethinkDB Adapter	NoSQL	@adityapandey9	Persistence for RethinkDB
DynamoDB Adapter	NoSQL	HOOQ	Persistence for Amazon DynamoDB
Minio/AWS S3 Adapter	Object storage	Soluto	Persistence for Minio and Amazon S3
Bolt Adapter	KV store	@wirepair	Persistence for Bolt

AutoSave

There is a feature called Auto-Save for adapters. When an adapter supports Auto-Save, it means it can support adding a single policy rule to the storage, or removing a single policy rule from the storage. This is unlike SavePolicy(), because the latter will delete all policy rules in the storage and save all policy rules from Casbin enforcer to the storage. So it may suffer performance issue when the number of policy rules is large.

When the adapter supports Auto-Save, you can switch this option via Enforcer.EnableAutoSave() function. The option is enabled by default (if the adapter supports it).

Note:

1. TheAuto-Save feature is optional. An adapter can choose to implement it or not.
2. Auto-Save only works for a Casbin enforcer when the adapter the enforcer uses supports it.
3. Currently, the adapters that support Auto-Save are:

Adapter with Auto-Save	Type	Author	Description
Xorm Adapter	ORM	Casbin	MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
Gorm Adapter	ORM	Casbin	MySQL, PostgreSQL, Sqlite3, SQL Server are supported by Gorm
Beego ORM Adapter	ORM	Casbin	MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
MongoDB Adapter	NoSQL	Casbin	Persistence for MongoDB
RQLite Adapter	SQL	EDOMO Systems	Persistence for RQLite
RethinkDB Adapter	NoSQL	@adityapandey9	Persistence for RethinkDB

Here's an example about how to use Auto-Save:

import (
    "github.com/casbin/casbin"
    "github.com/casbin/xorm-adapter"
    _ "github.com/go-sql-driver/mysql"
)

// By default, the AutoSave option is enabled for an enforcer.
a := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

// Disable the AutoSave option.
e.EnableAutoSave(false)

// Because AutoSave is disabled, the policy change only affects the policy in Casbin enforcer,
// it doesn't affect the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

// Enable the AutoSave option.
e.EnableAutoSave(true)

// Because AutoSave is enabled, the policy change not only affects the policy in Casbin enforcer,
// but also affects the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

For more examples, please see: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

How to write an adapter

All adapters should implement the Adapter interface by providing at least two mandatory methods:LoadPolicy(model model.Model) error and SavePolicy(model model.Model) error.

The other three functions are optional. They should be implemented if the adapter supports the Auto-Save feature.

Method	Type	Description
LoadPolicy()	mandatory	Load all policy rules from the storage
SavePolicy()	mandatory	Save all policy rules to the storage
AddPolicy()	optional	Add a policy rule to the storage
RemovePolicy()	optional	Remove a policy rule from the storage
RemoveFilteredPolicy()	optional	Remove policy rules that match the filter from the storage

Note: if an adapter doesn't support the Auto-Save feature, it should provide an empty implementation for the three optional functions. If you don't provide it, Golang compiler will complain errors. Here's an example:

// AddPolicy adds a policy rule to the storage.
func (a *Adapter) AddPolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemovePolicy removes a policy rule from the storage.
func (a *Adapter) RemovePolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemoveFilteredPolicy removes policy rules that match the filter from the storage.
func (a *Adapter) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error {
    return errors.New("not implemented")
}

Casbin enforcer will ignore the not implemented error when calling these three optional functions.

Who is responsible to create the DB?

As a convention, the adapter should be able to automatically create a database named casbin if it doesn't exist and use it for policy storage. Please use the MySQL adapter as a reference implementation: https://github.com/casbin/mysql-adapter