适配器 · Casbin

在Casbin中，策略存储作为adapter(Casbin的中间件) 实现。 Casbin用户可以使用adapter从存储中加载策略规则 (aka LoadPolicy()) 或者将策略规则保存到其中 (aka SavePolicy())。为了保持代码轻量级，我们没有把adapter代码放在主库中。

目前支持的adapter列表

Casbin角色管理器的完整列表如下所示。欢迎任何第三方对adapter进行新的贡献，如果有请通知我们，我们将把它放在这个列表中:)

Java

Node.js

PHP

Python

.NET

Rust

适配器	类型	作者	自动保存	描述
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
GF ORM Adapter	ORM	@vance-liu	✅	MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GF ORM
Filtered PostgreSQL Adapter	SQL	Casbin	✅	For PostgreSQL
PostgreSQL Adapter	SQL	@cychiuae	✅	For PostgreSQL
PostgreSQL Adapter (Archived)	SQL	Going	❌	For PostgreSQL
RQLite Adapter	SQL	EDOMO Systems	✅	For RQLite
MongoDB Adapter	NoSQL	Casbin	✅	For MongoDB based on MongoDB driver for Go
MongoDB Adapter	NoSQL	Titan DC	✅	For MongoDB based on MongoDB Go driver
RethinkDB Adapter	NoSQL	@adityapandey9	✅	For RethinkDB
Cassandra Adapter	NoSQL	Casbin	❌	For Apache Cassandra DB
DynamoDB Adapter	NoSQL	HOOQ	❌	For Amazon DynamoDB
Dynacasbin	NoSQL	NewbMiao	✅	For Amazon DynamoDB
ArangoDB Adapter	NoSQL	@adamwasila	✅	For ArangoDB
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	@sebastianliu	❌	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

适配器	类型	作者	自动保存	描述
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

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files with policy subset loading support
String Adapter (built-in)	String	@calebfaruki	❌	For String
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 and Casbin	✅	MongoDB is supported by Mongoose
Knex Adapter	ORM	@sarneeh	✅	MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Knex.js
Node MongoDB Native Adapter	NoSQL	@juicycleff	✅	For Node MongoDB Native
Couchbase Adapter	NoSQL	@MarkMYoung	✅	For Couchbase
Redis Adapter	KV store	@NandaKishorJeripothula	❌	For Redis

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Database Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by techone/database
Zend Db Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Oracle, IBM DB2, Microsoft SQL Server, Other PDO Driver are supported by zend-db
Doctrine DBAL Adapter(Recommend)	ORM	Casbin	✅	Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management.
Medoo Adapter	ORM	Casbin	✅	Medoo is a lightweight PHP Database Framework to Accelerate Development, supports all SQL databases, including `MySQL`, `MSSQL`, `SQLite`, `MariaDB`, `PostgreSQL`, `Sybase`, `Oracle` and more.
Redis Adapter	KV store	@nsnake	❌	For Redis

适配器	类型	作者	自动保存	描述
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
SQLAlchemy Adapter	ORM	Casbin	✅	PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by SQLAlchemy
Peewee Adapter	ORM	@shblhy	✅	PostgreSQL, MySQL, SQLite are supported by Peewee
MongoEngine Adapter	ORM	@zhangbailong945	❌	MongoDB is supported by MongoEngine
Couchbase Adapter	NoSQL	ScienceLogic	✅ (without `remove_filtered_policy()`)	For Couchbase
DynamoDB Adapter	NoSQL	@abqadeer	✅	For DynamoDB

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
EF Adapter	ORM	Casbin	❌	MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by Entity Framework 6
EFCore Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by Entity Framework Core

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Diesel Adapter	ORM	Casbin	✅	SQLite, PostgreSQL, MySQL are supported by Diesel
Sqlx Adapter	ORM	Casbin	✅	PostgreSQL, MySQL are supported by Sqlx with fully asynchronous operation

note

如果使用显式或隐式adapter调用casbin.NewEnforcer()，策略将自动加载。
可以调用e.LoadPolicy() 来从存储中重新加载策略规则。
如果adapter不支持Auto-Save特性，则在添加或删除策略时不能将策略规则自动保存回存储器。 You have to call SavePolicy() manually to save all policy rules. :::

例子

Here we provide several examples:

文件适配器 (内置)

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

PHP

import "github.com/casbin/casbin"

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

use Casbin\Enforcer;

$e = new Enforcer('examples/basic_model.conf', 'examples/basic_policy.csv');

This is the same with:

PHP

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)

use Casbin\Enforcer;
use Casbin\Persist\Adapters\FileAdapter;

$a = new FileAdapter('examples/basic_policy.csv');
$e = new Enforcer('examples/basic_model.conf', $a);

MySQL 适配器

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.

PHP

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)

// https://github.com/php-casbin/dbal-adapter

use Casbin\Enforcer;
use CasbinAdapter\DBAL\Adapter as DatabaseAdapter;

$config = [
    // Either 'driver' with one of the following values:
    // pdo_mysql,pdo_sqlite,pdo_pgsql,pdo_oci (unstable),pdo_sqlsrv,pdo_sqlsrv,
    // mysqli,sqlanywhere,sqlsrv,ibm_db2 (unstable),drizzle_pdo_mysql
    'driver'     => 'pdo_mysql', 
    'host' => '127.0.0.1',
    'dbname' => 'test',
    'user' => 'root',
    'password' => '',
    'port' => '3306',
];

$a = DatabaseAdapter::newAdapter($config);
$e = new Enforcer('examples/basic_model.conf', $a);

使用自建的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)

在运行时进行加载或保存配置信息

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

自动保存

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

Auto-Save 特性是可选的。 Adapter可以选择是否实现它。
Auto-Save 只在Casbin enforcer使用的adapter支持它时才有效。
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

如何编写 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.

方法	类型	描述
LoadPolicy()	强制的	从存储中加载所有策略规则
SavePolicy()	强制的	将所有策略规则保存到存储中
AddPolicy()	可选择的	向存储中添加策略规则
RemovePolicy()	可选择的	从存储中删除策略规则
RemoveFilteredPolicy()	可选择的	从存储中删除匹配筛选器的策略规则

If an adapter doesn't support `Auto-Save`, it should provide an empty implementation for the three optional functions. Here's an example for Golang: :::

// 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.

关于数据库表结构的创建

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