Merge lp:~dbpercona/percona-xtradb-cluster/README-wsrep-grammar-and-spelling-head into lp:percona-xtradb-cluster

Proposed by David Bennett on 2015-01-27
Status: Merged
Approved by: Raghavendra D Prabhu on 2015-01-30
Approved revision: 951
Merge reported by: David Bennett
Merged at revision: not available
Proposed branch: lp:~dbpercona/percona-xtradb-cluster/README-wsrep-grammar-and-spelling-head
Merge into: lp:percona-xtradb-cluster
Diff against target: 419 lines (+113/-107)
1 file modified
Docs/README-wsrep (+113/-107)
To merge this branch: bzr merge lp:~dbpercona/percona-xtradb-cluster/README-wsrep-grammar-and-spelling-head
Reviewer Review Type Date Requested Status
Raghavendra D Prabhu 2015-01-27 Pending
Review via email: mp+247734@code.launchpad.net

Description of the change

Fixed various spelling and grammatical errors.

To post a comment you must log in.
952. By David Bennett on 2015-02-01

Fixed type "Only one of the them"

Is this merged into 5.6 trunk? If so, please mark it 'Merged'.

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'Docs/README-wsrep'
2--- Docs/README-wsrep 2013-09-01 09:27:10 +0000
3+++ Docs/README-wsrep 2015-02-01 21:11:10 +0000
4@@ -19,7 +19,7 @@
5
6 Please see file COPYING that came with this distribution
7
8-Source code can be found at
9+The source code can be found at:
10 wsrep API: https://launchpad.net/wsrep
11 MySQL patch: https://launchpad.net/codership-mysql
12
13@@ -29,7 +29,7 @@
14 This document covers installation and configuration issues specific to this
15 wsrep-patched MySQL distribution by Codership. It does not cover the use or
16 administration of MySQL server per se. The reader is assumed to know how to
17-install, configure, administer and use standard MySQL server version 5.1.xx.
18+install, configure, administer and use the standard MySQL server version 5.1.xx.
19
20
21 MYSQL-5.5.x/wsrep-23.x
22@@ -58,9 +58,9 @@
23 1. WHAT IS WSREP PATCH FOR MYSQL/INNODB
24
25 Wsrep API developed by Codership Oy is a modern generic (database-agnostic)
26-replication API for transactional databases with a goal to make database
27+replication API for transactional databases with the goal to make a database
28 replication/logging subsystem completely modular and pluggable. It is developed
29-with flexibility and completeness in mind to satisfy broad range of modern
30+with flexibility and completeness in mind to satisfy a broad range of modern
31 replication scenarios. It is equally suitable for synchronous and asynchronous,
32 master-slave and multi-master replication.
33
34@@ -74,11 +74,11 @@
35
36 2. INSTALLATION
37
38-In the examples below mysql authentication options are omitted for brevity.
39+In the examples below, mysql authentication options are omitted for brevity.
40
41 2.1 Download and install mysql-wsrep package.
42
43-Download binary package for your Linux distribution from
44+Download the binary package for your Linux distribution from
45 https://launchpad.net/codership-mysql/
46
47 2.1.1 On Debian and Debian-derived distributions.
48@@ -142,9 +142,10 @@
49 2.2 Upgrade system tables.
50
51 If you're upgrading a previous MySQL installation, it might be advisable to
52-upgrade system tables. To do that start mysqld and run mysql_upgrade command.
53-Consult MySQL documentation in case of errors. Normally they are not critical
54-and can be ignored unless specific functionality is needed.
55+upgrade the system tables. To do that start mysqld and run the
56+mysql_upgrade command. Consult the MySQL documentation in case of errors.
57+Normally they are not critical and can be ignored unless specific
58+functionality is needed.
59
60
61 3. FIRST TIME SETUP
62@@ -154,8 +155,8 @@
63
64 3.1 CONFIGURATION FILES
65
66-* Make sure system-wide my.cnf does not bind mysqld to 127.0.0.1. That is, if
67- you have the following line in [mysqld] section, comment it out:
68+* Make sure the system-wide my.cnf does not bind mysqld to 127.0.0.1. That is, if
69+ you have the following line in the [mysqld] section, comment it out:
70
71 #bind-address = 127.0.0.1
72
73@@ -164,7 +165,7 @@
74 * Edit /etc/mysql/conf.d/wsrep.cnf and set wsrep_provider option by specifying
75 a path to provider library. If you don't have a provider, leave it as it is.
76
77-* When a new node joins the cluster it'll have to receive a state snapshot from
78+* When a new node joins the cluster it will have to receive a state snapshot from
79 one of the peers. This requires a privileged MySQL account with access from
80 the rest of the cluster. Edit /etc/mysql/conf.d/wsrep.cnf and set mysql
81 login/password pair for SST, for example:
82@@ -176,9 +177,9 @@
83
84 3.2 DATABASE PRIVILEGES
85
86-Restart MySQL server and connect to it as root to grant privileges to SST
87-account (empty users confuse MySQL authentication matching rules, we need to
88-delete them too):
89+Restart the MySQL server and connect to it as the root user to grant
90+privileges to the SST account. Empty users confuse the MySQL authentication
91+matching rules, we need to delete them too:
92
93 $ mysql -e "SET wsrep_on=OFF; DELETE FROM mysql.user WHERE user='';"
94 $ mysql -e "SET wsrep_on=OFF; GRANT ALL ON *.* TO wsrep_sst@'%' IDENTIFIED BY 'wspass'";
95@@ -186,8 +187,8 @@
96 3.3 CHECK AND CORRECT FIREWALL SETTINGS.
97
98 MySQL-wsrep server needs to be accessible from other cluster members through
99-its client listening socket and through wsrep provider socket. See your
100-distribution and wsrep provider documentation for details. For example on
101+it's client listening socket and through the wsrep provider socket. See your
102+distribution and wsrep provider documentation for details. For example, on
103 CentOS you might need to do something along these lines:
104
105 # iptables --insert RH-Firewall-1-INPUT 1 --proto tcp --source <my IP>/24 --destination <my IP>/32 --dport 3306 -j ACCEPT
106@@ -199,7 +200,7 @@
107 3.4 SELINUX
108
109 If you have SELinux enabled, it may block mysqld from doing required operations.
110-You'll need to either disable it or configure to allow mysqld to run external
111+You'll need to either disable it or configure it to allow mysqld to run external
112 programs and open listen sockets at unprivileged ports (i.e. things that
113 an unprivileged user can do). See SELinux documentation about it.
114
115@@ -209,19 +210,19 @@
116
117 3.5 APPARMOR
118
119-AppArmor automatically comes with Ubuntu and may also prevent mysqld to from
120-opening additional ports or run scripts. See AppArmor documentation about its
121-configuration. To disable AppArmor for mysqld:
122+AppArmor automatically comes with Ubuntu and may also prevent mysqld from
123+opening additional ports or run scripts. See AppArmor documentation about
124+it's configuration. To disable AppArmor for mysqld:
125
126 $ cd /etc/apparmor.d/disable/
127 $ sudo ln -s /etc/apparmor.d/usr.sbin.mysqld
128 $ sudo service apparmor restart
129
130
131-3.6 CONNECT TO CLUSTER
132+3.6 CONNECT TO A CLUSTER
133
134-Now you're ready to connect to cluster by setting wsrep_cluster_address variable
135-and monitor status of wsrep provider:
136+Now you're ready to connect to a cluster by setting the wsrep_cluster_address variable
137+and monitoring the status of wsrep provider:
138
139 mysql> SET GLOBAL wsrep_cluster_address='<cluster address string>';
140 mysql> SHOW STATUS LIKE 'wsrep%';
141@@ -259,15 +260,15 @@
142
143 binlog_format=ROW
144 This option is required to use row-level replication as opposed to
145- statement-level. For performance and consistency considerations don't change
146- that. As a side effect, binlog, if turned on, can be ROW only. In future this
147- option won't have special meaning.
148+ statement-level. For performance and consistency considerations, don't change
149+ it. As a side effect, binlog, if turned on, can be ROW only. In the future this
150+ option won't have a special meaning.
151
152 innodb_autoinc_lock_mode=2
153 This is a required parameter. Without it INSERTs into tables with
154 AUTO_INCREMENT column may fail.
155- autoinc lock modes 0 and 1 can cause unresolved deadlock, and make
156- system unresponsive.
157+ autoinc lock modes 0 and 1 can cause unresolved deadlocks, and make
158+ the system unresponsive.
159
160 innodb_locks_unsafe_for_binlog=1
161 This option is required for parallel applying.
162@@ -278,7 +279,7 @@
163 wsrep_sst_auth.
164
165 wsrep_provider=none
166- A full path to the library that implements WSREP interface. If none is
167+ A full path to the library that implements WSREP interface. If not
168 specified, the server behaves like a regular mysqld.
169
170 wsrep_provider_options=
171@@ -299,7 +300,7 @@
172 results (multiple network interfaces, NAT, etc.)
173 If not explicitly overridden by wsrep_sst_receive_address, the <address> part
174 will be used to listen for SST (see below). And the whole <address>[:port]
175- will be passed to wsrep provider to be used as a base address in its
176+ will be passed to the wsrep provider to be used as a base address in it's
177 communications.
178
179 wsrep_node_name=
180@@ -318,15 +319,15 @@
181
182 wsrep_convert_LOCK_to_trx=0
183 Implicitly convert locking sessions into transactions inside mysqld. By
184- itself it does not mean support for locking sessions, but it prevents the
185- database from going into logically inconsistent state. Note however, that
186- loading large database dump with LOCK statements might result in abnormally
187- large transactions and cause an out-of-memory condition
188+ itself it does not enable support for locking sessions, but it prevents the
189+ database from going into a logically inconsistent state. Note however, that
190+ loading a large database dump with LOCK statements might result in abnormally
191+ large transactions and cause an out-of-memory condition.
192
193 wsrep_retry_autocommit=1
194- Retry autocommit queries and single statement transactions should they fail
195+ Retry autocommit queries and single statement transactions if they fail
196 certification test. This is analogous to rescheduling an autocommit query
197- should it go into deadlock with other transactions in the database lock
198+ if it goes into a deadlock with other transactions in the database lock
199 manager.
200
201 wsrep_auto_increment_control=1
202@@ -335,10 +336,10 @@
203 certification conflict rate for INSERTS.
204
205 wsrep_drupal_282555_workaround=1
206- MySQL seems to have an obscure bug when INSERT into table with
207- AUTO_INCREMENT column with NULL value for that column can fail with a
208- duplicate key error. When this option is on, it retries such INSERTs.
209- Required for stable Drupal operation. Documented at:
210+ MySQL seems to have an obscure bug when an INSERT is performed on a table
211+ with an AUTO_INCREMENT column set to NULL. The INSERT can fail with a
212+ duplicate key error. When this option is on, it retries such INSERTs.
213+ This is required for stable Drupal operation. Documented at:
214 http://bugs.mysql.com/bug.php?id=41984
215 http://drupal.org/node/282555
216
217@@ -347,46 +348,50 @@
218 result in additional latencies. It is a session variable.
219
220 wsrep_OSU_method=TOI
221- Online Schema Upgrade (OSU) can be performed with two alternative methods:
222- Total Order Isolation (TOI) runs DDL statement in all cluster nodes in
223- same total order sequence locking the affected table for the duration of the
224- operation. This may result in the whole cluster being blocked for the
225- duration of the operation.
226+ Online Schema Upgrade (OSU) can be performed with two alternative methods:
227+ Total Order Isolation (TOI) runs a DDL statement in all cluster nodes in
228+ the same total order sequence locking the affected table for the duration
229+ of the operation. This may result in the whole cluster being blocked for
230+ the duration of the operation.
231 Rolling Schema Upgrade (RSU) executes the DDL statement only locally, thus
232- blocking only one cluster node. During the DDL processing, the node
233- is not replicating and may be unable to process replication events (due to
234- table lock). Once DDL operation is complete, the node will catch up and sync
235- with the cluster to become fully operational again. The DDL statement or
236- its effects are not replicated, so it is user's responsibility to manually
237- perform this operation on each of the nodes.
238+ blocking only one cluster node. During the DDL processing, the node is not
239+ replicating and may be unable to process replication events due to a table
240+ lock. Once the DDL operation is complete, the node will catch up and sync
241+ with the cluster to become fully operational again. The DDL statement or
242+ it's effects are not replicated, so it is the user's responsibility to
243+ manually perform this operation on each of the nodes.
244
245 wsrep_forced_binlog_format=none
246- Force every transaction to use given binlog format. When this variable is
247- set to something else than NONE, all transactions will use the given forced
248- format, regardless of what the client session has specified in binlog_format.
249- Valid choices for wsrep_forced_binlog_format are: ROW, STATEMENT, MIXED and
250- special value NONE, meaning that there is no forced binlog format in effect.
251- This variable was intruduced to support STATEMENT format replication during
252- rolling schema upgrade processing. However, in most cases ROW replication
253- is valid for asymmetrict schema replication.
254+ Force every transaction to use given binlog format. When this variable is
255+ set to something other than NONE, all transactions will use the given
256+ forced format, regardless of what the client session has specified in
257+ binlog_format. Valid choices for wsrep_forced_binlog_format are: ROW,
258+ STATEMENT, MIXED and the special value NONE, meaning that there is no
259+ forced binlog format in effect. This variable was introduced to support
260+ STATEMENT format replication during rolling schema upgrade processing.
261+ However, in most cases ROW replication is valid for asymmetric schema
262+ replication.
263
264 State snapshot transfer options.
265
266-When a new node joins the cluster it has to synchronize its initial state with
267-the other cluster members by transferring state snapshot from one of them.
268-The options below govern how this happens and should be set up before attempting
269-to join or start a cluster.
270+When a new node joins the cluster it has to synchronize it's initial state
271+with the other cluster members by transferring the state snapshot from one of
272+them. The options below govern how this happens and should be set up before
273+attempting to join or start a cluster.
274
275 wsrep_sst_method=rsync
276 What method to use to copy database state to a newly joined node. Supported
277 methods:
278- - mysqldump: slow (except for small datasets) but most tested.
279- - rsync: much faster on large datasets.
280- - rsync_wan: same as rsync but with deltaxfer to minimize network traffic.
281+ - mysqldump: slow (except for small datasets)
282+ - rsync: much faster on large datasets
283 - xtrabackup: very fast and practically non-blocking SST method based on
284- Percona's xtrabackup tool.
285+ Percona's xtrabackup tool (incompatable with xtrabackup-v2).
286+ - xtrabackup-v2: newer protocol version of xtrabackup method (default)
287+ - custom_script_name: Galera supports Scriptable State Snapshot Transfer.
288+ This enables users to create their own custom script for
289+ performing an SST.
290
291- (for xtrabackup to work the following settings must be present in my.cnf
292+ (for xtrabackup to work, the following settings must be present in my.cnf
293 on all nodes:
294 [mysqld]
295 wsrep_sst_auth=root:<root password>
296@@ -396,72 +401,73 @@
297 )
298
299 wsrep_sst_receive_address=
300- Address (hostname:port) at which this node wants to receive state snapshot.
301- Defaults to mysqld bind address, and if that is not specified (0.0.0.0) -
302- to the first IP of eth0 + mysqld bind port.
303+ Address in the format hostname:port at which this node wants to receive
304+ the state snapshot. Defaults to mysqld bind address, and if that is not
305+ specified (0.0.0.0) - to the first IP of eth0 + mysqld bind port.
306 NOTE: check that your firewall allows connections to this address from other
307 cluster nodes.
308
309 wsrep_sst_auth=
310- Authentication information needed for state transfer. Depends on the state
311- transfer method. For mysqldump-based SST it is
312+ Authentication information needed for state transfer. Thie depends on the
313+ state transfer method. For mysqldump-based SST it is
314 <mysql_root_user>:<mysql_root_password>
315 and should be the same on all nodes - it is used to authenticate with both
316 state snapshot receiver and state snapshot donor.
317
318 wsrep_sst_donor=
319 A name of the node which should serve as state snapshot donor. This allows
320- to control which node will serve state snapshot request. By default the
321- most suitable node is chosen by wsrep provider. This is the same as given in
322- wsrep_node_name.
323+ control over which node will serve state snapshot requests. By default the
324+ most suitable node is chosen by wsrep provider. This should be the same
325+ name specified in the wsrep_node_name option.
326
327
328 6. ONLINE SCHEMA UPGRADE
329
330- Schema upgrades mean any data definition statements (DDL statemnents) run
331+ Schema upgrades mean any data definition statements (DDL statements) run
332 for the database. They change the database structure and are non-
333 transactional.
334
335- Release 22.3 brings a new method for performing schema upgrades. User can
336+ Release 22.3 brings a new method for performing schema upgrades. The user can
337 now choose whether to use the traditional total order isolation or new
338- rolling schema upgrade method. The OSU method choice is done by global
339- parameter: 'wsrep_OSU_method'.
340+ rolling schema upgrade method. The OSU method choice is enabled by
341+ defining the global parameter: 'wsrep_OSU_method'.
342
343 6.1 Total Order Isolation (TOI)
344
345- With earlier releases, DDL processing happened always by Total Order
346- Isolation (TOI) method. With TOI, the DDL was scheduled to be processed in
347- same transaction seqeuncing 'slot' in each cluster node.
348- The processing is secured by locking the affected table from any other use.
349- With TOI method, the whole cluster has part of the database locked for the
350- duration of the DDL processing.
351+ With earlier releases, DDL processing always occured by the Total Order
352+ Isolation (TOI) method. With TOI, the DDL was scheduled to be processed in
353+ same transaction sequencing 'slot' in each cluster node.
354+ The processing is secured by locking the affected table from any other use.
355+ With the TOI method, the whole cluster has part of the database locked for
356+ the duration of the DDL processing.
357
358 6.2 Rolling Schema Upgrade (RSU)
359
360- Rolling schema upgrade is new DDL processing method, where DDL will be
361- processed locally for the node. The node is disconnected of the replication
362+ Rolling schema upgrade is the new DDL processing method, where the DDL will be
363+ processed locally for the node. The node is disconnected from replication
364 for the duration of the DDL processing, so that there is only DDL statement
365 processing in the node and it does not block the rest of the cluster. When
366 the DDL processing is complete, the node applies delayed replication events
367 and synchronizes back with the cluster.
368 The DDL can then be executed cluster-wide by running the same DDL statement
369- for each node in turn. When this rolling schema upgrade proceeds, part of
370- the cluster will have old schema structure and part of the cluster will have
371- new schema structure.
372+ for each node in turn. When this rolling schema upgrade proceeds, part of
373+ the cluster will have the old schema structure and part of the cluster will
374+ have new schema structure.
375
376
377 7. LIMITATIONS
378
379-1) Currently replication works only with InnoDB storage engine. Any writes to
380- tables of other types, including system (mysql.*) tables are not replicated.
381- However, DDL statements are replicated in statement level, and changes
382- to mysql.* tables will get replicated that way.
383- So, you can safely issue: CREATE USER...,
384- but issuing: INSERT INTO mysql.user..., will not be replicated.
385+1) Currently replication works only with the InnoDB storage engine. Any writes
386+ to tables of other types, including system (mysql.*) tables are not
387+ replicated. However, DDL statements are replicated in statement level, and
388+ changes to mysql.* tables will get replicated that way. So, you can safely
389+ issue: CREATE USER..., but issuing: INSERT INTO mysql.user..., will not be
390+ replicated.
391
392-2) DELETE operation is unsupported on tables without primary key. Also rows in
393- tables without primary key may appear in different order on different nodes.
394- As a result SELECT...LIMIT... may return slightly different sets.
395+2) The DELETE operation is unsupported on tables without a primary key. Also
396+ rows in tables without a primary key may appear in a different order on
397+ different nodes. As a result SELECT...LIMIT... may return slightly
398+ different sets.
399
400 3) Unsupported queries:
401 * LOCK/UNLOCK TABLES cannot be supported in multi-master setups.
402@@ -476,12 +482,12 @@
403 5) Maximum allowed transaction size is defined by wsrep_max_ws_rows and
404 wsrep_max_ws_size. Anything bigger (e.g. huge LOAD DATA) will be rejected.
405
406-6) Due to cluster level optimistic concurrency control, transaction issuing
407- COMMIT may still be aborted at that stage. There can be two transactions.
408- writing to same rows and committing in separate cluster nodes, and only one
409- of the them can successfully commit. The failing one will be aborted.
410- For cluster level aborts, MySQL/galera cluster gives back deadlock error.
411- code (Error: 1213 SQLSTATE: 40001 (ER_LOCK_DEADLOCK)).
412+6) Due to cluster level optimistic concurrency control, transactions issuing
413+ COMMIT may still be aborted at that stage. There can be two transactions
414+ writing to same rows and committing in separate cluster nodes. Only one of
415+ them can successfully commit. The failing one will be aborted. For
416+ cluster level aborts, MySQL/galera cluster will return a deadlock error
417+ code. (Error: 1213 SQLSTATE: 40001 (ER_LOCK_DEADLOCK)).
418
419 7) XA transactions can not be supported due to possible rollback on commit.
420

Subscribers

People subscribed via source and target branches

to all changes: