| List: | Internals | « Previous MessageNext Message » | |
| From: | jon | Date: | August 5 2005 4:42pm |
| Subject: | bk commit - mysqldoc@docsrva tree (jon:1.3176) | ||
| View as plain text | |||
Below is the list of changes that have just been committed into a local mysqldoc repository of jon. When jon does a push these changes will be propagated to the main repository and, within 24 hours after the push, to the public repository. For information on how to access the public repository see http://www.mysql.com/doc/I/n/Installing_source_tree.html ChangeSet 1.3176 05/08/06 00:42:05 jon@stripped +4 -0 RefMan-4.1 Administration chapter: remaining edits. Updated Status. Updated removed-sections. refman/mysql-database-administration.xml 1.40 05/08/06 00:42:03 jon@stripped +1 -1 Corrected typo. refman-4.1/removed-sections.txt 1.8 05/08/06 00:42:03 jon@stripped +1 -0 Updating... refman-4.1/mysql-database-administration.xml 1.30 05/08/06 00:42:03 jon@stripped +417 -543 Remaining RefMan-4.1 edits. refman-4.1/Status 1.2 05/08/06 00:42:03 jon@stripped +1 -1 Updating... # This is a BitKeeper patch. What follows are the unified diffs for the # set of deltas contained in the patch. The rest of the patch, the part # that BitKeeper cares about, is below these diffs. # User: jon # Host: gigan. # Root: /home/jon/bk/mysqldoc --- 1.1/refman-4.1/Status 2005-08-04 23:50:27 +10:00 +++ 1.2/refman-4.1/Status 2005-08-06 00:42:03 +10:00 @@ -1,10 +1,10 @@ - 4.1 chapters that have been edited: + mysql-database-administration - 4.1 chapters awaiting major edits: preface introduction tutorial - mysql-database-administration language-structure column-types functions --- 1.7/refman-4.1/removed-sections.txt 2005-08-05 13:19:14 +10:00 +++ 1.8/refman-4.1/removed-sections.txt 2005-08-06 00:42:03 +10:00 @@ -155,3 +155,4 @@ instance-manager-command-line-options instance-manager-configuration-files instance-manager-commands +secure-using-yassl --- 1.29/refman-4.1/mysql-database-administration.xml 2005-08-05 19:39:01 +10:00 +++ 1.30/refman-4.1/mysql-database-administration.xml 2005-08-06 00:42:03 +10:00 @@ -1845,7 +1845,7 @@ <listitem> <para> - <option>--help, -?</option> + <option>--help</option>, <option>-?</option> </para> <para> @@ -2225,7 +2225,7 @@ </para> <para> - (This is not done by default because in many setups it's + (This is not done by default because in many setups it is useful to have a mixture of the above options.) </para> </listitem> @@ -2456,7 +2456,7 @@ <listitem> <para> - <option>--log-warnings, -W</option> + <option>--log-warnings</option>, <option>-W</option> </para> <para> @@ -2674,7 +2674,7 @@ <listitem> <para> - <option>--old-protocol, -o</option> + <option>--old-protocol</option>, <option>-o</option> </para> <para> @@ -3238,7 +3238,7 @@ <listitem> <para> - <option>--version, -V</option> + <option>--version</option>, <option>-V</option> </para> <para> @@ -8503,7 +8503,7 @@ <para> The number of joins that used ranges on the first table. - (It's normally not critical even if this is big.) This + (it is normally not critical even if this is big.) This variable was added in MySQL 3.23.25. </para> </listitem> @@ -12592,7 +12592,7 @@ </para> <!-- NOTE: I changed the instructions to restart the server using -log - because it's not necessary since 3.22.something when the output + because it is not necessary since 3.22.something when the output from USER() started including the hostname. [js] --> <para> @@ -13550,7 +13550,7 @@ <para> PHP programmers migrating their MySQL databases from version 4.0 or lower to version 4.1 or higher should see - <ulink url="Old Client">Old Client</ulink>. + <xref linkend="old-client"/>. </para> </section> @@ -13697,14 +13697,14 @@ <listitem> <para> - MySQL usernames can be up to 16 characters long. Changing - the maximum length is not supported. If you still try to - change it, for example by changing the length of the - <literal>User</literal> column in the - <literal>mysql</literal> database tables, this will likely - result in strange and unpredictable effects. (Altering - privilege tables is not supported, anyway.) Operating system - usernames might have a different maximum length. For + MySQL usernames can be up to 16 characters long. + <emphasis>Changing the maximum length is not + supported</emphasis>. If you try to change it, for example + by changing the length of the <literal>User</literal> column + in the <literal>mysql</literal> database tables, this will + result in unpredictable behavior. (Altering + privilege tables is not supported in any case.) Operating + system usernames might have a different maximum length. For example, Unix usernames typically are limited to eight characters. </para> @@ -13748,7 +13748,7 @@ <para> When you install MySQL, the grant tables are populated with an initial set of accounts. These accounts have names and access - privileges that are described in + privileges that are described in <xref linkend="default-privileges"/>, which also discusses how to assign passwords to them. Thereafter, you normally set up, modify, and remove MySQL accounts using the @@ -13776,7 +13776,7 @@ <para> There must be <emphasis>no space</emphasis> between the - <literal>-p</literal> option and the following password value. + <option>-p</option> option and the following password value. See <xref linkend="connecting"/>. </para> @@ -13909,7 +13909,7 @@ <para> If you have assigned a password to the <literal>root</literal> - account, you'll also need to supply a + account, you also need to supply a <option>--password</option> or <option>-p</option> option for this <command>mysql</command> command and also for those later in this section. @@ -14071,10 +14071,10 @@ <para> Note that to set up a superuser account, it is necessary only to - create a <literal>user</literal> table entry with the privilege - columns set to <literal>'Y'</literal>. <literal>user</literal> - table privileges are global, so no entries in any of the other - grant tables are needed. + create a <literal>user</literal> table entry with all of the + privilege columns set to <literal>'Y'</literal>. + <literal>user</literal> table privileges are global, so no + entries in any of the other grant tables are needed. </para> <para> @@ -14334,11 +14334,6 @@ </para> <para> - From MySQL 5.0.3 on, it is also possible to limit the number of - simultaneous connection to the server on a per-account basis. - </para> - - <para> An account in this context is a single record in the <literal>user</literal> table. Each account is uniquely identified by its <literal>User</literal> and @@ -14371,8 +14366,7 @@ -> IDENTIFIED BY 'frank' -> WITH MAX_QUERIES_PER_HOUR 20 -> MAX_UPDATES_PER_HOUR 10 - -> MAX_CONNECTIONS_PER_HOUR 5 - -> MAX_USER_CONNECTIONS 2; + -> MAX_CONNECTIONS_PER_HOUR 5; </programlisting> <para> @@ -14382,14 +14376,7 @@ integer representing a count per hour. If the <literal>GRANT</literal> statement has no <literal>WITH</literal> clause, the limits are each set to the - default value of zero (that is, no limit). For - <literal>MAX_USER_CONNECTIONS</literal>, the limit is an integer - indicating the maximum number of simultaneous connections the - account can make at any one time. If the limit is set to the - default value of zero, the - <literal>max_user_connections</literal> system variable - determines the number of simultaneous connections for the - account. + default value of zero (that is, no limit). </para> <para> @@ -14435,18 +14422,6 @@ all such cases, an appropriate error message is issued. </para> -<!-- TODO: this is not correct for pre-5.0.3, where counting is per user+actual --> - -<!-- host. --> - - <para> - Resource counting is done per account, not per client. For - example, if your account has a query limit of 50, you cannot - increase your limit to 100 by making two simultaneous client - connections to the server. Queries issued on both connections - are counted together. - </para> - <para> The current per-hour resource-use counts can be reset globally for all accounts, or individually for a given account: @@ -14619,19 +14594,19 @@ mysql> FLUSH PRIVILEGES; </programlisting> -<!-- Unnecessarily complex for the explanation below, but it may be useful --> - -<!-- at some point to include this elsewhere: --> - -<!-- When the user @code{jeffrey} attempts to connect to the server using this --> - -<!-- password, the @command{mysql} client encrypts it with @code{PASSWORD()}, --> - -<!-- generates an authentication vector based on @strong{encrypted} password --> - -<!-- and a random number, obtained from server, and sends the result to --> - -<!-- the server. --> +<!-- + Unnecessarily complex for the explanation below, but it may be + useful at some point to include this elsewhere: + + <para> + When the user <literal>jeffrey</literal> attempts to connect to + the server using this password, the <command>mysql</command> + client encrypts it with <literal>PASSWORD()</literal>, generates + an authentication vector based on the + <emphasis>encrypted</emphasis> password and a random number + obtained from the server, and sends the result to the server. + </para> +--> <para> The result is that the literal value @@ -14665,18 +14640,17 @@ </section> +<!-- + TODO: Perhaps most of this should be in Using MySQL Programs? + Other than the first item, it seems primarily applicable to + running clients, not to administering the server. If it gets + moved, be sure to retarget xrefs that now point here. +--> + <section id="password-security"> <title id='title-password-security'>&title-password-security;</title> -<!-- TODO: Perhaps most of this should be in Using MySQL Programs? Other than --> - -<!-- the first item, it seems primarily applicable to running clients, not --> - -<!-- to administering the server. If it gets moved, be sure to retarget xrefs --> - -<!-- that now point here. --> - <para> On an administrative level, you should never grant access to the <literal>mysql.user</literal> table to any non-administrative @@ -14729,18 +14703,18 @@ <listitem> <para> - Use a <literal>-p</literal> or <option>--password</option> + Use the <option>-p</option> or <option>--password</option> option with no password value specified. In this case, the client program solicits the password from the terminal: </para> <programlisting> shell> mysql -u francis -p <replaceable>db_name</replaceable> -Enter password: ******** +Enter password: <userinput>********</userinput> </programlisting> <para> - The '<literal>*</literal>' characters indicate where you + The '<userinput>*</userinput>' characters indicate where you enter your password. The password is not displayed as you enter it. </para> @@ -14754,7 +14728,7 @@ non-interactively, there is no opportunity to enter the password from the terminal. On some systems, you may even find that the first line of your script is read and - interpreted (incorrectly) as your password! + interpreted (incorrectly) as your password. </para> <indexterm type="type"> @@ -14812,8 +14786,8 @@ </itemizedlist> <para> - All in all, the safest methods are to have the client program - prompt for the password or to specify the password in a properly + In sum, the safest methods are to have the client program prompt + for the password or to specify the password in a properly protected option file. </para> @@ -14826,16 +14800,10 @@ <indexterm type="concept"> <primary>OpenSSL</primary> </indexterm> - <indexterm type="concept"> - <primary>yaSSL</primary> - </indexterm> <indexterm type="concept"> <primary>SSL and X509 Basics</primary> </indexterm> - <indexterm type="concept"> - <primary>yaSSL Basics</primary> - </indexterm> <para> Beginning with version 4.0.0, MySQL has support for secure @@ -14845,24 +14813,6 @@ </para> <para> - Beginning with version 5.0.10, MySQL has built-in yaSSL support. - yaSSL is an SSL Library for programmers building security - functionality into their applications and devices. yaSSL employs - the dual licensing model, like MySQL, so it is available under - GPL and commercial licenses. More information about yaSSL can - be found on <ulink url="http://yassl.com"/>. - </para> - - <para> - Using MySQL's built-in yaSSL support makes it easier to use - secure connections. You do not have to install OpenSSL and - perform the other steps described in - <xref linkend="secure-requirements"/>. Apart from that, most - of the information given in this section applies to OpenSSL as - well as to yaSSL. - </para> - - <para> The standard configuration of MySQL is intended to be as fast as possible, so encrypted connections are not used by default. Doing so would make the client/server protocol much slower. @@ -14884,9 +14834,9 @@ <title id='title-secure-basics'>&title-secure-basics;</title> <para> - To understand how MySQL uses SSL, it's necessary to explain + To understand how MySQL uses SSL, it is necessary to explain some basic SSL and X509 concepts. People who are familiar with - them can skip this part. + these can skip this part of the discussion. </para> <para> @@ -14958,9 +14908,6 @@ To use SSL connections between the MySQL server and client programs, your system must be able to support OpenSSL and your version of MySQL must be 4.0.0 or newer. - If you are using a MySQL version with built-in yaSSL support - (as of version 5.0.10), do not read this section, but rather - <xref linkend="secure-using-yassl"/>. </para> <para> @@ -15024,95 +14971,6 @@ </section> - <section id="secure-using-yassl"> - - <title id='title-secure-using-yassl'>&title-secure-using-yassl;</title> - - <indexterm type="concept"> - <primary>OpenSSL</primary> - </indexterm> - - <para> - Using MySQL's built-in yaSSL support makes it easier to use - secure connections. You do not have to install OpenSSL and - perform the other steps described in - <xref linkend="secure-requirements"/>. Also, both MySQL and - yaSSL employ the same licensing model. - </para> - - <para> - Currently, yaSSL support is available for these platforms: - <itemizedlist> - <listitem><para> - Linux/x86-64 Red Hat Enterprise 3.0 - </para></listitem> - <listitem><para> - Linux RHAS21 Itanium-2 with gcc, statically linked - </para></listitem> - <listitem><para> - Linux Itanium-2 with gcc - </para></listitem> - <listitem><para> - Windows (all builds) - </para></listitem> - </itemizedlist> - </para> - - <para> - If you want to enable yaSSL when building MySQL from source, - you should configure MySQL like this: - <programlisting> -./configure --with-yassl=yes -</programlisting> - </para> - - <para> - To start the MySQL server with yaSSL support, use the same - options as with OpenSSL support and identify the certificates - needed to establish a secure connection: - <programlisting> -shell> <userinput>mysqld --ssl-ca=<replaceable>cacert.pem</replaceable> \ - --ssl-cert=<replaceable>server-cert.pem</replaceable> \ - --ssl-key=<replaceable>server-key.pem</replaceable></userinput> -</programlisting> - <itemizedlist> - <listitem><para> - <option>--ssl-ca</option> identifies the - Certificate Authority certificate. - </para></listitem> - <listitem><para> - <option>--ssl-cert</option> identifies the server - certificate. - </para></listitem> - <listitem><para> - <option>--ssl-key</option> identifies the client - certificate. - </para></listitem> - </itemizedlist> - </para> - - <para> - To establish a secure connection to a MySQL server with yaSSL - support, start a client like this: - <programlisting> -shell> <userinput>mysql --ssl-ca=<replaceable>cacert.pem</replaceable> \ - --ssl-cert=<replaceable>server-cert.pem</replaceable> \ - --ssl-key=<replaceable>server-key.pem</replaceable></userinput> -</programlisting> - In other words, the options are the same as for the server, - and the Certificate Authority certificate has to be the same. - </para> - - <para> - To establish a secure connection from an application program, - use the <literal>mysql_ssl_set()</literal> API function to - set the appropriate certificate options, before calling - <literal>mysql_real_connect()</literal>. - See <xref linkend="mysql-ssl-set"/>. - </para> - - </section> - <section id="secure-create-certs"> <title id='title-secure-create-certs'>&title-secure-create-certs;</title> @@ -15427,7 +15285,10 @@ option is unnecessary. </para> -<!-- TODO: is not preceding sentence also true for X509, SUBJECT, and CIPHER? --> +<!-- + TODO: is not preceding sentence also true for X509, SUBJECT, and + CIPHER? +--> <programlisting> mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' @@ -15644,13 +15505,12 @@ <title id='title-windows-and-ssh'>&title-windows-and-ssh;</title> -<!-- WHEN THE WEB TEAM MOVES MY (MIKE HILLYER) MYSQL AND SSH ARTICLE --> - -<!-- TO DEV.MYSQL.COM WE COULD POINT TO IT INSTEAD --> - -<!-- http://www.vbmysql.com/articles/security/sshtunnel.html --> - -<!-- --> +<!-- + WHEN THE WEB TEAM MOVES MY (MIKE HILLYER) MYSQL AND SSH ARTICLE TO + DEV.MYSQL.COM WE COULD POINT TO IT INSTEAD + + http://www.vbmysql.com/articles/security/sshtunnel.html +--> <indexterm type="concept"> <primary>SSH</primary> @@ -15674,7 +15534,7 @@ <para> Install an SSH client on your Windows machine. As a user, - the best non-free one I've found is from + the best non-free one I have found is from <literal>SecureCRT</literal> from <ulink url="http://www.vandyke.com/"/>. Another option is <literal>f-secure</literal> from @@ -15699,7 +15559,7 @@ Set up port forwarding. Either do a remote forward (Set <literal>local_port: 3306</literal>, <literal>remote_host: yourmysqlservername_or_ip</literal>, <literal>remote_port: - 3306</literal> ) or a local forward (Set <literal>port: + 3306</literal>) or a local forward (Set <literal>port: 3306</literal>, <literal>host: localhost</literal>, <literal>remote port: 3306</literal>). </para> @@ -15707,8 +15567,8 @@ <listitem> <para> - Save everything, otherwise you'll have to redo it the next - time. + Save everything, otherwise you will have to redo it the + next time. </para> </listitem> @@ -15731,14 +15591,15 @@ Create a new file in Windows and link to MySQL using the ODBC driver the same way you normally do, except type in <literal>localhost</literal> for the MySQL host server, - not <literal>yourmysqlservername</literal>. + not + <literal><replaceable>yourmysqlservername</replaceable></literal>. </para> </listitem> </orderedlist> <para> - You should have an ODBC connection to MySQL, encrypted using + You should now have an ODBC connection to MySQL, encrypted using SSH. </para> @@ -15748,14 +15609,15 @@ </section> +<!-- + TODO: a lot of the information here assumes MyISAM implicitly and + will not necessarily work for other storage engines. +--> + <section id="disaster-prevention"> <title id='title-disaster-prevention'>&title-disaster-prevention;</title> -<!-- TODO: a lot of the information here assumes MyISAM implicitly and will not --> - -<!-- necessarily work for other storage engines. --> - <!-- help_category Recovery --> <para> @@ -15815,7 +15677,7 @@ <listitem> <para> - Do a full backup of your database: + Create a full backup of your database: </para> <programlisting> @@ -15852,7 +15714,7 @@ <listitem> <para> - Stop <command>mysqld</command> if it's running, then start + Stop <command>mysqld</command> if it is running, then start it with the <option>--log-bin[=file_name]</option> option. See <xref linkend="binary-log"/>. The binary log files provide you with the information you need to replicate @@ -15864,7 +15726,7 @@ </orderedlist> <para> - For <literal>InnoDB</literal> tables, it's possible to perform + For <literal>InnoDB</literal> tables, it is possible to perform an online backup that takes no locks on tables; see <xref linkend="mysqldump"/> </para> @@ -15945,8 +15807,7 @@ </para> <para> - If you are using the update logs instead (which is a - deprecated feature removed in MySQL 5.0), you can process + If you are using the update logs instead, you can process their contents like this: </para> @@ -15955,7 +15816,7 @@ </programlisting> <para> - <literal>ls</literal> is used to sort the update log + <command>ls</command> is used to sort the update log filenames into the right order. </para> </listitem> @@ -15963,7 +15824,7 @@ </orderedlist> <para> - You can also do selective backups of individual files: + You can also make selective backups of individual files: </para> <itemizedlist> @@ -15979,9 +15840,10 @@ <listitem> <para> To reload the table, use and restore with <literal>LOAD DATA - INFILE 'file_name' REPLACE ...</literal> To avoid duplicate - records, the table must have a <literal>PRIMARY - KEY</literal> or a <literal>UNIQUE</literal> index. The + INFILE '<replaceable>file_name</replaceable>' REPLACE + ...</literal>. To avoid duplicate records, the table must + have a <literal>PRIMARY KEY</literal> or a + <literal>UNIQUE</literal> index. The <literal>REPLACE</literal> keyword causes old records to be replaced with new ones when a new record duplicates an old record on a unique key value. @@ -16093,16 +15955,16 @@ </para> <para> - We'll assume that data is stored into the - <literal>InnoDB</literal> storage engine of MySQL, which has - support for transactions and automatic crash recovery. We'll - always assume that the MySQL server is under load at the time of - crash. If it were not, no recovery would ever be needed. + We assume that data is stored in the <literal>InnoDB</literal> + storage engine, which has support for transactions and automatic + crash recovery. We also assume that the MySQL server is under + load at the time of crash. If it were not, no recovery would + ever be needed. </para> <para> - For the cases of operating system crashes or power failures, we - can assume the MySQL disk data is available after a restart. The + In cases of operating system crashes or power failures, we can + assume the MySQL disk data is available after a restart. The <literal>InnoDB</literal> data files might not contain consistent data due to the crash, but <literal>InnoDB</literal> reads its logs and finds in them the list of pending committed @@ -16143,12 +16005,11 @@ assume that the MySQL disk data is <emphasis>not</emphasis> available after a restart. This means that MySQL fails to start successfully because some blocks of disk data are no longer - readable. In this case, it's necessary to reformat the disk, + readable. In this case, it is necessary to reformat the disk, install a new one, or otherwise correct the underlying problem. - Then it's necessary to recover our MySQL data from backups, + Then it is necessary to recover our MySQL data from backups, which means that we must already have made backups. To make sure - that is the case, let's step back in time and design a backup - policy. + that is the case, we should have a backup policy. </para> <section id="backup-policy"> @@ -16193,19 +16054,19 @@ </para> <para> - The resulting <filename>.sql</filename> file produced by the - <command>mysqldump</command> command contains SQL + The resulting <filename>.sql</filename> file produced by + <command>mysqldump</command> contains SQL <literal>INSERT</literal> statements that can be used to - reload the dumped tables later. + reload the dumped tables at a later time. </para> <para> Full backups are necessary, but they are not always - convenient. They produce large backup files and take time to + convenient. They produce large files and take time to generate. They are not optimal in the sense that each successive full backup includes all data, even that part that - didn't change since the previous full backup. After we have - made the initial full backup, it is more optimal to make + has not changed since the previous full backup. After we have + made the initial full backup, it is preferable to make incremental backups. They are smaller and take less time to produce. (The tradeoff is that at recovery time, you do not restore your data just by reloading the full backup. You must @@ -16219,10 +16080,11 @@ <option>--log-bin</option> option so that it stores these changes in a file while it updates data. This option enables binary logging, so that the server writes each SQL statement - that updates data into a file called a MySQL binary log. Let's - look at the data directory of a MySQL server that was started - with the <option>--log-bin</option> option and that has been - running for some days. We find these MySQL binary log files: + that updates data into a file called a MySQL binary log. + Looking at the data directory of a MySQL server that was + started with the <option>--log-bin</option> option and that + has been running for some days, we find these MySQL binary log + files: </para> <programlisting> @@ -16310,7 +16172,7 @@ creates <filename>gbichot2-bin.000008</filename>. All changes between the Sunday 1 PM full backup and Monday 1 PM are the file <filename>gbichot2-bin.000007</filename>. This - incremental backup is important, so it's a good idea to copy + incremental backup is important, so it is a good idea to copy it to a safe place. (For example, back it up on tape or DVD, or copy it to another machine.) On Tuesday 1 PM, execute another <command>mysqladmin flush-logs</command> command. All @@ -16391,7 +16253,7 @@ device containing the directory is.) If we had done this, we would have the <filename>gbichot2-bin.000009</filename> at hand, and we could apply it to restore the most recent data - changes with no loss how it was at the moment of the crash. + changes with no loss of data up to the moment of the crash. </para> </section> @@ -16473,7 +16335,7 @@ know the path and name of the current binary log file. The path can tyically be found in the options file (that is, <filename>my.cnf</filename> or <filename>my.ini</filename>, - depending on your system). If it's not contained in the options + depending on your system). If it is not contained in the options file, it may be given as an option at the command-line when the server is started. The option for enabling binary logging is <option>--log-bin</option>. To determine the name of the current @@ -16508,10 +16370,11 @@ <option>--stop-date</option> options are available for <command>mysqlbinlog</command> to specify the start and end times in the <literal>DATETIME</literal> format. As an - example, suppose that exactly at 10:00 a.m. today (today being - April 20, 2005) an SQL statement was executed which deleted a - large table. To restore the table and data, you could restore - the previous night's backup, and then enter the following: + example, suppose that exactly at 10:00:00 a.m. today + (<quote>today</quote> being April 20, 2005) an SQL statement + was executed which deleted a large table. To restore the table + and data, you could restore the previous night's backup, and + then enter the following: <programlisting> mysqlbinlog --stop-date="2005-04-20 9:59:59" /var/log/mysql/bin.123456 \ @@ -16583,7 +16446,7 @@ labeled with <literal>log_pos</literal> followed by a number. After restoring the previous backup file, using the position numbers, you would then enter something like the following - from the command-line: + from the command line: <programlisting> mysqlbinlog --stop-position="368312" /var/log/mysql/bin.123456 \ @@ -16637,7 +16500,7 @@ <para> Even though table repair with <command>myisamchk</command> is - quite secure, it's always a good idea to make a backup + quite secure, it is always a good idea to make a backup <emphasis>before</emphasis> doing a repair (or any maintenance operation that could make a lot of changes to a table) </para> @@ -16764,7 +16627,7 @@ </para> <programlisting> -shell> myisamchk /path/to/database_dir/*.MYI +shell> myisamchk <replaceable>/path/to/database_dir/</replaceable>*.MYI </programlisting> <para> @@ -16773,7 +16636,7 @@ </para> <programlisting> -shell> myisamchk /path/to/datadir/*/*.MYI +shell> myisamchk <replaceable>/path/to/datadir/</replaceable>*/*.MYI </programlisting> <para> @@ -16866,7 +16729,7 @@ <listitem> <para> - <option>--help, -?</option> + <option>--help<option>, </option>-?</option> </para> <para> @@ -16876,8 +16739,8 @@ <listitem> <para> - <literal>--debug=<replaceable>debug_options</replaceable>, - -# <replaceable>debug_options</replaceable></literal> + <option>--debug=<replaceable>debug_options</replaceable>, + -# <replaceable>debug_options</replaceable></option> </para> <para> @@ -16889,33 +16752,33 @@ <listitem> <para> - <option>--silent, -s</option> + <option>--silent</option>, <option>-s</option> </para> <para> Silent mode. Write output only when errors occur. You can - use <literal>-s</literal> twice (<literal>-ss</literal>) - to make <command>myisamchk</command> very silent. + use <option>-s</option> twice (<option>-ss</option>) to + make <command>myisamchk</command> very silent. </para> </listitem> <listitem> <para> - <option>--verbose, -v</option> + <option>--verbose</option>, <option>-v</option> </para> <para> Verbose mode. Print more information. This can be used - with <literal>-d</literal> and <literal>-e</literal>. Use - <literal>-v</literal> multiple times - (<literal>-vv</literal>, <literal>-vvv</literal>) for even + with <option>-d</option> and <option>-e</option>. Use + <option>-v</option> multiple times + (<option>-vv</option>, <option>-vvv</option>) for even more output. </para> </listitem> <listitem> <para> - <option>--version, -V</option> + <option>--version</option>, <option>-V</option> </para> <para> @@ -16925,7 +16788,7 @@ <listitem> <para> - <option>--wait, -w</option> + <option>--wait</option>, <option>-w</option> </para> <para> @@ -17206,7 +17069,7 @@ <listitem> <para> - <option>--check, -c</option> + <option>--check</option>, <option>-c</option> </para> <para> @@ -17218,7 +17081,7 @@ <listitem> <para> - <option>--check-only-changed, -C</option> + <option>--check-only-changed</option>, <option>-C</option> </para> <para> @@ -17228,7 +17091,7 @@ <listitem> <para> - <option>--extend-check, -e</option> + <option>--extend-check</option>, <option>-e</option> </para> <para> @@ -17249,7 +17112,7 @@ <listitem> <para> - <option>--fast, -F</option> + <option>--fast</option>, <option>-F</option> </para> <para> @@ -17259,7 +17122,7 @@ <listitem> <para> - <option>--force, -f</option> + <option>--force</option>, <option>-f</option> </para> <para> @@ -17273,7 +17136,7 @@ <listitem> <para> - <option>--information, -i</option> + <option>--information</option>, <option>-i</option> </para> <para> @@ -17284,7 +17147,7 @@ <listitem> <para> - <option>--medium-check, -m</option> + <option>--medium-check</option>, <option>-m</option> </para> <para> @@ -17297,7 +17160,7 @@ <listitem> <para> - <option>--read-only, -T</option> + <option>--read-only</option>, <option>-T</option> </para> <para> @@ -17311,7 +17174,7 @@ <listitem> <para> - <option>--update-state, -U</option> + <option>--update-state</option>, <option>-U</option> </para> <para> @@ -17352,7 +17215,7 @@ <listitem> <para> - <option>--backup, -B</option> + <option>--backup</option>, <option>-B</option> </para> <para> @@ -17390,13 +17253,13 @@ <para> Maximum length of the data file (when re-creating data - file when it's <quote>full</quote>). + file when it is <quote>full</quote>). </para> </listitem> <listitem> <para> - <option>--extend-check, -e</option> + <option>--extend-check</option>, <option>-e</option> </para> <para> @@ -17409,7 +17272,7 @@ <listitem> <para> - <option>--force, -f</option> + <option>--force</option>, <option>-f</option> </para> <para> @@ -17421,8 +17284,8 @@ <listitem> <para> - <literal>--keys-used=<replaceable>#</replaceable>, -k - <replaceable>#</replaceable></literal> + <option>--keys-used=<replaceable>#</replaceable></option>, + <option>-k <replaceable>#</replaceable></option> </para> <para> @@ -17442,7 +17305,7 @@ <listitem> <para> - <option>--no-symlinks, -l</option> + <option>--no-symlinks</option>, <option>-l</option> </para> <para> @@ -17453,24 +17316,26 @@ during repair operations. </para> </listitem> + +<!-- TODO: Is this considered stable yet? [js] --> <listitem> <para> - <option>--parallel-recover, -p</option> + <option>--parallel-recover</option>, <option>-p</option> </para> <para> Uses the same technique as <literal>-r</literal> and <literal>-n</literal>, but creates all the keys in parallel, using different threads. This option was added - in MySQL 4.0.2. <emphasis>This is alpha code. Use at your - own risk!</emphasis> + in MySQL 4.0.2. <emphasis>This is alpha code; use at your + own risk</emphasis>. </para> </listitem> <listitem> <para> - <option>--quick, -q</option> + <option>--quick</option>, <option>-q</option> </para> <para> @@ -17483,7 +17348,7 @@ <listitem> <para> - <option>--recover, -r</option> + <option>--recover</option>, <option>-r</option> </para> <para> @@ -17494,9 +17359,9 @@ If you want to recover a table, this is the option to try first. You should try <literal>-o</literal> only if <command>myisamchk</command> reports that the table cannot - be recovered by <literal>-r</literal>. (In the unlikely - case that <literal>-r</literal> fails, the data file is - still intact.) + be recovered by <option>-r</option>. (In the unlikely + case that <option>-r</option> fails, the data file remains + intact.) </para> <para> @@ -17507,19 +17372,19 @@ <listitem> <para> - <option>--safe-recover, -o</option> + <option>--safe-recover</option>, <option>-o</option> </para> <para> Do a repair using an old recovery method that reads through all rows in order and updates all index trees based on the rows found. This is an order of magnitude - slower than <literal>-r</literal>, but can handle a couple - of very unlikely cases that <literal>-r</literal> cannot. + slower than <option>-r</option>, but can handle a couple + of very unlikely cases that <option>-r</option> cannot. This recovery method also uses much less disk space than - <literal>-r</literal>. Normally, you should repair first - with <literal>-r</literal>, and then with - <literal>-o</literal> only if <literal>-r</literal> fails. + <option>-r</option>. Normally, you should repair first + using <option>-r</option>, and then with + <option>-o</option> only if <option>-r</option> fails. </para> <para> @@ -17536,7 +17401,7 @@ <para> Change the character set used by the table indexes. This option was replaced by <option>--set-collation</option> - in MySQL 4.1.1/5.0.3. + in MySQL 4.1.1. </para> </listitem> @@ -17548,14 +17413,13 @@ <para> Change the collation used to sort table indexes. The character set name is implied by the first part of the - collation name. This option was added in MySQL - 4.1.11/5.0.3. + collation name. This option was added in MySQL 4.1.11. </para> </listitem> <listitem> <para> - <option>--sort-recover, -n</option> + <option>--sort-recover</option>, <option>-n</option> </para> <para> @@ -17567,8 +17431,8 @@ <listitem> <para> - <literal>--tmpdir=<replaceable>path</replaceable>, -t - <replaceable>path</replaceable></literal> + <option>--tmpdir=<replaceable>path</replaceable></option>, + <option>-t <replaceable>path</replaceable></option> </para> <para> @@ -17587,7 +17451,7 @@ <listitem> <para> - <option>--unpack, -u</option> + <option>--unpack</option>, <option>-u</option> </para> <para> @@ -17613,7 +17477,7 @@ <listitem> <para> - <option>--analyze, -a</option> + <option>--analyze</option>, <option>-a</option> </para> <para> @@ -17630,7 +17494,7 @@ <listitem> <para> - <option>--description, -d</option> + <option>--description</option>, <option>-d</option> </para> <para> @@ -17640,8 +17504,8 @@ <listitem> <para> - <literal>--set-auto-increment[=<replaceable>value</replaceable>], - -A[<replaceable>value</replaceable>]</literal> + <option>--set-auto-increment[=<replaceable>value</replaceable>]</option>, + <option>-A[<replaceable>value</replaceable>]</option> </para> <para> @@ -17658,7 +17522,7 @@ <listitem> <para> - <option>--sort-index, -S</option> + <option>--sort-index</option>, <option>-S</option> </para> <para> @@ -17669,8 +17533,8 @@ <listitem> <para> - <literal>--sort-records=<replaceable>#</replaceable>, -R - <replaceable>#</replaceable></literal> + <option>--sort-records=<replaceable>#</replaceable></option>, + <option>-R <replaceable>#</replaceable></option> </para> <para> @@ -17703,7 +17567,7 @@ Memory allocation is important when you run <command>myisamchk</command>. <command>myisamchk</command> uses no more memory than you specify with the - <literal>-O</literal> options. If you are going to use + <option>-O</option> options. If you are going to use <command>myisamchk</command> on very large tables, you should first decide how much memory you want it to use. The default is to use only about 3MB to perform repairs. By using larger @@ -17718,7 +17582,7 @@ </programlisting> <para> - Using <literal>-O sort=16M</literal> should probably be enough + Using <option>-O sort=16M</option> should probably be enough for most cases. </para> @@ -17744,9 +17608,10 @@ Double the size of the data file (the original one and a copy). This space is not needed if you do a repair with <option>--quick</option>; in this case, only the index - file is re-created. This space is needed on the same - filesystem as the original data file! (The copy is created - in the same directory as the original.) + file is re-created. <emphasis>This space must be available + on the same filesystem as the original data + file</emphasis>, as the copy is created in the same + directory as the original. </para> </listitem> @@ -17754,8 +17619,9 @@ <para> Space for the new index file that replaces the old one. The old index file is truncated at the start of the repair - operation, so you usually ignore this space. This space is - needed on the same filesystem as the original index file! + operation, so you usually ignore this space. This space + must be available on the same filesystem as the original + data file. </para> </listitem> @@ -17824,12 +17690,11 @@ </para> <para> - If you are not using - <option>--skip-external-locking</option>, you can use - <command>myisamchk</command> to check tables at any time. - While you do this, all clients that try to update the table - wait until <command>myisamchk</command> is ready before - continuing. + If you are not using <option>--skip-external-locking</option>, + you can use <command>myisamchk</command> to check tables at + any time. While you do this, all clients that try to update + the table wait until <command>myisamchk</command> is ready + before continuing. </para> <para> @@ -17847,14 +17712,14 @@ <para> This section describes how to check for and deal with data - corruption in MySQL databases. If your tables get corrupted + corruption in MySQL databases. If your tables are corrupted frequently you should try to find the reason why. See <xref linkend="crashing"/>. </para> <para> - The <literal>MyISAM</literal> table section contains reason - for why a table could be corrupted. See + The <literal>MyISAM</literal> table section discusses some + reasons why a table could be corrupted. See <xref linkend="myisam-table-problems"/>. </para> @@ -17959,9 +17824,9 @@ corruption that involves <emphasis>only</emphasis> the data file (which is very unusual). If you want to check a table, you should normally run - <command>myisamchk</command> without options or with - either the <literal>-s</literal> or - <option>--silent</option> option. + <command>myisamchk</command> without options or using + the <option>-s</option> or <option>--silent</option> + option. </para> </listitem> @@ -17995,9 +17860,9 @@ indexes. Normally, <command>myisamchk</command> stops after the first error it finds. If you want to obtain more information, you can add the <option>--verbose</option> - (<literal>-v</literal>) option. This causes - <command>myisamchk</command> to keep going, up through a - maximum of 20 errors. + (<option>-v</option>) option. This causes + <command>myisamchk</command> to continue, up to a maximum + of 20 errors. </para> </listitem> @@ -18008,9 +17873,9 @@ </para> <para> - Like the previous command, but the <literal>-i</literal> - option tells <command>myisamchk</command> to print some - informational statistics, too. + Like the previous command, but the <option>-i</option> + option tells <command>myisamchk</command> to print + additional statistical information. </para> </listitem> @@ -18188,7 +18053,7 @@ <para> Run <command>myisamchk *.MYI</command> or <command>myisamchk -e *.MYI</command> if you have more time. Use the - <literal>-s</literal> (silent) option to suppress unnecessary + <option>-s</option> (silent) option to suppress unnecessary information. </para> @@ -18205,8 +18070,8 @@ </para> <para> - If you get weird errors when checking (such as <literal>out of - memory</literal> errors), or if <command>myisamchk</command> + If you get strange errors when checking (such as <literal>out + of memory</literal>), or if <command>myisamchk</command> crashes, go to Stage 3. </para> @@ -18225,8 +18090,8 @@ <para> First, try <command>myisamchk -r -q - <replaceable>tbl_name</replaceable></command> (<literal>-r - -q</literal> means <quote>quick recovery mode</quote>). This + <replaceable>tbl_name</replaceable></command> (<option>-r + -q</option> means <quote>quick recovery mode</quote>). This attempts to repair the index file without touching the data file. If the data file contains everything that it should and the delete links point at the correct locations within the @@ -18247,10 +18112,9 @@ <para> Use <command>myisamchk -r <replaceable>tbl_name</replaceable></command> - (<literal>-r</literal> means <quote>recovery - mode</quote>). This removes incorrect records and deleted - records from the data file and reconstructs the index - file. + (<option>-r</option> means <quote>recovery mode</quote>). + This removes incorrect and deleted records from the data + file and reconstructs the index file. </para> </listitem> @@ -18268,9 +18132,9 @@ </orderedlist> <para> - If you get weird errors when repairing (such as <literal>out - of memory</literal> errors), or if - <command>myisamchk</command> crashes, go to Stage 3. + If you get strange errors when checking (such as <literal>out + of memory</literal>), or if <command>myisamchk</command> + crashes, go to Stage 3. </para> <para> @@ -18280,7 +18144,7 @@ <para> You should reach this stage only if the first 16KB block in the index file is destroyed or contains incorrect information, - or if the index file is missing. In this case, it's necessary + or if the index file is missing. In this case, it is necessary to create a new index file. Do so as follows: </para> @@ -18288,7 +18152,7 @@ <listitem> <para> - Move the data file to some safe place. + Move the data file to a safe place. </para> </listitem> @@ -18419,28 +18283,27 @@ <listitem> <para> - <literal>-S</literal>, <option>--sort-index</option> + <option>-S</option>, <option>--sort-index</option> </para> </listitem> <listitem> <para> - <literal>-R - <replaceable>index_num</replaceable></literal>, + <option>-R <replaceable>index_num</replaceable></option>, <option>--sort-records=<replaceable>index_num</replaceable></option> </para> </listitem> <listitem> <para> - <literal>-a</literal>, <option>--analyze</option> + <option>-a</option>, <option>--analyze</option> </para> </listitem> </itemizedlist> <para> - For a full description of the options, see + For a full description of all available options, see <xref linkend="myisamchk-syntax"/>. </para> @@ -18486,17 +18349,17 @@ </indexterm> <para> - It's also a good idea to check tables when the server starts. + it is also a good idea to check tables when the server starts. For example, whenever the machine has done a restart in the middle of an update, you usually need to check all the tables - that could have been affected. (These are <quote>expected - crashed tables.</quote>) To check <literal>MyISAM</literal> - tables automatically, start the server with the - <option>--myisam-recover</option> option, available as of - MySQL 3.23.25. If your server is too old to support this option, - you could add a test to <command>mysqld_safe</command> that runs - <command>myisamchk</command> to check all tables that have been - modified during the last 24 hours if there is an old + that could have been affected. (These are + <quote>expected</quote> crashed tables.) To check + <literal>MyISAM</literal> tables automatically, start the server + with the <option>--myisam-recover</option> option, available as + of MySQL 3.23.25. If your server is too old to support this + option, you could add a test to <command>mysqld_safe</command> + that runs <command>myisamchk</command> to check all tables that + have been modified during the last 24 hours if there is an old <filename>.pid</filename> (process ID) file left after a restart. (The <filename>.pid</filename> file is created by <command>mysqld</command> when it starts and removed when it @@ -18519,7 +18382,7 @@ </para> <programlisting> -35 0 * * 0 /path/to/myisamchk --fast --silent /path/to/datadir/*/*.MYI + 35 0 * * 0 <replaceable>/path/to/</replaceable>myisamchk --fast --silent <replaceable>/path/to/datadir/</replaceable>*/*.MYI </programlisting> <para> @@ -18528,10 +18391,9 @@ </para> <para> - Because we haven't had any unexpectedly crashed tables (tables + Because we have not had any unexpectedly crashed tables (tables that become corrupted for reasons other than hardware trouble) - for a couple of years (this is really true), once a week is more - than enough for us. + for several years, once a week is more than sufficient for us. </para> <para> @@ -18620,7 +18482,7 @@ </para> <para> - Adding <literal>-v</literal> runs + Adding <option>-v</option> runs <command>myisamchk</command> in verbose mode so that it produces more information about what it is doing. </para> @@ -18645,7 +18507,7 @@ </para> <para> - This is like <literal>-eis</literal>, but tells you what is + This is like <option>-eis</option>, but tells you what is being done. </para> </listitem> @@ -19012,7 +18874,7 @@ </para> <para> - Where in the record this index part starts. + Where in the record this portion of the index starts. </para> </listitem> @@ -19022,11 +18884,11 @@ </para> <para> - How long this index part is. For packed numbers, this - should always be the full length of the column. For - strings, it may be shorter than the full length of the - indexed column, because you can index a prefix of a - string column. + How long this portion of the index is. For packed + numbers, this should always be the full length of the + column. For strings, it may be shorter than the full + length of the indexed column, because you can index a + prefix of a string column. </para> </listitem> @@ -19037,8 +18899,8 @@ <para> Whether a key value can exist multiple times in the - index. Values are <literal>unique</literal> or - <literal>multip.</literal> (multiple). + index. Possible values are <literal>unique</literal> or + <literal>multip</literal>. (multiple). </para> </listitem> @@ -19048,10 +18910,11 @@ </para> <para> - What data type this index part has. This is a - <literal>MyISAM</literal> data type with the options - <literal>packed</literal>, <literal>stripped</literal>, - or <literal>empty</literal>. + What data type this portion of the index has. This is a + <literal>MyISAM</literal> data type with the possible + values <literal>packed</literal>, + <literal>stripped</literal>, or + <literal>empty</literal>. </para> </listitem> @@ -19205,7 +19068,7 @@ Average number of blocks per record (that is, how many links a fragmented record is composed of). This is always 1.0 for fixed-format tables. This value should stay as close to 1.0 - as possible. If it gets too big, you can reorganize the + as possible. If it gets too large, you can reorganize the table. See <xref linkend="optimization"/>. </para> </listitem> @@ -19216,8 +19079,8 @@ </para> <para> - How many blocks (links) are used. For fixed format, this is - the same as the number of records. + How many blocks (links) are used. For fixed-format tables, + this is the same as the number of records. </para> </listitem> @@ -19373,7 +19236,7 @@ <para> When a client connects to a MySQL server, the server indicates to the client what the server's default character set is. The - client switches to use this character set for this connection. + client switches to this character set for this connection. </para> <para> @@ -19528,7 +19391,7 @@ <para> To start <command>mysqld</command> with a particular language for error messages, use the <option>--language</option> or - <literal>-L</literal> option. The option value can be a language + <option>-L</option> option. The option value can be a language name or the full path to the error message file. For example: </para> @@ -19566,7 +19429,7 @@ </programlisting> <para> - If you upgrade to a newer version of MySQL, remember to repeat + When you upgrade to a newer version of MySQL, remember to repeat your changes with the new <filename>errmsg.txt</filename> file. </para> @@ -19587,8 +19450,8 @@ </indexterm> <para> - This section discusses the procedure for adding add another - character set to MySQL. You must have a MySQL source + This section discusses the procedure for adding additional + character sets to MySQL. You must have a MySQL source distribution to use these instructions. </para> @@ -19623,7 +19486,7 @@ </para> <para> - In the following procedures, the name of your character set is + In the following procedures, the name of the character set is represented by <replaceable>MYSET</replaceable>. </para> @@ -19698,7 +19561,7 @@ Add the character set name to the <literal>CHARSETS_AVAILABLE</literal> and <literal>COMPILED_CHARSETS</literal> lists in - <literal>configure.in</literal>. + <filename>configure.in</filename>. </para> </listitem> @@ -19878,7 +19741,7 @@ <literal>to_lower[]</literal>, <literal>to_upper[]</literal>, and <literal>sort_order[]</literal> are indexed by character value, but <literal>ctype[]</literal> is indexed by character - value + 1. This is an old legacy convention to be able to handle + value + 1. This is an old legacy convention for handling <literal>EOF</literal>.) </para> @@ -20162,13 +20025,14 @@ </para> <para> - If your system has its own zoneinfo database (the set of files - describing time zones), you should use the - <command>mysql_tzinfo_to_sql</command> program for filling the - time zone tables. Examples of such systems are Linux, FreeBSD, - Sun Solaris, and Mac OS X. One likely location for these files - is the <filename>/usr/share/zoneinfo</filename> directory. If - your system does not have a zoneinfo database, you can use the + If your system has its own <firstterm>zoneinfo + database</firstterm> (the set of files describing time zones), + you should use the <command>mysql_tzinfo_to_sql</command> + program for filling the time zone tables. Examples of such + systems are Linux, FreeBSD, Sun Solaris, and Mac OS X. One + likely location for these files is the + <filename>/usr/share/zoneinfo</filename> directory. If your + system does not have a zoneinfo database, you can use the downloadable package described later in this section. </para> @@ -20260,7 +20124,7 @@ <para> MySQL has several different log files that can help you find out - what's going on inside <command>mysqld</command>: + what is going on inside <command>mysqld</command>: </para> <informaltable> @@ -20270,34 +20134,40 @@ <tbody> <row> <entry><emphasis role="bold">Log File</emphasis></entry> - <entry><emphasis role="bold">Types of Information Logged to File</emphasis></entry> + <entry><emphasis role="bold">Types of Information Logged to + File</emphasis></entry> </row> <row> <entry>The error log</entry> - <entry>Logs problems encountered starting, running, or stopping - <command>mysqld</command>.</entry> + <entry>Logs problems encountered starting, running, or + stopping <command>mysqld</command>.</entry> </row> <row> <entry>The isam log</entry> - <entry>Logs all changes to the <literal>ISAM</literal> tables. Used only for - debugging the isam code.</entry> + <entry>Logs all changes to the <literal>ISAM</literal> + tables. Used only for debugging the + <literal>ISAM</literal> code.</entry> </row> <row> <entry>The query log</entry> - <entry>Logs established client connections and executed statements.</entry> + <entry>Logs established client connections and executed + statements.</entry> </row> <row> <entry>The update log</entry> - <entry>Logs statements that change data. This log is deprecated.</entry> + <entry>Logs statements that change data. This log is + deprecated.</entry> </row> <row> <entry>The binary log</entry> - <entry>Logs all statements that change data. Also used for replication.</entry> + <entry>Logs all statements that change data. Also used for + replication.</entry> </row> <row> <entry>The slow log</entry> - <entry>Logs all queries that took more than <literal>long_query_time</literal> - seconds to execute or didn't use indexes.</entry> + <entry>Logs all queries that took more than + <literal>long_query_time</literal> seconds to execute or + did not use indexes.</entry> </row> </tbody> </tgroup> @@ -20412,9 +20282,11 @@ <command>mysqld</command>. </para> -<!-- Note: This instance of "safe_mysql" should not be changed to "mysqld_safe" --> - -<!-- because it's a 3.23.x-specific command --> +<!-- + NOTE: This instance of "safe_mysql" should not be changed to + "mysqld_safe" because it is in the context of a 3.23.x-specific + command. +--> <para> Older versions of the <command>mysql.server</command> script @@ -20474,10 +20346,8 @@ <para> <emphasis role="bold">Note</emphasis>: The update log has been - deprecated and replaced by the binary log. See - <xref linkend="binary-log"/>. The binary log can do anything the - old update log could do, and more. <emphasis>The update log is - unavailable as of MySQL 5.0.0</emphasis>. + deprecated and replaced by the more useful, informative, and + efficient binary log. See <xref linkend="binary-log"/>. </para> <para> @@ -20498,16 +20368,17 @@ <para> <emphasis role="bold">Note</emphasis>: For this naming scheme to work, you must not create your own files with the same names as - those that might be used for the log file sequence. + those that might be used in the log file sequence. </para> <para> - Update logging is smart because it logs only statements that - really update data. So, an <literal>UPDATE</literal> or a - <literal>DELETE</literal> with a <literal>WHERE</literal> that - finds no rows is not written to the log. It even skips - <literal>UPDATE</literal> statements that set a column to its - existing value. + Update logging is <quote>smart</quote> in that <emphasis>it logs + only statements that actually update data</emphasis>. Thus, an + <literal>UPDATE</literal> or <literal>DELETE</literal> with a + <literal>WHERE</literal> clause that finds no rows is not + written to the log. Update logging also skips + <literal>UPDATE</literal> statements that merely set a column to + its existing value. </para> <para> @@ -20527,7 +20398,7 @@ </programlisting> <para> - <literal>ls</literal> is used to sort the update log filenames + <command>ls</command> is used to sort the update log filenames into the right order. </para> @@ -20554,9 +20425,10 @@ <para> The binary log has replaced the old update log, which is - unavailable starting from MySQL 5.0. The binary log contains all - information that is available in the update log in a more - efficient format and in a manner that is transactionally safe. + being phased out of future MySQL release series after 4.1. The + binary log contains all information that is available in the + update log in a more efficient format and in a manner that is + transaction-safe. </para> <para> @@ -20693,7 +20565,7 @@ <para> An example of what does not work as you might expect: If the server is started with - <literal>binlog-do-db=sales</literal>, and you do + <literal>binlog-do-db=sales</literal>, and you run <literal>USE prices; UPDATE sales.january SET amount=amount+1000;</literal>, this statement does not get written into the binary log. @@ -20716,7 +20588,7 @@ <para> An example of what does not work as you might expect: If the server is started with - <literal>binlog-ignore-db=sales</literal>, and you do + <literal>binlog-ignore-db=sales</literal>, and you run <literal>USE prices; UPDATE sales.january SET amount=amount+1000;</literal>, this statement is not written into the binary log. @@ -20724,10 +20596,11 @@ <para> Similar to the case for <option>--binlog-do-db</option>, - there is an exception to the <literal>CREATE/ALTER/DROP - DATABASE</literal> statements, which use the database - manipulated to decide if it should log the statement rather - than the current database. + there is an exception to the + <literal>CREATE</literal>/<literal>ALTER</literal>/<literal>DROP</literal> + <literal>DATABASE</literal> statements, which use the + database manipulated to decide if it should log the + statement rather than the current database. </para> </listitem> @@ -20741,10 +20614,11 @@ <para> The rules for logging or ignoring updates to the binary log are evaluated according to the following rules. Observe that there - is an exception for <literal>CREATE/ALTER/DROP - DATABASE</literal> statements. In those cases, the database - being <emphasis>created/altered/dropped</emphasis> replace the - current database in the rules below. + is an exception for + <literal>CREATE</literal>/<literal>ALTER</literal>/<literal>DROP</literal> + <literal>DATABASE</literal> statements. In those cases, the + database being <emphasis>created, altered, or dropped</emphasis> + replaces the current database in the rules below. </para> <orderedlist> @@ -20928,7 +20802,7 @@ or <literal>INSERT</literal>) that change tables are cached until a <literal>COMMIT</literal> statement is received by the server. At that point, <command>mysqld</command> writes the - whole transaction to the binary log before the + entire transaction to the binary log before the <literal>COMMIT</literal> is executed. When the thread that handles the transaction starts, it allocates a buffer of <literal>binlog_cache_size</literal> to buffer queries. If a @@ -20964,31 +20838,31 @@ </para> <para> - The binary log format is different in versions 3.23, 4.0, and - 5.0.0. Those format changes were required to implement - enhancements to replication. MySQL 4.1 has the same binary log - format as 4.0. See <xref linkend="replication-compatibility"/>. + The binary log format differs between versions 3.23 and 4.0. + (These format changes were required to implement enhancements to + replication.) However, MySQL 4.1 has the same binary log format + as 4.0. See <xref linkend="replication-compatibility"/>. </para> <para> By default, the binary log is not synchronized to disk at each - write. So if the operating system or machine (not only the MySQL - server) crashes, there is a chance that the last statements of - the binary log are lost. To prevent this, you can make the - binary log be synchronized to disk after every - <replaceable>N</replaceable>th binary log write, with the - <literal>sync_binlog</literal> global variable (1 being the - safest value, but also the slowest). See - <xref linkend="server-system-variables"/>. Even with - <literal>sync_binlog</literal> set to 1, there is still the - chance of an inconsistency between the tables content and the - binary log content in case of crash. For example, if using - <literal>InnoDB</literal> tables, and the MySQL server processes + write. So if the operating system or machine (and not only the + MySQL server) crashes, there is a chance that the last + statements in the binary log are lost. To prevent this, you can + force the binary log to be synchronized to disk after every + <replaceable>N</replaceable>th binary log write using the + <literal>sync_binlog</literal> global variable + (<literal>1</literal> being the safest value, but also the + slowest). See <xref linkend="server-system-variables"/>. Even + with <literal>sync_binlog</literal> set to 1, there is still the + chance of an inconsistency between tables content and binary log + content in the event of a crash. For example, when using + <literal>InnoDB</literal> tables, if the MySQL server processes a <literal>COMMIT</literal> statement, it writes the whole transaction to the binary log and then commits this transaction - into <literal>InnoDB</literal>. If it crashes between those two - operations, at restart the transaction is rolled back by - <literal>InnoDB</literal> but still exists in the binary log. + into <literal>InnoDB</literal>. If the server crashes between + those two operations, on restart the transaction is rolled back + by <literal>InnoDB</literal> but still exists in the binary log. This problem can be solved with the <option>--innodb-safe-binlog</option> option (available starting from MySQL 4.1.3), which adds consistency between the @@ -20996,17 +20870,17 @@ </para> <para> - For this option to really bring safety to you, the MySQL server - should also be configured to synchronize to disk, at every + For this option to provide real safety, the MySQL server should + also be configured to synchronize to disk, with every transaction, the binary log (<literal>sync_binlog=1</literal>) and (which is true by default) the <literal>InnoDB</literal> - logs. The effect of this option is that at restart after a - crash, after doing a rollback of transactions, the MySQL server - cuts rolled back <literal>InnoDB</literal> transactions from the + logs. The effect of this option is that, when restarting after a + crash and rolling back transactions, the MySQL server cuts + rolled back <literal>InnoDB</literal> transactions from the binary log. This ensures that the binary log reflects the exact - data of <literal>InnoDB</literal> tables, and so, that the slave - remains in sync with the master (not receiving a statement which - has been rolled back). + state of <literal>InnoDB</literal> tables, and thus, that the + slave remains in sync with the master (and does not receive any + statements which have been rolled back). </para> <para> @@ -21014,17 +20888,18 @@ even if the MySQL server updates other storage engines than <literal>InnoDB</literal>. Only statements/transactions affecting <literal>InnoDB</literal> tables are subject to being - removed from the binary log at <literal>InnoDB</literal>'s crash - recovery. If at crash recovery the MySQL server discovers that - the binary log is shorter than it should have been (that is, it - lacks at least one successfully committed - <literal>InnoDB</literal> transaction), which should not happen - if <literal>sync_binlog=1</literal> and the disk/filesystem do - an actual sync when they are requested to (some do not), it - prints an error message ("The binary log <name> is shorter - than its expected size"). In this case, this binary log is not - correct, replication should be restarted from a fresh master's - data snapshot. + removed from the binary log during <literal>InnoDB</literal> + crash recovery. If the MySQL server discovers that the binary + log is shorter than it should have been (that is, it lacks at + least one successfully committed <literal>InnoDB</literal> + transaction), which should not happen if + <literal>sync_binlog=1</literal> and the disk and filesystem + actually synchronise when requested (some do not), the server + prints the error message <literal>The binary log + <<replaceable>name</replaceable>> is shorter than its + expected size</literal>. In this case, this binary log is not + correct, and replication should be restarted using a fresh data + snapshot from the master. </para> <para> @@ -21104,8 +20979,7 @@ to the slow query log. This logging was disabled in MySQL 4.1 until 4.1.13, when the <option>--log-slow-admin-statements</option> server option was - added to enable you to request logging of slow administrative - statements. + added to specify logging of slow administrative statements. </para> <para> @@ -21154,7 +21028,7 @@ <literal>mysql-log-rotate</literal> script for this. If you installed MySQL from an RPM distribution, the script should have been installed automatically. You should be careful with this - script if you are using the binary log for replication! (You + script if you are using the binary log for replication. (You should not remove binary logs until you are certain that their contents have been processed by all slaves.) </para> @@ -21199,7 +21073,7 @@ </itemizedlist> <para> - If you are using only an update log, you only have to rename the + If you are using only an update log, you have only to rename the log file and then flush the logs before making a backup. For example, you can do something like this: </para> @@ -21288,7 +21162,7 @@ <para> <option>--socket</option> controls the Unix socket file path on Unix and the name of the named pipe on Windows. On Windows, - it's necessary to specify distinct pipe names only for those + it is necessary to specify distinct pipe names only for those servers that support named pipe connections. </para> </listitem> @@ -21301,7 +21175,7 @@ <para> This option currently is used only on Windows. It designates the shared memory name used by a Windows server to allow - clients to connect via shared memory. This option is new in + clients to connect via shared memory. This option was added in MySQL 4.1. </para> </listitem> @@ -21372,7 +21246,7 @@ </para> <para> - If you want more performance, you can also specify the following + If you want better performance, you can also specify the following options differently for each server, to spread the load between several physical disks: </para> @@ -21406,10 +21280,10 @@ </para> <para> - <emphasis role="bold">Warning:</emphasis> Normally you should - never have two servers that update data in the same databases! + <emphasis role="bold">Warning</emphasis>: Normally you should + never have two servers that update data in the same databases. This may lead to unpleasant surprises if your operating system - does not support fault-free system locking! If (despite this + does not support fault-free system locking. If (despite this warning) you run multiple servers using the same data directory and they have logging enabled, you must use the appropriate options to specify log filenames that are unique to each server. @@ -21422,26 +21296,26 @@ <para> The warning against sharing a data directory among servers also applies in an NFS environment. Allowing multiple MySQL servers to - access a common data directory over NFS is a <emphasis>bad - idea</emphasis>! + access a common data directory over NFS is a <emphasis>very bad + idea</emphasis>. </para> <itemizedlist> <listitem> <para> - The primary problem is that NFS is the speed bottleneck. It is + The main problem is that NFS is the speed bottleneck. It is not meant for such use. </para> </listitem> <listitem> <para> - Another risk with NFS is that you has to come up with a way to - make sure that two or more servers do not interfere with each - other. Usually NFS file locking is handled by the - <literal>lockd</literal> daemon, but at the moment there is no - platform that performs locking 100% reliably in every + Another risk with NFS is that you must devise a way to ensure + that two or more servers do not interfere with each other. + Usually NFS file locking is handled by the + <command>lockd</command> daemon, but at the moment there is no + platform that performs locking 100% reliably in every situation. </para> </listitem> @@ -21464,10 +21338,10 @@ to the base directory). In that case, the only other options you need to specify are the <option>--socket</option> and <option>--port</option> options. For example, suppose that you - install different versions of MySQL using <filename>tar</filename> - file binary distributions. These install in different locations, - so you can start the server for each installation using the - command <command>bin/mysqld_safe</command> under its corresponding + install different versions of MySQL using tarfile binary + distributions. These install in different locations, so you can + start the server for each installation using + <command>bin/mysqld_safe</command> under its own corresponding base directory. <command>mysqld_safe</command> determines the proper <option>--basedir</option> option to pass to <command>mysqld</command>, and you need specify only the @@ -21511,8 +21385,8 @@ <para> To start multiple servers manually from the command line, you can specify the appropriate options on the command line or in - an option file. It's more convenient to place the options in - an option file, but it's necessary to make sure that each + an option file. it is more convenient to place the options in + an option file, but it is necessary to make sure that each server gets its own set of options. To do this, create an option file for each server and tell the server the filename with a <option>--defaults-file</option> option when you run @@ -21564,7 +21438,7 @@ <para> On NT, each server starts in the foreground (no new prompt - appears until the server exits later); you'll need to issue + appears until the server exits later); you will need to issue those two commands in separate console windows. </para> @@ -21657,12 +21531,11 @@ group in the standard option files. </para> </listitem> + +<!-- TODO: Change this back after bug gets fixed. --> +<!-- TODO: Bug#? --> <listitem> -<!-- TODO change this back after bug gets fixed --> - -<!-- If you specify a service name different than @code{MySQL} after the --> - <para> If you specify a service name after the <option>--install</option> option, the server ignores @@ -21856,11 +21729,10 @@ <para> The easiest way is to run multiple servers on Unix is to compile them with different TCP/IP ports and Unix socket files so that - each one is listening on different network interfaces. Also, by - compiling in different base directories for each installation, - that automatically results in different compiled-in data - directory, log file, and PID file locations for each of your - servers. + each one is listening on different network interfaces. Compiling + in different base directories for each installation also results + automatically in a separate, compiled-in data directory, log + file, and PID file location for each server. </para> <para> @@ -21914,10 +21786,10 @@ </para> <para> - You do not have to compile a new MySQL server just to start with - a different Unix socket file and TCP/IP port number. It is also - possible to specify those values at runtime. One way to do so is - by using command-line options: + However, it is not necessary to compile a new MySQL server + merely to start it with a different Unix socket file and TCP/IP + port number. It is also possible to specify those values at + runtime. One way to do so is by using command-line options: </para> <programlisting> @@ -21970,7 +21842,7 @@ testing. The nice thing about this method is that the environment variable settings apply to any client programs that you invoke from the same shell. Thus, connections for those - clients are automatically directed to the second server! + clients are automatically directed to the second server. </para> <para> @@ -21980,8 +21852,8 @@ </para> <para> - For automatic server execution, your startup script that is - executed at boot time should execute the following command once + For automatic server execution, the startup script that is + executed at boot time should run the following command once for each server with an appropriate option file path for each command: </para> @@ -22033,7 +21905,7 @@ <listitem> <para> - As of MySQL 4.1, start the client with + As of MySQL 4.1, you can start the client with <option>--protocol=tcp</option> to connect via TCP/IP, <option>--protocol=socket</option> to connect via a Unix socket file, <option>--protocol=pipe</option> to connect @@ -22157,7 +22029,7 @@ From version 4.0.1 on, MySQL Server features a query cache. When in use, the query cache stores the text of a <literal>SELECT</literal> query together with the corresponding - result that was sent to the client. If the identical query is + result that was sent to the client. If an identical query is received later, the server retrieves the results from the query cache rather than parsing and executing the query again. </para> @@ -22165,8 +22037,8 @@ <para> The query cache is extremely useful in an environment where you have tables that do not change very often and for which the server - receives a lot of identical queries. This is a typical situation - for many Web servers that generate a lot of dynamic pages based on + receives many identical queries. This is a typical situation + for many Web servers that generate a dynamic pages based on database content. </para> @@ -22178,7 +22050,7 @@ <para> <emphasis role="bold">Note</emphasis>: The query cache does not - work in an environment where you have many + work in an environment where you have multiple <command>mysqld</command> servers updating the same <literal>MyISAM</literal> tables. </para> @@ -22186,13 +22058,13 @@ <para> <emphasis role="bold">Note</emphasis>: The query cache is not used for server-side prepared statements. If you are using server-side - prepared statements consider that these statement will not be + prepared statements consider that these statements will not be satisfied by the query cache. See <xref linkend="c-api-prepared-statements"/>. </para> <para> - Some performance data for the query cache follow. These results + Some performance data for the query cache follows. These results were generated by running the MySQL benchmark suite on a Linux Alpha 2 x 500MHz system with 2GB RAM and a 64MB query cache. </para> @@ -22226,9 +22098,11 @@ To disable the query cache at server startup, set the <literal>query_cache_size</literal> system variable to 0. By disabling the query cache code, there is no noticeable overhead. - Query cache capabilities can be excluded from the server entirely - by using the <option>--without-query-cache</option> option to - <command>configure</command> when compiling MySQL. + Query caching capabilities can be excluded from the + server altogether by using the + <option>--without-query-cache</option> option to + <command>configure</command> when compiling MySQL. See also + <xref linkend="query-cache-configuration"/>. </para> <section id="query-cache-how"> @@ -22252,12 +22126,12 @@ </programlisting> <para> - Queries must be exactly the same (byte for byte) to be seen as - identical. In addition, query strings that are identical may be - treated as different for other reasons. Queries that use - different databases, different protocol versions, or different - default character sets are considered different queries and are - cached separately. + Queries must be <emphasis>exactly</emphasis> the same (byte for + byte) to be seen as identical. In addition, query strings that + are identical may be treated as <quote>different</quote> for + other reasons. Queries that use different databases, different + protocol versions, or different default character sets are + considered different queries and are cached separately. </para> <para> @@ -22301,9 +22175,8 @@ </para> <para> - Before MySQL 5.0, a query that begins with a leading comment - might be cached, but could not be fetched from the cache. This - problem is fixed in MySQL 5.0. + A query that begins with a leading comment may be cached, but + cannot be fetched from the cache. </para> <para> @@ -22342,20 +22215,21 @@ </row> <row> <entry><literal>FOUND_ROWS()</literal></entry> + <entry/> <entry><literal>GET_LOCK()</literal></entry> - <entry><literal>LAST_INSERT_ID()</literal></entry> </row> <row> + <entry><literal>LAST_INSERT_ID()</literal></entry> <entry><literal>LOAD_FILE()</literal></entry> <entry><literal>MASTER_POS_WAIT()</literal></entry> - <entry><literal>NOW()</literal></entry> </row> <row> + <entry><literal>NOW()</literal></entry> <entry><literal>RAND()</literal></entry> <entry><literal>RELEASE_LOCK()</literal></entry> - <entry><literal>SYSDATE()</literal></entry> </row> <row> + <entry><literal>SYSDATE()</literal></entry> <entry><literal>UNIX_TIMESTAMP()</literal> with no parameters</entry> <entry><literal>USER()</literal></entry> </row> @@ -22543,7 +22417,7 @@ When setting <literal>query_cache_size</literal> to a non-zero value keep in mind that the query cache needs a minimum size of about 40KB to allocate its structures. (The exact size depends - on architecture.) If you set the value too small, you'll get a + on architecture.) If you set the value too small, you will get a warning, like in this example: <programlisting> @@ -22565,7 +22439,7 @@ +------------------+-------+ | query_cache_size | 41984 | +------------------+-------+ - </programlisting> +</programlisting> </para> <para> --- 1.39/refman/mysql-database-administration.xml 2005-08-05 19:39:01 +10:00 +++ 1.40/refman/mysql-database-administration.xml 2005-08-06 00:42:03 +10:00 @@ -16597,7 +16597,7 @@ <para> From MySQL 5.0.3 on, it is also possible to limit the number of - simultaneous connection to the server on a per-account basis. + simultaneous connections to the server on a per-account basis. </para> <para>
| Thread | ||
|---|---|---|
| • bk commit - mysqldoc@docsrva tree (jon:1.3176) | jon | 5 Aug |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 1.099 sec. using MySQL 5.1.14-beta-log