You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Start your journey with MariaDB MaxScale. This guide introduces the database
4
+
proxy's architecture, key components, and basic setup steps for first-time
5
+
users.
6
+
---
7
+
8
+
# MariaDB MaxScale Beginner's Guide
2
9
3
10
## Introduction
4
11
5
-
After MaxScale has been installed, test that MaxScale starts by executing
6
-
`sudo systemctl start maxscale`, followed by `sudo systemctl status maxscale`.
12
+
After MaxScale has been installed, test that MaxScale starts by executing `sudo systemctl start maxscale`, followed by `sudo systemctl status maxscale`.
Active: active (running) since Mon 2024-09-23 08:57:14 CEST; 6s ago
12
18
```
13
19
14
-
Stop MaxScale with `sudo systemctl stop maxscale`. The log file is
15
-
written at `/var/log/maxscale/maxscale.log`. If the startup failed, the log
16
-
should explain why. With the default configuration file, MaxScale does not yet
17
-
do anything interesting.
20
+
Stop MaxScale with `sudo systemctl stop maxscale`. The log file is written at `/var/log/maxscale/maxscale.log`. If the startup failed, the log should explain why. With the default configuration file, MaxScale does not yet do anything interesting.
18
21
19
-
A functional configuration of MaxScale should include a listener, a service, a
20
-
monitor and one or more servers. An incoming client connects to a listener
21
-
port. Once the connection is established, the listener passes the client to a
22
-
service. The service then handles all client traffic, from authentication to
23
-
disconnection. Client queries are routed to servers and query results from
24
-
servers back to the client. A monitor regularly checks the status of the
25
-
servers.
22
+
A functional configuration of MaxScale should include a listener, a service, a monitor and one or more servers. An incoming client connects to a listener port. Once the connection is established, the listener passes the client to a service. The service then handles all client traffic, from authentication to disconnection. Client queries are routed to servers and query results from servers back to the client. A monitor regularly checks the status of the servers.
26
23
27
-
24
+
!\[]\(<../.gitbook/assets/service\_example.png)
28
25
29
-
MaxScale configuration files use the common
30
-
[INI](https://en.wikipedia.org/wiki/INI_file) file format. The files contain
31
-
sections and each section can contain multiple key-value pairs. The MaxScale
32
-
installer creates an example configuration file to `/etc/maxscale.cnf`.
26
+
MaxScale configuration files use the common [INI](https://en.wikipedia.org/wiki/INI_file) file format. The files contain sections and each section can contain multiple key-value pairs. The MaxScale installer creates an example configuration file to `/etc/maxscale.cnf`.
33
27
34
28
## Configure a Read-Write Service
35
29
36
-
Let's modify the example configuration file to include a service that routes all
37
-
queries to one server. For this, you will need to have a running MariaDB Server
38
-
accessible in the network. One option is to run a MariaDB Server
39
-
[Docker image](https://hub.docker.com/_/mariadb/). Once the server is running,
40
-
log in to it with an administrative account and create a user account for
41
-
MaxScale itself to use when monitoring the server and fetching user
42
-
accounts. The following example creates user *maxscale* with all privileges.
30
+
Let's modify the example configuration file to include a service that routes all queries to one server. For this, you will need to have a running MariaDB Server accessible in the network. One option is to run a MariaDB Server [Docker image](https://hub.docker.com/_/mariadb/). Once the server is running, log in to it with an administrative account and create a user account for MaxScale itself to use when monitoring the server and fetching user accounts. The following example creates user _maxscale_ with all privileges.
31
+
43
32
```
44
33
CREATE USER 'maxscale' IDENTIFIED BY 'maxscale_passwd';
45
34
GRANT ALL PRIVILEGES ON *.* to 'maxscale';
46
35
```
47
36
48
37
Next, edit `/etc/maxscale.cnf`. Perform the following modifications:
49
38
50
-
1. In the section `[server1]`, set correct *address* and *port*. These should match the running MariaDB Server.
51
-
2. In the section `[MariaDB-Monitor]`, set *user* to `maxscale` and *password* to `maxscale_passwd`
52
-
(or whatever user/password was created earlier).
53
-
3. In the section `[Read-Write-Service]`, set *user* to `maxscale` and *password* to `maxscale_passwd`
54
-
(or whatever user/password was created earlier).
39
+
1. In the section `[server1]`, set correct _address_ and _port_. These should match the running MariaDB Server.
40
+
2. In the section `[MariaDB-Monitor]`, set _user_ to `maxscale` and _password_ to `maxscale_passwd` (or whatever user/password was created earlier).
41
+
3. In the section `[Read-Write-Service]`, set _user_ to `maxscale` and _password_ to `maxscale_passwd` (or whatever user/password was created earlier).
55
42
56
43
The configuration file should now have the following effective contents.
44
+
57
45
```
58
46
[maxscale]
59
47
threads=auto
@@ -84,9 +72,8 @@ user=maxscale
84
72
password=maxscale_passwd
85
73
```
86
74
87
-
Then, start MaxScale. If MaxScale started successfully, run
88
-
`maxctrl list servers` in the terminal. If MaxScale can successfully connect to
89
-
the server, the output should be approximately:
75
+
Then, start MaxScale. If MaxScale started successfully, run `maxctrl list servers` in the terminal. If MaxScale can successfully connect to the server, the output should be approximately:
Next, check the log file at `/var/log/maxscale/maxscale.log`. It should have a
99
-
message like:
85
+
Next, check the log file at `/var/log/maxscale/maxscale.log`. It should have a message like:
86
+
100
87
```
101
88
2024-09-17 17:55:55 notice : Read 16 user@host entries from 'server1' for service 'Read-Write-Service'.
102
89
```
103
90
104
-
If the monitor cannot connect to the server, the *State* is *Down*. In this
105
-
case, check the log for error messages. Similarly, if the service cannot load
106
-
user account information, an error is logged.
91
+
If the monitor cannot connect to the server, the _State_ is _Down_. In this case, check the log for error messages. Similarly, if the service cannot load user account information, an error is logged.
92
+
93
+
If everything is working properly, connect as client to the MaxScale listener port, configured to 4006.
107
94
108
-
If everything is working properly, connect as client to the MaxScale listener
The Read-Write Service configured above only uses one server. To enable read-write splitting, a replication cluster with a primary server and one or more replicas is required. Setting up such a cluster is outside the scope of this document, see [here](../../server/ha-and-performance/standard-replication/setting-up-replication.md) for more information.
119
+
120
+
Once the replicas are set up, add them to the MaxScale configuration file as separate sections: `[server2]`, `[server3]` etc., similar to `[server1]`. Remember to set the addresses and ports. Then, add the server names to the _servers_-settings of the monitor:
139
121
140
-
Once the replicas are set up, add them to the MaxScale configuration file as
141
-
separate sections: `[server2]`, `[server3]` etc., similar to `[server1]`.
142
-
Remember to set the addresses and ports. Then, add the server names to the
143
-
*servers*-settings of the monitor:
144
122
```
145
123
[MariaDB-Monitor]
146
124
type=monitor
@@ -151,10 +129,8 @@ password=maxscale_passwd
151
129
monitor_interval=2s
152
130
```
153
131
154
-
Then, restart MaxScale to take the configuration into use and run
155
-
`maxctrl list servers` once more. If replication is working and MaxScale can
156
-
connect to all the servers, the output should be as below. If this is not the
157
-
case, check the log again for error messages.
132
+
Then, restart MaxScale to take the configuration into use and run `maxctrl list servers` once more. If replication is working and MaxScale can connect to all the servers, the output should be as below. If this is not the case, check the log again for error messages.
Run `maxctrl show servers` to get more detailed information about the servers
170
-
such as connection and query counts, and `maxctrl show monitors` to see
171
-
monitor-related information such as replication status.
172
145
173
-
Connect to the listener port again with
174
-
`mariadb -h127.0.0.1 -P4006 -umaxscale -pmaxscale_passwd` and run the
175
-
query `select @@server_id;` a few times. It should give the
176
-
server id of a replica, alternating if multiple are available. This
177
-
demonstrates that read queries are sent to the replicas. Writes and other
178
-
queries that depend on the primary are sent to the primary only, e.g.
179
-
`select @@last_insert_id,@@server_id;`. Reads inside transactions are also
180
-
ran on the primary to maintain transaction consistency.
146
+
Run `maxctrl show servers` to get more detailed information about the servers such as connection and query counts, and `maxctrl show monitors` to see monitor-related information such as replication status.
147
+
148
+
Connect to the listener port again with `mariadb -h127.0.0.1 -P4006 -umaxscale -pmaxscale_passwd` and run the query `select @@server_id;` a few times. It should give the server id of a replica, alternating if multiple are available. This demonstrates that read queries are sent to the replicas. Writes and other queries that depend on the primary are sent to the primary only, e.g. `select @@last_insert_id,@@server_id;`. Reads inside transactions are also ran on the primary to maintain transaction consistency.
181
149
182
150
## Add a filter
183
151
184
-
Filters are components added to the query processing chain that can act on the
185
-
query. A typical use-case is logging. To add a log filter, add the following to
186
-
the configuration file:
152
+
Filters are components added to the query processing chain that can act on the query. A typical use-case is logging. To add a log filter, add the following to the configuration file:
153
+
187
154
```
188
155
[MyLogFilter]
189
156
type=filter
@@ -194,6 +161,7 @@ flush=true
194
161
```
195
162
196
163
Then, add the filter to the service:
164
+
197
165
```
198
166
[Read-Write-Service]
199
167
type=service
@@ -203,27 +171,13 @@ cluster=MariaDB-Monitor
203
171
user=maxscale
204
172
password=maxscale_passwd
205
173
```
206
-
Again, restart MaxScale to take the configuration into use. MaxScale will now
207
-
log any client queries passing through MaxScale to
208
-
`/var/log/maxscale/query_log.unified`.
174
+
175
+
Again, restart MaxScale to take the configuration into use. MaxScale will now log any client queries passing through MaxScale to `/var/log/maxscale/query_log.unified`.
209
176
210
177
## Test the GUI
211
178
212
-
Add `admin_secure_gui=false` to the `[maxscale]`-section of the configuration
213
-
file and restart MaxScale. This allows access to the GUI without configuring
214
-
SSL certificates. Then, open a web browser and navigate to
215
-
`http://127.0.0.1:8989`. A login screen should open, use username `admin` and
216
-
password `mariadb` to access the GUI. The GUI can show MaxScale and server
217
-
status, show and modify MaxScale configuration, perform SQL queries and much
218
-
more. See [here](../maxscale-management/maxgui/) for more information on the GUI.
179
+
Add `admin_secure_gui=false` to the `[maxscale]`-section of the configuration file and restart MaxScale. This allows access to the GUI without configuring SSL certificates. Then, open a web browser and navigate to `http://127.0.0.1:8989`. A login screen should open, use username `admin` and password `mariadb` to access the GUI. The GUI can show MaxScale and server status, show and modify MaxScale configuration, perform SQL queries and much more. See [here](../maxscale-management/maxgui/) for more information on the GUI.
explains monitor features such as failover and switchover.
183
+
The [Configuration Guide](../maxscale-management/deployment/maxscale-configuration-guide.md) lists all global configuration parameters. The [ReadWriteSplit documentation](../reference/maxscale-routers/maxscale-readwritesplit.md) explains the ReadWriteSplit-router and its features, such as transaction replay and causal reads. The [MariaDB Monitor documentation](../reference/maxscale-monitors/mariadb-monitor.md) explains monitor features such as failover and switchover.
0 commit comments