From: Date: May 15 2007 6:11pm
Subject: svn commit - mysqldoc@docsrva: r6465 - trunk/userguide
List-Archive: http://lists.mysql.com/commits/26718
Message-Id: <200705151611.l4FGB8dr011156@docsrva.mysql.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Author: plavin
Date: 2007-05-15 18:11:05 +0200 (Tue, 15 May 2007)
New Revision: 6465
Log:
Clean up and add section on the help command
Modified:
trunk/userguide/mysql-client.xml
Modified: trunk/userguide/mysql-client.xml
===================================================================
--- trunk/userguide/mysql-client.xml 2007-05-15 14:26:01 UTC (rev 6464)
+++ trunk/userguide/mysql-client.xml 2007-05-15 16:11:05 UTC (rev 6465)
Changed blocks: 14, Lines Added: 205, Lines Deleted: 115; 20178 bytes
@@ -10,8 +10,8 @@
The MySQL Client
- To interact with a database server you need a client program.
- The most useful client for interacting with a MySQL server is
+ To interact with a database server you need a client program. The
+ most useful client for interacting with a MySQL server is
mysql, the command-line, client program. Use
mysql to:
@@ -39,24 +39,21 @@
- Most often databases are integrated into applications and most of the
- interaction with the database server happens through the
- program's user interface. However,
- this is usually not a convenient way to create databases or database objects.
- Nor is it a convenient or conventional way of
- creating users or changing their privileges.
- Likewise, it is often helpful to test any SQL statements that are
- issued by a program. A convenient way to do this is to use the
+ Most often databases are integrated into applications and most of
+ the interaction with the database server happens through the
+ program's user interface. However, this is usually not a convenient
+ way to create databases or database objects. Nor is it a convenient
+ way of creating users or changing their privileges. Likewise, it is
+ often helpful to test any SQL statements that are issued by a
+ program. A convenient way to perform all these tasks is to use the
MySQL client.
-
+
- However, we won't be discussing SQL commands here
- Next to the MySQL server, the mysql program, is
- the most important program that ....
- The purpose of this section is to explain the options and commands
- most commonly used with the MySQL client. Using these options and commands
- is essential
+ However, we won't be discussing SQL commands here. The purpose of
+ this section is to explain the options and commands most commonly
+ used with the MySQL client. Using these options and commands is an
+ essential part of mastering MySQL.
@@ -70,8 +67,8 @@
connecting to a MySQL server possible and also change the way that
the mysql client program behaves. Some of these
options are absolutely essential, some are nice to know, and
- others are used infrequently. We will deal with the essential
- and nice-to-know options. Essential options are as follows:
+ others are used infrequently. We will deal with the essential and
+ nice-to-know options. Essential options are as follows:
@@ -113,10 +110,15 @@
The commonly used options of any MySQL program typically have a
- long and a short form. When an option is first introduced, using
- the long form is helpful for reasons of clarity. Once an option
- has been introduced, the short form is preferred for the sake
- of brevity.
+ long and a short form. The long form is always a full word
+ preceded by two dashes and followed by an equals sign and a
+ value, if a value is required. The short form is a single
+ letter, upper or lower case, preceded by one dash and followed
+ by a space and a value if required. (The short form of the
+ password option is the only exception to this rule and will be
+ dealt with shortly.) When an option is first introduced, using
+ the long form is helpful for reasons of clarity. Afterwards, the
+ short form is preferred for the sake of brevity.
@@ -136,15 +138,15 @@
Any of the utilities that require a connection to the MySQL
- server, will require , and
- options. For this reason, these options
- will be required by many of the utility programs discussed here.
+ server, will have , and
+ options. The syntax for using these
+ options is the same for all the various MySQL programs so
+ mastering the use of these options here pays future benefits.
- The basic syntax for using mysql to open a
- console window and communicate with a MySQL server is as
- follows:
+ To open a mysql console window and communicate
+ with a MySQL server, type the following:
@@ -154,16 +156,17 @@
If you have only just installed MySQL and have not yet defined
- any MySQL users then specify the default, root, as
- the user name. There is no password for this default
- user. For information on creating additional users see
- <xref>.
+ any MySQL users then specify the default,
+ root, as the user name. There is no password
+ for this default user. For information on creating additional
+ users see <xref>.
The same effect can be achieved using the short forms of the above
- options. Starting mysql using short forms is as follows:
+ options. Starting mysql using short forms is as
+ follows:
@@ -171,10 +174,19 @@
+ Specifying a password immediately after the
+ option is not a requirement but if you do so no space is permitted
+ between the option and the password. Omitting
+ the password value following the password option is considered
+ more secure. If you do this, you are prompted for a password and
+ asterisks replace any letters typed.
+
+
+
Fortunately, both the and
options have default values so you need not
supply them every time you connect to a MySQL server. The default
- value for the port is 3306, and for the host
+ value for the port is 3306, and for the host,
localhost. Most MySQL servers listen on port
3306 and typically you will connect to a server
running on the same machine as the MySQL client.
@@ -199,7 +211,7 @@
-shell> echo echo $USER
+shell> echo $USER
@@ -215,16 +227,24 @@
If this user name is a valid user name for the MySQL server then
you need not specify the option in order
- to connect.
+ to connect. Connecting to a MySQL server can be as simple as:
+
+shell> mysql
+
+
- Specifying a password immediately after the option is not
- a requirement but if you do so no space is permitted between the
- option and the password. Omitting the password
- value following the password option is considered more secure. If
- you do this, you are prompted for a password and asterisks replace
- any letters typed.
+ With the use of a configuration file, even this option need not be
+ specified at the command line. If you typically start up
+ mysql using a number of options, then storing
+ these options in a configuration file is a good way to simplify
+ things. Configuration files are discussed in detail in
+ <xref>.
+
+
+ no longer use these options from this point on?
+
@@ -292,7 +312,7 @@
- – copy
output to the specified file
@@ -319,9 +339,10 @@
The option is on by default. It
- enables completion of table and column names, like most Unix
- command shells and only works on Unix operating systems. For
- performance purposes you can turn this option off by specifying
+ enables automatic completion of table and column names, in the way
+ that most Unix command shells complete file names. Unfortunately,
+ this option only works on Unix operating systems. For performance
+ purposes you can turn this option off by specifying
.
@@ -329,25 +350,24 @@
If you wish to start the MySQL client using a specific database,
use the
- option. In addition to using the short form,
- ,
- you can also start the MySQL client
- using a specific database simply by specifying the database name
- at the command line. This option is equivalent to opening the
- MySQL client and then issuing a use
+ option. In addition to using the short form, , you can also start the
+ MySQL client using a specific database simply by specifying the
+ database name at the command line. This option is equivalent to
+ opening the MySQL client and then issuing a use
dbname command.
- To issue a single SQL command and the exit the client shell, use
- the
+ To execute a single SQL statement and then exit the client shell,
+ use the
option. For example, the following command shows all the records
in a specific table:
-shell> mysql -u -p -e "SELECT * FROM dbname.table_name;"
+ shell> mysql -u -p --execute="SELECT * FROM dbname.table_name;"
@@ -363,17 +383,18 @@
need to be familiar with the
option
— an option that copies all the output of
- mysql to a text file. To create an
- HTML file of all statements issue the following command:
+ mysql to a text file. To create an HTML file of
+ all statements issue the following command:
-shell> mysql -u -p --tee=outfile.html --html
+shell> mysql -u -p --tee=outfile.html --html
-
+
- Note: There is no short form for the
- option.
+ Note: There is no short form for the
+
+ option.
@@ -383,124 +404,193 @@
way to begin creating a script file. Script files are dealt with
in more detail in <xref>.
-
+
- prompt
+ The option allows you to customized the
+ prompt that the MySQL console displays. The prompt can be
+ configured in a variety of ways; to show the current date and
+ time, to display the default database, and the current server
+ version, for example. This topic will be dealt with in detail in
+ <xref>.
- For a complete list of all the available options see
- .
+ As noted earlier, only selected mysql options
+ are discussed here. For a complete list see
+ or, at the
+ command line simply type mysql -?.
-
-
- it can be quite cumbersome to specify options at the command line.
-
-
- <command>mysql</command> Commands
-
+ The <command>mysql</command> Commands
+
- Once the MySQL client is open
+ Once you have opened the MySQL client you can use the
+ mysql commands. A shortlist of the most useful
+ commands follows:
-
-
-
+
- help, \?, ? – display the available commands
+ help [argument], \?
+ [argument], ?
+ [argument] –
+ display the available commands, provide assistance with SQL
-
+
exit, quit, \q – exit the MySQL shell
-
+
- notee – stop capturing output to file
+ notee, \t – stop capturing output to
+ file
-
+
- source, \. –
+ source, \.
+ file_name – run a
+ script file
-
+
- tee file_name, \T file_name –
- copy output to the specified file
+ tee file_name, \T
+ file_name – copy
+ output to the specified file
-
+
- use dbname, \u dbname –
+ use dbname, \u
+ dbname –
-
+
-
- the mysql client is interactive The long forms
+ The mysql client is interactive The long forms
of commands can be issued by typing the command name with or
- without a ‘;’. For example, the commands
- help; and help produce the
- same output.
+ without a ‘;’. For example, the
+ commands help; and help
+ produce the same output.
- Some of the commands are identical to the options shown in
- . For
- example issuing the tee
- outfile.txt command is
- identical to using the start-up option . Being able to
- redirect output to a file after starting up the MySQL client can
- be very convenient when you only want to capture some and not all
- output to file. When you no longer wish to capture output,
- issue the no-tee command.
+ To quit the MySQL shell use one of the forms of the
+ quit command.
-
+
- On the other hand, the help
- command, though it shares the same name as the
- option, outputs commands only.
+ To execute a script file use the source
+ command. You can also execute script commands by redirecting a
+ file to the mysql command. This is done on all
+ operating systems by using the redirection operator like so;
+ mysql -u user_name -p <
+ script.sql. Using script files is especially useful
+ when you have repetitive tasks to perform. Script files are
+ discussed in detail in <xref>.
-
+ To avoid having to fully qualify a table name by
+ preceding it with the database name, use the
+ use dbname command.
+ This command makes the specified database the default database.
-
-
+
+ Some of the commands are identical to the options shown in
+ . For example issuing
+ the tee outfile.txt
+ command is identical to using the start-up option . Being able to
+ redirect output to a file after starting up the MySQL client can
+ be very convenient when you only want to capture some and not all
+ output to file. When you no longer wish to capture output, issue
+ the no-tee command.
+
+
+
+ On the other hand, the help command, though it
+ shares the same name as the option, when
+ issued without an argument, outputs a list of all the commands
+ and no options.
For a complete list of all the available commands see
- .
+ or
+ from the mysql shell issue the command
+ ?.
+
+ However, the help command does a lot more than
+ list available commands. For this reason the next section is
+ devoted entirely to this command.
+
+
-
+
- Using <command>mysql</command>
+ Using the <command>help</command> Command
+ It is very easy to overlook the usefulness of the
+ help command. Firstly, it is easily confused
+ with the option. Secondly, you may
+ mistakenly believe that it only displays a list of the
+ mysql commands.
+
+
+
+ To see just how helpful this command can be,
+ from the mysql shell, issue the command
+ help followed by the argument,
+ contents. Doing this results in the following
+ display:
+
+
+
+ You asked for help about help category: "Contents"
+ For more information, type 'help <item>', where <item> is one of the following
+ categories:
+ Account Management
+ Administration
+ Data Definition
+ Data Manipulation
+ Data Types
+ Functions
+ Functions and Modifiers for Use with GROUP BY
+ Geographic Features
+ Language Structure
+ Storage Engines
+ Stored Routines
+ Table Maintenance
+ Transactions
+ Triggers
+
+
+
+ Now try issuing the ? Functions command.
- redirection operator to accept input from file
+ a recent release then the help database