Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

Plugin Development - Accessing the datastore

Kong interacts with the model layer through classes we refer to as "DAOs". This chapter will detail the available API to interact with the datastore.

Note: Currently, Kong only supports Cassandra as its datastore. This guide assumes that you are already familiar with it and sometimes describes concepts only related to Cassandra, such as indexes and clustering keys.

The DAO Factory

All entities in Kong are represented by:

  • A schema that describes which table the entity relates to in the datastore, constraints on its fields such as foreign keys, non-null constraints etc... This schema is a table described in the plugin configuration chapter.
  • A child implementation of the kong.dao.cassandra.base_dao module, which consumes the schema exposing methods to insert, update, find and delete entities of that type. See the children DAOs interface.

The core entities in Kong are: Apis, Consumers and Plugins. Each of these entities can be interacted with through their corresponding DAO instance, available through the DAO Factory instance. The DAO Factory is responsible for loading these core entities' DAOs as well as any additional entities, provided for example by plugins.

The DAO Factory is generally accessible from the dao global variable:

local dao_factory = dao

-- Core DAOs
local apis_dao = dao_factory.apis
local consumers_dao = dao_factory.consumers
local plugins_dao = dao_factory.plugins

For performance reasons, it is recommended to cache the global variable. In some cases, the DAO Factory is given as a local variable, and should be used over the global variable for the same reasons.


DAOs Lua API

All methods available on DAOs are documented in the kong.dao.cassandra.base_dao module in Kong's Public Lua API Reference. See the public interface and children DAOs interface sections of the base_dao module.

By extending the base_dao module, all DAOs have access to an abstraction on top of Cassandra, providing methods for inserting, updating, finding and deleting rows, with validation and pagination features that Cassandra does not provide by itself.

For example, inserting an API is as easy as:

local inserted_api, err = dao.apis:insert({
  name = "mockbin",
  upstream_url = "http://mockbin.com",
  request_host = "mockbin.com"
})

Custom DAOs

Because Kong needs to deal with more than the three core entities, the kong.dao.cassandra.base_dao can be inherited to support any entity. Plugins make heavy use of this feature, and every exising plugin implements their own DAO, loaded by the DAO Factory and made available everywhere the factory is, just like the core entities.

Now, let's see how to create your own DAO for your plugin in the next chapter: Custom Entities.


Next: Custom Entities ›