Author: jrussell
Date: 2010-10-19 01:12:57 +0200 (Tue, 19 Oct 2010)
New Revision: 23210
Log:
More cleanup throughout the afternoon, mostly in the first few chapters.
Modified:
trunk/mysql-enterprise-backup-3.5/all-entities.ent
trunk/mysql-enterprise-backup-3.5/manual.xml
Modified: trunk/mysql-enterprise-backup-3.5/all-entities.ent
===================================================================
--- trunk/mysql-enterprise-backup-3.5/all-entities.ent 2010-10-18 20:19:27 UTC (rev 23209)
+++ trunk/mysql-enterprise-backup-3.5/all-entities.ent 2010-10-18 23:12:57 UTC (rev 23210)
Changed blocks: 1, Lines Added: 7, Lines Deleted: 0; 936 bytes
@@ -4,12 +4,19 @@
current directory. All ENTITY declarations should be given
first, followed by references to the those entities.
-->
+
+<!-- Major product-specific terms. -->
+
+<!ENTITY prodname "MySQL Enterprise Backup">
+
<!-- Making the command names into entities in case of change. -->
<!-- 'low level backup' and 'high level backup' commands. -->
+
<!ENTITY llbackup "ibbackup">
<!ENTITY hlbackup "mysqlbackup">
<!-- Entities for LSN values that get updated every time the example output is refreshed. -->
+
<!ENTITY example-3.1-lsn "32164666380">
<!ENTITY example-3.2-lsn "32164666380">
<!ENTITY example-5.6-lsn "2626689439">
Modified: trunk/mysql-enterprise-backup-3.5/manual.xml
===================================================================
--- trunk/mysql-enterprise-backup-3.5/manual.xml 2010-10-18 20:19:27 UTC (rev 23209)
+++ trunk/mysql-enterprise-backup-3.5/manual.xml 2010-10-18 23:12:57 UTC (rev 23210)
Changed blocks: 31, Lines Added: 111, Lines Deleted: 86; 18831 bytes
@@ -254,13 +254,13 @@
</indexterm>
<para>
- The <literal>&llbackup;</literal> of MySQL Enterprise Backup lets
- you back up InnoDB tables from a running MySQL database without
- setting any locks or disturbing normal database processing. You
- get a consistent copy of your database, as if the copy were taken
- at a precise point in time. MySQL Enterprise Backup is also the
- ideal method of setting up new slaves if you use MySQL replication
- on InnoDB tables.
+ The <literal>&llbackup;</literal> of MySQL Enterprise Backup backs
+ up InnoDB tables from a running MySQL database without disturbing
+ normal database processing. You get a consistent copy of your
+ database, as if the copy were taken at a precise point in time,
+ even though the backup job could take minutes or hours. MySQL
+ Enterprise Backup is also the ideal method of setting up new
+ slaves if you use MySQL replication on InnoDB tables.
</para>
<para>
@@ -278,16 +278,17 @@
<para>
You specify two filenames on the &llbackup; command line. These
- <literal>.cnf</literal> files represent MySQL options files.
- These options file have the following requirements:
+ <literal>.cnf</literal> files represent MySQL options files and
+ use similar syntax. These options file have the following
+ requirements:
</para>
<itemizedlist>
<listitem>
<para>
- Each options file must contain the following parameter
- values:
+ Each options file must contain the following
+ <emphasis role="bold">parameter values</emphasis>:
</para>
<programlisting>
@@ -304,15 +305,16 @@
<listitem>
<para>
- The directory paths must be absolute, because
- <literal>&llbackup;</literal> is not aware of the defaults.
+ The <emphasis role="bold">directory paths</emphasis> must be
+ absolute, because <literal>&llbackup;</literal> is not aware
+ of the defaults.
</para>
</listitem>
<listitem>
<para>
- The specification of the number of data files and their
- sizes must match in <literal>my.cnf</literal> and
+ The number of <emphasis role="bold">data files</emphasis>
+ and their sizes must match in <literal>my.cnf</literal> and
<literal>my2.cnf</literal>. For example, if the last data
file is specified as auto-extending in
<literal>my.cnf</literal>, it must be specified as
@@ -322,10 +324,10 @@
<listitem>
<para>
- The number of log files and their size must be explicitly
- specified, but their number and size can be different
- between <literal>my.cnf</literal> and
- <literal>my2.cnf</literal>.
+ The number of <emphasis role="bold">log files</emphasis> and
+ their size must be explicitly specified, but their number
+ and size can be different between <literal>my.cnf</literal>
+ and <literal>my2.cnf</literal>.
</para>
</listitem>
@@ -385,7 +387,7 @@
<title>Command-Line Options</title>
<para>
- The call <literal>ibbackup --help</literal> displays usage
+ The command <literal>ibbackup --help</literal> displays usage
information for the command-line options:
</para>
@@ -583,10 +585,12 @@
</para>
</listitem>
+<!-- JDR: consider which other items to link to the InnoDB glossary, e.g. file-per-table, file format names. -->
+
<listitem>
<para>
Any separate data files produced under the InnoDB
- "file-per-table" setting.
+ <quote>file-per-table</quote> setting.
</para>
</listitem>
@@ -598,13 +602,13 @@
<listitem>
<para>
- Data stored in both the original "Antelope" and new
- "Barracuda" file formats. Barracuda is a relatively
- recent file format that was first introduced with the InnoDB
- plugin. In particular, it includes support for compression
- within table data. Barracuda file format support is new in Hot
- Backup Version 3.5. It is automatic, without any option
- required for <literal>&llbackup;</literal>.
+ Data stored in both the original <quote>Antelope</quote> and
+ new <quote>Barracuda</quote> file formats. Barracuda is a
+ relatively recent file format that was first introduced with
+ the InnoDB plugin. In particular, it includes support for
+ compression within table data. Barracuda file format support
+ is new in &prodname; Version 3.5. It is automatic, without any
+ option required for <literal>&llbackup;</literal>.
</para>
</listitem>
@@ -622,12 +626,13 @@
<title>Example: Making an Uncompressed Backup of InnoDB Tables</title>
<para>
- We have prepared an options file
- <literal>/home/pekka/.backup-my.cnf</literal> which defines the
+ In this example, the options file
+ <literal>/home/pekka/.backup-my.cnf</literal> defines the
location of the backup (as described in the previous section).
The options file <literal>/home/pekka/.my.cnf</literal> defines
- the MySQL installation we want to back up. We run
- <literal>&llbackup;</literal>:
+ the MySQL installation to back up. Running
+ <literal>&llbackup;</literal> performs the first phase of the
+ process:
</para>
<programlisting id="example-2.1a">
@@ -695,9 +700,9 @@
Make a note of the LSN value in the message at the end of
both full and incremental backups, for example,
<literal>ibbackup: Was able to parse the log up to lsn
- 928223244</literal>. You must specify this value when
- performing incremental backups of changes that occur after
- this full backup.
+ <replaceable>LSN_number</replaceable></literal>. You specify
+ this value when performing incremental backups of changes
+ that occur after this full backup.
</para>
</listitem>
@@ -707,7 +712,8 @@
the uncompressed backup files, so that the full backup is
ready to be restored at any time. You can move the backup
data to a different server first, to avoid the CPU and I/O
- overhead of this operation on the database server itself.
+ overhead of performing this operation on the database
+ server.
</para>
</listitem>
@@ -738,14 +744,13 @@
</indexterm>
<para>
- Many users want to save disk space by compressing backup data
- files. The <literal>--compress</literal> option instructs
- <literal>&llbackup;</literal> to compress backup data files.
- Compression allows you to keep more sets of backup data on hand,
- and saves on transmission time when sending the backup data to
- another server. The downside is extra CPU overhead during the
- backup itself, and extra time needed during the restore process
- as the data is uncompressed.
+ To save disk space, you can compress backup data files by using
+ the <literal>--compress</literal> option of
+ <literal>&llbackup;</literal>. Compression lets you keep more
+ sets of backup data on hand, and saves on transmission time when
+ sending the backup data to another server. The downside is extra
+ CPU overhead during the backup itself, and extra time needed
+ during the restore process as the data is uncompressed.
</para>
<para>
@@ -761,7 +766,7 @@
<para>
You can use the <literal>--compress</literal> option for full
- backups or for incremental backups (with the
+ backups, or for incremental backups in combination with the
<literal>--incremental</literal> option.
</para>
@@ -811,8 +816,8 @@
<para>
The backup directory is shown below. Compressed data files have
- the suffix <literal>.ibz</literal>. Typically compression ratios
- of more than 70% are achieved:
+ the suffix <literal>.ibz</literal>. Typically, compression
+ ratios of more than 70% are achieved:
</para>
<programlisting id="example-2.2b">
@@ -829,14 +834,16 @@
<itemizedlist>
+<!-- JDR: some of these step-paragraphs are reused, could be entity-ized. -->
+
<listitem>
<para>
Make a note of the LSN value in the message at the end of
both full and incremental backups, for example,
<literal>ibbackup: Was able to parse the log up to lsn
- 928223244</literal>. You must specify this value when
- performing incremental backups of changes that occur after
- this full backup.
+ <replaceable>LSN_number</replaceable></literal>. You specify
+ this value when performing incremental backups of changes
+ that occur after this full backup.
</para>
</listitem>
@@ -846,7 +853,8 @@
the compressed backup files, so that the full backup is
ready to be restored at any time. You can move the backup
data to a different server first, to avoid the CPU and I/O
- overhead of this operation on the database server itself.
+ overhead of performing this operation on the database
+ server.
</para>
</listitem>
@@ -868,15 +876,18 @@
<title>Example: Making an Incremental Backup of InnoDB Tables</title>
<para>
- Incremental backup means that only changes are backed up, which
- provides additional flexibility in designing a backup strategy
- and reduces required storage for backups. Because an incremental
- backup always adds to an existing set of backup files, this
- procedure requires that you have already made a full
+ An incremental backup only backs up data that changed since the
+ previous backup. This technique provides additional flexibility
+ in designing a backup strategy and reduces required storage for
+ backups. Because an incremental backup always adds to an
+ existing set of backup files, make a full
<link linkend="backup.uncompressed">uncompressed</link> or
- <link linkend="backup.compressed">compressed</link> backup.
+ <link linkend="backup.compressed">compressed</link> backup
+ before doing any incremental backups.
</para>
+<!-- JDR: if enough internal-style tips like this, consider a later "Internals" or "Troubleshooting" section. -->
+
<para>
Incremental backups detect changes at the level of pages in the
data file, as opposed to table rows; each page that has changed
@@ -888,23 +899,23 @@
Incremental backup is enabled through the
<literal>--incremental</literal> option of the
<literal>&llbackup;</literal> command. You must also indicate
- the point in time of the previous <emphasis>full or
- incremental</emphasis> backup, through the
- <literal>--lsn</literal> option, where you specify the highest
- log sequence number from a previous <emphasis>full or
- incremental</emphasis> backup.
+ the point in time of the previous full or incremental backup,
+ through the <literal>--lsn</literal> option, where you specify
+ the highest log sequence number from a previous full or
+ incremental backup.
</para>
<para>
- When running the "apply log" step for an incremental
- backup, you specify the option sequence <literal>--apply-log
- --incremental</literal>, and the paths to 2 MySQL configuration
- files, first the <literal>.cnf</literal> file pointing to the
- full backup that you are updating, then the .cnf file pointing
- to the incremental backup data files. If you have taken several
- incremental backups since the last full backup, you might run
- several such <quote>apply log</quote> steps, one after the
- other, to bring the full backup entirely up to date.
+ When running the <quote>apply log</quote> step for an
+ incremental backup, you specify the option sequence
+ <literal>--apply-log --incremental</literal>, and the paths to 2
+ MySQL configuration files, first the <literal>.cnf</literal>
+ file pointing to the full backup that you are updating, then the
+ .cnf file pointing to the incremental backup data files. If you
+ have taken several incremental backups since the last full
+ backup, you might run several such <quote>apply log</quote>
+ steps, one after the other, to bring the full backup entirely up
+ to date.
</para>
<para>
@@ -915,9 +926,11 @@
command-line syntax.
</para>
+<!-- JDR: see whether these LSN numbers should refer to one of the new entities. -->
+
<para>
- In this example, we run an incremental backup. The last full
- backup we ran reported that the highest
+ This example shows an incremental backup. The last full backup
+ we ran reported that the highest
<link linkend="glos_lsn">LSN</link> was 2244068296:
</para>
@@ -1066,7 +1079,7 @@
taking a full
<link linkend="backup.uncompressed">uncompressed</link> or
<link linkend="backup.compressed">compressed</link> backup.
- Typically, this milestone is when you could archive and/or
+ Typically, this milestone happens when you can archive and
clear out your oldest backup data.
</para>
</listitem>
@@ -1075,6 +1088,8 @@
</section>
+<!-- JDR: really should have this section much later, so it doesn't come before the mysqlbackup instructions. -->
+
<section remap="h2" id="backup.myisam">
<title>Making a Point-in-Time Backup of Both InnoDB and MyISAM Tables</title>
@@ -1082,7 +1097,7 @@
<note>
<para>
This section describes low-level backup techniques that are
- only applicable for expert users. You can use the
+ intended for expert users. You can use the
<literal>&hlbackup;</literal> command to automate the
procedure presented in this section, as described in
<xref linkend="mysqlbackup"/>.
@@ -1095,12 +1110,12 @@
backup of both MyISAM and InnoDB tables. This option pauses the
backup process when an <literal>&llbackup;</literal> run is
close to ending, so that a script written by you can copy the
- MyISAM tables to a backup. Since the backup taken by
- <literal>&llbackup;</literal> corresponds to the time at the end
- of the run, and your script will block modifications to the
- MyISAM tables at that point, the backup contains a snapshot of
- MyISAM tables at the same point in time. Your script must follow
- this outline:
+ MyISAM tables and other non-InnoDB files to a backup. Since the
+ backup taken by <literal>&llbackup;</literal> corresponds to the
+ time at the end of the run, and your script blocks modifications
+ to the MyISAM tables at that point, the backup contains a
+ snapshot of MyISAM tables at the same point in time. Your script
+ must follow this outline:
</para>
<itemizedlist>
@@ -1169,6 +1184,8 @@
<title>Preparing the Backup to be Restored</title>
+<!-- JDR: cf. "raw backup", "prepared backup". -->
+
<para>
The initial backup files might not be in a consistent state,
because data could be changed while the backup is running. The
@@ -1188,7 +1205,7 @@
<para>
The option for applying the log is <literal>--apply-log</literal>.
- In the old InnoDB Hot Backup Product, this option was called
+ In the prior InnoDB Hot Backup Product, this option was called
<literal>--restore</literal>, but that option was renamed because
it prepares the data to be restored, rather than actually
restoring it.
@@ -1210,7 +1227,7 @@
<para>
The backup directory looks like this before applying the log to
- the backup.
+ the backup:
</para>
<programlisting id="example-3.1a">
@@ -1293,7 +1310,7 @@
</para>
<para>
- If the backup is compressed, give the
+ If the backup is compressed, specify the
<literal>--uncompress</literal> option to
<literal>&llbackup;</literal> when applying the log to the
backup:
@@ -1378,6 +1395,8 @@
<xref linkend="backup.incremental"/>.
</para>
+<!-- JDR: cf. "raw backup", "prepared backup". -->
+
<para>
After you take an incremental backup, the changes reflected in
those backup files must be applied to a full backup to bring the
@@ -1470,6 +1489,8 @@
101004 13:02:41 ibbackup: Incremental backup applied successfully!
</programlisting>
+<!-- JDR: clarify "that are labelled as". -->
+
<para>
Now the data files that are labelled as the full backup are
fully up-to-date, as of the time of the incremental backup:
@@ -1507,10 +1528,12 @@
<para>
After applying the log and creating the new
- <literal>ib_logfile</literal>s we are ready to start
+ <literal>ib_logfile</literal>s, we are ready to start
<literal>mysqld</literal> on our backup database.
</para>
+<!-- JDR: don't understand "by the user or automatically..." in the last sentence. -->
+
<para>
The backup database directory looks like this before we start
<literal>mysqld</literal>. Note that the backup directory
@@ -1573,6 +1596,8 @@
database and ready to serve clients.
</para>
+<!-- JDR: is there another step where you use the binlog position for more rolling forward? -->
+
<para>
If you originally took the backup from a MySQL replication
slave, then mysqld also prints the
@@ -2069,7 +2094,7 @@
completed successfully, either by verifying that the
<literal>&hlbackup;</literal> command returned exit code 0,
or by observing that <literal>&hlbackup;</literal> has
- printed the text "innobackup completed OK!".
+ printed the text <quote>innobackup completed OK!</quote>.
</para>
</listitem>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r23210 - trunk/mysql-enterprise-backup-3.5 | john.russell | 19 Oct |
