Imported freely distributable documentation from upstream MySQL 5.1.34 source tarball.

1 files changed, 454 insertions, 0 deletions

diff --git a/man/mysqlslap.1 b/man/mysqlslap.1
new file mode 100644
index 00000000000..8c9782060a4
--- /dev/null
+++ b/man/mysqlslap.1
@@ -0,0 +1,454 @@
+.\"     Title: \fBmysqlslap\fR
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
+.\"      Date: 03/31/2009
+.\"    Manual: MySQL Database System
+.\"    Source: MySQL 5.1
+.\"
+.TH "\fBMYSQLSLAP\fR" "1" "03/31/2009" "MySQL 5.1" "MySQL Database System"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+mysqlslap \- load emulation client
+.SH "SYNOPSIS"
+.HP 20
+\fBmysqlslap [\fR\fB\fIoptions\fR\fR\fB]\fR
+.SH "DESCRIPTION"
+.PP
+\fBmysqlslap\fR
+is a diagnostic program designed to emulate client load for a MySQL server and to report the timing of each stage. It works as if multiple clients are accessing the server.
+\fBmysqlslap\fR
+is available as of MySQL 5.1.4.
+.PP
+Invoke
+\fBmysqlslap\fR
+like this:
+.sp
+.RS 3n
+.nf
+shell> \fBmysqlslap [\fR\fB\fIoptions\fR\fR\fB]\fR
+.fi
+.RE
+.PP
+Some options such as
+\fB\-\-create\fR
+or
+\fB\-\-query\fR
+enable you to specify a string containing an SQL statement or a file containing statements. If you specify a file, by default it must contain one statement per line. (That is, the implicit statement delimiter is the newline character.) Use the
+\fB\-\-delimiter\fR
+option to specify a different delimiter, which enables you to specify statements that span multiple lines or place multiple statements on a single line. You cannot include comments in a file;
+\fBmysqlslap\fR
+does not understand them.
+.PP
+\fBmysqlslap\fR
+runs in three stages:
+.TP 3n
+1.
+Create schema, table, and optionally any stored programs or data you want to using for the test. This stage uses a single client connection.
+.TP 3n
+2.
+Run the load test. This stage can use many client connections.
+.TP 3n
+3.
+Clean up (disconnect, drop table if specified). This stage uses a single client connection.
+.sp
+.RE
+.PP
+Examples:
+.PP
+Supply your own create and query SQL statements, with 50 clients querying and 200 selects for each:
+.sp
+.RS 3n
+.nf
+mysqlslap \-\-delimiter=";" \\
+  \-\-create="CREATE TABLE a (b int);INSERT INTO a VALUES (23)" \\
+  \-\-query="SELECT * FROM a" \-\-concurrency=50 \-\-iterations=200
+.fi
+.RE
+.PP
+Let
+\fBmysqlslap\fR
+build the query SQL statement with a table of two
+INT
+columns and three
+VARCHAR
+columns. Use five clients querying 20 times each. Do not create the table or insert the data (that is, use the previous test's schema and data):
+.sp
+.RS 3n
+.nf
+mysqlslap \-\-concurrency=5 \-\-iterations=20 \\
+  \-\-number\-int\-cols=2 \-\-number\-char\-cols=3 \\
+  \-\-auto\-generate\-sql
+.fi
+.RE
+.PP
+Tell the program to load the create, insert, and query SQL statements from the specified files, where the
+\fIcreate.sql\fR
+file has multiple table creation statements delimited by
+\';'
+and multiple insert statements delimited by
+\';'. The
+\fB\-\-query\fR
+file will have multiple queries delimited by
+\';'. Run all the load statements, then run all the queries in the query file with five clients (five times each):
+.sp
+.RS 3n
+.nf
+mysqlslap \-\-concurrency=5 \\
+  \-\-iterations=5 \-\-query=query.sql \-\-create=create.sql \\
+  \-\-delimiter=";"
+.fi
+.RE
+.PP
+\fBmysqlslap\fR
+supports the options in the following list. It also reads option files and supports the options for processing them described at
+Section\ 4.2.3.2.1, \(lqCommand\-Line Options that Affect Option\-File Handling\(rq.
+.TP 3n
+\(bu
+\fB\-\-help\fR,
+\fB\-?\fR
+.sp
+Display a help message and exit.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\fR,
+\fB\-a\fR
+.sp
+Generate SQL statements automatically when they are not supplied in files or via command options.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-add\-autoincrement\fR
+.sp
+Add an
+AUTO_INCREMENT
+column to automatically generated tables. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-execute\-number=\fR\fB\fIN\fR\fR
+.sp
+Specify how many queries to generate automatically. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-guid\-primary\fR
+.sp
+Add a GUID\-based primary key to automatically generated tables. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-load\-type=\fR\fB\fItype\fR\fR
+.sp
+Specify the test load type. The allowable values are
+read
+(scan tables),
+write
+(insert into tables),
+key
+(read primary keys),
+update
+(update primary keys), or
+mixed
+(half inserts, half scanning selects). The default is
+mixed. This option was added in MySQL 5.1.16.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-secondary\-indexes=\fR\fB\fIN\fR\fR
+.sp
+Specify how many secondary indexes to add to automatically generated tables. By default, none are added. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-unique\-query\-number=\fR\fB\fIN\fR\fR
+.sp
+How many different queries to generate for automatic tests. For example, if you run a
+key
+test that performs 1000 selects, you can use this option with a value of 1000 to run 1000 unique queries, or with a value of 50 to perform 50 different selects. The default is 10. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-unique\-write\-number=\fR\fB\fIN\fR\fR
+.sp
+How many different queries to generate for
+\fB\-\-auto\-generate\-sql\-write\-number\fR. The default is 10. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-auto\-generate\-sql\-write\-number=\fR\fB\fIN\fR\fR
+.sp
+How many row inserts to perform on each thread. The default is 100. This option was added in MySQL 5.1.16.
+.TP 3n
+\(bu
+\fB\-\-commit=\fR\fB\fIN\fR\fR
+.sp
+How many statements to execute before committing. The default is 0 (no commits are done). This option was added in MySQL 5.1.21.
+.TP 3n
+\(bu
+\fB\-\-compress\fR,
+\fB\-C\fR
+.sp
+Compress all information sent between the client and the server if both support compression.
+.TP 3n
+\(bu
+\fB\-\-concurrency=\fR\fB\fIN\fR\fR,
+\fB\-c \fR\fB\fIN\fR\fR
+.sp
+The number of clients to simulate when issuing the
+SELECT
+statement.
+.TP 3n
+\(bu
+\fB\-\-create=\fR\fB\fIvalue\fR\fR
+.sp
+The file or string containing the statement to use for creating the table.
+.TP 3n
+\(bu
+\fB\-\-create\-schema=\fR\fB\fIvalue\fR\fR
+.sp
+The schema in which to run the tests. This option was added in MySQL 5.1.5.
+.TP 3n
+\(bu
+\fB\-\-csv[=\fR\fB\fIfile_name\fR\fR\fB]\fR
+.sp
+Generate output in comma\-separated values format. The output goes to the named file, or to the standard output if no file is given. This option was added in MySQL 5.1.5.
+.TP 3n
+\(bu
+\fB\-\-debug[=\fR\fB\fIdebug_options\fR\fR\fB]\fR,
+\fB\-# [\fR\fB\fIdebug_options\fR\fR\fB]\fR
+.sp
+Write a debugging log. The
+\fIdebug_options\fR
+string often is
+\'d:t:o,\fIfile_name\fR'.
+.TP 3n
+\(bu
+\fB\-\-debug\-check\fR
+.sp
+Print some debugging information when the program exits. This option was added in MySQL 5.1.21.
+.TP 3n
+\(bu
+\fB\-\-debug\-info\fR,
+\fB\-T\fR
+.sp
+Print debugging information and memory and CPU usage statistics when the program exits. This option was added in MySQL 5.1.21.
+.TP 3n
+\(bu
+\fB\-\-delimiter=\fR\fB\fIstr\fR\fR,
+\fB\-F \fR\fB\fIstr\fR\fR
+.sp
+The delimiter to use in SQL statements supplied in files or via command options.
+.TP 3n
+\(bu
+\fB\-\-detach=\fR\fB\fIN\fR\fR
+.sp
+Detach (close and reopen) each connection after each
+\fIN\fR
+statements. The default is 0 (connections are not detached). This option was added in MySQL 5.1.21.
+.TP 3n
+\(bu
+\fB\-\-engine=\fR\fB\fIengine_name\fR\fR,
+\fB\-e \fR\fB\fIengine_name\fR\fR
+.sp
+The storage engine to use for creating tables.
+.TP 3n
+\(bu
+\fB\-\-host=\fR\fB\fIhost_name\fR\fR,
+\fB\-h \fR\fB\fIhost_name\fR\fR
+.sp
+Connect to the MySQL server on the given host.
+.TP 3n
+\(bu
+\fB\-\-iterations=\fR\fB\fIN\fR\fR,
+\fB\-i \fR\fB\fIN\fR\fR
+.sp
+The number of times to run the tests.
+.TP 3n
+\(bu
+\fB\-\-lock\-directory=\fR\fB\fIpath\fR\fR
+.sp
+The directory to use for storing locks. This option was added in MySQL 5.1.5 and removed in 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-number\-char\-cols=\fR\fB\fIN\fR\fR,
+\fB\-x \fR\fB\fIN\fR\fR
+.sp
+The number of
+VARCHAR
+columns to use if
+\fB\-\-auto\-generate\-sql\fR
+is specified.
+.TP 3n
+\(bu
+\fB\-\-number\-int\-cols=\fR\fB\fIN\fR\fR,
+\fB\-y \fR\fB\fIN\fR\fR
+.sp
+The number of
+INT
+columns to use if
+\fB\-\-auto\-generate\-sql\fR
+is specified.
+.TP 3n
+\(bu
+\fB\-\-number\-of\-queries=\fR\fB\fIN\fR\fR
+.sp
+Limit each client to approximately this number of queries. This option was added in MySQL 5.1.5.
+.TP 3n
+\(bu
+\fB\-\-only\-print\fR
+.sp
+Do not connect to databases.
+\fBmysqlslap\fR
+only prints what it would have done. This option was added in MySQL 5.1.5.
+.TP 3n
+\(bu
+\fB\-\-password[=\fR\fB\fIpassword\fR\fR\fB]\fR,
+\fB\-p[\fR\fB\fIpassword\fR\fR\fB]\fR
+.sp
+The password to use when connecting to the server. If you use the short option form (\fB\-p\fR), you
+\fIcannot\fR
+have a space between the option and the password. If you omit the
+\fIpassword\fR
+value following the
+\fB\-\-password\fR
+or
+\fB\-p\fR
+option on the command line, you are prompted for one.
+.sp
+Specifying a password on the command line should be considered insecure. See
+Section\ 5.5.6.2, \(lqEnd\-User Guidelines for Password Security\(rq.
+.TP 3n
+\(bu
+\fB\-\-pipe\fR,
+\fB\-W\fR
+.sp
+On Windows, connect to the server via a named pipe. This option applies only for connections to a local server, and only if the server supports named\-pipe connections.
+.TP 3n
+\(bu
+\fB\-\-port=\fR\fB\fIport_num\fR\fR,
+\fB\-P \fR\fB\fIport_num\fR\fR
+.sp
+The TCP/IP port number to use for the connection.
+.TP 3n
+\(bu
+\fB\-\-post\-query=\fR\fB\fIvalue\fR\fR
+.sp
+The file or string containing the statement to execute after the tests have completed. This execution is not counted for timing purposes. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-shared\-memory\-base\-name=\fR\fB\fIname\fR\fR
+.sp
+On Windows, the shared\-memory name to use, for connections made via shared memory to a local server. This option applies only if the server supports shared\-memory connections.
+.TP 3n
+\(bu
+\fB\-\-post\-system=\fR\fB\fIstr\fR\fR
+.sp
+The string to execute via
+system()
+after the tests have completed. This execution is not counted for timing purposes. This option was added in MySQL 5.1.21.
+.TP 3n
+\(bu
+\fB\-\-pre\-query=\fR\fB\fIvalue\fR\fR
+.sp
+The file or string containing the statement to execute before running the tests. This execution is not counted for timing purposes. This option was added in MySQL 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-pre\-system=\fR\fB\fIstr\fR\fR
+.sp
+The string to execute via
+system()
+before running the tests. This execution is not counted for timing purposes. This option was added in MySQL 5.1.21.
+.TP 3n
+\(bu
+\fB\-\-preserve\-schema\fR
+.sp
+Preserve the schema from the
+\fBmysqlslap\fR
+run. The
+\fB\-\-auto\-generate\-sql\fR
+and
+\fB\-\-create\fR
+options disable this option. This option was added in MySQL 5.1.5 and removed in MySQL 5.1.23.
+.TP 3n
+\(bu
+\fB\-\-protocol={TCP|SOCKET|PIPE|MEMORY}\fR
+.sp
+The connection protocol to use for connecting to the server. It is useful when the other connection parameters normally would cause a protocol to be used other than the one you want. For details on the allowable values, see
+Section\ 4.2.2, \(lqConnecting to the MySQL Server\(rq.
+.TP 3n
+\(bu
+\fB\-\-query=\fR\fB\fIvalue\fR\fR,
+\fB\-q \fR\fB\fIvalue\fR\fR
+.sp
+The file or string containing the
+SELECT
+statement to use for retrieving data.
+.TP 3n
+\(bu
+\fB\-\-silent\fR,
+\fB\-s\fR
+.sp
+Silent mode. No output.
+.TP 3n
+\(bu
+\fB\-\-slave\fR
+.sp
+Follow master locks for other
+\fBmysqlslap\fR
+clients. Use this option if you are trying to synchronize around one master server with
+\fB\-\-lock\-directory\fR
+plus NFS. This option was added in MySQL 5.1.5 and removed in 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-socket=\fR\fB\fIpath\fR\fR,
+\fB\-S \fR\fB\fIpath\fR\fR
+.sp
+For connections to
+localhost, the Unix socket file to use, or, on Windows, the name of the named pipe to use.
+.TP 3n
+\(bu
+\fB\-\-ssl*\fR
+.sp
+Options that begin with
+\fB\-\-ssl\fR
+specify whether to connect to the server via SSL and indicate where to find SSL keys and certificates. See
+Section\ 5.5.7.3, \(lqSSL Command Options\(rq.
+.TP 3n
+\(bu
+\fB\-\-use\-threads\fR
+.sp
+On Unix, the default is to use
+fork()
+calls and this option causes
+\fBpthread\fR
+calls to be used instead. (On Windows, the default is to use
+pthread
+calls and the option has no effect.) This option was added in MySQL 5.1.6 and removed in 5.1.18.
+.TP 3n
+\(bu
+\fB\-\-user=\fR\fB\fIuser_name\fR\fR,
+\fB\-u \fR\fB\fIuser_name\fR\fR
+.sp
+The MySQL user name to use when connecting to the server.
+.TP 3n
+\(bu
+\fB\-\-verbose\fR,
+\fB\-v\fR
+.sp
+Verbose mode. Print more information about what the program does. This option can be used multiple times to increase the amount of information.
+.TP 3n
+\(bu
+\fB\-\-version\fR,
+\fB\-V\fR
+.sp
+Display version information and exit.
+.SH "COPYRIGHT"
+.PP
+Copyright 2007\-2008 MySQL AB, 2009 Sun Microsystems, Inc.
+.PP
+This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
+.PP
+This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+.PP
+You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110\-1301 USA or see http://www.gnu.org/licenses/.
+.SH "SEE ALSO"
+For more information, please refer to the MySQL Reference Manual,
+which may already be installed locally and which is also available
+online at http://dev.mysql.com/doc/.
+.SH AUTHOR
+MySQL AB (http://www.mysql.com/).