diff --git a/Documentation/Filters/Cache.md b/Documentation/Filters/Cache.md index 68958287a..d946e0e76 100644 --- a/Documentation/Filters/Cache.md +++ b/Documentation/Filters/Cache.md @@ -3,14 +3,22 @@ This filter was introduced in MariaDB MaxScale 2.1. ## Overview -_Note that the cache is still experimental and that non-backward compatible -changes may be made._ + +From MaxScale version 2.2.11 onwards, the cache filter is no longer +considered experimental. The following changes to the default behaviour +have also been made: + +* The default value of `cached_data` is now `thread_specific` (used to be + `shared`). +* The default value of `selects` is now `assume_cacheable` (used to be + `verify_cacheable`). The cache filter is a simple cache that is capable of caching the result of SELECTs, so that subsequent identical SELECTs are served directly by MaxScale, without the queries being routed to any server. By _default_ the cache will be used and populated in the following circumstances: + * There is _no_ explicit transaction active, that is, _autocommit_ is used, * there is an _explicitly_ read-only transaction (that is,`START TRANSACTION READ ONLY`) active, or @@ -29,24 +37,9 @@ the isolation level of the backends actually is. The default behaviour can be altered using the configuration parameter [cache_inside_transactions](#cache_inside_transactions). -By default, it is *ensured* that the cache is **not** used in the following -circumstances: - -* The `SELECT` uses any of the following functions: `BENCHMARK`, - `CONNECTION_ID`, `CONVERT_TZ`, `CURDATE`, `CURRENT_DATE`, `CURRENT_TIMESTAMP`, - `CURTIME`, `DATABASE`, `ENCRYPT`, `FOUND_ROWS`, `GET_LOCK`, `IS_FREE_LOCK`, - `IS_USED_LOCK`, `LAST_INSERT_ID`, `LOAD_FILE`, `LOCALTIME`, `LOCALTIMESTAMP`, - `MASTER_POS_WAIT`, `NOW`, `RAND`, `RELEASE_LOCK`, `SESSION_USER`, `SLEEP`, - `SYSDATE`, `SYSTEM_USER`, `UNIX_TIMESTAMP`, `USER`, `UUID`, `UUID_SHORT`. -* The `SELECT` accesses any of the following fields: `CURRENT_DATE`, - `CURRENT_TIMESTAMP`, `LOCALTIME`, `LOCALTIMESTAMP` -* The `SELECT` uses system or user variables. - -In order to ensure that, all `SELECT` statements have to be parsed, which -carries a _significant_ performance cost. If it is known that there are no -such statements or that it does not matter even if they are cached, that -safety measure can be turned off. Please read [performance](#performance) -for more details. +By default it is assumed that all `SELECT` statements are cacheable, which +means that also statements like `SELECT LOCALTIME` are cached. Please check +[selects](#selects) for how to change the default behaviour. ## Limitations @@ -229,11 +222,11 @@ allowed values are: multiple times. ``` -cached_data=thread_specific +cached_data=shared ``` -Default is `shared`. See `max_count` and `max_size` what implication changing -this setting to `thread_specific` has. +Default is `thread_specific`. See `max_count` and `max_size` what implication +changing this setting to `shared` has. #### `selects` @@ -246,17 +239,33 @@ respect to `SELECT` statements. The allowed values are: statements are cacheable, but must verify that. ``` -selects=assume_cacheable +selects=verify_cacheable ``` -Default is `verify_cacheable`. In this case, the `SELECT` statements will be +Default is `assume_cacheable`. In this case, all `SELECT` statements are +assumed to be cacheable and will be parsed *only* if some specific rule +requires that. + +If `verify_cacheable` is specified, then all `SELECT` statements will be parsed and only those that are safe for caching - e.g. do *not* call any non-cacheable functions or access any non-cacheable variables - will be subject to caching. -If `assume_cacheable` is specified, then all `SELECT` statements are -assumed to be cacheable and will be parsed *only* if some specific rule -requires that. +If `verify_cacheable` has been specified, the cache will not be used in +the following circumstances: + +* The `SELECT` uses any of the following functions: `BENCHMARK`, + `CONNECTION_ID`, `CONVERT_TZ`, `CURDATE`, `CURRENT_DATE`, `CURRENT_TIMESTAMP`, + `CURTIME`, `DATABASE`, `ENCRYPT`, `FOUND_ROWS`, `GET_LOCK`, `IS_FREE_LOCK`, + `IS_USED_LOCK`, `LAST_INSERT_ID`, `LOAD_FILE`, `LOCALTIME`, `LOCALTIMESTAMP`, + `MASTER_POS_WAIT`, `NOW`, `RAND`, `RELEASE_LOCK`, `SESSION_USER`, `SLEEP`, + `SYSDATE`, `SYSTEM_USER`, `UNIX_TIMESTAMP`, `USER`, `UUID`, `UUID_SHORT`. +* The `SELECT` accesses any of the following fields: `CURRENT_DATE`, + `CURRENT_TIMESTAMP`, `LOCALTIME`, `LOCALTIMESTAMP` +* The `SELECT` uses system or user variables. + +Note that parsing all `SELECT` statements carries a _significant_ performance +cost. Please read [performance](#performance) for more details. #### `cache_inside_transactions` @@ -353,6 +362,7 @@ Each entry in the `store` array is an object containing three fields, ``` where, + * the _attribute_ can be `database`, `table`, `column` or `query`, * the _op_ can be `=`, `!=`, `like` or `unlike`, and * the _value_ a string. @@ -520,6 +530,7 @@ Each entry in the `use` array is an object containing three fields, ``` where, + * the _attribute_ can be `user`, * the _op_ can be `=`, `!=`, `like` or `unlike`, and * the _value_ a string. @@ -828,7 +839,8 @@ rule like ``` The exact match rule requires all statements to be parsed. -Note that the qps figures are only indicative. +Note that the qps figures are only indicative and that the difference under +high load may be significantly _greater_. | `selects` | Rule | qps | | -------------------| ---------------|-----| @@ -842,9 +854,9 @@ Note that the qps figures are only indicative. ## Summary For maximum performance: -* Arrange the situation so that `selects=assume_cacheable` can be - configured, and use _no_ rules. -* If `selects=assume_cacheable` has been configured, use _only_ - regexp based rules. -* If `selects=verify_cacheable` has been configured non-regex based + +* Arrange the situation so that the default `selects=assume_cacheable` + can be used, and use _no_ rules. +* If `selects=assume_cacheable` is used, use _only_ regexp based rules. +* If `selects=verify_cacheable` has been configured, non-regex based matching can be used. diff --git a/Documentation/Release-Notes/MaxScale-2.2.11-Release-Notes.md b/Documentation/Release-Notes/MaxScale-2.2.11-Release-Notes.md new file mode 100644 index 000000000..4d689639b --- /dev/null +++ b/Documentation/Release-Notes/MaxScale-2.2.11-Release-Notes.md @@ -0,0 +1,44 @@ +# MariaDB MaxScale 2.2.11 Release Notes -- 2018-06 + +Release 2.2.11 is a GA release. + +This document describes the changes in release 2.2.11, when compared to +release 2.2.10. + +For any problems you encounter, please consider submitting a bug +report at [Jira](https://jira.mariadb.org). + +## Changed Features + +### Cache + +The cache filter is no longer marked as being experimental. The default +value for `cached_data` been changed from `shared` to `thread_specific`, +and the default value for `selects` has been changed from `verify_cacheable` +to `assume_cacheable`. +Please consult the +[cache documentation](../Filters/Cache.md) +for details. + +## Bug fixes + + +## Known Issues and Limitations + +There are some limitations and known issues within this version of MaxScale. +For more information, please refer to the [Limitations](../About/Limitations.md) document. + +## Packaging + +RPM and Debian packages are provided for the Linux distributions supported +by MariaDB Enterprise. + +Packages can be downloaded [here](https://mariadb.com/downloads/mariadb-tx/maxscale). + +## Source Code + +The source code of MaxScale is tagged at GitHub with a tag, which is identical +with the version of MaxScale. For instance, the tag of version X.Y.Z of MaxScale +is X.Y.Z. Further, *master* always refers to the latest released non-beta version. + +The source code is available [here](https://github.com/mariadb-corporation/MaxScale). diff --git a/server/modules/filter/cache/cachefilter.cc b/server/modules/filter/cache/cachefilter.cc index 1391c311b..1346650d6 100644 --- a/server/modules/filter/cache/cachefilter.cc +++ b/server/modules/filter/cache/cachefilter.cc @@ -53,8 +53,8 @@ void cache_config_finish(CACHE_CONFIG& config) config.hard_ttl = 0; config.soft_ttl = 0; config.debug = 0; - config.thread_model = CACHE_THREAD_MODEL_MT; - config.selects = CACHE_SELECTS_VERIFY_CACHEABLE; + config.thread_model = CACHE_DEFAULT_THREAD_MODEL; + config.selects = CACHE_DEFAULT_SELECTS; } /** @@ -79,6 +79,9 @@ void cache_config_free(CACHE_CONFIG* pConfig) void cache_config_reset(CACHE_CONFIG& config) { memset(&config, 0, sizeof(config)); + + config.thread_model = CACHE_DEFAULT_THREAD_MODEL; + config.selects = CACHE_DEFAULT_SELECTS; } /** @@ -163,7 +166,7 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE() static MXS_MODULE info = { MXS_MODULE_API_FILTER, - MXS_MODULE_IN_DEVELOPMENT, + MXS_MODULE_GA, MXS_FILTER_VERSION, "A caching filter that is capable of caching and returning cached data.", VERSION_STRING, @@ -177,7 +180,7 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE() { "storage", MXS_MODULE_PARAM_STRING, - CACHE_DEFAULT_STORAGE + CACHE_ZDEFAULT_STORAGE }, { "storage_options", @@ -186,32 +189,32 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE() { "hard_ttl", MXS_MODULE_PARAM_COUNT, - CACHE_DEFAULT_HARD_TTL + CACHE_ZDEFAULT_HARD_TTL }, { "soft_ttl", MXS_MODULE_PARAM_COUNT, - CACHE_DEFAULT_SOFT_TTL + CACHE_ZDEFAULT_SOFT_TTL }, { "max_resultset_rows", MXS_MODULE_PARAM_COUNT, - CACHE_DEFAULT_MAX_RESULTSET_ROWS + CACHE_ZDEFAULT_MAX_RESULTSET_ROWS }, { "max_resultset_size", MXS_MODULE_PARAM_SIZE, - CACHE_DEFAULT_MAX_RESULTSET_SIZE + CACHE_ZDEFAULT_MAX_RESULTSET_SIZE }, { "max_count", MXS_MODULE_PARAM_COUNT, - CACHE_DEFAULT_MAX_COUNT + CACHE_ZDEFAULT_MAX_COUNT }, { "max_size", MXS_MODULE_PARAM_SIZE, - CACHE_DEFAULT_MAX_SIZE + CACHE_ZDEFAULT_MAX_SIZE }, { "rules", @@ -220,26 +223,26 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE() { "debug", MXS_MODULE_PARAM_COUNT, - CACHE_DEFAULT_DEBUG + CACHE_ZDEFAULT_DEBUG }, { "cached_data", MXS_MODULE_PARAM_ENUM, - CACHE_DEFAULT_THREAD_MODEL, + CACHE_ZDEFAULT_THREAD_MODEL, MXS_MODULE_OPT_NONE, parameter_cached_data_values }, { "selects", MXS_MODULE_PARAM_ENUM, - CACHE_DEFAULT_SELECTS, + CACHE_ZDEFAULT_SELECTS, MXS_MODULE_OPT_NONE, parameter_selects_values }, { "cache_in_transactions", MXS_MODULE_PARAM_ENUM, - CACHE_DEFAULT_CACHE_IN_TRXS, + CACHE_ZDEFAULT_CACHE_IN_TRXS, MXS_MODULE_OPT_NONE, parameter_cache_in_trxs_values }, diff --git a/server/modules/filter/cache/cachefilter.h b/server/modules/filter/cache/cachefilter.h index 12dbfa4f7..7675ace8a 100644 --- a/server/modules/filter/cache/cachefilter.h +++ b/server/modules/filter/cache/cachefilter.h @@ -38,35 +38,37 @@ #define UINT64_MAX (18446744073709551615UL) #endif -// Count -#define CACHE_DEFAULT_MAX_RESULTSET_ROWS "0" -// Bytes -#define CACHE_DEFAULT_MAX_RESULTSET_SIZE "0" -// Seconds -#define CACHE_DEFAULT_HARD_TTL "0" -// Seconds -#define CACHE_DEFAULT_SOFT_TTL "0" -// Integer value -#define CACHE_DEFAULT_DEBUG "0" -// Positive integer -#define CACHE_DEFAULT_MAX_COUNT "0" -// Positive integer -#define CACHE_DEFAULT_MAX_SIZE "0" -// Thread model -#define CACHE_DEFAULT_THREAD_MODEL "shared" -// Cacheable selects -#define CACHE_DEFAULT_SELECTS "verify_cacheable" -// Storage -#define CACHE_DEFAULT_STORAGE "storage_inmemory" -// Transaction behaviour -#define CACHE_DEFAULT_CACHE_IN_TRXS "all_transactions" - typedef enum cache_selects { CACHE_SELECTS_ASSUME_CACHEABLE, CACHE_SELECTS_VERIFY_CACHEABLE, } cache_selects_t; +// Count +#define CACHE_ZDEFAULT_MAX_RESULTSET_ROWS "0" +// Bytes +#define CACHE_ZDEFAULT_MAX_RESULTSET_SIZE "0" +// Seconds +#define CACHE_ZDEFAULT_HARD_TTL "0" +// Seconds +#define CACHE_ZDEFAULT_SOFT_TTL "0" +// Integer value +#define CACHE_ZDEFAULT_DEBUG "0" +// Positive integer +#define CACHE_ZDEFAULT_MAX_COUNT "0" +// Positive integer +#define CACHE_ZDEFAULT_MAX_SIZE "0" +// Thread model +#define CACHE_ZDEFAULT_THREAD_MODEL "thread_specific" +const cache_thread_model CACHE_DEFAULT_THREAD_MODEL = CACHE_THREAD_MODEL_ST; +// Cacheable selects +#define CACHE_ZDEFAULT_SELECTS "assume_cacheable" +const cache_selects_t CACHE_DEFAULT_SELECTS = CACHE_SELECTS_ASSUME_CACHEABLE; +// Storage +#define CACHE_ZDEFAULT_STORAGE "storage_inmemory" +// Transaction behaviour +#define CACHE_ZDEFAULT_CACHE_IN_TRXS "all_transactions" + typedef enum cache_in_trxs { // Do NOT change the order. Code relies upon NEVER < READ_ONLY < ALL.