docs/Adapters.md

id: adapters title: 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:)

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
SQL Adapter	SQL	@Blank-Xu	✅	MySQL, PostgreSQL, SQL Server, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by `database/sql`
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
Ent Adapter	ORM	Casbin	✅	MySQL, MariaDB, PostgreSQL, SQLite, Gremlin-based graph databases are supported by ent ORM
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
Sqlx Adapter	SQL	@Blank-Xu	✅	MySQL, PostgreSQL, SQL Server, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by sqlx
GF ORM Adapter	ORM	@vance-liu	✅	MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame ORM Adapter	ORM	@kotlin2018	✅	MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Filtered PostgreSQL Adapter	SQL	Casbin	✅	For PostgreSQL
Filtered pgx Adapter	SQL	@pckhoi	✅	PostgreSQL is supported by pgx
PostgreSQL Adapter	SQL	@cychiuae	✅	For PostgreSQL
RQLite Adapter	SQL	EDOMO Systems	✅	For RQLite
MongoDB Adapter	NoSQL	Casbin	✅	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 Firestore Adapter	Cloud	@reedom	❌	For Google Cloud Platform Firestore
GCP Cloud Storage Adapter	Cloud	qurami	❌	For Google Cloud Platform Cloud Storage
GCP Cloud Spanner Adapter	Cloud	@flowerinthenight	✅	For Google Cloud Platform Cloud Spanner
Consul Adapter	KV store	@ankitm123	❌	For HashiCorp Consul
Redis Adapter (Redigo)	KV store	Casbin	✅	For Redis
Redis Adapter (go-redis)	KV store	@mlsen	✅	For Redis
Etcd Adapter	KV store	@sebastianliu	❌	For etcd
BoltDB Adapter	KV store	@speza	✅	For Bolt
Bolt Adapter	KV store	@wirepair	❌	For Bolt
BadgerDB Adapter	KV store	@inits	✅	For BadgerDB
Protobuf Adapter	Stream	Casbin	❌	For Google Protocol Buffers
JSON Adapter	String	Casbin	❌	For JSON
String Adapter	String	@qiangmzsx	❌	For String
HTTP File Adapter	HTTP	@h4ckedneko	❌	For http.FileSystem
FileSystem Adapter	File	@naucon	❌	For fs.FS and embed.FS

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
Hibernate Adapter	ORM	Casbin	✅	Oracle, DB2, SQL Server, Sybase, MySQL, PostgreSQL are supported by Hibernate
MyBatis Adapter	ORM	Casbin	✅	MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server (the same as JDBC) are supported by MyBatis 3
Hutool Adapter	ORM	@mapleafgo	✅	MySQL, Oracle, PostgreSQL, SQLite are supported by Hutool
MongoDB Adapter	NoSQL	Casbin	✅	MongoDB is supported by mongodb-driver-sync
DynamoDB Adapter	NoSQL	Casbin	❌	For Amazon DynamoDB
Redis Adapter	KV store	Casbin	✅	For Redis

Adapter	Type	Author	AutoSave	Description
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
Basic Adapter	Native ORM	Casbin	✅	pg, mysql, mysql2, sqlite3, oracledb, mssql are supported by the adapter itself
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
Prisma Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, AWS Aurora, Azure SQL are supported by Prisma
Knex Adapter	ORM	@sarneeh and knex	✅	MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Knex.js
Objection.js Adapter	ORM	@willsoto	✅	MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by Objection.js
Node PostgreSQL Native Adapter	SQL	@touchifyapp	✅	PostgreSQL adapter with advanced policy subset loading support and improved performances built with node-postgres.
Mongoose Adapter	NoSQL	elastic.io and Casbin	✅	MongoDB is supported by Mongoose
Mongoose Adapter (No-Transaction)	NoSQL	minhducck	✅	MongoDB is supported by Mongoose
Node MongoDB Native Adapter	NoSQL	@juicycleff	✅	For Node MongoDB Native
DynamoDB Adapter	NoSQL	@fospitia	✅	For Amazon DynamoDB
Couchbase Adapter	NoSQL	@MarkMYoung	✅	For Couchbase
Redis Adapter	KV store	Casbin	❌	For Redis
Redis Adapter	KV store	@NandaKishorJeripothula	❌	For Redis

Adapter	Type	Author	AutoSave	Description
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.
Laminas-db Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, Oracle, IBM DB2, Microsoft Sql Server, PDO, etc. are supported by laminas-db
Zend-db Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, Oracle, IBM DB2, Microsoft Sql Server, PDO, etc. are supported by zend-db
Redis Adapter	KV store	@nsnake	❌	For Redis

Adapter	Type	Author	AutoSave	Description
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
Async Databases Adapter	ORM	sampingantech	✅	PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by Databases
Peewee Adapter	ORM	@shblhy	✅	PostgreSQL, MySQL, SQLite are supported by Peewee
MongoEngine Adapter	ORM	@zhangbailong945	❌	MongoDB is supported by MongoEngine
Pony ORM Adapter	ORM	@drorvinkler	✅	MySQL, PostgreSQL, SQLite, Oracle, CockroachDB are supported by Pony ORM
Tortoise ORM Adapter	ORM	@thearchitector	✅	PostgreSQL (>=9.4), MySQL, MariaDB, and SQLite are supported by Tortoise ORM
Couchbase Adapter	NoSQL	ScienceLogic	✅ (without `remove_filtered_policy()`)	For Couchbase
DynamoDB Adapter	NoSQL	@abqadeer	✅	For DynamoDB
Pymongo Adapter	NoSQL	Casbin	❌	MongoDB is supported by Pymongo
GCP Firebase Adapter	Cloud	@devrushi41	✅	For Google Cloud Platform Firebase
Async ormar Adapter	ORM	sampingantech	✅	PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by ormar

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
EFCore Adapter (.NET Core 5)	ORM	@g4dvali	✅	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
SeaORM Adapter	ORM	lingdu1234	✅	PostgreSQL, MySQL are supported by SeaORM with fully asynchronous operation
JSON Adapter	String	Casbin	✅	For JSON
YAML Adapter	String	Casbin	✅	For YAML

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Sequel Adapter	ORM	CasbinRuby	✅	ADO, Amalgalite, IBM_DB, JDBC, MySQL, Mysql2, ODBC, Oracle, PostgreSQL, SQLAnywhere, SQLite3, and TinyTDS are supported by Sequel

Adapter	Type	Author	AutoSave	Description
File Adapter (built-in)	File	Casbin	❌	For .CSV (Comma-Separated Values) files
Memory Adapter (built-in)	Memory	Casbin	❌	For memory
Fluent Adapter	ORM	Casbin	✅	PostgreSQL, SQLite, MySQL, MongoDB are supported by Fluent

Adapter	Type	Author	AutoSave	Description
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
LuaSQL Adapter	ORM	Casbin	✅	MySQL, PostgreSQL, SQLite3 are supported by LuaSQL
4DaysORM Adapter	ORM	Casbin	✅	MySQL, SQLite3 are supported by 4DaysORM

:::note

If casbin.NewEnforcer() is called with an explicit or implicit adapter, the policy will be loaded automatically.
You can call e.LoadPolicy() to reload the policy rules from the storage.
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 have 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")

use Casbin\Enforcer;

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

use casbin::prelude::*;

let mut e = Enforcer::new("examples/basic_model.conf", "examples/basic_policy.csv").await?;

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)

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

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

use casbin::prelude::*;

let a = FileAdapter::new("examples/basic_policy.csv");
let e = Enforcer::new("examples/basic_model.conf", a).await?;

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)

// https://github.com/casbin-rs/diesel-adapter
// make sure you activate feature `mysql`

use casbin::prelude::*;
use diesel_adapter::{ConnOptions, DieselAdapter};

let mut conn_opts = ConnOptions::default();
conn_opts
	.set_hostname("127.0.0.1")
	.set_port(3306)
	.set_host("127.0.0.1:3306") // overwrite hostname, port config
	.set_database("casbin")
	.set_auth("casbin_rs", "casbin_rs");

let a = DieselAdapter::new(conn_opts)?;
let mut e = Enforcer::new("examples/basic_model.conf", a).await?;

// 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);

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)

Migrate/Convert between different adapter

If you want to convert adapter from A to B, you can do like this:

Load policy from A to memory

e, _ := NewEnforcer(m, A)

e.SetAdapter(A)
e.LoadPolicy()

convert your adapter from A to B
```
e.SetAdapter(B)
```
Save policy from memory to B
```
e.LoadPolicy()
```

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

The Auto-Save feature is optional. An adapter can choose to implement it or not.
Auto-Save only works for a Casbin enforcer when the adapter the enforcer uses supports it.
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 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.

There're details about how to write an adapter.

Data Structure. Adapter should support reading at least six columns.
Database Name. The default database name should be casbin.
Table Name. The default table name should be casbin_rule.
Ptype Column. Name of this column should be ptype instead of p_type or Ptype.
Table definition should be (id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar).
The unique key index should be built on columns ptype,v0,v1,v2,v3,v4,v5.

LoadFilteredPolicy requires a filter as parameter. The filter should be something like this.

{
    "p":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

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