hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-1940 Turn cache filter non-experimental

Browse Source 
Also change the following defaults:

- "selects": Was "verify_cacheable", is now "assume_cacheable"
- "cached_data": Was "shared", is now "thread_specific"
This commit is contained in:
Johan Wikman
2018-06-27 10:34:00 +03:00
parent 76fb7a695e
commit b0902402b6
4 changed files with 132 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
Documentation/Filters/Cache.md
View File

@ -3,14 +3,22 @@
This filter was introduced in MariaDB MaxScale 2.1. This filter was introduced in MariaDB MaxScale 2.1.
## Overview ## 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 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, SELECTs, so that subsequent identical SELECTs are served directly by MaxScale,
without the queries being routed to any server. without the queries being routed to any server.
By _default_ the cache will be used and populated in the following circumstances: 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 _no_ explicit transaction active, that is, _autocommit_ is used,
* there is an _explicitly_ read-only transaction (that is,`START TRANSACTION * there is an _explicitly_ read-only transaction (that is,`START TRANSACTION
READ ONLY`) active, or 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 The default behaviour can be altered using the configuration parameter
[cache_inside_transactions](#cache_inside_transactions). [cache_inside_transactions](#cache_inside_transactions).
By default, it is *ensured* that the cache is **not** used in the following By default it is assumed that all `SELECT` statements are cacheable, which
circumstances: means that also statements like `SELECT LOCALTIME` are cached. Please check
[selects](#selects) for how to change the default behaviour.
* 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.
## Limitations ## Limitations
@ -229,11 +222,11 @@ allowed values are:
multiple times. multiple times.
``` ```
cached_data=thread_specific cached_data=shared
``` ```
Default is `shared`. See `max_count` and `max_size` what implication changing Default is `thread_specific`. See `max_count` and `max_size` what implication
this setting to `thread_specific` has. changing this setting to `shared` has.
#### `selects` #### `selects`
@ -246,17 +239,33 @@ respect to `SELECT` statements. The allowed values are:
statements are cacheable, but must verify that. 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 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 non-cacheable functions or access any non-cacheable variables - will be
subject to caching. subject to caching.
If `assume_cacheable` is specified, then all `SELECT` statements are If `verify_cacheable` has been specified, the cache will not be used in
assumed to be cacheable and will be parsed *only* if some specific rule the following circumstances:
requires that.
* 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` #### `cache_inside_transactions`
@ -353,6 +362,7 @@ Each entry in the `store` array is an object containing three fields,
``` ```
where, where,
* the _attribute_ can be `database`, `table`, `column` or `query`, * the _attribute_ can be `database`, `table`, `column` or `query`,
* the _op_ can be `=`, `!=`, `like` or `unlike`, and * the _op_ can be `=`, `!=`, `like` or `unlike`, and
* the _value_ a string. * the _value_ a string.
@ -520,6 +530,7 @@ Each entry in the `use` array is an object containing three fields,
``` ```
where, where,
* the _attribute_ can be `user`, * the _attribute_ can be `user`,
* the _op_ can be `=`, `!=`, `like` or `unlike`, and * the _op_ can be `=`, `!=`, `like` or `unlike`, and
* the _value_ a string. * the _value_ a string.
@ -828,7 +839,8 @@ rule like
``` ```
The exact match rule requires all statements to be parsed. 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 | | `selects` | Rule | qps |
| -------------------| ---------------|-----| | -------------------| ---------------|-----|
@ -842,9 +854,9 @@ Note that the qps figures are only indicative.
## Summary ## Summary
For maximum performance: For maximum performance:
* Arrange the situation so that `selects=assume_cacheable` can be
configured, and use _no_ rules. * Arrange the situation so that the default `selects=assume_cacheable`
* If `selects=assume_cacheable` has been configured, use _only_ can be used, and use _no_ rules.
regexp based rules. * If `selects=assume_cacheable` is used, use _only_ regexp based rules.
* If `selects=verify_cacheable` has been configured non-regex based * If `selects=verify_cacheable` has been configured, non-regex based
matching can be used. matching can be used.

44
Documentation/Release-Notes/MaxScale-2.2.11-Release-Notes.md Normal file
View File

@ -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).

31
server/modules/filter/cache/cachefilter.cc vendored
View File

@ -53,8 +53,8 @@ void cache_config_finish(CACHE_CONFIG& config)
config.hard_ttl = 0; config.hard_ttl = 0;
config.soft_ttl = 0; config.soft_ttl = 0;
config.debug = 0; config.debug = 0;
config.thread_model = CACHE_THREAD_MODEL_MT; config.thread_model = CACHE_DEFAULT_THREAD_MODEL;
config.selects = CACHE_SELECTS_VERIFY_CACHEABLE; config.selects = CACHE_DEFAULT_SELECTS;
} }
/** /**
@ -79,6 +79,9 @@ void cache_config_free(CACHE_CONFIG* pConfig)
void cache_config_reset(CACHE_CONFIG& config) void cache_config_reset(CACHE_CONFIG& config)
{ {
memset(&config, 0, sizeof(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 = static MXS_MODULE info =
{ {
MXS_MODULE_API_FILTER, MXS_MODULE_API_FILTER,
MXS_MODULE_IN_DEVELOPMENT, MXS_MODULE_GA,
MXS_FILTER_VERSION, MXS_FILTER_VERSION,
"A caching filter that is capable of caching and returning cached data.", "A caching filter that is capable of caching and returning cached data.",
VERSION_STRING, VERSION_STRING,
@ -177,7 +180,7 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE()
{ {
"storage", "storage",
MXS_MODULE_PARAM_STRING, MXS_MODULE_PARAM_STRING,
CACHE_DEFAULT_STORAGE CACHE_ZDEFAULT_STORAGE
}, },
{ {
"storage_options", "storage_options",
@ -186,32 +189,32 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE()
{ {
"hard_ttl", "hard_ttl",
MXS_MODULE_PARAM_COUNT, MXS_MODULE_PARAM_COUNT,
CACHE_DEFAULT_HARD_TTL CACHE_ZDEFAULT_HARD_TTL
}, },
{ {
"soft_ttl", "soft_ttl",
MXS_MODULE_PARAM_COUNT, MXS_MODULE_PARAM_COUNT,
CACHE_DEFAULT_SOFT_TTL CACHE_ZDEFAULT_SOFT_TTL
}, },
{ {
"max_resultset_rows", "max_resultset_rows",
MXS_MODULE_PARAM_COUNT, MXS_MODULE_PARAM_COUNT,
CACHE_DEFAULT_MAX_RESULTSET_ROWS CACHE_ZDEFAULT_MAX_RESULTSET_ROWS
}, },
{ {
"max_resultset_size", "max_resultset_size",
MXS_MODULE_PARAM_SIZE, MXS_MODULE_PARAM_SIZE,
CACHE_DEFAULT_MAX_RESULTSET_SIZE CACHE_ZDEFAULT_MAX_RESULTSET_SIZE
}, },
{ {
"max_count", "max_count",
MXS_MODULE_PARAM_COUNT, MXS_MODULE_PARAM_COUNT,
CACHE_DEFAULT_MAX_COUNT CACHE_ZDEFAULT_MAX_COUNT
}, },
{ {
"max_size", "max_size",
MXS_MODULE_PARAM_SIZE, MXS_MODULE_PARAM_SIZE,
CACHE_DEFAULT_MAX_SIZE CACHE_ZDEFAULT_MAX_SIZE
}, },
{ {
"rules", "rules",
@ -220,26 +223,26 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE()
{ {
"debug", "debug",
MXS_MODULE_PARAM_COUNT, MXS_MODULE_PARAM_COUNT,
CACHE_DEFAULT_DEBUG CACHE_ZDEFAULT_DEBUG
}, },
{ {
"cached_data", "cached_data",
MXS_MODULE_PARAM_ENUM, MXS_MODULE_PARAM_ENUM,
CACHE_DEFAULT_THREAD_MODEL, CACHE_ZDEFAULT_THREAD_MODEL,
MXS_MODULE_OPT_NONE, MXS_MODULE_OPT_NONE,
parameter_cached_data_values parameter_cached_data_values
}, },
{ {
"selects", "selects",
MXS_MODULE_PARAM_ENUM, MXS_MODULE_PARAM_ENUM,
CACHE_DEFAULT_SELECTS, CACHE_ZDEFAULT_SELECTS,
MXS_MODULE_OPT_NONE, MXS_MODULE_OPT_NONE,
parameter_selects_values parameter_selects_values
}, },
{ {
"cache_in_transactions", "cache_in_transactions",
MXS_MODULE_PARAM_ENUM, MXS_MODULE_PARAM_ENUM,
CACHE_DEFAULT_CACHE_IN_TRXS, CACHE_ZDEFAULT_CACHE_IN_TRXS,
MXS_MODULE_OPT_NONE, MXS_MODULE_OPT_NONE,
parameter_cache_in_trxs_values parameter_cache_in_trxs_values
}, },

48
server/modules/filter/cache/cachefilter.h vendored
View File

@ -38,35 +38,37 @@
#define UINT64_MAX (18446744073709551615UL) #define UINT64_MAX (18446744073709551615UL)
#endif #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 typedef enum cache_selects
{ {
CACHE_SELECTS_ASSUME_CACHEABLE, CACHE_SELECTS_ASSUME_CACHEABLE,
CACHE_SELECTS_VERIFY_CACHEABLE, CACHE_SELECTS_VERIFY_CACHEABLE,
} cache_selects_t; } 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 typedef enum cache_in_trxs
{ {
// Do NOT change the order. Code relies upon NEVER < READ_ONLY < ALL. // Do NOT change the order. Code relies upon NEVER < READ_ONLY < ALL.