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:
-
-
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:
-
-
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:
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 thet
parameter, such as a PUT query would do for example.
Returns:
See also:
-
Optional overrides
Can be optionally overridden 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 overridden 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 overridden for entities where marshalling applies.Parameters:
-
t
table Entity to unmarshall.
Returns:
- table Deserialized entity.
See also:
-
-
BaseDao:new
-
Constructor.
Instantiate a new Cassandra DAO. This method is to be overridden from the
child class and called once the child class has a schema set.
Parameters:
-
properties
Cassandra properties from the configuration file.
Returns:
- table Instantiated 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:
-
-
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:
-