svn commit - mysqldoc@docsrva: r6428 - trunk/userguide

[plavin]

Author: plavin
Date: 2007-05-11 18:31:55 +0200 (Fri, 11 May 2007)
New Revision: 6428

Log:
Additions to mysqladmin

Modified:
   trunk/userguide/mysqladmin.xml


Modified: trunk/userguide/mysqladmin.xml
===================================================================
--- trunk/userguide/mysqladmin.xml	2007-05-11 03:56:07 UTC (rev 6427)
+++ trunk/userguide/mysqladmin.xml	2007-05-11 16:31:55 UTC (rev 6428)
Changed blocks: 5, Lines Added: 185, Lines Deleted: 28; 9443 bytes

@@ -7,34 +7,36 @@
 ]>
 <chapter id="user-guide-mysqladmin">
 
-  <title>Using <command>mysqladmin</command></title>
+  <title><command>mysqladmin</command></title>
 
   <para>
-    The <command>mysqladmin</command> utility is a client utility for
-    administering a MySQL seerver.
+    The <command>mysqladmin</command> program is a client utility for
+    administering a MySQL server.
   </para>
 
   <para>
     As is the case with most MySQL utilities, there are often other
-    alternatives to using mysqladmin. The GUI Tool, MySQL Administrator,
-    for example, can do most of the tasks performed by mysqladmin. This
-    is an especially useful administrative tool especially if you are
-    new to MySQL. This application is examined in detail in &lt;xref&gt;.
-    Likewise, many of the capabilities of mysqladmin are also available
-    when using the MySQL client program. 
+    alternatives to using <command>mysqladmin</command>. The GUI Tool,
+    MySQL Administrator, for example, can do most of the tasks performed
+    by <command>mysqladmin</command> and is a very useful administrative
+    tool especially if you are new to MySQL. This application is
+    examined in detail in &lt;xref&gt;. Likewise, many of the
+    capabilities of <command>mysqladmin</command> are also available
+    when using the MySQL client program.
   </para>
-  
-  <para>
-    
-    approach to administrative
-    tasks if you use <literal>ssh</literal> to sometimes no access to
-  </para>
 
   <para>
-    This chapter shows how to make to use mysqladmin for
-    essential tasks. It is not meant as a definite treatment of
-    <literal>mysqladmin</literal>; for complete coverage of this utility
-    see <ulink url="&base-url-refman;5.0/en/mysqladmin.html"/>.
+    However, the MySQL server may be running on a machine that does not
+    have a GUI; for instance, most web servers would fall into this
+    category. <command>mysqladmin</command> offers a convenient
+    alternative that allows you to perform common tasks quickly from the
+    command line without starting up a GUI application or the MySQL
+    client. This chapter shows to use <command>mysqladmin</command> for
+    these kinds of tasks. It is not meant as a definite treatment of
+    <command>mysqladmin</command>; for complete coverage of this utility
+    see <ulink url="&base-url-refman;5.0/en/mysqladmin.html"/>. The more
+    advanced commands and options of <command>mysqladmin</command> will
+    be discussed in more detail in &lt;xref&gt;.
   </para>
 
 <!-- start options -->

@@ -44,10 +46,11 @@
     <title>Options and Commands</title>
 
     <para>
-      Unlike other utilities, <literal>mysqladmin</literal> supports
+      Unlike other utilities, <command>mysqladmin</command> supports
       both commands and options. This section identifies the most
-      commonly used options and briefly describes each one. Examples of
-      using these options are given in subsequent sections.
+      commonly used options and commands and briefly describes each one.
+      Examples of using these options and commands are given in
+      subsequent sections.
     </para>
 
     <para>

@@ -58,24 +61,24 @@
 
       <listitem>
         <para>
-          create <replaceable>db_name</replaceable> &ndash; create a
+          <command>create</command>
<replaceable>db_name</replaceable> &ndash; create a
           database
         </para>
       </listitem>
 
       <listitem>
         <para>
-          drop <replaceable>db_name</replaceable> &ndash; drop a
+          <command>drop</command>
<replaceable>db_name</replaceable> &ndash; drop a
           database
         </para>
       </listitem>
 
       <listitem>
         <para>
-          ping &ndash; check that the MySQL server is running
+          <command>ping</command> &ndash; check that the MySQL server is
running
         </para>
       </listitem>
-      
+
       <listitem>
         <para>
           <command>shutdown</command> &ndash; bring down the MySQL

@@ -97,7 +100,8 @@
     </para>
 
     <para>
-      Other essential mysqladmin options are as follows:
+      Apart from the options mentioned above, other essential
+      <command>mysqladmin</command> options are as follows:
 
       <itemizedlist>
 

@@ -119,11 +123,164 @@
     </para>
 
     <para>
-      For a complete list of all the available options see
+      For a complete list of all the available options and commands see
       <ulink url="&base-url-refman;5.0/en/mysqladmin.html"/>.
     </para>
 
   </section>
 
+  <section id="using-mysqladmin">
+
+    <title>Using <command>mysqladmin</command></title>
+
+    <para>
+      This section is concerned with the <command>mysqladmin</command>
+      commands and options listed in the previous section, discussing
+      them in more detail with the exception of the
+      <option>--help</option> option since this option functions in
+      exactly the same way for all the MySQL programs.
+    </para>
+
+    <section>
+
+      <title>Shutting Down the Server</title>
+
+      <para>
+        The most common use for <command>mysqladmin</command> is to shut
+        down the MySQL server. This is done in the following way:
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysqladmin shutdown <option>-u
<replaceable>user_name</replaceable> -p</option></userinput>     

+</programlisting>
+
+      <para>
+        <emphasis>Note</emphasis>: This is a command rather than an
+        option so do not precede <literal>shutdown</literal> with
+        &rsquo;<literal>--</literal>&lsquo;. The reasons for shutting
+        down a MySQL server are various:
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              you wish to start the server with different options
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              you have changed the configuration file
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              you wish to back up data
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        This command is used extensively in &lt;xref&gt;. In that
+        section we examine the configuration file
+        (<filename>my.ini</filename> under Windows, <filename>
+        my.cnf</filename> under Unix). In order for configuration
+        changes to have effect the server must be stopped and restarted.
+      </para>
+
+    </section>
+
+    <section>
+
+      <title>Creating and Dropping Databases</title>
+
+      <para>
+        Instead of issuing an SQL command to create a database, you can
+        create one using <command>mysqladmin</command> in the following
+        way:
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysqladmin create
<replaceable>db_name</replaceable> <option>-u
<replaceable>user_name</replaceable></option>
<option>-p</option></userinput>      
+</programlisting>
+
+      <para>
+        You can just as easily remove a database using the <command>drop
+        <replaceable>db_name</replaceable></command> command. To avoid
+        confirming your action use this command with the
+        <option>-f</option> option.
+      </para>
+
+    </section>
+
+    <section id="mysqladmin-ping-server">
+
+      <title>Checking that the Server is Running</title>
+
+      <para>
+        If your MySQL server is running, go to the command line and
+        issue the command:
+      </para>
+
+<programlisting>
+shell&gt; <userinput>mysqladmin ping <option>-u
<replaceable>user_name</replaceable> -p</option></userinput>     

+</programlisting>
+
+      <para>
+        This should result in the message, <literal>mysqld is
+        alive</literal>, confirming that your MySQL server is running.
+      </para>
+
+      <para>
+        If you are working in a development environment, shut down the
+        server using <command>mysqladmin</command> and the
+        <command>shutdown</command> command. Try connecting to the
+        server using the MySQL client <command>mysql</command>. On
+        Windows you should see the error message:
+      </para>
+
+<programlisting>
+ERROR 2003 (HY000) Can't connect to MySQL server on 'localhost' (10061)
+</programlisting>
+
+      <para>
+        The message on Unix systems is slightly different:
+      </para>
+
+<programlisting>
+ERROR 2002 (HY000): Can't connect to local MySQL server through socket 
+'/var/lib/mysql/mysql.sock' (2)  
+</programlisting>
+
+      <para>
+        Familiarize yourself with these error messages because you will
+        see them again &mdash; but probably by accident and not, as in
+        this case, by design. In most situations, these errors indicate
+        that the MySQL server is not running
+      </para>
+
+      <para>
+        Execute <command>mysqladmin</command> once more with the
+        <command>ping</command> command, to see the message displayed
+        when the server is down. You should see:
+      </para>
+
+<programlisting>
+mysqladmin: connect to server at 'localhost' failed
+error: Can't connect to MySQL server  ...
+Check that mysqld is running
+</programlisting>
+
+      <para>
+        To restart the server on Unix [and Mac] systems issue the
+        command, <command>mysqld_safe</command> and on Windows,
+        <command>mysqld</command> (?).
+      </para>
+
+    </section>
+
+  </section>
+
 </chapter>
 <!-- END mysqladmin CHAPTER -->