Translate

Adapters

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.

Supported adapters

A complete list of Casbin adapters is provided as below. Any 3rd-party contribution on a new adapter is welcomed, please inform us and we will put it in this list:)

Go

Java

Node.js

PHP

Python

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)	File	@faceless-saint	❌	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
SQLX Adapter	ORM	@memwey	✅	MySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
PostgreSQL Adapter	SQL	Going	❌	For PostgreSQL
RQLite Adapter	SQL	EDOMO Systems	✅	For RQLite
MongoDB Adapter	NoSQL	Casbin	✅	For MongoDB
RethinkDB Adapter	NoSQL	@adityapandey9	✅	For RethinkDB
Cassandra Adapter	NoSQL	Casbin	❌	For Apache Cassandra DB
DynamoDB Adapter	NoSQL	HOOQ	❌	For Amazon DynamoDB
Amazon S3 Adapter	Cloud	Soluto	❌	For Minio and Amazon S3
Azure Cosmos DB Adapter	Cloud	@spacycoder	✅	For Microsoft Azure Cosmos DB
GCP Datastore Adapter	Cloud	LivingPackets	❌	For Google Cloud Platform Datastore
Consul Adapter	KV store	@ankitm123	❌	For HashiCorp Consul
Redis Adapter	KV store	Casbin	❌	For Redis
Etcd Adapter	KV store	Casbin	❌	For etcd
Bolt Adapter	KV store	@wirepair	❌	For Bolt
Protobuf Adapter	Stream	Casbin	❌	For Google Protocol Buffers
JSON Adapter	String	Casbin	❌	For JSON
String Adapter	String	@qiangmzsx	❌	For String

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
JDBC Adapter	JDBC	Casbin	✅	MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server are supported by JDBC

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Sequelize Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by Sequelize
TypeORM Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, WebSQL, MongoDB are supported by TypeORM
Mongoose Adapter	ORM	elastic.io	✅	MongoDB is supported by Mongoose
Knex Adapter	ORM	@sarneeh	✅	MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Knex.js

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Database Adapter	Database	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by Database Adapter

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)	File	@faceless-saint	❌	For .CSV (Comma-Separated Values) files with policy subset loading support
SQLAlchemy Adapter	database	Casbin	✅	PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by SQLAlchemy

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()

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. The Auto-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. See the AutoSave column in the above adapter list to see if Auto-Save is supported by an adapter.

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 Xorm adapter as a reference implementation: https://github.com/casbin/xorm-adapter