From f9eef8f44c3c6fd53fe5419987b64c73534e2eb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Mon, 17 Jun 2019 11:24:41 +0300 Subject: [PATCH 1/3] Fix configuration guide documentation Fixed limitations section, the heading depths and the document name, corrected localhost_match_wildcard_host, added deprecation notes where required. --- Documentation/Getting-Started/Configuration-Guide.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index e8a535eb3..8fb6fac7e 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -1252,6 +1252,8 @@ _5.5.5-MaxScale-Service_ being sent to the client. ### `weightby` **Note:** This parameter has been deprecated in MaxScale 2.3.2. +[A rank mechanism](https://github.com/mariadb-corporation/MaxScale/blob/develop/Documentation/Getting-Started/Configuration-Guide.md#rank) +will be added in MaxScale 2.4 to allow better control over server usage. The weightby parameter is used in conjunction with server parameters in order to control the load balancing applied in the router in use by the service. This @@ -1985,9 +1987,6 @@ password=61DD955512C39A4A8BC4BB1E5F116705 Read the following documents for different methods of altering the MaxScale configuration at runtime. -* MaxAdmin - * [Runtime Configuration Changes](../Reference/MaxAdmin.md#runtime-configuration-changes) - * MaxCtrl * [`create`](../Reference/MaxCtrl.md#create) * [`destroy`](../Reference/MaxCtrl.md#destroy) @@ -1997,6 +1996,9 @@ configuration at runtime. * [REST API](../REST-API/API.md) documentation +* MaxAdmin (deprecated) + * [Runtime Configuration Changes](../Reference/MaxAdmin.md#runtime-configuration-changes) + All changes to the configuration are persisted as individual configuration files in `/var/lib/maxscale/maxscale.cnf.d/`. These files are applied after the main configuration file and all auxiliary configurations have been loaded. This means From 5f3ff7d1be1e58a936020c223abdb22bf01a7c7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Thu, 20 Jun 2019 14:09:23 +0300 Subject: [PATCH 2/3] MXS-2521: Add test case The test case doesn't reproduce the problem due to MDEV-19811 getting in the way but it is likely to reproduce it once that bug has been avoided. --- maxscale-system-test/CMakeLists.txt | 3 + .../maxscale.cnf.template.mxs2521_double_exec | 26 +++++++ maxscale-system-test/mxs2521_double_exec.cpp | 67 +++++++++++++++++++ 3 files changed, 96 insertions(+) create mode 100644 maxscale-system-test/cnf/maxscale.cnf.template.mxs2521_double_exec create mode 100644 maxscale-system-test/mxs2521_double_exec.cpp diff --git a/maxscale-system-test/CMakeLists.txt b/maxscale-system-test/CMakeLists.txt index 0f9667860..a8ded287f 100644 --- a/maxscale-system-test/CMakeLists.txt +++ b/maxscale-system-test/CMakeLists.txt @@ -966,6 +966,9 @@ add_test_executable(mxs2464_sescmd_reconnect.cpp mxs2464_sescmd_reconnect mxs246 # MXS-2563: Failing debug assertion at rwsplitsession.cc:1129 : m_expected_responses == 0 add_test_executable(mxs2563_concurrent_slave_failure.cpp mxs2563_concurrent_slave_failure mxs2563_concurrent_slave_failure LABELS REPL_BACKEND readwritesplit) +# MXS-2521: COM_STMT_EXECUTE maybe return empty result +add_test_executable(mxs2521_double_exec.cpp mxs2521_double_exec mxs2521_double_exec LABELS REPL_BACKEND readwritesplit) + ############################################ # BEGIN: binlogrouter and avrorouter tests # ############################################ diff --git a/maxscale-system-test/cnf/maxscale.cnf.template.mxs2521_double_exec b/maxscale-system-test/cnf/maxscale.cnf.template.mxs2521_double_exec new file mode 100644 index 000000000..bf6901071 --- /dev/null +++ b/maxscale-system-test/cnf/maxscale.cnf.template.mxs2521_double_exec @@ -0,0 +1,26 @@ +[maxscale] +threads=###threads### +log_info=1 + +###server### + +[MariaDB-Monitor] +type=monitor +module=mariadbmon +servers=###server_line### +user=maxskysql +password=skysql +monitor_interval=1000 + +[RW-Split-Router] +type=service +router=readwritesplit +servers=###server_line### +user=maxskysql +password=skysql + +[RW-Split-Listener] +type=listener +service=RW-Split-Router +protocol=MySQLClient +port=4006 diff --git a/maxscale-system-test/mxs2521_double_exec.cpp b/maxscale-system-test/mxs2521_double_exec.cpp new file mode 100644 index 000000000..ad110ecfe --- /dev/null +++ b/maxscale-system-test/mxs2521_double_exec.cpp @@ -0,0 +1,67 @@ +/** + * MXS-2521: COM_STMT_EXECUTE maybe return empty result + * https://jira.mariadb.org/browse/MXS-2521 + */ + +#include "testconnections.h" + +int main(int argc, char** argv) +{ + TestConnections test(argc, argv); + test.maxscales->connect(); + + auto conn = test.maxscales->conn_rwsplit[0]; + + test.try_query(conn, "DROP TABLE IF EXISTS double_execute;"); + test.try_query(conn, "CREATE TABLE double_execute(a int);"); + test.try_query(conn, "INSERT INTO double_execute VALUES (123), (456)"); + + auto stmt = mysql_stmt_init(conn); + std::string sql = "select a, @@server_id from double_execute where a = ?"; + test.expect(mysql_stmt_prepare(stmt, sql.c_str(), sql.length()) == 0, + "Prepare should work: %s", mysql_error(conn)); + + int data[2] = {0, 0}; + MYSQL_BIND my_bind[2] = {}; + char is_null = 0; + my_bind[0].buffer_type = MYSQL_TYPE_LONG; + my_bind[0].buffer = &data[0]; + my_bind[0].buffer_length = sizeof(data[0]); + my_bind[0].is_null = &is_null; + my_bind[1].buffer_type = MYSQL_TYPE_LONG; + my_bind[1].buffer = &data[1]; + my_bind[1].buffer_length = sizeof(data[2]); + my_bind[1].is_null = &is_null; + data[1] = 123; + test.expect(mysql_stmt_bind_param(stmt, my_bind) == 0, "Bind: %s", mysql_stmt_error(stmt)); + + // The first execute is done on the master + test.try_query(conn, "BEGIN"); + + test.expect(mysql_stmt_execute(stmt) == 0, "First execute should work: %s", mysql_stmt_error(stmt)); + data[0] = 0; + + mysql_stmt_store_result(stmt); + test.expect(mysql_stmt_fetch(stmt) == 0, "First fetch of first execute should work"); + test.expect(data[0] == 123, "Query should return one row with value 123: `%d`", data[0]); + test.expect(mysql_stmt_fetch(stmt) != 0, "Second fetch of first execute should NOT work"); + + test.try_query(conn, "COMMIT"); + + // The second execute goes to a slave, no new parameters are sent in it + data[0] = 123; + test.expect(mysql_stmt_execute(stmt) == 0, "Second execute should work: %s", mysql_stmt_error(stmt)); + data[0] = 0; + + mysql_stmt_store_result(stmt); + + test.expect(mysql_stmt_fetch(stmt) == 0, "First fetch of second execute should work"); + test.expect(data[0] == 123, "Query should return one row with value 123: `%d`", data[0]); + test.expect(mysql_stmt_fetch(stmt) != 0, "Second fetch of second execute should NOT work"); + + mysql_stmt_close(stmt); + + test.try_query(conn, "DROP TABLE IF EXISTS double_execute;"); + + return test.global_result; +} From 9d06ff84026b1b60462149e0ac8fc5b72620103a Mon Sep 17 00:00:00 2001 From: Esa Korhonen Date: Tue, 18 Jun 2019 14:05:52 +0300 Subject: [PATCH 3/3] Cleanup basic tutorials Rephrased some of the text. Moved some parts to the general tutorial to avoid repeating it in the two specialized tutorials. --- .../Tutorials/Connection-Routing-Tutorial.md | 177 ++++-------------- Documentation/Tutorials/MaxScale-Tutorial.md | 174 ++++++++++++----- .../Read-Write-Splitting-Tutorial.md | 164 +++------------- 3 files changed, 192 insertions(+), 323 deletions(-) diff --git a/Documentation/Tutorials/Connection-Routing-Tutorial.md b/Documentation/Tutorials/Connection-Routing-Tutorial.md index d91c63d22..90319dbe5 100644 --- a/Documentation/Tutorials/Connection-Routing-Tutorial.md +++ b/Documentation/Tutorials/Connection-Routing-Tutorial.md @@ -1,61 +1,23 @@ # Connection Routing with MariaDB MaxScale -The object of this tutorial is to have a system that has two ports -available, one for write connections and another for read connection that -are load balanced across all servers. +The goal of this tutorial is to configure a system that has two ports available, one for +write connections and another for read connections. The read connections are load- +balanced across slave servers. ## Setting up MariaDB MaxScale -The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). -Please read it and follow the instructions for setting up MariaDB MaxScale with -the type of cluster you want to use. +This tutorial is a part of the [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). +Please read it and follow the instructions. Return here once basic setup is complete. -Once you have MariaDB MaxScale installed and the database users created, we can -create the configuration file for MariaDB MaxScale. +## Configuring services -## Creating Your MariaDB MaxScale Configuration +We want two services and ports to which the client application can connect. One service +routes client connections to the master server, the other load balances between slave +servers. To achieve this, we need to define two services in the configuration file. -MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template -configuration is provided with the MaxScale installation. - -A global `[maxscale]` section is included in every MariaDB MaxScale -configuration file; this is used to set the values of various global parameters, -perhaps the most important of these is the number of threads that MariaDB -MaxScale will use to handle client requests. To automatically configure the -thread count, use the `threads=auto` parameter. - -``` -[maxscale] -threads=auto -``` - -## Configuring Servers - -Read the [Configuring Servers](Configuring-Servers.md) mini-tutorial to see how -the servers are configured. - -## Configuring the Monitor - -The next step is the configuration of the monitor. This depends on the type of -cluster you use with MaxScale. - -For master-slave clusters read the -[Configuring MariaDB Monitor](Configuring-MariaDB-Monitor.md) -tutorial. If you are using a Galera cluster, read the -[Configuring Galera Monitor](Configuring-Galera-Monitor.md) -tutorial instead. - -## Configuring the Service - -We want two different ports to which the client application can connect; one -that will be directed to a server where writes can be sent and another that will -load balance between all servers. To achieve this, we need to define two -services in the configuration file. - -Create the following two sections in your configuration file. The section -names are the names of the services themselves and should be meaningful to -the administrator. For this tutorial, we use the `Write-Service` and -`Read-Service` names for our services. +Create the following two sections in your configuration file. The section names are the +names of the services and should be meaningful. For this tutorial, we use the names +*Write-Service* and *Read-Service*. ``` [Write-Service] @@ -75,32 +37,28 @@ user=maxscale password=maxscale_pw ``` -The router module for these two sections is identical, the `readconnroute` -module. +*router* defines the routing module used. Here we use *readconnroute* for +connection-level routing. -The services must be provided with the list of servers where queries -will be routed to. The server names given here are the names of server sections -in the configuration file (to be defined later) and not the physical hostnames -or addresses of the servers. +A service needs a list of servers to route queries to. The server names must +match the names of server sections in the configuration file and not the hostnames or +addresses of the servers. -In order to instruct the router to which servers it should route we must add the -`router_options` parameter to the service. This parameter tells what sort of -servers the service will use. For the write service we use the _master_ type and -for the read service we use the _slave_ type. +The *router_options*-parameter tells the *readconnroute*-module which servers it should +route a client connection to. For the write service we use the _master_-type and for the +read service the _slave_-type. -The final part of the service configuration is the `user` and `password` -parameters that define the credentials that the service will use to populate the +The *user* and *password* parameters define the credentials the service uses to populate user authentication data. These users were created at the start of the [MaxScale Tutorial](MaxScale-Tutorial.md). -**Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md). +For increased security, see [password encryption](Encrypting-Passwords.md). ## Configuring the Listener -In order to allow network connections to the service, we must associate a network -port with the service. This is done by creating a separate listener section in -the configuration file. A service may have multiple listeners but for this -tutorial we will only need one per service. +To allow network connections to a service, a network ports must be associated with it. +This is done by creating a separate listener section in the configuration file. A service +may have multiple listeners but for this tutorial one per service is enough. ``` [Write-Listener] @@ -116,84 +74,17 @@ protocol=MariaDBClient port=3307 ``` -The `service` parameter tells to which service the listener connects to. For the -`Write-Listener` we set it to `Write-Service` and for the `Read-Listener` we set -it to `Read-Service`. +The *service* parameter tells which service the listener connects to. For the +*Write-Listener* we set it to *Write-Service* and for the *Read-Listener* we set +it to *Read-Service*. -A listener must also define the protocol module it will use for the incoming -network protocol (must be the `MariaDBClient` protocol for all database -listeners) as well as the the network port to listen on. +A listener must define the protocol module it uses. This must be *MariaDBClient* for all +database listeners. *port* defines the the network port to listen on. -Additionally, the `address` parameter may be given if the listener is required -to bind to a particular network interface when the host machine has multiple -network interfaces. The default behavior is to listen on all network interfaces -(the IPv6 address `::`). - -## Configuring the Administrative Interface - -The MaxAdmin configuration is described in the -[Configuring MaxAdmin](Configuring-MaxAdmin.md) document. +The optional *address*-parameter defines the local address the listener should bind to. +This may be required when the host machine has multiple network interfaces. The +default behavior is to listen on all network interfaces (the IPv6 address `::`). ## Starting MariaDB MaxScale -Upon completion of the configuration process MariaDB MaxScale is ready to be -started for the first time. For newer systems that use systemd, use the _systemctl_ command. - -``` -sudo systemctl start maxscale -``` - -For older SysV systems, use the _service_ command. - -``` -sudo service maxscale start -``` - -If MaxScale fails to start, check the error log in -`/var/log/maxscale/maxscale.log` to see if any errors are detected in the -configuration file. The `maxadmin` command may be used to confirm that MariaDB -MaxScale is running and the services, listeners and servers have been correctly -configured. - -``` -% sudo maxadmin list services - -Services. ---------------------------+-------------------+--------+----------------+------------------- -Service Name | Router Module | #Users | Total Sessions | Backend databases ---------------------------+-------------------+--------+----------------+------------------- -Write-Service | readconnroute | 1 | 1 | dbserv1, dbserv2, dbserv3 -Read-Service | readconnroute | 1 | 1 | dbserv1, dbserv2, dbserv3 -CLI | cli | 2 | 3 | ---------------------------+-------------------+--------+----------------+------------------- - -% sudo maxadmin list servers - -Servers. --------------------+-----------------+-------+-------------+-------------------- -Server | Address | Port | Connections | Status --------------------+-----------------+-------+-------------+-------------------- -dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave -dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master -dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave --------------------+-----------------+-------+-------------+-------------------- - -% sudo maxadmin list listeners - -Listeners. ----------------------+---------------------+--------------------+-----------------+-------+-------- -Name | Service Name | Protocol Module | Address | Port | State ----------------------+---------------------+--------------------+-----------------+-------+-------- -Write-Listener | Write-Service | MariaDBClient | * | 3306 | Running -Read-Listener | Read-Service | MariaDBClient | * | 3307 | Running -CLI-Listener | CLI | maxscaled | default | 0 | Running ----------------------+---------------------+--------------------+-----------------+-------+-------- -``` - -MariaDB MaxScale is now ready to start accepting client connections and routing -them to the cluster. More options may be found in the -[Configuration Guide](../Getting-Started/Configuration-Guide.md) -and in the [readconnroute module documentation](../Routers/ReadConnRoute.md). - -More detail on the use of `maxadmin` can be found in the -[MaxAdmin](../Reference/MaxAdmin.md) document. +For the last steps, please return to [MaxScale Tutorial](MaxScale-Tutorial.md). diff --git a/Documentation/Tutorials/MaxScale-Tutorial.md b/Documentation/Tutorials/MaxScale-Tutorial.md index 5bb8b69b2..fb0824b91 100644 --- a/Documentation/Tutorials/MaxScale-Tutorial.md +++ b/Documentation/Tutorials/MaxScale-Tutorial.md @@ -2,31 +2,32 @@ This document is designed as a quick introduction to setting up MariaDB MaxScale. -The installation and configuration of the MariaDB Server will not be covered in -this document. The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/) -article on the MariaDB knowledgebase can help you get started with replication clusters -and the -[Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) -article will help you set up a Galera cluster. +The installation and configuration of the MariaDB Server is not covered in this document. +See the following MariaDB knowledgebase articles for more information on setting up a +master-slave-cluster or a Galera-cluster: +[Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/) + and + [Getting Started With MariaDB Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) +. -This tutorial will assume the user is running from one of the binary distributions -available and has installed this in the default location. -Building from source code in GitHub is covered in the -[Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. +This tutorial assumes that one of the standard MaxScale binary distributions is used and +that MaxScale is installed using default options. + +Building from source code in GitHub is covered in +[Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md). ## Installing MaxScale -The precise installation process will vary from one distribution to another. -Details of what to do with the RPM and DEB packages -[can be found on the MaxScale download page](https://mariadb.com/downloads/mariadb-tx/maxscale) -when you select the distribution you are downloading from. +The precise installation process varies from one distribution to another. Details on +package installation can be found in the +[Installation Guide](../Getting-Started/MariaDB-MaxScale-Installation-Guide.md). -## Creating Database Users +## Creating a user account for MaxScale -After installation, we need to create a database user. We do this as we need to -connect to the backend databases to retrieve the user authentication -information. To create this user, execute the following SQL commands on -the master server of your database cluster. +MaxScale checks that incoming clients are valid. To do this, MaxScale needs to retrieve +user authentication information from the backend databases. Create a special user +account for this purpose by executing the following SQL commands on the master server of +your database cluster. The following tutorials will use these credentials. ``` CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw'; @@ -35,28 +36,21 @@ GRANT SELECT ON mysql.db TO 'maxscale'@'%'; GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%'; GRANT SELECT ON mysql.roles_mapping TO 'maxscale'@'%'; GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%'; - --- MariaDB from 10.2.2 to 10.2.10 requires extra grants -GRANT SELECT ON mysql.* TO 'maxscale'@'%'; ``` -These credentials will be used by the services in MaxScale to populate the user -authentication data. The tutorials that follow will be using these credentials. +MariaDB versions 10.2.2 to 10.2.10 also require `GRANT SELECT ON mysql.* TO +'maxscale'@'%';` -## Creating additional grants for users +## Creating client user accounts -**Note:** The client host and MaxScale host must have the same username and - password for both client and MaxScale hosts. +Because MariaDB MaxScale sits between the clients and the backend databases, the backend +databases will see all clients as if they were connecting from MaxScale's address. This +usually means that two sets of grants for each user are required. -Because MariaDB MaxScale sits between the clients and the backend databases, the -backend databases will see all clients as if they were connecting from MariaDB -MaxScale's address. This usually means that you must create two sets of grants -for each user. - -For example, if you have the `'jdoe'@'client-host'` user and MaxScale is located -at `maxscale-host`, the `'jdoe'@'maxscale-host'` user must be created with the -same password as `'jdoe'@'client-host'` and given the same grants that -`'jdoe'@'client-host'` has. +For example, assume that the user *'jdoe'@'client-host'* exists and MaxScale is located at +*maxscale-host*. If *'jdoe'@'client-host'* needs to be able to connect through MaxScale, +another user, *'jdoe'@'maxscale-host'*, must be created. The second user must have the +same password and similar grants as *'jdoe'@'client-host'*. The quickest way to do this is to first create the new user: @@ -76,23 +70,113 @@ MariaDB [(none)]> SHOW GRANTS FOR 'jdoe'@'client-host'; 1 row in set (0.01 sec) ``` -Followed by copying grant the same grants to the `'jdoe'@'maxscale-host'` user. +Then copy the same grants to the `'jdoe'@'maxscale-host'` user. ``` GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'maxscale-host'; ``` -Another other option is to use a wildcard grant that covers both hosts. This is -more convenient but less secure than having specific grants for both the -client's hostname and MariaDB MaxScale's hostname as it allows access from all -hosts. +An alternative to generating two separate accounts is to use one account with a wildcard +host (*'jdoe'@'%'*) which covers both hosts. This is more convenient but less secure than +having specific user accounts as it allows access from all hosts. ## Creating the configuration file -The next step is to create the configuration file. This part is covered in two -different tutorials. +MaxScale reads its configuration from */etc/maxscale.cnf*. A template configuration is +provided with the MaxScale installation. -For a fully automated read/write splitting setup, read the +A global *maxscale* section is included in every MaxScale configuration file. This section +sets the values of various global parameters, such as the number of threads MaxScale uses +to handle client requests. To set thread count to the number of available cpu cores, set +the following. + +``` +[maxscale] +threads=auto +``` + +## Configuring the servers + +Read the [Configuring Servers](Configuring-Servers.md) mini-tutorial for server +configuration instructions. + +## Configuring the monitor + +The type of monitor used depends on the type of cluster used. For a master-slave cluster +read +[Configuring MariaDB Monitor](Configuring-MariaDB-Monitor.md). +For a Galera cluster read +[Configuring Galera Monitor](Configuring-Galera-Monitor.md). + +## Configuring the services and listeners + +This part is covered in two different tutorials. For a fully automated +read-write-splitting setup, read the [Read Write Splitting Tutorial](Read-Write-Splitting-Tutorial.md). -For a simpler connection based setup, read the +For a simple connection based setup, read the [Connection Routing Tutorial](Connection-Routing-Tutorial.md). + +## Starting MaxScale + +After configuration is complete, MariaDB MaxScale is ready to start. For systems that +use systemd, use the _systemctl_ command. + +``` +sudo systemctl start maxscale +``` + +For older SysV systems, use the _service_ command. + +``` +sudo service maxscale start +``` + +If MaxScale fails to start, check the error log in */var/log/maxscale/maxscale.log* to see +if any errors are detected in the configuration file. + +## Checking MaxScale status with MaxCtrl + +The *maxctrl*-command can be used to confirm that MaxScale is running and the services, +listeners and servers have been correctly configured. The following shows expected output +when using a read-write-splitting configuration. + +``` +% sudo maxctrl list services + +┌──────────────────┬────────────────┬─────────────┬───────────────────┬───────────────────────────┐ +│ Service │ Router │ Connections │ Total Connections │ Servers │ +├──────────────────┼────────────────┼─────────────┼───────────────────┼───────────────────────────┤ +│ Splitter-Service │ readwritesplit │ 1 │ 1 │ dbserv1, dbserv2, dbserv3 │ +└──────────────────┴────────────────┴─────────────┴───────────────────┴───────────────────────────┘ + +% sudo maxctrl list servers + +┌─────────┬─────────────┬──────┬─────────────┬─────────────────┬───────────┐ +│ Server │ Address │ Port │ Connections │ State │ GTID │ +├─────────┼─────────────┼──────┼─────────────┼─────────────────┼───────────┤ +│ dbserv1 │ 192.168.2.1 │ 3306 │ 0 │ Master, Running │ 0-3000-62 │ +├─────────┼─────────────┼──────┼─────────────┼─────────────────┼───────────┤ +│ dbserv2 │ 192.168.2.2 │ 3306 │ 0 │ Slave, Running │ 0-3000-62 │ +├─────────┼─────────────┼──────┼─────────────┼─────────────────┼───────────┤ +│ dbserv3 │ 192.168.2.3 │ 3306 │ 0 │ Slave, Running │ 0-3000-62 │ +└─────────┴─────────────┴──────┴─────────────┴─────────────────┴───────────┘ + +% sudo maxctrl list listeners Splitter-Service + +┌───────────────────┬──────┬──────┬─────────┐ +│ Name │ Port │ Host │ State │ +├───────────────────┼──────┼──────┼─────────┤ +│ Splitter-Listener │ 3306 │ │ Running │ +└───────────────────┴──────┴──────┴─────────┘ +``` + +MariaDB MaxScale is now ready to start accepting client connections and route queries to +the backend cluster. + +More options can be found in the +[Configuration Guide](../Getting-Started/Configuration-Guide.md), +[readwritesplit module documentation](../Routers/ReadWriteSplit.md) and +[readconnroute module documentation](../Routers/ReadConnRoute.md). + +For more information about MaxCtrl and how to secure it, see the +[REST-API Tutorial](REST-API-Tutorial.md). diff --git a/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md b/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md index dd2328e15..442a30442 100644 --- a/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md +++ b/Documentation/Tutorials/Read-Write-Splitting-Tutorial.md @@ -1,58 +1,20 @@ -# Read/Write Splitting with MariaDB MaxScale +# Read-Write Splitting with MariaDB MaxScale -The object of this tutorial is to have a system that appears to the client as a -single database. MariaDB MaxScale will split the statements such that write -statements will be sent to the current master server in the replication cluster -and read statements will be balanced across the rest of the servers. +The goal of this tutorial is to configure a system that appears to the client as a single +database. MariaDB MaxScale will split the statements such that write statements are sent +to the master server and read statements are balanced across the slave servers. ## Setting up MariaDB MaxScale -The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). -Please read it and follow the instructions for setting up MariaDB MaxScale with -the type of cluster you want to use. +This tutorial is a part of [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). +Please read it and follow the instructions. Return here once basic setup is complete. -Once you have MariaDB MaxScale installed and the database users created, we can -create the configuration file for MariaDB MaxScale. +## Configuring the service -## Creating Your MariaDB MaxScale Configuration - -MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template -configuration is provided with the MaxScale installation. - -A global `[maxscale]` section is included in every MariaDB MaxScale -configuration file; this is used to set the values of various global parameters, -perhaps the most important of these is the number of threads that MariaDB -MaxScale will use to handle client requests. To automatically configure the -thread count, use the `threads=auto` parameter. - -``` -[maxscale] -threads=auto -``` - -## Configuring Servers - -Read the [Configuring Servers](Configuring-Servers.md) mini-tutorial to see how -the servers are configured. - -## Configuring the Monitor - -The next step is the configuration of the monitor. This depends on the type of -cluster you use with MaxScale. - -For master-slave clusters read the -[Configuring MariaDB Monitor](Configuring-MariaDB-Monitor.md) -tutorial. If you are using a Galera cluster, read the -[Configuring Galera Monitor](Configuring-Galera-Monitor.md) -tutorial instead. - -## Configuring the Service - -After configuring the servers and the monitor, we create a Read/Write Splitter -service configuration. Create the following section in your configuration -file. The section name is the names of the service and should be meaningful to -the administrator. For this tutorial, we use the `Splitter-Service` name for our -service. +After configuring the servers and the monitor, we create a read-write-splitter service +configuration. Create the following section in your configuration file. The section name +is also the name of the service and should be meaningful. For this tutorial, we use the +name *Splitter-Service*. ``` [Splitter-Service] @@ -62,27 +24,24 @@ servers=dbserv1, dbserv2, dbserv3 user=maxscale password=maxscale_pw ``` +*router* defines the routing module used. Here we use *readwritesplit* for +query-level read-write-splitting. -The router module we use for this service is `readwritesplit`. +A service needs a list of servers where queries will be routed to. The server names must +match the names of server sections in the configuration file and not the hostnames or +addresses of the servers. -The services must be provided with the list of servers where queries -will be routed to. The server names given here are the names of server sections -in the configuration file (to be defined later) and not the physical hostnames -or addresses of the servers. - -The final part of the service configuration is the `user` and `password` -parameters that define the credentials that the service will use to populate the +The *user* and *password* parameters define the credentials the service uses to populate user authentication data. These users were created at the start of the [MaxScale Tutorial](MaxScale-Tutorial.md). -**Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md). +For increased security, see [password encryption](Encrypting-Passwords.md). ## Configuring the Listener -In order to allow network connections to the services, we must associate network -ports with the services. This is done by creating a separate listener section in -the configuration file. A service may have multiple listeners but for this -tutorial we will only need one. +To allow network connections to a service, a network ports must be associated with it. +This is done by creating a separate listener section in the configuration file. A service +may have multiple listeners but for this tutorial one is enough. ``` [Splitter-Listener] @@ -92,81 +51,16 @@ protocol=MariaDBClient port=3306 ``` -The `service` parameter tells to which service the listener connects to. For the -`Splitter-Listener` we set it to `Splitter-Service`. +The *service* parameter tells which service the listener connects to. For the +*Splitter-Listener* we set it to *Splitter-Service*. -A listener must also define the protocol module it will use for the incoming -network protocol (must be the `MariaDBClient` protocol for all database -listeners) as well as the the network port to listen on. +A listener must define the protocol module it uses. This must be *MariaDBClient* for all +database listeners. *port* defines the the network port to listen on. -Additionally, the `address` parameter may be given if the listener is required -to bind to a particular network interface when the host machine has multiple -network interfaces. The default behavior is to listen on all network interfaces -(the IPv6 address `::`). - -## Configuring the Administrative Interface - -The MaxAdmin configuration is described in the -[Configuring MaxAdmin](Configuring-MaxAdmin.md) document. +The optional *address*-parameter defines the local address the listener should bind to. +This may be required when the host machine has multiple network interfaces. The +default behavior is to listen on all network interfaces (the IPv6 address `::`). ## Starting MariaDB MaxScale -Upon completion of the configuration process MariaDB MaxScale is ready to be -started for the first time. For newer systems that use systemd, use the _systemctl_ command. - -``` -sudo systemctl start maxscale -``` - -For older SysV systems, use the _service_ command. - -``` -sudo service maxscale start -``` - -If MaxScale fails to start, check the error log in -`/var/log/maxscale/maxscale.log` to see if any errors are detected in the -configuration file. The `maxadmin` command may be used to confirm that MariaDB -MaxScale is running and the services, listeners and servers have been correctly -configured. - -``` -% sudo maxadmin list services - -Services. ---------------------------+-------------------+--------+----------------+------------------- -Service Name | Router Module | #Users | Total Sessions | Backend databases ---------------------------+-------------------+--------+----------------+------------------- -Splitter-Service | readwritesplit | 1 | 1 | dbserv1, dbserv2, dbserv3 -CLI | cli | 2 | 3 | ---------------------------+-------------------+--------+----------------+------------------- - -% sudo maxadmin list servers - -Servers. --------------------+-----------------+-------+-------------+-------------------- -Server | Address | Port | Connections | Status --------------------+-----------------+-------+-------------+-------------------- -dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave -dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master -dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave --------------------+-----------------+-------+-------------+-------------------- - -% sudo maxadmin list listeners - -Listeners. ----------------------+---------------------+--------------------+-----------------+-------+-------- -Name | Service Name | Protocol Module | Address | Port | State ----------------------+---------------------+--------------------+-----------------+-------+-------- -Splitter-Listener | Splitter-Service | MariaDBClient | * | 3306 | Running -CLI-Listener | CLI | maxscaled | default | 0 | Running ----------------------+---------------------+--------------------+-----------------+-------+-------- -``` - -MariaDB MaxScale is now ready to start accepting client connections and routing -them to the cluster. More options may be found in the -[Configuration Guide](../Getting-Started/Configuration-Guide.md) -and in the [readwritesplit module documentation](../Routers/ReadWriteSplit.md). - -More detail on the use of `maxadmin` can be found in the -[MaxAdmin](../Reference/MaxAdmin.md) document. +For the last steps, please return to [MaxScale Tutorial](MaxScale-Tutorial.md).