| List: | Commits | « Previous MessageNext Message » | |
| From: | plavin | Date: | May 15 2007 6:11pm |
| Subject: | svn commit - mysqldoc@docsrva: r6465 - trunk/userguide | ||
| View as plain text | |||
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 @@ <title>The MySQL Client</title> <para> - 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 <command>mysql</command>, the command-line, client program. Use <command>mysql</command> to: @@ -39,24 +39,21 @@ </para> <para> - 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. </para> - + <para> - However, we won't be discussing SQL commands here - Next to the MySQL server, the <command>mysql</command> 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. </para> <!-- start essential options --> @@ -70,8 +67,8 @@ connecting to a MySQL server possible and also change the way that the <command>mysql</command> 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: </para> <itemizedlist> @@ -113,10 +110,15 @@ <note> <para> 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. </para> </note> @@ -136,15 +138,15 @@ <para> Any of the utilities that require a connection to the MySQL - server, will require <option>host, port, user</option>, and - <option>password</option> options. For this reason, these options - will be required by many of the utility programs discussed here. + server, will have <option>host, port, user</option>, and + <option>password</option> 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. </para> <para> - The basic syntax for using <command>mysql</command> to open a - console window and communicate with a MySQL server is as - follows: + To open a <command>mysql</command> console window and communicate + with a MySQL server, type the following: </para> <programlisting> @@ -154,16 +156,17 @@ <note> <para> If you have only just installed MySQL and have not yet defined - any MySQL users then specify the default, <literal>root</literal>, 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, + <literal>root</literal>, as the user name. There is no password + for this default user. For information on creating additional + users see <xref>. </para> </note> <para> The same effect can be achieved using the short forms of the above - options. Starting <command>mysql</command> using short forms is as follows: + options. Starting <command>mysql</command> using short forms is as + follows: </para> <programlisting> @@ -171,10 +174,19 @@ </programlisting> <para> + Specifying a password immediately after the <option>-p</option> + option is not a requirement but if you do so no space is permitted + between the option <option>-p</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. + </para> + + <para> Fortunately, both the <option>host</option> and <option>port</option> 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 <literal>3306</literal>, and for the host + value for the port is <literal>3306</literal>, and for the host, <literal>localhost</literal>. Most MySQL servers listen on port <literal>3306</literal> and typically you will connect to a server running on the same machine as the MySQL client. @@ -199,7 +211,7 @@ </para> <programlisting> -shell> echo <userinput>echo $USER</userinput> +shell> <userinput>echo $USER</userinput> </programlisting> <warning> @@ -215,16 +227,24 @@ <para> If this user name is a valid user name for the MySQL server then you need not specify the <option>--user</option> option in order - to connect. + to connect. Connecting to a MySQL server can be as simple as: </para> +<programlisting> +shell> <userinput>mysql <option>-p</option></userinput> +</programlisting> + <para> - Specifying a password immediately after the <option>-p</option> option is not - a requirement but if you do so no space is permitted between the - option <option>-p</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 + <command>mysql</command> 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>. + + <remark> + no longer use these options from this point on? + </remark> </para> </section> @@ -292,7 +312,7 @@ <listitem> <para> - <option>tee=<replaceable>outfile</replaceable>, -T + <option>--tee=<replaceable>outfile</replaceable>, -T <replaceable>outfile</replaceable></option> – copy output to the specified file </para> @@ -319,9 +339,10 @@ <para> The <option>--auto-rehash</option> 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 <option>--skip-auto-rehash</option>. </para> @@ -329,25 +350,24 @@ If you wish to start the MySQL client using a specific database, use the <option>--database=<replaceable>dbname</replaceable></option> - option. In addition to using the short form, - <option>-D <replaceable>dbname</replaceable></option>, - 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 <command>use + option. In addition to using the short form, <option>-D + <replaceable>dbname</replaceable></option>, 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 <command>use <replaceable>dbname</replaceable></command> command. </para> <para> - 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>--execute=<replaceable>statement</replaceable></option> option. For example, the following command shows all the records in a specific table: </para> <programlisting> -shell> mysql -u <option>user_name</option> -p -e "SELECT * FROM <replaceable>dbname.table_name</replaceable>;" + shell> <command>mysql -u <option>user_name</option> -p --execute="SELECT * FROM <replaceable>dbname.table_name</replaceable>;"</command> </programlisting> <para> @@ -363,17 +383,18 @@ need to be familiar with the <option>--tee=<replaceable>file_name</replaceable></option> option — an option that copies all the output of - <command>mysql</command> to a text file. To create an - HTML file of all statements issue the following command: + <command>mysql</command> to a text file. To create an HTML file of + all statements issue the following command: </para> <programlisting> -shell> <userinput>mysql -u <option>user_name</option> -p --tee=outfile.html --html</userinput> +shell> <userinput>mysql -u <option>user_name</option> -p --tee=<replaceable>outfile.html</replaceable> --html</userinput> </programlisting> - + <para> - <emphasis>Note</emphasis>: There is no short form for the - <option>--tee=<replaceable>file_name</replaceable></option> option. + <emphasis>Note</emphasis>: There is no short form for the + <option>--tee=<replaceable>file_name</replaceable></option> + option. </para> <para> @@ -383,124 +404,193 @@ way to begin creating a script file. Script files are dealt with in more detail in <xref>. </para> - + <para> - prompt + The <option>--prompt</option> 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>. </para> <para> - For a complete list of all the available options see - <ulink url="&base-url-refman;5.0/en/mysql.html"/>. + As noted earlier, only selected <command>mysql</command> options + are discussed here. For a complete list see + <ulink url="&base-url-refman;5.0/en/mysql.html"/> or, at the + command line simply type <userinput>mysql -?</userinput>. </para> - - <para> - it can be quite cumbersome to specify options at the command line. - - </para> </section> <section id="mysql-client-commands"> - <title><command>mysql</command> Commands</title> - + <title>The <command>mysql</command> Commands</title> + <para> - Once the MySQL client is open + Once you have opened the MySQL client you can use the + <command>mysql</command> commands. A shortlist of the most useful + commands follows: </para> - - <itemizedlist> - + <listitem> <para> - <command>help, \?, ?</command> – display the available commands + <command>help <replaceable>[argument]</replaceable>, \? + <replaceable>[argument]</replaceable>, ? + <replaceable>[argument]</replaceable></command> – + display the available commands, provide assistance with SQL </para> </listitem> - + <listitem> <para> <command>exit, quit, \q</command> – exit the MySQL shell </para> </listitem> - + <listitem> <para> - <command>notee</command> – stop capturing output to file + <command>notee, \t</command> – stop capturing output to + file </para> </listitem> - + <listitem> <para> - <command>source, \.</command> – + <command>source, \. + <replaceable>file_name</replaceable></command> – run a + script file </para> </listitem> - + <listitem> <para> - <command>tee <replaceable>file_name</replaceable>, \T <replaceable>file_name</replaceable></command> – - copy output to the specified file + <command>tee <replaceable>file_name</replaceable>, \T + <replaceable>file_name</replaceable></command> – copy + output to the specified file </para> </listitem> - + <listitem> <para> - <command>use <replaceable>dbname</replaceable>, \u <replaceable>dbname</replaceable></command> – + <command>use <replaceable>dbname</replaceable>, \u + <replaceable>dbname</replaceable></command> – </para> </listitem> - + </itemizedlist> - <para> - the <command>mysql</command> client is interactive The long forms + The <command>mysql</command> client is interactive The long forms of commands can be issued by typing the command name with or - without a <literal>‘;’</literal>. For example, the commands - <command>help;</command> and <command>help</command> produce the - same output. + without a <literal>‘;’</literal>. For example, the + commands <command>help;</command> and <command>help</command> + produce the same output. </para> <para> - Some of the commands are identical to the options shown in - <xref linkend="mysql-client-other-options"/>. For - example issuing the <command>tee - <replaceable>outfile.txt</replaceable></command> command is - identical to using the start-up option <option>--tee - <replaceable>outfile.txt</replaceable></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 <command>no-tee</command> command. + To quit the MySQL shell use one of the forms of the + <command>quit</command> command. </para> - + <para> - On the other hand, the <command>help</command> - command, though it shares the same name as the <option>--help</option> - option, outputs commands only. + To execute a script file use the <command>source</command> + command. You can also execute script commands by redirecting a + file to the <command>mysql</command> command. This is done on all + operating systems by using the redirection operator like so; + <userinput>mysql -u <replaceable>user_name</replaceable> -p < + <replaceable>script.sql</replaceable></userinput>. Using script files is especially useful + when you have repetitive tasks to perform. Script files are + discussed in detail in <xref>. </para> <para> - + To avoid having to fully qualify a table name by + preceding it with the database name, use the + <command>use <replaceable>dbname</replaceable></command> command. + This command makes the specified database the default database. </para> - - + <para> + Some of the commands are identical to the options shown in + <xref linkend="mysql-client-other-options"/>. For example issuing + the <command>tee <replaceable>outfile.txt</replaceable></command> + command is identical to using the start-up option <option>--tee + <replaceable>outfile.txt</replaceable></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 <command>no-tee</command> command. + </para> + + <para> + On the other hand, the <command>help</command> command, though it + shares the same name as the <option>--help</option> 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 - <ulink url="&base-url-refman;5.0/en/mysql-commands.html"/>. + <ulink url="&base-url-refman;5.0/en/mysql-commands.html"/> or + from the <command>mysql</command> shell issue the command + <userinput>?</userinput>. </para> + <para> + However, the <command>help</command> command does a lot more than + list available commands. For this reason the next section is + devoted entirely to this command. + </para> + </section> - <section id="using-mysql-client"> + <section id="mysql-client-help-command"> - <title>Using <command>mysql</command></title> + <title>Using the <command>help</command> Command</title> <para> + It is very easy to overlook the usefulness of the + <command>help</command> command. Firstly, it is easily confused + with the <option>--help</option> option. Secondly, you may + mistakenly believe that it only displays a list of the + <command>mysql</command> commands. + </para> + + <para> + To see just how helpful this command can be, + from the <command>mysql</command> shell, issue the command + <command>help</command> followed by the argument, + <literal>contents</literal>. Doing this results in the following + display: + </para> + +<programlisting> + 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 +</programlisting> + + <para> + Now try issuing the <userinput>? Functions</userinput> command. </para> <para> - redirection operator to accept input from file + a recent release then the help database </para> </section>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r6465 - trunk/userguide | plavin | 15 May |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.650 sec. using MySQL 5.1.14-beta-log