kong.dao.cassandra.base_dao

Kong's Cassandra base DAO module.

Provides functionalities on top of lua-cassandra (https://github.com/thibaultCha/lua-cassandra) for schema validations, CRUD operations, preparation and caching of executed statements, etc...

Public interface

BaseDao:execute (query, args_to_bind, options) Bind a table of arguments to a query depending on the entity's schema, and then execute the query via :_execute().

Children DAOs interface

BaseDao:count_by_keys (where_t, paging_state) Retrieve the number of rows in the related column family matching a possible 'WHERE' clause.
BaseDao:delete (where_t) Delete the row with PRIMARY KEY from the configured table (_table attribute).
BaseDao:drop () Truncate the table related to this DAO (the _table attribute).
BaseDao:find (page_size, paging_state) Retrieve a page of rows from the related column family.
BaseDao:find_by_keys (where_t, page_size, paging_state) Retrieve a set of rows from the given columns/value table with a given 'WHERE' clause.
BaseDao:find_by_primary_key (where_t) Retrieve a row at given PRIMARY KEY.
BaseDao:insert (t) Insert a row in the defined column family (defined by the _table attribute).
BaseDao:update (t, full) Update an entity: find the row with the given PRIMARY KEY and update the other values Performs schema validation, 'UNIQUE' and 'FOREIGN' checks.

Optional overrides

BaseDao:_marshall (t) Marshall an entity.
BaseDao:_unmarshall (t) Unmarshall an entity.
BaseDao:new (properties) Constructor.

Private methods

BaseDao:_close_session (session) Close the given opened session.
BaseDao:_execute (query, args, options, keyspace) Execute a query (internally).
BaseDao:_open_session (keyspace) Open a session on the configured keyspace.
BaseDao:check_foreign_fields (t) Perform "foreign" check on a column.
BaseDao:check_unique_fields (t, is_update) Perform "unique" check on a column.
BaseDao:get_or_prepare_stmt (query) Get a prepared statement from the statements cache or prepare it (and thus insert it in the cache).

Public interface

Public methods developers can use in Kong core or in any plugin.

BaseDao:execute

Bind a table of arguments to a query depending on the entity's schema, and then execute the query via :_execute().
Parameters:
  • query string The query to execute
  • args_to_bind table Key/value table of arguments to bind
  • options stable Options to pass to lua-cassandra's :execute()
Returns:
  • return values of _execute()
See also:

Children DAOs interface

Those methds are to be used in any child DAO and will perform the named operations the entity they represent.

BaseDao:count_by_keys

Retrieve the number of rows in the related column family matching a possible 'WHERE' clause.
Parameters:
  • where_t table (Optional) columns/values table by which to count entities.
  • paging_state string Start page from given offset. See lua-cassandra's related :execute() option.
Returns:
  • number The number of rows matching the specified criteria
  • table An error if any
  • boolean A boolean indicating if the 'ALLOW FILTERING' clause was needed by the query

BaseDao:delete

Delete the row with PRIMARY KEY from the configured table (_table attribute).
Parameters:
  • where_t A table containing the PRIMARY KEY (columns/values) of the row to delete
Returns:
  • boolean True if deleted, false if otherwise or not found
  • table Error if any during the query execution or the cascade delete hook

BaseDao:drop

Truncate the table related to this DAO (the _table attribute). Only executes a 'TRUNCATE' query using the execute method.
Returns:
  • Return values of execute()
See also:

BaseDao:find

Retrieve a page of rows from the related column family.
Parameters:
  • page_size number Size of the page to retrieve (number of rows). The default is the default value from lua-cassandra.
  • paging_state string Start page from given offset. See lua-cassandra's related :execute() option.
Returns:
  • return values of findbykeys()
See also:

BaseDao:find_by_keys

Retrieve a set of rows from the given columns/value table with a given 'WHERE' clause.
Parameters:
  • where_t table (Optional) columns/values table by which to find an entity.
  • page_size number Size of the page to retrieve (number of rows).
  • paging_state string Start page from given offset. See lua-cassandra's related :execute() option.
Returns:
  • table An array (of possible length 0) of entities as the result of the query
  • table An error if any
  • boolean A boolean indicating if the 'ALLOW FILTERING' clause was needed by the query

BaseDao:find_by_primary_key

Retrieve a row at given PRIMARY KEY.
Parameters:
  • where_t table A table containing the PRIMARY KEY (it can be composite, hence be multiple columns as keys and their values) of the row to retrieve.
Returns:
  • table The first row of the result.
  • table Error if any during the execution

BaseDao:insert

Insert a row in the defined column family (defined by the _table attribute). Perform schema validation, 'UNIQUE' checks, 'FOREIGN' checks.
Parameters:
  • t A table representing the entity to insert
Returns:
  • table Inserted entity or nil
  • table Error if any during the execution
See also:

BaseDao:update

Update an entity: find the row with the given PRIMARY KEY and update the other values Performs schema validation, 'UNIQUE' and 'FOREIGN' checks.
Parameters:
  • t table A table representing the entity to update. It must contain the entity's PRIMARY KEY (can be composite).
  • full boolean If true, set to NULL any column not in the t parameter, such as a PUT query would do for example.
Returns:
  • table Updated entity or nil
  • table Error if any during the execution
See also:

Optional overrides

Can be optionally overriden by a child DAO.

BaseDao:_marshall

Marshall an entity. Executed on each entity insertion to serialize eventual properties for Cassandra storage. Does nothing by default, must be overriden for entities where marshalling applies.
Parameters:
  • t table Entity to marshall.
Returns:
  • table Serialized entity.
See also:

BaseDao:_unmarshall

Unmarshall an entity. Executed each time an entity is being retrieved from Cassandra to deserialize properties serialized by :_mashall(), Does nothing by default, must be overriden for entities where marshalling applies.
Parameters:
  • t table Entity to unmarshall.
Returns:
  • table Deserialized entity.
See also:

BaseDao:new

Constructor. Instanciate a new Cassandra DAO. This method is to be overriden from the child class and called once the child class has a schema set.
Parameters:
  • properties Cassandra properties from the configuration file.
Returns:
  • table Instanciated DAO.

Private methods

For internal use in the base_dao itself or advanced usage in a child DAO.

BaseDao:_close_session

Close the given opened session. Will try to put the session in the socket pool for re-use if supported by the current phase.
Parameters:
  • session table Cassandra session to close
Returns:
  • table Error if any
  • table The prepared statement, ready to be used by lua-cassandra.
  • table Error if any during the preparation of the statement

BaseDao:_execute

Execute a query (internally). This method should be called with the proper args formatting (as an array). See :execute() for building this parameter. Make sure the query is either prepared and cached, or retrieved from the current cache. Opens a socket, execute the statement, puts the socket back into the socket pool and returns a parsed result.
Parameters:
  • query Plain string query or BatchStatement.
  • args table (Optional) Arguments to the query, as an array. Simply passed to lua-cassandra's :execute()
  • options table (Optional) Options to give to lua-resty-cassandra's :execute()
  • keyspace string (Optional) Override the keyspace for this query if specified.
Returns:
  • table If the result set consists of ROWS, a table with an array of unmarshalled rows and a next_page property if the results have a paging_state.
  • table An error if any during the whole execution (sockets/query execution)
See also:

BaseDao:_open_session

Open a session on the configured keyspace.
Parameters:
  • keyspace string (Optional) Override the keyspace for this session if specified.
Returns:

BaseDao:check_foreign_fields

Perform "foreign" check on a column. Check all fields marked with foreign in the schema have an existing parent row.
Parameters:
  • t table Key/value representation of the entity
Returns:
  • boolean True if all fields marked as foreign have a parent row.
  • table A key/value table of all columns (as keys) not having a parent row.

BaseDao:check_unique_fields

Perform "unique" check on a column. Check that all fields marked with unique in the schema do not already exist with the same value.
Parameters:
  • t table Key/value representation of the entity
  • is_update boolean If true, we ignore an identical value if the row containing it is the one we are trying to update.
Returns:
  • boolean True if all unique fields are not already present, false if any already exists with the same value.
  • table A key/value table of all columns (as keys) having values already in the database.

BaseDao:get_or_prepare_stmt

Get a prepared statement from the statements cache or prepare it (and thus insert it in the cache). The cache is unique for each Cassandra contact_point (base on the host and port). The statement's cache key will be the plain string query representation.
Parameters:
  • query string The query to prepare
Returns:
  • table The prepared statement, ready to be used by lua-cassandra.
  • string The cache key used to store it into the cache
  • table Error if any during the query preparation