| List: | Internals | « Previous MessageNext Message » | |
| From: | jon | Date: | September 7 2005 5:21am |
| Subject: | bk commit - mysqldoc@docsrva tree (jon:1.3490) | ||
| 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.3490 05/09/07 13:21:56 jon@stripped +5 -0 Merge bk://mysqldoc@stripped into gigan.homedns.org:/home/jon/bk/mysqldoc refman-5.1/storage-engines.xml 1.17 05/09/07 13:21:54 jon@stripped +0 -0 Auto merged refman-5.1/manual.xml 1.13 05/09/07 13:21:54 jon@stripped +0 -0 Auto merged refman/storage-engines.xml 1.24 05/09/07 13:21:53 jon@stripped +0 -0 Auto merged refman-5.0/storage-engines.xml 1.17 05/09/07 13:21:53 jon@stripped +0 -0 Auto merged refman-4.1/storage-engines.xml 1.25 05/09/07 13:21:53 jon@stripped +0 -0 Auto merged # 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/RESYNC --- 1.12/refman-5.1/manual.xml 2005-09-07 07:15:55 +10:00 +++ 1.13/refman-5.1/manual.xml 2005-09-07 13:21:54 +10:00 @@ -13,7 +13,7 @@ <title id="top">⊤</title> - <xi:include href="preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> <xi:include href="introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> --- 1.16/refman-5.1/storage-engines.xml 2005-09-07 07:15:54 +10:00 +++ 1.17/refman-5.1/storage-engines.xml 2005-09-07 13:21:54 +10:00 @@ -311,7 +311,7 @@ </remark> <remark role="todo"> - this behavior now may be "using the default storage engine" rather + This behavior now may be "using the default storage engine" rather than "using MyISAM", but when did that change? </remark> @@ -654,8 +654,8 @@ <listitem> <para> - <command>myisamchk</command> marks tables as checked if run - using the <option>--update-state</option> option. + <command>myisamchk</command> marks tables as checked if you + run it with the <option>--update-state</option> option. <command>myisamchk --fast</command> checks only those tables that don't have this mark. </para> @@ -664,7 +664,7 @@ <listitem> <para> <command>myisamchk --analyze</command> stores statistics for - key parts, as well as for entire keys. + portions of keys, as well as for entire keys. </para> </listitem> @@ -802,7 +802,7 @@ <para> Used to help MySQL to decide when to use the slow but safe key cache index creation method. - <emphasis role="bold">Note</emphasis>: This was parameter + <emphasis role="bold">Note</emphasis>: This parameter was given in bytes before MySQL 5.0.6, when it was removed. </para> </listitem> @@ -1229,7 +1229,7 @@ <para> All MySQL distributions include <command>myisampack</command> - by default. Compressed tablescan be uncompressed with + by default. Compressed tables can be uncompressed with <command>myisamchk</command>. </para> @@ -1251,7 +1251,7 @@ <para> Each record is compressed separately, so there is very little access overhead. The header for a record takes up - 1-3 bytes depending on the biggest record in the table. + 1 to 3 bytes depending on the biggest record in the table. Each column is compressed differently. There is usually a different Huffman tree for each column. Some of the compression types are: @@ -1602,11 +1602,12 @@ The <literal>MERGE</literal> storage engine, also known as the <literal>MRG_MyISAM</literal> engine, is a collection of identical <literal>MyISAM</literal> tables that can be used as one. - "Identical" means that all tables have identical column and index - information. You cannot merge tables in which the columns are - listed in a different order, don't have exactly the same columns, - or have the indexes in different order. However, any or all of the - tables can be compressed with <command>myisampack</command>. See + <quote>Identical</quote> means that all tables have identical + column and index information. You cannot merge tables in which the + columns are listed in a different order, do not have exactly the + same columns, or have the indexes in different order. However, any + or all of the tables can be compressed with + <command>myisampack</command>. See <xref linkend="myisampack"/>. Differences in table options such as <literal>AVG_ROW_LENGTH</literal>, <literal>MAX_ROWS</literal>, or <literal>PACK_KEYS</literal> do not matter. @@ -3034,8 +3035,8 @@ <listitem> <para> - <literal>SHOW TABLE STATUS</literal> does not yet provide - some information for <literal>BDB</literal> tables: + <literal>SHOW TABLE STATUS</literal> does not provide some + information for <literal>BDB</literal> tables: </para> <programlisting> @@ -3097,7 +3098,7 @@ <para> Each <literal>BDB</literal> table stores in the <filename>.db</filename> file the path to the file as it was - created. This was done to be able to detect locks in a + created. This was done enable detection of locks in a multi-user environment that supports symlinks. As a consequence of this, it is not possible to move <literal>BDB</literal> table files from one database @@ -3736,7 +3737,7 @@ </itemizedlist> <para> - <emphasis role="bold">Retrieval:</emphasis> On retrieval, records + <emphasis role="bold">Retrieval</emphasis>: On retrieval, records are uncompressed on demand; there is no row cache. A <literal>SELECT</literal> operation performs a complete table scan: When a <literal>SELECT</literal> occurs, it finds out how @@ -3838,7 +3839,7 @@ <section id="blackhole-storage-engine"> - <title id="title-blackhole-storage-engine"/> + <title id="title-blackhole-storage-engine">&title-blackhole-storage-engine;</title> <indexterm> <primary><literal>BLACKHOLE</literal> storage engine</primary> @@ -3855,36 +3856,9 @@ <para> The <literal>BLACKHOLE</literal> storage engine acts as a - <quote>black hole</quote> that accepts data but throws it away and - does not store it. Retrievals always return the empty set. - </para> - - <para> - To enable this storage engine, use the - <option>--with-blackhole-storage-engine</option> option to - <command>configure</command> when you build MySQL. The - <literal>BLACKHOLE</literal> storage engine is available in - MySQL-supplied server binaries; you can determine whether or not - your version supports this engine by viewing the output of - <literal>SHOW ENGINES</literal> or <literal>SHOW VARIABLES LIKE - 'have%'</literal>. - </para> - - <para> - When you create a <literal>BLACKHOLE</literal> table, the server - creates a table definition file in the database directory. The - file begins with the table name and has an - <filename>.frm</filename> extension. There are no other files - associated with the table. - </para> - - <para> - Inserts into a <literal>BLACKHOLE</literal> table do not store any - data, but if the binary log is enabled, the SQL statements are - logged (and replicated to slave servers). This can be useful when - you need a record of statements that have been issued, but do not - require immediate, <quote>live</quote> access to the data. - </para> + <quote>black hole</quote> that + accepts data but throws it away and does not store it. Retrievals + always return the empty set: <programlisting> mysql> <userinput>CREATE TABLE test(i INT, c CHAR(10)) ENGINE = BLACKHOLE;</userinput> @@ -3897,10 +3871,102 @@ mysql> <userinput>SELECT * FROM test;</userinput> Empty set (0.00 sec) </programlisting> + </para> + + <para> + When you create a <literal>BLACKHOLE</literal> table, the server + creates a table definition file in the database directory. The + file begins with the table name and has an + <filename>.frm</filename> extension. There are no other files + associated with the table. + </para> <para> The <literal>BLACKHOLE</literal> storage engine supports all kinds of indexing. + </para> + + <para> + To enable this storage engine, use the + <option>--with-blackhole-storage-engine</option> option to + <command>configure</command> when you build MySQL. The + <literal>BLACKHOLE</literal> storage engine is available in + MySQL-supplied server binaries; you can determine whether or not + your version supports this engine by viewing the output of + <literal>SHOW ENGINES</literal> or <literal>SHOW VARIABLES LIKE + 'have%'</literal>. + </para> + + <para> + Inserts into a <literal>BLACKHOLE</literal> table do not store any + data, but if the binary log is enabled, the SQL statements are + logged (and replicated to slave servers). This can be useful as a + repeater or filter mechanism. For example, suppose that your + application requires slave-side filtering rules, but transfering + all binlog data to the slave first results in too much traffic. + In such a case, it is possible to set up on the master host a + <quote>dummy</quote> slave process whose default storage engine is + <literal>BLACKHOLE</literal>, depicted as follows: + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/blackhole-1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase lang="en">Replication using <literal>BLACKHOLE</literal> + for filtering</phrase> + </textobject> + </mediaobject> + + <para> + The master writes to its binary log. The <quote>dummy</quote> + <literal>mysqld</literal> process acts as a slave, applying the + desired combination of <literal>replicate-do</literal> and + <literal>replicate-ignore</literal> rules, and writes a new, + filtered binlog of its own. (See + <xref linkend="replication-options"/>.) This filtered log is + provided to the slave. + </para> + + <para> + Since the dummy process does not actually store any data, there is + little processing over head incurred by running the additional + <literal>mysqld</literal> process on the replication master host. + This type of setup can be repeated with additional replication + slaves. + </para> + + <para> + Other possible uses for the <literal>BLACKHOLE</literal> storage + engine include: + + <itemizedlist> + + <listitem> + <para> + Verification of dumpfile syntax. + </para> + </listitem> + + <listitem> + <para> + Measurement of the overhead from binary logging, by + comparing performance using <literal>BLACKHOLE</literal> + with and without binary logging enabled. + </para> + </listitem> + + <listitem> + <para> + since <literal>BLACKHOLE</literal> is essentially a + <quote>no-op</quote> storage engine, it could be used for + finding performance bottlenecks not related to the storage + engine itself. + </para> + </listitem> + + </itemizedlist> </para> </section> --- 1.24/refman-4.1/storage-engines.xml 2005-09-07 07:15:47 +10:00 +++ 1.25/refman-4.1/storage-engines.xml 2005-09-07 13:21:53 +10:00 @@ -124,6 +124,14 @@ <primary><literal>ARCHIVE</literal> table type</primary> </indexterm> + <indexterm> + <primary><literal>BLACKHOLE</literal> storage engine</primary> + </indexterm> + + <indexterm> + <primary><literal>BLACKHOLE</literal> table type</primary> + </indexterm> + <para> MySQL supports several storage engines that act as handlers for different table types. MySQL storage engines include both those that @@ -178,12 +186,12 @@ <listitem> <para> The <literal>EXAMPLE</literal> storage engine was added in MySQL - 4.1.3. It is a <quote>stub</quote> engine that does nothing. You - can create tables with this engine, but no data can be stored - into them or retrieved from them. The purpose of this engine is - to serve as an example in the MySQL source code that illustrates - how to begin writing new storage engines. As such, it is - primarily of interest to developers. + 4.1.3. It is a <quote>stub</quote> engine that does nothing. You can create + tables with this engine, but no data can be stored in them or + retrieved from them. The purpose of this engine is to serve as + an example in the MySQL source code that illustrates how to + begin writing new storage engines. As such, it is primarily of + interest to developers. </para> </listitem> @@ -212,6 +220,14 @@ </para> </listitem> + <listitem> + <para> + The <literal>BLACKHOLE</literal> storage engine was added in + MySQL 4.1.11. This engine accepts but does not store data and + retrievals always return an empty set. + </para> + </listitem> + </itemizedlist> <para> @@ -279,7 +295,7 @@ </remark> <remark role="todo"> - this behavior now may be "using the default storage engine" rather + This behavior now may be "using the default storage engine" rather than "using MyISAM", but when did that change? </remark> @@ -432,8 +448,9 @@ files. The files have names that begin with the table name and have an extension to indicate the file type. An <filename>.frm</filename> file stores the table definition. The - data file has an <filename>.MYD</filename> (MYData) extension. The - index file has an <filename>.MYI</filename> (MYIndex) extension, + data file has an <filename>.MYD</filename> + (<literal>MYData</literal>) extension. The index file has an + <filename>.MYI</filename> (<literal>MYIndex</literal>) extension. </para> <para> @@ -456,7 +473,7 @@ <para> You can check or repair <literal>MyISAM</literal> tables with the <command>myisamchk</command> utility. See - <xref linkend="crash-recovery"/>. You can compress + <xref linkend="crash-recovery"/>. You can also compress <literal>MyISAM</literal> tables with <command>myisampack</command> to take up much less space. See <xref linkend="myisampack"/>. @@ -584,8 +601,8 @@ <listitem> <para> - If a table doesn't have free blocks in the middle of the data - file, you can <literal>INSERT</literal> new rows into it at + If a table has no free blocks in the middle of the data file, + you can <literal>INSERT</literal> new rows into it at the same time that other threads are reading from the table. (These are known as concurrent inserts.) A free block can occur as a result of deleting rows or an update of a dynamic @@ -619,7 +636,8 @@ <command>mysqld</command> is started with the <option>--myisam-recover</option> option, <literal>MyISAM</literal> tables are automatically checked - when opened and repaired if the table wasn't closed properly. + when opened, and are repaired if the table wasn't closed + properly. </para> </listitem> @@ -635,7 +653,7 @@ <listitem> <para> <command>myisamchk --analyze</command> stores statistics for - key parts, not only for whole keys as in + portions of keys, not only for whole keys as in <literal>ISAM</literal>. </para> </listitem> @@ -684,8 +702,8 @@ A hashed computed index can be used for <literal>UNIQUE</literal>. This allows you to have <literal>UNIQUE</literal> on any combination of columns in a - table. (You can't search on a <literal>UNIQUE</literal> - computed index, however.) + table. (However, you cannot search on a + <literal>UNIQUE</literal> computed index.) </para> </listitem> @@ -948,17 +966,10 @@ the <literal>ROW_FORMAT</literal> table option. This causes <literal>CHAR</literal> and <literal>VARCHAR</literal> columns to become <literal>CHAR</literal> for <literal>FIXED</literal> - format or <literal>VARCHAR</literal> for + format, or <literal>VARCHAR</literal> for <literal>DYNAMIC</literal> format. </para> - <para> - In the future, you will be able to compress or decompress tables - by specifying <literal>ROW_FORMAT={COMPRESSED | - DEFAULT}</literal> to <literal>ALTER TABLE</literal>. See - <xref linkend="create-table"/>. - </para> - <section id="static-format"> <title id="title-static-format">&title-static-format;</title> @@ -1132,8 +1143,8 @@ information that extends the row length, the row becomes fragmented. In this case, you may have to run <literal>OPTIMIZE TABLE</literal> or <command>myisamchk - -r</command> from time to time to get better performance. - Use <command>myisamchk -ei</command> to obtain table + -r</command> from time to time to improve performance. Use + <command>myisamchk -ei</command> to obtain table statistics. </para> </listitem> @@ -1166,9 +1177,9 @@ record is linked whenever an update causes an enlargement of the record. Each new link is at least 20 bytes, so the next enlargement probably goes in the same link. If not, - there is another link. You may check how many links there - are with <command>myisamchk -ed</command>. All links may - be removed with <command>myisamchk -r</command>. + another link is created. You can find the number of links + using <command>myisamchk -ed</command>. All links may be + removed with <command>myisamchk -r</command>. </para> </listitem> @@ -1226,7 +1237,7 @@ <listitem> <para> Compressed tables take very little disk space. This - minimizes disk usage, which is very nice when using slow + minimizes disk usage, which is helpful when using slow disks (such as CD-ROMs). </para> </listitem> @@ -1234,8 +1245,8 @@ <listitem> <para> Each record is compressed separately, so there is very - little access overhead. The header for a record is fixed - (1-3 bytes) depending on the biggest record in the table. + little access overhead. The header for a record takes up + 1 to 3 bytes depending on the biggest record in the table. Each column is compressed differently. There is usually a different Huffman tree for each column. Some of the compression types are: @@ -1283,8 +1294,8 @@ <listitem> <para> - A column may use a combination of the preceding - compressions. + A column may use any combination of the preceding + compression types. </para> </listitem> @@ -1321,7 +1332,7 @@ Even though the <literal>MyISAM</literal> table format is very reliable (all changes to a table made by an SQL statement are written before the statement returns), you can still get - corrupted tables if some of the following things happen: + corrupted tables if any of the following events occur: </para> <itemizedlist> @@ -1342,7 +1353,7 @@ <listitem> <para> - Hardware errors. + Hardware failures. </para> </listitem> @@ -1364,7 +1375,7 @@ </itemizedlist> <para> - Typical symptoms for a corrupt table are: + Typical symptoms of a corrupt table are: </para> <itemizedlist> @@ -1390,9 +1401,9 @@ </itemizedlist> <para> - You can check whether a <literal>MyISAM</literal> table is - okay with the <literal>CHECK TABLE</literal> statement. You - can repair a corrupted <literal>MyISAM</literal> table with + You can check the health of a <literal>MyISAM</literal> table + using the <literal>CHECK TABLE</literal> statement, and repair + a corrupted <literal>MyISAM</literal> table with <literal>REPAIR TABLE</literal>. When <command>mysqld</command> is not running, you can also check or repair a table with the <command>myisamchk</command> @@ -1409,7 +1420,7 @@ recent <literal>restarted mysqld</literal> message in the error log. If there is such a message, it is likely that table corruption is a result of the server dying. Otherwise, - corruption may have occurred during normal operation, which is + corruption may have occurred during normal operation. This is a bug. You should try to create a reproducible test case that demonstrates the problem. See <xref linkend="crashing"/> and <xref linkend="reproduceable-test-case"/>. @@ -1436,8 +1447,7 @@ <para> This warning doesn't necessarily mean that the table is - corrupted, but you should at least check the table to verify - that it's okay. + corrupted, but you should at least check the table. </para> <para> @@ -1494,8 +1504,8 @@ <listitem> <para> - The <literal>MyISAM</literal> tables are copied without a - preceding <literal>LOCK TABLES</literal> and + The <literal>MyISAM</literal> tables are copied without + first issuing <literal>LOCK TABLES</literal> and <literal>FLUSH TABLES</literal>. </para> </listitem> @@ -1520,11 +1530,11 @@ <listitem> <para> - Many <command>mysqld</command> servers are using the table - and one server performed a <literal>REPAIR TABLE</literal> - or <literal>CHECK TABLE</literal> on the table while it - was in use by another server. In this setup, it is safe to - use <literal>CHECK TABLE</literal>, although you might get + Multiple <command>mysqld</command> servers are using the + table and one server performed a <literal>REPAIR + TABLE</literal> or <literal>CHECK TABLE</literal> on the + table while it was in use by another server. In this + setup, it is safe to use <literal>CHECK TABLE</literal>, although you might get the warning from other servers. However, <literal>REPAIR TABLE</literal> should be avoided because when one server replaces the data file with a new one, this is not @@ -1593,12 +1603,12 @@ A <literal>MERGE</literal> table is a collection of identical <literal>MyISAM</literal> tables that can be used as one. <quote>Identical</quote> means that all tables have identical - column and index information. You can't merge tables in which the - columns are listed in a different order, don't have exactly the + column and index information. You cannot merge tables in which the + columns are listed in a different order, do not have exactly the same columns, or have the indexes in different order. However, any or all of the tables can be compressed with - <command>myisampack</command>. See <xref linkend="myisampack"/>. - Differences in table options such as + <command>myisampack</command>. See + <xref linkend="myisampack"/>. Differences in table options such as <literal>AVG_ROW_LENGTH</literal>, <literal>MAX_ROWS</literal>, or <literal>PACK_KEYS</literal> do not matter. @@ -1621,8 +1631,8 @@ <para> You can use <literal>SELECT</literal>, <literal>DELETE</literal>, <literal>UPDATE</literal>, and (as of MySQL 4.0) - <literal>INSERT</literal> on the collection of tables. For the - moment, you must have <literal>SELECT</literal>, + <literal>INSERT</literal> on the + collection of tables. You must have <literal>SELECT</literal>, <literal>UPDATE</literal>, and <literal>DELETE</literal> privileges on the tables that you map to a <literal>MERGE</literal> table. @@ -1636,16 +1646,18 @@ <para> When you create a <literal>MERGE</literal> table, you must specify - a <literal>UNION=(list-of-tables)</literal> clause that indicates - which tables you want to use as one. You can optionally specify an - <literal>INSERT_METHOD</literal> option if you want inserts for - the <literal>MERGE</literal> table to happen in the first or last - table of the <literal>UNION</literal> list. Use a value of - <literal>FIRST</literal> or <literal>LAST</literal> to have - inserts go to the first or last table. If you don't specify any - <literal>INSERT_METHOD</literal> option or specify it with a value - of <literal>NO</literal>, attempts to insert records into the - <literal>MERGE</literal> table result in an error. + a + <literal>UNION=(<replaceable>list-of-tables</replaceable>)</literal> + clause that indicates which tables you want to use as one. You can + optionally specify an <literal>INSERT_METHOD</literal> option if + you want inserts for the <literal>MERGE</literal> table to take + place in the first or last table of the <literal>UNION</literal> + list. Use a value of <literal>FIRST</literal> or + <literal>LAST</literal> to cause inserts to be made in the first + or last table, respectively. If you do not specify an + <literal>INSERT_METHOD</literal> option or if you specify it with + a value of <literal>NO</literal>, attempts to insert records into + the <literal>MERGE</literal> table result in an error. </para> <para> @@ -1682,8 +1694,8 @@ </para> <para> - After creating the <literal>MERGE</literal> table, you can do - things like this: + After creating the <literal>MERGE</literal> table, you can issue + queries that operate on the group of tables as a whole: </para> <programlisting> @@ -1713,15 +1725,16 @@ <para> To remap a <literal>MERGE</literal> table to a different - collection of <literal>MyISAM</literal> tables, you can do one of - the following: + collection of <literal>MyISAM</literal> tables, you can perform + one of the following: </para> <itemizedlist> <listitem> <para> - <literal>DROP</literal> the table and re-create it. + <literal>DROP</literal> the <literal>MERGE</literal> table and + re-create it. </para> </listitem> @@ -1775,10 +1788,10 @@ <listitem> <para> - Do more efficient searches. If you know exactly what you are - looking for, you can search in just one of the split tables - for some queries and use a <literal>MERGE</literal> table for - others. You can even have many different + Perform more efficient searches. If you know exactly what you + are looking for, you can search in just one of the split + tables for some queries and use a <literal>MERGE</literal> + table for others. You can even have many different <literal>MERGE</literal> tables that use overlapping sets of tables. </para> @@ -1786,10 +1799,10 @@ <listitem> <para> - Do more efficient repairs. It's easier to repair the + Perform more efficient repairs. It is easier to repair individual tables that are mapped to a - <literal>MERGE</literal> table than to repair a single really - big table. + <literal>MERGE</literal> table than to repair a single large + table. </para> </listitem> @@ -1828,8 +1841,8 @@ You can create an alias or synonym for a <literal>MyISAM</literal> table by defining a <literal>MERGE</literal> table that maps to that single table. - There should be no really notable performance impact of doing - this (only a couple of indirect calls and + There should be no really notable performance impact from + doing this (only a couple of indirect calls and <literal>memcpy()</literal> calls for each read). </para> </listitem> @@ -1887,12 +1900,11 @@ Key reads are slower. When you read a key, the <literal>MERGE</literal> storage engine needs to issue a read on all underlying tables to check which one most closely - matches the given key. If you then do a - <quote>read-next,</quote> the <literal>MERGE</literal> storage - engine needs to search the read buffers to find the next key. - Only when one key buffer is used up, the storage engine needs - to read the next key block. This makes - <literal>MERGE</literal> keys much slower on + matches the given key. If you then do a read-next, the + <literal>MERGE</literal> storage engine needs to search the + read buffers to find the next key. Only when one key buffer is + used up does the storage engine need to read the next key + block. This makes <literal>MERGE</literal> keys much slower on <literal>eq_ref</literal> searches, but not much slower on <literal>ref</literal> searches. See <xref linkend="explain"/> for more information about <literal>eq_ref</literal> and @@ -1907,8 +1919,8 @@ <title id="title-merge-table-problems">&title-merge-table-problems;</title> <para> - The following are the known problems with - <literal>MERGE</literal> tables: + The following are known problems with <literal>MERGE</literal> + tables: </para> <itemizedlist> @@ -1919,7 +1931,7 @@ <literal>MERGE</literal> table to another table type, the mapping to the underlying tables is lost. Instead, the rows from the underlying <literal>MyISAM</literal> tables are - copied into the altered table, which then is assigned the + copied into the altered table, which is then assigned the new type. </para> </listitem> @@ -1934,24 +1946,25 @@ <listitem> <para> - <literal>REPLACE</literal> doesn't work. + <literal>REPLACE</literal> does not work. </para> </listitem> <listitem> <para> - You can't use <literal>DROP TABLE</literal>, <literal>ALTER + You cannot use <literal>DROP TABLE</literal>, <literal>ALTER TABLE</literal>, <literal>DELETE FROM</literal> without a <literal>WHERE</literal> clause, <literal>REPAIR TABLE</literal>, <literal>TRUNCATE TABLE</literal>, <literal>OPTIMIZE TABLE</literal>, or <literal>ANALYZE - TABLE</literal> on any of the tables that are mapped into a - <literal>MERGE</literal> table that is <quote>open.</quote> - If you do this, the <literal>MERGE</literal> table may still - refer to the original table and you get unexpected results. - The easiest way to work around this deficiency is to issue a - <literal>FLUSH TABLES</literal> statement to ensure that no - <literal>MERGE</literal> tables remain <quote>open.</quote> + TABLE</literal> on any of the tables that are mapped into an + open <literal>MERGE</literal> table. If you do so, the + <literal>MERGE</literal> table may still refer to the + original table, which yields unexpected results. The easiest + way to work around this deficiency is to issue a + <literal>FLUSH TABLES</literal> statement prior to + performing any of these operations to ensure that no + <literal>MERGE</literal> tables remain open. </para> </listitem> @@ -1991,11 +2004,11 @@ <listitem> <para> When you create a <literal>MERGE</literal> table, there is - no check whether the underlying tables exist and have - identical structure. When the <literal>MERGE</literal> table - is used, MySQL does a quick check that the record length for - all mapped tables is equal, but this is not foolproof. If - you create a <literal>MERGE</literal> table from dissimilar + no check to insure that the underlying tables exist and have + identical structures. When the <literal>MERGE</literal> + table is used, MySQL checks that the record length for all + mapped tables is equal, but this is not foolproof. If you + create a <literal>MERGE</literal> table from dissimilar <literal>MyISAM</literal> tables, you are very likely to run into strange problems. </para> @@ -2003,18 +2016,19 @@ <listitem> <para> - Index order in the <literal>MERGE</literal> table and its - underlying tables should be the same. If you use + The order of indexes in the <literal>MERGE</literal> table + and its underlying tables should be the same. If you use <literal>ALTER TABLE</literal> to add a <literal>UNIQUE</literal> index to a table used in a <literal>MERGE</literal> table, and then use <literal>ALTER TABLE</literal> to add a non-unique index on the - <literal>MERGE</literal> table, the index order is different - for the tables if there was an old non-unique index in the - underlying table. (This is because <literal>ALTER - TABLE</literal> puts <literal>UNIQUE</literal> indexes - before non-unique indexes to be able to detect duplicate - keys as early as possible.) Consequently, queries may return + <literal>MERGE</literal> table, the index ordering is + different for the tables if there was already a non-unique + index in the underlying table. (This is because + <literal>ALTER TABLE</literal> puts + <literal>UNIQUE</literal> indexes before non-unique indexes + to facilitate rapid detection of duplicate keys.) + Consequently, queries on tables with such indexes may return unexpected results. </para> </listitem> @@ -2023,10 +2037,10 @@ <para> <literal>DROP TABLE</literal> on a table that is in use by a <literal>MERGE</literal> table does not work on Windows - because the <literal>MERGE</literal> storage engine does the - table mapping hidden from the upper layer of MySQL. Because - Windows doesn't allow you to delete files that are open, you - first must flush all <literal>MERGE</literal> tables (with + because the <literal>MERGE</literal> storage engine's table + mapping is hidden from the upper layer of MySQL. Since + Windows does not allow the deletion of open files, you first + must flush all <literal>MERGE</literal> tables (with <literal>FLUSH TABLES</literal>) or drop the <literal>MERGE</literal> table before dropping the table. </para> @@ -2049,7 +2063,7 @@ <title id="title-memory-storage-engine">&title-memory-storage-engine;</title> <remark role="todo"> - parts of this may be true only for hash indexes. Now that MEMORY + Parts of this may be true only for hash indexes. Now that MEMORY supports BTREE indexes, some statements may need to be qualified. </remark> @@ -2084,9 +2098,9 @@ contents that are stored in memory. Before MySQL 4.1, <literal>MEMORY</literal> tables are called <literal>HEAP</literal> tables. As of 4.1, - <literal>MEMORY</literal> is the preferred term, and - <literal>HEAP</literal> is a synonym for - <literal>MEMORY</literal>. + <literal>MEMORY</literal> is the preferred term, although + <literal>HEAP</literal> remains supported for backwards + compatibility. </para> <para> @@ -2108,18 +2122,19 @@ </programlisting> <para> - <literal>MEMORY</literal> tables are stored in memory and use hash - indexes by default. This makes them very fast, and very useful for - creating temporary tables. However, when the server shuts down, - all data stored in <literal>MEMORY</literal> tables is lost. The - tables continue to exist because their definitions are stored in - the <filename>.frm</filename> files on disk, but their contents - are empty when the server restarts. + As indicated by their name, <literal>MEMORY</literal> tables are + stored in memory and use hash indexes by default. This makes them + very fast, and very useful for creating temporary tables. However, + when the server shuts down, all data stored in + <literal>MEMORY</literal> tables is lost. The tables themselves + continue to exist because their definitions are stored in + <filename>.frm</filename> files on disk, but they are empty when + the server restarts. </para> <para> - Here is an example that shows how you might create, use, and - remove a <literal>MEMORY</literal> table: + This example shows how you might create, use, and remove a + <literal>MEMORY</literal> table: </para> <programlisting> @@ -2140,13 +2155,13 @@ <listitem> <para> Space for <literal>MEMORY</literal> tables is allocated in - small blocks. The tables use 100% dynamic hashing (on - inserting). No overflow areas and no extra key space are - needed. There is no extra space needed for free lists. Deleted - rows are put in a linked list and are reused when you insert - new data into the table. <literal>MEMORY</literal> tables also - don't have problems with deletes plus inserts, which is common - with hashed tables. + small blocks. Tables use 100% dynamic hashing for inserts. No + overflow area or extra key space is needed. No extra space is + needed for free lists. Deleted rows are put in a linked list + and are reused when you insert new data into the table. + <literal>MEMORY</literal> tables also have none of the + problems commonly associated with deletes plus inserts in + hashed tables. </para> </listitem> @@ -2168,7 +2183,8 @@ are still the default, but you can specify explicitly that a <literal>MEMORY</literal> table index should be a <literal>HASH</literal> or <literal>BTREE</literal> by adding - a <literal>USING</literal> clause: + a <literal>USING</literal> + clause as shown here: </para> <programlisting> @@ -2208,7 +2224,7 @@ that has a high degree of key duplication (many index entries containing the same value), updates to the table that affect key values and all deletes are significantly slower. The - degree of slowdown is proportional to the degree of + degree of this slowdown is proportional to the degree of duplication (or, inversely proportional to the index cardinality). You can use a <literal>BTREE</literal> index to avoid this problem. @@ -2291,7 +2307,7 @@ <listitem> <para> - The server needs enough extra memory to maintain all + The server needs sufficient memory to maintain all <literal>MEMORY</literal> tables that are in use at the same time. </para> @@ -2299,11 +2315,11 @@ <listitem> <para> - To free memory used by a <literal>MEMORY</literal> table if + To free memory used by a <literal>MEMORY</literal> table when you no longer require its contents, you should execute - <literal>DELETE</literal> or <literal>TRUNCATE - TABLE</literal>, or else remove the table with <literal>DROP - TABLE</literal>. + <literal>DELETE FROM</literal> or <literal>TRUNCATE + TABLE</literal>, or remove the table altogether (using + <literal>DROP TABLE</literal>). </para> </listitem> @@ -2313,9 +2329,10 @@ the MySQL server starts, you can use the <option>--init-file</option> option. For example, you can put statements such as <literal>INSERT INTO ... SELECT</literal> - or <literal>LOAD DATA INFILE</literal> into the file to load - the table from some persistent data source. See - <xref linkend="server-options"/>. + or <literal>LOAD DATA INFILE</literal> into this file in order + to load the table from a persistent data source. See + <xref linkend="server-options"/> and + <xref linkend="load-data"/>. </para> </listitem> @@ -2327,15 +2344,15 @@ tables have become empty, so it returns out-of-date content if you select data from them. Beginning with MySQL 4.0.18, when a <literal>MEMORY</literal> table is used on the master for the - first time since the master's startup, a <literal>DELETE + first time since the master was started, a <literal>DELETE FROM</literal> statement is written to the master's binary log automatically, thus synchronizing the slave to the master again. Note that even with this strategy, the slave still has - out-of-date data in the table during the interval between the - master's restart and its first use of the table. But if you - use the <option>--init-file</option> option to populate the - <literal>MEMORY</literal> table on the master at startup, it - ensures that the failing time interval is zero. + outdated data in the table during the interval between the + master's restart and its first use of the table. However, if + you use the <option>--init-file</option> option to populate + the <literal>MEMORY</literal> table on the master at startup, + it ensures that this time interval is zero. </para> </listitem> @@ -2414,25 +2431,25 @@ surviving crashes and are also capable of <literal>COMMIT</literal> and <literal>ROLLBACK</literal> operations on transactions. The MySQL source distribution comes - with a <literal>BDB</literal> distribution that has a couple of - small patches to make it work more smoothly with MySQL. You can't - use a non-patched <literal>BDB</literal> version with MySQL. + with a <literal>BDB</literal> distribution that is patched to make + it work with MySQL. You cannot use a non-patched version of + <literal>BDB</literal> with MySQL. </para> <para> - We at MySQL AB are working in close cooperation with Sleepycat to - keep the quality of the MySQL/BDB interface high. (Even though - Berkeley DB is in itself very tested and reliable, the MySQL - interface is still considered gamma quality. We are improving and - optimizing it.) + We at MySQL AB work in close cooperation with Sleepycat to keep + the quality of the MySQL/BDB interface high. (Even though Berkeley + DB is in itself very tested and reliable, the MySQL interface is + still considered gamma quality. We continue to improve and + optimize it.) </para> <para> When it comes to support for any problems involving <literal>BDB</literal> tables, we are committed to helping our - users locate the problem and create a reproducible test case. Any - such test case is forwarded to Sleepycat, which in turn helps us - find and fix the problem. As this is a two-stage operation, any + users locate the problem and create reproducible test cases. Any + such test case is forwarded to Sleepycat, who in turn help us find + and fix the problem. As this is a two-stage operation, any problems with <literal>BDB</literal> tables may take a little longer for us to fix than for other storage engines. However, we anticipate no significant difficulties with this procedure because @@ -2492,11 +2509,17 @@ </para> </listitem> + <listitem> + <para> + Windows NT/2000/XP + </para> + </listitem> + </itemizedlist> <para> - <literal>BDB</literal> does not work with the following - operating systems: + <literal>BDB</literal> does <emphasis>not</emphasis> work with + the following operating systems: </para> <itemizedlist> @@ -2580,12 +2603,12 @@ </para> <programlisting> -shell> <userinput>./configure --with-berkeley-db [other-options]</userinput> +shell> <userinput>./configure --with-berkeley-db [<replaceable>other-options</replaceable>]</userinput> </programlisting> <para> For more information, see <xref linkend="installing-binary"/>, - <xref linkend="mysqld-max"/>, and See + <xref linkend="mysqld-max"/>, and <xref linkend="installing-source"/>. </para> @@ -2644,7 +2667,7 @@ </para> <para> - Don't start Berkeley DB in recover mode. + Do not start Berkeley DB in recover mode. </para> </listitem> @@ -2667,7 +2690,7 @@ </para> <para> - Start Berkeley DB in multi-process mode. (Don't use + Start Berkeley DB in multi-process mode. (Do not use <literal>DB_PRIVATE</literal> when initializing Berkeley DB.) </para> @@ -2712,29 +2735,31 @@ See <xref linkend="server-options"/>. </para> - <para> - The following system variable affects the behavior of - <literal>BDB</literal> tables: - </para> + <remark> + Seems a bit odd to have a single-item list here... This + bsaically just repeats what's show about 2 paras below, so I'm + commenting it out for now + </remark> - <itemizedlist> +<!-- + <para> + The following system variable affects the behavior of + <literal>BDB</literal> tables: + </para> - <listitem> - <para> - <literal>bdb_max_lock</literal> - </para> + <itemizedlist> - <para> - The maximum number of locks you can have active on a - <literal>BDB</literal> table. - </para> - </listitem> + <listitem><para> + <literal>bdb_max_lock</literal> + </para> - </itemizedlist> + <para> + The maximum number of locks that can be active on a + <literal>BDB</literal> table. + </para></listitem> - <para> - See <xref linkend="server-system-variables"/>. - </para> + </itemizedlist> +--> <para> If you use the <option>--skip-bdb</option> option, MySQL does @@ -2748,8 +2773,8 @@ <para> Normally, you should start <command>mysqld</command> without the <option>--bdb-no-recover</option> option if you intend to use - <literal>BDB</literal> tables. However, this may give you - problems when you try to start <command>mysqld</command> if the + <literal>BDB</literal> tables. However, this may cause problems + when you try to start <command>mysqld</command> if the <literal>BDB</literal> log files are corrupted. See <xref linkend="starting-server"/>. </para> @@ -2776,6 +2801,10 @@ <xref linkend="binary-log"/>. </para> + <para> + See also <xref linkend="server-system-variables"/>. + </para> + </section> <section id="bdb-characteristics"> @@ -2869,7 +2898,9 @@ uniquely identified. If you don't create one explicitly, MySQL creates and maintains a hidden <literal>PRIMARY KEY</literal> for you. The hidden key has a length of five - bytes and is incremented for each insert attempt. + bytes and is incremented for each insert attempt. This key + does not appear in the output of <literal>SHOW CREATE + TABLE</literal> or <literal>DESCRIBE</literal>. </para> </listitem> @@ -2967,9 +2998,9 @@ <para> <literal>LOCK TABLES</literal> works on <literal>BDB</literal> tables as with other tables. If you - don't use <literal>LOCK TABLE</literal>, MySQL issues an - internal multiple-write lock on the table (a lock that - doesn't block other writers) to ensure that the table is + do not use <literal>LOCK TABLES</literal>, MySQL issues an + internal multiple-write lock on the table (a lock that does + not block other writers) to ensure that the table is properly locked if another thread issues a table lock. </para> </listitem> @@ -3019,12 +3050,12 @@ <listitem> <para> - If you get full disk with a <literal>BDB</literal> table, + If you get a full disk with a <literal>BDB</literal> table, you get an error (probably error 28) and the transaction should roll back. This contrasts with <literal>MyISAM</literal> and <literal>ISAM</literal> - tables, for which <command>mysqld</command> waits for enough - free disk before continuing. + tables, for which <command>mysqld</command> waits for sufficient free disk + space before continuing. </para> </listitem> @@ -3045,8 +3076,7 @@ <literal>BDB</literal> tables, you should not have a very large table cache (for example, with a size larger than 256) and you should use the <option>--no-auto-rehash</option> - option when you use the <command>mysql</command> client. We - plan to partly fix this in 4.0. + option when you use the <command>mysql</command> client. </para> </listitem> @@ -3088,8 +3118,7 @@ <listitem> <para> - Change to not use page locks at all for table scanning - operations. + Change to use no page locks for table scanning operations. </para> </listitem> @@ -3116,10 +3145,11 @@ <para> Each <literal>BDB</literal> table stores in the <filename>.db</filename> file the path to the file as it was - created. This was done to be able to detect locks in a - multi-user environment that supports symlinks. However, the - consequence is that <literal>BDB</literal> table files - cannot be moved from one database directory to another. + created. This was done enable detection of locks in a + multi-user environment that supports symlinks. As a + consequence of this, it is not possible to move + <literal>BDB</literal> table files from one database + directory to another. </para> </listitem> @@ -3160,9 +3190,9 @@ <listitem> <para> If the following error occurs when you start - <command>mysqld</command>, it means that the new - <literal>BDB</literal> version doesn't support the old log - file format: + <command>mysqld</command> after upgrading, it means that the + new <literal>BDB</literal> version doesn't support the old + log file format: </para> <programlisting> @@ -3455,8 +3485,8 @@ <para> If you examine the <filename>test.CSV</filename> file in the - database directory after executing the preceding statements, its - contents look like this: + database directory created by executing the preceding statements, + its contents should look like this: </para> <programlisting> @@ -3473,7 +3503,7 @@ <section id="blackhole-storage-engine"> - <title id="title-blackhole-storage-engine"/> + <title id="title-blackhole-storage-engine">&title-blackhole-storage-engine;</title> <indexterm> <primary><literal>BLACKHOLE</literal> storage engine</primary> @@ -3492,35 +3522,7 @@ The <literal>BLACKHOLE</literal> storage engine was added in MySQL 4.1.11. This engine acts as a <quote>black hole</quote> that accepts data but throws it away and does not store it. Retrievals - always return the empty set. - </para> - - <para> - To enable this storage engine, use the - <option>--with-blackhole-storage-engine</option> option to - <command>configure</command> when you build MySQL. The - <literal>BLACKHOLE</literal> storage engine is available in - MySQL-supplied server binaries beginning with MySQL 4.1.12; you - can determine whether or not your version supports this engine by - viewing the output of <literal>SHOW ENGINES</literal> or - <literal>SHOW VARIABLES LIKE 'have%'</literal>. - </para> - - <para> - When you create a <literal>BLACKHOLE</literal> table, the server - creates a table definition file in the database directory. The - file begins with the table name and has an - <filename>.frm</filename> extension. There are no other files - associated with the table. - </para> - - <para> - Inserts into a <literal>BLACKHOLE</literal> table do not store any - data, but if the binary log is enabled, the SQL statements are - logged (and replicated to slave servers). This can be useful when - you need a record of statements that have been issued, but do not - require immediate, <quote>live</quote> access to the data. - </para> + always return the empty set: <programlisting> mysql> <userinput>CREATE TABLE test(i INT, c CHAR(10)) ENGINE = BLACKHOLE;</userinput> @@ -3533,10 +3535,102 @@ mysql> <userinput>SELECT * FROM test;</userinput> Empty set (0.00 sec) </programlisting> + </para> + + <para> + When you create a <literal>BLACKHOLE</literal> table, the server + creates a table definition file in the database directory. The + file begins with the table name and has an + <filename>.frm</filename> extension. There are no other files + associated with the table. + </para> <para> The <literal>BLACKHOLE</literal> storage engine supports all kinds of indexing. + </para> + + <para> + To enable this storage engine, use the + <option>--with-blackhole-storage-engine</option> option to + <command>configure</command> when you build MySQL. The + <literal>BLACKHOLE</literal> storage engine is available in + MySQL-supplied server binaries beginning with MySQL 4.1.12; you + can determine whether or not your version supports this engine by + viewing the output of <literal>SHOW ENGINES</literal> or <literal>SHOW VARIABLES LIKE + 'have%'</literal>. + </para> + + <para> + Inserts into a <literal>BLACKHOLE</literal> table do not store any + data, but if the binary log is enabled, the SQL statements are + logged (and replicated to slave servers). This can be useful as a + repeater or filter mechanism. For example, suppose that your + application requires slave-side filtering rules, but transfering + all binlog data to the slave first results in too much traffic. + In such a case, it is possible to set up on the master host a + <quote>dummy</quote> slave process whose default storage engine is + <literal>BLACKHOLE</literal>, depicted as follows: + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/blackhole-1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase lang="en">Replication using <literal>BLACKHOLE</literal> + for filtering</phrase> + </textobject> + </mediaobject> + + <para> + The master writes to its binary log. The <quote>dummy</quote> + <literal>mysqld</literal> process acts as a slave, applying the + desired combination of <literal>replicate-do</literal> and + <literal>replicate-ignore</literal> rules, and writes a new, + filtered binlog of its own. (See + <xref linkend="replication-options"/>.) This filtered log is + provided to the slave. + </para> + + <para> + Since the dummy process does not actually store any data, there is + little processing over head incurred by running the additional + <literal>mysqld</literal> process on the replication master host. + This type of setup can be repeated with additional replication + slaves. + </para> + + <para> + Other possible uses for the <literal>BLACKHOLE</literal> storage + engine include: + + <itemizedlist> + + <listitem> + <para> + Verification of dumpfile syntax. + </para> + </listitem> + + <listitem> + <para> + Measurement of the overhead from binary logging, by + comparing performance using <literal>BLACKHOLE</literal> + with and without binary logging enabled. + </para> + </listitem> + + <listitem> + <para> + since <literal>BLACKHOLE</literal> is essentially a + <quote>no-op</quote> storage engine, it could be used for + finding performance bottlenecks not related to the storage + engine itself. + </para> + </listitem> + + </itemizedlist> </para> </section> --- 1.23/refman/storage-engines.xml 2005-09-07 07:13:08 +10:00 +++ 1.24/refman/storage-engines.xml 2005-09-07 13:21:53 +10:00 @@ -303,16 +303,16 @@ <xref linkend="alter-table"/>. </para> -<!-- - We should consider removing this or making a new section 'What - happens when a table is created'. Currently it seems a bit out of - place and not that helpful. - --> - -<!-- - TODO: this behavior now may be "using the default storage engine" - rather than "using MyISAM", but when did that change? ---> + <remark> + We should consider removing this or making a new section 'What + happens when a table is created'. Currently it seems a bit out of + place and not that helpful. + </remark> + + <remark role="todo"> + This behavior now may be "using the default storage engine" rather + than "using MyISAM", but when did that change? + </remark> <para> If you try to use a storage engine that is not compiled in or that @@ -1610,7 +1610,9 @@ <secondary>partitioning</secondary> </indexterm> -<!-- description_for_help_topic MERGE --> + <remark> + description_for_help_topic MERGE + </remark> <para> The <literal>MERGE</literal> storage engine was introduced in @@ -1631,7 +1633,9 @@ <literal>AVG_ROW_LENGTH</literal>, <literal>MAX_ROWS</literal>, or <literal>PACK_KEYS</literal> do not matter. -<!-- end_description_for_help_topic --> + <remark> + end_description_for_help_topic + </remark> </para> <para> @@ -1680,7 +1684,9 @@ <literal>MERGE</literal> table: </para> -<!-- example_for_help_topic MERGE --> + <remark> + example_for_help_topic MERGE + </remark> <programlisting> mysql> <userinput>CREATE TABLE t1 (</userinput> @@ -1791,10 +1797,11 @@ disks. A <literal>MERGE</literal> table on this could be much faster than using the big table. -<!-- (You can also use a RAID table to get the same --> + <remark> + (You can also use a RAID table to get the same kind of + benefits.) + </remark> </para> - -<!-- kind of benefits.) --> </listitem> <listitem> @@ -2072,9 +2079,10 @@ <title id='title-memory-storage-engine'>&title-memory-storage-engine;</title> -<!-- TODO: parts of this may be true only for hash indexes. Now that --> - -<!-- MEMORY supports BTREE indexes, some statements may need to be qualified. --> + <remark role="todo"> + Parts of this may be true only for hash indexes. Now that MEMORY + supports BTREE indexes, some statements may need to be qualified. + </remark> <indexterm> <primary><literal>HEAP</literal> storage engine</primary> @@ -2180,7 +2188,7 @@ length supported by this storage engine was 255 bytes; as of MySQL 4.1.13 and MySQL 5.0.8, <literal>MEMORY</literal> tables support a maximum key length of 500 bytes. (See - <xref linkend="news-4-1-3"/>, <xref linkend="news-5-0-8"/>.) + <xref linkend="news-4-1-3"/> and <xref linkend="news-5-0-8"/>.) </para> </listitem> @@ -3075,8 +3083,8 @@ <listitem> <para> - <literal>SHOW TABLE STATUS</literal> does not yet provide - some information for <literal>BDB</literal> tables: + <literal>SHOW TABLE STATUS</literal> does not provide some + information for <literal>BDB</literal> tables: </para> <programlisting> @@ -3766,7 +3774,7 @@ </itemizedlist> <para> - <emphasis role="bold">Retrieval:</emphasis> On retrieval, records + <emphasis role="bold">Retrieval</emphasis>: On retrieval, records are uncompressed on demand; there is no row cache. A <literal>SELECT</literal> operation performs a complete table scan: When a <literal>SELECT</literal> occurs, it finds out how @@ -3869,7 +3877,7 @@ <section id="blackhole-storage-engine"> - <title id='title-blackhole-storage-engine'>&title-blackhole-storage-engine;</title> + <title id="title-blackhole-storage-engine">&title-blackhole-storage-engine;</title> <indexterm> <primary><literal>BLACKHOLE</literal> storage engine</primary> @@ -3888,35 +3896,7 @@ The <literal>BLACKHOLE</literal> storage engine was added in MySQL 4.1.11. This engine acts as a <quote>black hole</quote> that accepts data but throws it away and does not store it. Retrievals - always return the empty set. - </para> - - <para> - To enable this storage engine, use the - <option>--with-blackhole-storage-engine</option> option to - <command>configure</command> when you build MySQL. The - <literal>BLACKHOLE</literal> storage engine is available in - MySQL-supplied server binaries beginning with MySQL 4.1.12; you - can determine whether or not your version supports this engine by - viewing the output of <literal>SHOW ENGINES</literal> or - <literal>SHOW VARIABLES LIKE 'have%'</literal>. - </para> - - <para> - When you create a <literal>BLACKHOLE</literal> table, the server - creates a table definition file in the database directory. The - file begins with the table name and has an - <filename>.frm</filename> extension. There are no other files - associated with the table. - </para> - - <para> - Inserts into a <literal>BLACKHOLE</literal> table do not store any - data, but if the binary log is enabled, the SQL statements are - logged (and replicated to slave servers). This can be useful when - you need a record of statements that have been issued, but do not - require immediate, <quote>live</quote> access to the data. - </para> + always return the empty set: <programlisting> mysql> <userinput>CREATE TABLE test(i INT, c CHAR(10)) ENGINE = BLACKHOLE;</userinput> @@ -3929,10 +3909,102 @@ mysql> <userinput>SELECT * FROM test;</userinput> Empty set (0.00 sec) </programlisting> + </para> + + <para> + When you create a <literal>BLACKHOLE</literal> table, the server + creates a table definition file in the database directory. The + file begins with the table name and has an + <filename>.frm</filename> extension. There are no other files + associated with the table. + </para> <para> The <literal>BLACKHOLE</literal> storage engine supports all kinds of indexing. + </para> + + <para> + To enable this storage engine, use the + <option>--with-blackhole-storage-engine</option> option to + <command>configure</command> when you build MySQL. The + <literal>BLACKHOLE</literal> storage engine is available in + MySQL-supplied server binaries beginning with MySQL 4.1.12; you + can determine whether or not your version supports this engine by + viewing the output of <literal>SHOW ENGINES</literal> or + <literal>SHOW VARIABLES LIKE 'have%'</literal>. + </para> + + <para> + Inserts into a <literal>BLACKHOLE</literal> table do not store any + data, but if the binary log is enabled, the SQL statements are + logged (and replicated to slave servers). This can be useful as a + repeater or filter mechanism. For example, suppose that your + application requires slave-side filtering rules, but transfering + all binlog data to the slave first results in too much traffic. + In such a case, it is possible to set up on the master host a + <quote>dummy</quote> slave process whose default storage engine is + <literal>BLACKHOLE</literal>, depicted as follows: + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/blackhole-1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase lang="en">Replication using <literal>BLACKHOLE</literal> + for filtering</phrase> + </textobject> + </mediaobject> + + <para> + The master writes to its binary log. The <quote>dummy</quote> + <literal>mysqld</literal> process acts as a slave, applying the + desired combination of <literal>replicate-do</literal> and + <literal>replicate-ignore</literal> rules, and writes a new, + filtered binlog of its own. (See + <xref linkend="replication-options"/>.) This filtered log is + provided to the slave. + </para> + + <para> + Since the dummy process does not actually store any data, there is + little processing over head incurred by running the additional + <literal>mysqld</literal> process on the replication master host. + This type of setup can be repeated with additional replication + slaves. + </para> + + <para> + Other possible uses for the <literal>BLACKHOLE</literal> storage + engine include: + + <itemizedlist> + + <listitem> + <para> + Verification of dumpfile syntax. + </para> + </listitem> + + <listitem> + <para> + Measurement of the overhead from binary logging, by + comparing performance using <literal>BLACKHOLE</literal> + with and without binary logging enabled. + </para> + </listitem> + + <listitem> + <para> + since <literal>BLACKHOLE</literal> is essentially a + <quote>no-op</quote> storage engine, it could be used for + finding performance bottlenecks not related to the storage + engine itself. + </para> + </listitem> + + </itemizedlist> </para> </section> --- 1.16/refman-5.0/storage-engines.xml 2005-09-07 07:15:51 +10:00 +++ 1.17/refman-5.0/storage-engines.xml 2005-09-07 13:21:53 +10:00 @@ -311,7 +311,7 @@ </remark> <remark role="todo"> - this behavior now may be "using the default storage engine" rather + This behavior now may be "using the default storage engine" rather than "using MyISAM", but when did that change? </remark> @@ -654,8 +654,8 @@ <listitem> <para> - <command>myisamchk</command> marks tables as checked if run - using the <option>--update-state</option> option. + <command>myisamchk</command> marks tables as checked if you + run it with the <option>--update-state</option> option. <command>myisamchk --fast</command> checks only those tables that don't have this mark. </para> @@ -664,7 +664,7 @@ <listitem> <para> <command>myisamchk --analyze</command> stores statistics for - key parts, as well as for entire keys. + portions of keys, as well as for entire keys. </para> </listitem> @@ -802,7 +802,7 @@ <para> Used to help MySQL to decide when to use the slow but safe key cache index creation method. - <emphasis role="bold">Note</emphasis>: This was parameter + <emphasis role="bold">Note</emphasis>: This parameter was given in bytes before MySQL 5.0.6, when it was removed. </para> </listitem> @@ -1229,7 +1229,7 @@ <para> All MySQL distributions include <command>myisampack</command> - by default. Compressed tablescan be uncompressed with + by default. Compressed tables can be uncompressed with <command>myisamchk</command>. </para> @@ -1251,7 +1251,7 @@ <para> Each record is compressed separately, so there is very little access overhead. The header for a record takes up - 1-3 bytes depending on the biggest record in the table. + 1 to 3 bytes depending on the biggest record in the table. Each column is compressed differently. There is usually a different Huffman tree for each column. Some of the compression types are: @@ -1602,11 +1602,12 @@ The <literal>MERGE</literal> storage engine, also known as the <literal>MRG_MyISAM</literal> engine, is a collection of identical <literal>MyISAM</literal> tables that can be used as one. - "Identical" means that all tables have identical column and index - information. You cannot merge tables in which the columns are - listed in a different order, don't have exactly the same columns, - or have the indexes in different order. However, any or all of the - tables can be compressed with <command>myisampack</command>. See + <quote>Identical</quote> means that all tables have identical + column and index information. You cannot merge tables in which the + columns are listed in a different order, do not have exactly the + same columns, or have the indexes in different order. However, any + or all of the tables can be compressed with + <command>myisampack</command>. See <xref linkend="myisampack"/>. Differences in table options such as <literal>AVG_ROW_LENGTH</literal>, <literal>MAX_ROWS</literal>, or <literal>PACK_KEYS</literal> do not matter. @@ -3034,8 +3035,8 @@ <listitem> <para> - <literal>SHOW TABLE STATUS</literal> does not yet provide - some information for <literal>BDB</literal> tables: + <literal>SHOW TABLE STATUS</literal> does not provide some + information for <literal>BDB</literal> tables: </para> <programlisting> @@ -3097,7 +3098,7 @@ <para> Each <literal>BDB</literal> table stores in the <filename>.db</filename> file the path to the file as it was - created. This was done to be able to detect locks in a + created. This was done enable detection of locks in a multi-user environment that supports symlinks. As a consequence of this, it is not possible to move <literal>BDB</literal> table files from one database @@ -3736,7 +3737,7 @@ </itemizedlist> <para> - <emphasis role="bold">Retrieval:</emphasis> On retrieval, records + <emphasis role="bold">Retrieval</emphasis>: On retrieval, records are uncompressed on demand; there is no row cache. A <literal>SELECT</literal> operation performs a complete table scan: When a <literal>SELECT</literal> occurs, it finds out how @@ -3838,7 +3839,7 @@ <section id="blackhole-storage-engine"> - <title id="title-blackhole-storage-engine"/> + <title id="title-blackhole-storage-engine">&title-blackhole-storage-engine;</title> <indexterm> <primary><literal>BLACKHOLE</literal> storage engine</primary> @@ -3855,36 +3856,9 @@ <para> The <literal>BLACKHOLE</literal> storage engine acts as a - <quote>black hole</quote> that accepts data but throws it away and - does not store it. Retrievals always return the empty set. - </para> - - <para> - To enable this storage engine, use the - <option>--with-blackhole-storage-engine</option> option to - <command>configure</command> when you build MySQL. The - <literal>BLACKHOLE</literal> storage engine is available in - MySQL-supplied server binaries; you can determine whether or not - your version supports this engine by viewing the output of - <literal>SHOW ENGINES</literal> or <literal>SHOW VARIABLES LIKE - 'have%'</literal>. - </para> - - <para> - When you create a <literal>BLACKHOLE</literal> table, the server - creates a table definition file in the database directory. The - file begins with the table name and has an - <filename>.frm</filename> extension. There are no other files - associated with the table. - </para> - - <para> - Inserts into a <literal>BLACKHOLE</literal> table do not store any - data, but if the binary log is enabled, the SQL statements are - logged (and replicated to slave servers). This can be useful when - you need a record of statements that have been issued, but do not - require immediate, <quote>live</quote> access to the data. - </para> + <quote>black hole</quote> that + accepts data but throws it away and does not store it. Retrievals + always return the empty set: <programlisting> mysql> <userinput>CREATE TABLE test(i INT, c CHAR(10)) ENGINE = BLACKHOLE;</userinput> @@ -3897,10 +3871,102 @@ mysql> <userinput>SELECT * FROM test;</userinput> Empty set (0.00 sec) </programlisting> + </para> + + <para> + When you create a <literal>BLACKHOLE</literal> table, the server + creates a table definition file in the database directory. The + file begins with the table name and has an + <filename>.frm</filename> extension. There are no other files + associated with the table. + </para> <para> The <literal>BLACKHOLE</literal> storage engine supports all kinds of indexing. + </para> + + <para> + To enable this storage engine, use the + <option>--with-blackhole-storage-engine</option> option to + <command>configure</command> when you build MySQL. The + <literal>BLACKHOLE</literal> storage engine is available in + MySQL-supplied server binaries; you can determine whether or not + your version supports this engine by viewing the output of + <literal>SHOW ENGINES</literal> or <literal>SHOW VARIABLES LIKE + 'have%'</literal>. + </para> + + <para> + Inserts into a <literal>BLACKHOLE</literal> table do not store any + data, but if the binary log is enabled, the SQL statements are + logged (and replicated to slave servers). This can be useful as a + repeater or filter mechanism. For example, suppose that your + application requires slave-side filtering rules, but transfering + all binlog data to the slave first results in too much traffic. + In such a case, it is possible to set up on the master host a + <quote>dummy</quote> slave process whose default storage engine is + <literal>BLACKHOLE</literal>, depicted as follows: + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/blackhole-1.png" format="PNG"/> + </imageobject> + <textobject> + <phrase lang="en">Replication using <literal>BLACKHOLE</literal> + for filtering</phrase> + </textobject> + </mediaobject> + + <para> + The master writes to its binary log. The <quote>dummy</quote> + <literal>mysqld</literal> process acts as a slave, applying the + desired combination of <literal>replicate-do</literal> and + <literal>replicate-ignore</literal> rules, and writes a new, + filtered binlog of its own. (See + <xref linkend="replication-options"/>.) This filtered log is + provided to the slave. + </para> + + <para> + Since the dummy process does not actually store any data, there is + little processing over head incurred by running the additional + <literal>mysqld</literal> process on the replication master host. + This type of setup can be repeated with additional replication + slaves. + </para> + + <para> + Other possible uses for the <literal>BLACKHOLE</literal> storage + engine include: + + <itemizedlist> + + <listitem> + <para> + Verification of dumpfile syntax. + </para> + </listitem> + + <listitem> + <para> + Measurement of the overhead from binary logging, by + comparing performance using <literal>BLACKHOLE</literal> + with and without binary logging enabled. + </para> + </listitem> + + <listitem> + <para> + since <literal>BLACKHOLE</literal> is essentially a + <quote>no-op</quote> storage engine, it could be used for + finding performance bottlenecks not related to the storage + engine itself. + </para> + </listitem> + + </itemizedlist> </para> </section>
| Thread | ||
|---|---|---|
| • bk commit - mysqldoc@docsrva tree (jon:1.3490) | jon | 7 Sep |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 1.072 sec. using MySQL 5.1.14-beta-log