From e8dfccb4c8484b3182a78187dabef4c9dbddede1 Mon Sep 17 00:00:00 2001 From: Esa Korhonen Date: Fri, 21 Apr 2017 10:49:20 +0300 Subject: [PATCH] 2.1 doc esak (#127) * Update MySQL-Replication-Read-Write-Splitting-Tutorial.md * Update MySQL-Replication-Read-Write-Splitting-Tutorial.md * Update MySQL-Replication-Read-Write-Splitting-Tutorial.md * Update MySQL-Cluster-Setup.md * Update Administration-Tutorial.md * Update Administration-Tutorial.md * Update Galera-Cluster-Connection-Routing-Tutorial.md * Update CLI.md * Update ReadWriteSplit.md * Update Tee-Filter.md * Update CCRFilter.md * Update RabbitMQ-Filter.md * Update Debug-And-Diagnostic-Support.md * Update MaxBinlogCheck.md * Update Configuration-Guide.md * Update Module-Commands.md --- Documentation/Filters/CCRFilter.md | 2 +- Documentation/Filters/RabbitMQ-Filter.md | 5 +- Documentation/Filters/Tee-Filter.md | 10 +- .../Getting-Started/Configuration-Guide.md | 41 ++++---- .../Reference/Debug-And-Diagnostic-Support.md | 8 +- Documentation/Reference/MaxBinlogCheck.md | 35 +++---- Documentation/Reference/Module-Commands.md | 5 +- Documentation/Routers/CLI.md | 7 +- Documentation/Routers/ReadWriteSplit.md | 26 +++--- .../Tutorials/Administration-Tutorial.md | 64 +++++++------ .../Tutorials/MySQL-Cluster-Setup.md | 93 ++++++++++--------- ...plication-Read-Write-Splitting-Tutorial.md | 35 +++---- 12 files changed, 166 insertions(+), 165 deletions(-) diff --git a/Documentation/Filters/CCRFilter.md b/Documentation/Filters/CCRFilter.md index baad24144..b900ec2f7 100644 --- a/Documentation/Filters/CCRFilter.md +++ b/Documentation/Filters/CCRFilter.md @@ -10,7 +10,7 @@ done through MaxScale while still allowing scaleout of non-critical reads. When the filter detects a statement that would modify the database, it attaches a routing hint to all following statements. This routing hint guides the routing module to route the statement to the master server where data is guaranteed to be -in a up-to-date state. +in an up-to-date state. ## Filter Options diff --git a/Documentation/Filters/RabbitMQ-Filter.md b/Documentation/Filters/RabbitMQ-Filter.md index 35fb285d6..83f5da6a7 100644 --- a/Documentation/Filters/RabbitMQ-Filter.md +++ b/Documentation/Filters/RabbitMQ-Filter.md @@ -1,7 +1,8 @@ -#RabbitMQ Filter +# RabbitMQ Filter ## Overview -This filter is designed to extract queries and transform them into a canonical form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter pushes these canonicalized queries and their replies in to a RabbitMQ broker where they can later be retrieved. The retrieval can be done with your own application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) utility tool, which reads the messages from the broker and sends the contents of those messages as SQL queries to a database. + +This filter is designed to extract queries and transform them into a canonical form e.g. `INSERT INTO database.table VALUES ("John Doe", "Downtown",100,50.0);` turns into `INSERT INTO database.table VALUES ("?", "?",?,?);`. The filter pushes these canonized queries and their replies into a RabbitMQ broker where they can later be retrieved from. The retrieval can be done with a custom application or the [RabbitMQ Consumer Client](RabbitMQ-Consumer-Client.md) utility tool, which reads the messages from the broker and sends the contents of those messages as SQL queries to a database. ## Configuration diff --git a/Documentation/Filters/Tee-Filter.md b/Documentation/Filters/Tee-Filter.md index 29f35c2b6..c0a1e3d47 100644 --- a/Documentation/Filters/Tee-Filter.md +++ b/Documentation/Filters/Tee-Filter.md @@ -2,7 +2,7 @@ ## Overview -The tee filter is a filter module for MariaDB MaxScale is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. It can be used in a filter pipeline of a service to make a copy of requests from the client and dispatch a copy of the request to another service within MariaDB MaxScale. +The tee filter is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. It can be used in a filter pipeline of a service to make copies of requests from the client and send the copies to another service within MariaDB MaxScale. ## Configuration @@ -45,7 +45,7 @@ The tee filter requires a mandatory parameter to define the service to replicate ### Match -An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. Only SQL statements that matches the text passed as the value of this parameter will be sent to the service defined in the filter section. +An optional parameter used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. Only SQL statements that matches the text passed as the value of this parameter will be sent to the service defined in the filter section. ``` match=insert.*into.*order* @@ -55,7 +55,7 @@ All regular expressions are evaluated with the option to ignore the case of the ### Exclude -An optional parameter that can be used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. SQL statements that match the text passed as the value of this parameter will be excluded from the replication stream. +An optional parameter used to limit the queries that will be replicated by the tee filter. The parameter value is a regular expression that is used to match against the SQL text. SQL statements that match the text passed as the value of this parameter will be excluded from the replication stream. ``` exclude=select @@ -83,9 +83,9 @@ user=john ### Example 1 - Replicate all inserts into the orders table -Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not however required. +Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not, however, required. -Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk the datamart server, using the DataMart service. The tee filter would have as it’s service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server. +Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk to the datamart server, using the DataMart service. The tee filter would have as it’s service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server. ``` [Orders] diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index 2f8613dbe..ec3eefd51 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -2,11 +2,11 @@ ## Introduction -The purpose of this document is to describe how to configure MariaDB MaxScale -and to discuss some possible usage scenarios for MariaDB MaxScale. MariaDB +This document describes how to configure MariaDB MaxScale +and presents some possible usage scenarios. MariaDB MaxScale is designed with flexibility in mind, and consists of an event processing core with various support functions and plugin modules that tailor -the behavior of the MariaDB MaxScale itself. +the behavior of the program. # Table of Contents @@ -25,23 +25,22 @@ the behavior of the MariaDB MaxScale itself. * [Authentication](#authentication) * [Error Reporting](#error-reporting) -### Terms +## Glossary - -| Term | Description -------------------- | ------------------ - service | A service represents a set of databases with a specific access mechanism that is offered to clients of MariaDB MaxScale. The access mechanism defines the algorithm that MariaDB MaxScale will use to direct particular requests to the individual databases. - server | A server represents an individual database server to which a client can be connected via MariaDB MaxScale. - router | A router is a module within MariaDB MaxScale that will route client requests to the various database servers which MariaDB MaxScale provides a service interface to. -connection routing | Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established. -statement routing | Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session. - protocol | A protocol is a module of software that is used to communicate with another software entity within the system. MariaDB MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility. - module | A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects. - monitor | A monitor is a module that can be executed within MariaDB MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MariaDB MaxScale. - listener | A listener is the network endpoint that is used to listen for connections to MariaDB MaxScale from the client applications. A listener is associated to a single service, however, a service may have many listeners. -connection failover| When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention - backend database | A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale. - filter | A module that can be placed between the client and the MariaDB MaxScale router module. All client data passes through the filter module and may be examined or modified by the filter modules. Filters may be chained together to form processing pipelines. +Word | Description +--------------------|---------------------------------------------------- +service | A service represents a set of databases with a specific access mechanism that is offered to clients of MariaDB MaxScale. The access mechanism defines the algorithm that MariaDB MaxScale will use to direct particular requests to the individual databases. +server | A server represents an individual database server to which a client can be connected via MariaDB MaxScale. +router | A router is a module within MariaDB MaxScale that will route client requests to the various database servers which MariaDB MaxScale provides a service interface to. +connection routing | Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established. +statement routing | Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session. +protocol | A protocol is a module of software that is used to communicate with another software entity within the system. MariaDB MaxScale supports the dynamic loading of protocol modules to allow for increased flexibility. +module | A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects. +monitor | A monitor is a module that can be executed within MariaDB MaxScale to monitor the state of a set of database. The use of an internal monitor is optional, monitoring may be performed externally to MariaDB MaxScale. +listener | A listener is the network endpoint that is used to listen for connections to MariaDB MaxScale from the client applications. A listener is associated to a single service, however, a service may have many listeners. +connection failover | When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention +backend database | A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale. +filter | A module that can be placed between the client and the MariaDB MaxScale router module. All client data passes through the filter module and may be examined or modified by the filter modules. Filters may be chained together to form processing pipelines. ## Configuration @@ -134,7 +133,7 @@ used for systems dedicated for running MariaDB MaxScale. threads=1 ``` -It should be noted that additional threads will be created to execute other +Additional threads will be created to execute other internal services within MariaDB MaxScale. This setting is used to configure the number of threads that will be used to manage the user connections. @@ -346,7 +345,7 @@ To disable the augmentation use the value 0 and to enable it use the value 1. #### `log_throttling` -In some circumstances it is possible that a particular error (or warning) is +It is possible that a particular error (or warning) is logged over and over again, if the cause for the error persistently remains. To prevent the log from flooding, it is possible to specify how many times a particular error may be logged within a time period, before the logging of that diff --git a/Documentation/Reference/Debug-And-Diagnostic-Support.md b/Documentation/Reference/Debug-And-Diagnostic-Support.md index cec11bd33..a9e1557f4 100644 --- a/Documentation/Reference/Debug-And-Diagnostic-Support.md +++ b/Documentation/Reference/Debug-And-Diagnostic-Support.md @@ -1,10 +1,4 @@ -MariaDB MaxScale - -Debug & Diagnostic Support - -Mark Riddoch - -Last Updated: 24th November 2014 +# MariaDB MaxScale Debug & Diagnostic Support [[TOC]] diff --git a/Documentation/Reference/MaxBinlogCheck.md b/Documentation/Reference/MaxBinlogCheck.md index 9210f379a..3041cd79a 100644 --- a/Documentation/Reference/MaxBinlogCheck.md +++ b/Documentation/Reference/MaxBinlogCheck.md @@ -1,24 +1,16 @@ -# Maxbinlogcheck - -# The MySQL/MariaDB binlog check utility - -Massimiliano Pinto - -Last Updated: 07th December 2016 +# Maxbinlogcheck, the MySQL/MariaDB binlog check utility # Overview -Maxbinlogcheck is a command line utility for checking binlogfiles downloaded by MariaDB MaxScale binlog router or the MySQL/MariaDB binlog files stored in a database server acting as a master in a replication environment. -It checks the binlog file against any corruption and incomplete transaction stored and reports a transaction summary after reading all the events. -It may optionally truncate binlog file. +Maxbinlogcheck is a command line utility for checking binlogfiles. The files may have been downloaded by the MariaDB MaxScale binlog router or they may be MySQL/MariaDB binlog files stored in a database server acting as a master in a replication environment. Maxbinlogcheck checks the binlog files against any corruption and stored incomplete transactions and reports a transaction summary after reading all the events. It may optionally truncate the binlog file. -Maxbinlogcheck supports +Maxbinlogcheck supports: * MariaDB 5.5 and MySQL 5.6 - * MariaDB 10.0 and 10.1 with a command line option # Running maxbinlogcheck + ``` # /usr/local/bin/maxbinlogcheck /path_to_file/bin.000002 ``` @@ -36,27 +28,27 @@ The maxbinlogcheck command accepts a number of switches -f --fix - If the option is set the binlog file will be truncated at last safe transaction pos in case of any error + If set the binlog file will be truncated at last safe transaction pos in case of any error -M --mariadb10 - Check the current binlog against MariaDB 10.0.x events + Checks the current binlog against MariaDB 10.0.x events -d --debug - Set the debug mode. If set the FD Events, Rotate events and opening/closing transactions are displayed. + Sets the debug mode. If set the FD Events, Rotate events and opening/closing transactions are displayed. -? --help - Print usage information regarding maxbinlogcheck + Prints usage information regarding maxbinlogcheck -V --version - Print the maxbinlogcheck version information + Prints the maxbinlogcheck version information -K @@ -71,7 +63,7 @@ The maxbinlogcheck command accepts a number of switches -H --header - Print the binlog event header + Prints the binlog event header @@ -183,7 +175,7 @@ This file is corrupted, as reported by the utility: 2015-09-08 10:03:16 Check retcode: 1, Binlog Pos = 245 ``` -The suggested safe pos is 245 +The suggested safe pos is 245. Use -f option for fix with debug: @@ -281,8 +273,9 @@ And finally big transaction is now done. 2015-09-08 10:17:16 Check retcode: 0, Binlog Pos = 590760698 ``` -**Note** -with current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors +**Note** + +With current maxbinlogcheck it's not possible to fix a binlog with incomplete transaction and no other errors If that is really desired it will be possible with UNIX command line: diff --git a/Documentation/Reference/Module-Commands.md b/Documentation/Reference/Module-Commands.md index 624ad0af8..2fffa4b33 100644 --- a/Documentation/Reference/Module-Commands.md +++ b/Documentation/Reference/Module-Commands.md @@ -53,9 +53,8 @@ int main(int argc, char **argv) } ``` -The array of _modulecmd_arg_type_t_ type is used to tell what kinds of arguments -the command expects. The first argument is a SERVER which will be replaced with a -pointer to a server. The second argument is an optional string argument. +The array _my_args_ of type _modulecmd_arg_type_t_ is used to tell what kinds of arguments +the command expects. The first argument is a boolean and the second argument is an optional string. Arguments are passed to the parsing function as an array of void pointers. They are interpreted as the types the command expects. diff --git a/Documentation/Routers/CLI.md b/Documentation/Routers/CLI.md index 5d088e1fd..706e2b4b7 100644 --- a/Documentation/Routers/CLI.md +++ b/Documentation/Routers/CLI.md @@ -5,7 +5,7 @@ of the `maxscaled` protocol. ## Configuration -Two components are required in order to run the command line interface for use with +Two components are required to run the command line interface for _maxadmin_; a service and a listener. The listener may either use a Unix domain socket or an internet socket. @@ -31,6 +31,7 @@ protocol=maxscaled address=localhost port=6603 ``` + In the example above, two listeners have been specified; one that listens on the default Unix domain socket and one that listens on the default port. In the latter case, if the `address=` entry is removed, connections are allowed from any machine @@ -38,9 +39,9 @@ on your network. In the former case, if the value of `socket` is changed and in the latter case, if the value of `port` is changed, _maxadmin_ must be invoked with the `-S` and -`-P` options respectively. +`-P` options, respectively. -Note that if Unix domain sockets are used, the connection is secure, but _maxadmin_ +If Unix domain sockets are used, the connection is secure, but _maxadmin_ can only be used on the same host where MariaDB MaxScale runs. If internet sockets are used, the connection is _inherently insecure_ but _maxadmin_ can be used from another host than the one where MariaDB MaxScale runs. diff --git a/Documentation/Routers/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 49608eee2..4fe082241 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -1,6 +1,6 @@ # Readwritesplit -This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and examples of the router's use are provided. +This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and use examples are provided. ## Overview @@ -10,7 +10,7 @@ The router is designed to be used with a traditional Master-Slave replication cl ## Configuration -Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section. +Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference in a listener section. For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md). @@ -23,18 +23,16 @@ For more details about the standard service parameters, refer to the [Configurat max_slave_connections= ### `max_slave_replication_lag` -**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than configured value a slave can't be used for routing. + +**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than the configured value a slave can't be used for routing. This feature is disabled by default. max_slave_replication_lag= -This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set. -Please note max_slave_replication_lag must be greater than monitor interval. - -This option only affects Master-Slave clusters. Galera clusters do not have a -concept of slave lag even if the application of write sets might have lag. +This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set. max_slave_replication_lag must be greater than the monitor interval. +This option only affects Master-Slave clusters. Galera clusters do not have a concept of slave lag even if the application of write sets might have lag. ### `use_sql_variables_in` @@ -44,11 +42,11 @@ concept of slave lag even if the application of write sets might have lag. The default is to use SQL variables in all servers. -When value all is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Note, that queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as: +When value `all` is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as: INSERT INTO test.t1 VALUES (@myid:=@myid+1) -In above-mentioned case the user-defined variable would only be updated in the master where query would be routed due to `INSERT` statement. +In above-mentioned case the user-defined variable would only be updated in the master where the query would be routed to due to the `INSERT` statement. **Note:** As of version 2.1 of MaxScale, all of the router options can also be defined as parameters. The values defined in _router_options_ will have priority @@ -74,7 +72,9 @@ Multiple options can be defined as a comma-separated list of parameter-value pai ``` router_options=