diff options
Diffstat (limited to 'Docs')
| -rw-r--r-- | Docs/Manual_style_guidelines.txt | 117 | ||||
| -rwxr-xr-x | Docs/Support/docbook-fixup.pl | 40 | ||||
| -rwxr-xr-x | Docs/Support/docbook-prefix.pl | 50 | ||||
| -rwxr-xr-x | Docs/Support/make-docbook | 3 | ||||
| -rw-r--r-- | Docs/manual.texi | 2479 |
5 files changed, 1445 insertions, 1244 deletions
diff --git a/Docs/Manual_style_guidelines.txt b/Docs/Manual_style_guidelines.txt index 9616fa6fae4..6c9294e5cad 100644 --- a/Docs/Manual_style_guidelines.txt +++ b/Docs/Manual_style_guidelines.txt @@ -55,6 +55,7 @@ singular form. The manual uses it as plural, which means you use "data are" rather than "data is". It's unfortunate that no matter which form we use, it will look incorrect to some people. But we can at least be internally consistent. +(Paul: I think that the O'Reilly proofread might have caught one or two of these; could you please pick up on these but don't change them back straight away until the book is finished? Thanks; Arjen). Write "press Enter", not "hit Return" or "hit Enter". @@ -70,7 +71,7 @@ Exceptions: - When showing the output from a program, show the output exactly; don't change "ok" to "okay", etc. -Write "Open Source", not "open source". +Write "Open Source" (inside @code{}), not "open source". To put something in quotes, do it ``like this,'' not "like this" or 'like this.' In the latter two cases, the quotes will come @@ -138,3 +139,117 @@ Write thread-safe, transaction-safe, replication-safe, not thread safe, transaction safe, replication safe. Write wildcard, not wild card or wild-card. + +Write "heavy-load production systems" (used as an adjective), +but "...used under heavy load" (used on its own). + +Write PostScript, not Postscript. + +When writing a list like "A, B, and C", include a comma before the last and. + +Write case-sensitive and case-insensitive (hyphenated). + +Write runtime, not run time. + +Write backward-compatible, not backward compatible or backwards compatible. + +Write application-related, not application related. + +Write filesystem, not file system. + +Write file-size, not file size. + +Write datafile, not data file. + +Write power-start, not power start. + +Write percent, not per cent. + +Write "toward", "and onward", not "towards", "onwards". + +Write third-party, not third party. + +Write turnkey, not turn-key. + +Write "the Net" (capitalised) if referring to the Internet in that way. + +Write long-awaited, not long awaited. + +Write natural-language, not natural language. + +Write low-volume <something> (when used as an adjective). + +Write platform-dependent, not platform dependent. + +Write something like "mentioned previously" instead of "above", and "later in this section" instead of "below" when making such relative references in your text. +Write "... shown here", not "... shown below". +Write "following some", not "something [shown] below". + +Write high-priority <something> (when used as an adjective), not high priority. + +Write "whether", not "whether or not". + +Write hand-held, not hand held. + +Write rewriting, not re-writing. + +Write re-issue(ing), not reissue(ing). + +Write command-line, not command line. + +Write server-side, not server side. + +Write "<blabla> only", not "only <blabla>". + +Write floating-point, not floating point. + +Write heavy-duty, not heavy duty. + +Write online, not on-line. + +Write user-defined, not user defined. + +Write multi-user, not multi user. + +Write multi-thread(ed), not multithread(ed). + +Write memory-based, not memory based. + +Write long-time <something> (when used as an adjective), not long time. + +Write 32-bit, not 32 bit or 32 bits. (Same goes for 64-bit, of course! ;-) + +Write "different from [what] ...", not "different than ...". + +Write "@-e.g., " instead of " e.g. " in the middle of a sentence. (The @- will be turned into a dash, or — for DocBook output.) +Following "e.g." by a comma, not a space or a colon. + +Write "@-" if you need to put a dash in a text, no surrounding spaces. + +Similar story for "for example" as for "e.g." + +Write CPU, not cpu (it's an acronym, not a word! ;-) + +Write "... uses ... CPU time", not "... uses ... CPU" (unless you're referring the processor itself.) + +If a (comment) is at the end of a sentence, start the comment with lowercase and put the . after the closing ), such as (like this). +If a comment is separate, start with uppercase and put the . inside the closing ). (Like this.) + +Write "something cannot do something", not "something can not something". + +Write "otherwise, ..." (with the comma) at the start of a sentence. + +Paul, could you please check "honoring"... is this proper British English? Thanks, Arjen. + +Write "byte-swapping", not "byte swapping". + +Write "Note:", not "NOTE:". And then continue with lowercase, it is not the start of a new sentence. + +Write "single-CPU" and "multiple-CPU", not "single CPU" and "multiple CPU". + +Paul, I think we should also decide whether to write Version or version, and in what situation. I am not changing much now because there's lots of funny instances and I don't want to risk getting it wrong. Thanks, Arjen. + +After a semicolon, don't use uppercase. It is NOT the start of a new sentence! + +It's "unstable", not "instable". ;-) + diff --git a/Docs/Support/docbook-fixup.pl b/Docs/Support/docbook-fixup.pl index 5528a114b87..f9934822f40 100755 --- a/Docs/Support/docbook-fixup.pl +++ b/Docs/Support/docbook-fixup.pl @@ -3,7 +3,7 @@ # Fix the output of `makeinfo --docbook` version 4.0c # Convert the broken docbook output to well-formed XML that conforms to the O'Reilly idiom # See code for detailed comments -# Authors: Arjen Lentz and Zak Greant +# Authors: Arjen Lentz and Zak Greant (original code by Jeremy Cole) use strict; @@ -13,7 +13,7 @@ my $apx = ''; my @nodes = (); my $nodes = ''; -msg ("\n-- Post-processing `makeinfo --docbook` output --"); +msg ("-- Post-processing `makeinfo --docbook` output --"); msg ("** Written to work with makeinfo version 4.0c **\n"); msg ("Discarding DTD - not required by subsequent scripts"); @@ -31,6 +31,26 @@ msg ("Add missing <bookinfo> and <abstract> opening tags"); # ...as soon as we find the first instance, we can stop looking. $data =~ s/<book lang="en">/<book lang="en"><bookinfo><abstract>/; + +# arjen 2002-05-01 +msg ("Processing docbook-prefix special strings"); +$data =~ s/FIXUPmdashFIXUP/\&mdash\;/g; + +$data =~ s/FIXUPdoubledashFIXUP/--/g; + +$data =~ s/FIXUPstrongFIXUP/<emphasis\ role\=bold>/g; +$data =~ s/FIXUPendstrongFIXUP/<\/emphasis>/g; + +$data =~ s/FIXUPemphFIXUP/<emphasis>/g; +$data =~ s/FIXUPendemphFIXUP/<\/emphasis>/g; + +$data =~ s/FIXUPfileFIXUP/<filename>/g; +$data =~ s/FIXUPendfileFIXUP/<\/filename>/g; + +$data =~ s/FIXUPsampFIXUP/<literal>/g; +$data =~ s/FIXUPendsampFIXUP/<\/literal>/g; + + msg ("Removing mailto: from email addresses..."); $data =~ s/mailto://g; @@ -38,9 +58,19 @@ msg ("Removing INFORMALFIGURE..."); $data =~ s{<informalfigure>.+?</informalfigure>} {}gs; -msg ("Convert ampersands to XML escape sequences "); +msg ("Convert ampersand to XML escape sequence..."); $data =~ s/&(?!\w+;)/&/g; - + +# arjen 2002-05-01 +msg ("Changing (TM) to XML escape sequence..."); +$data =~ s/MySQL \(TM\)/MySQL™/g; +$data =~ s{<command>TM</command>} + {™}g; + +# arjen 2002-05-01 +msg ("Changing ' -- ' to XML escape sequence..."); +$data =~ s/ -- /—/g; + msg ("Changing @@ to @..."); $data =~ s/@@/@/g; @@ -142,7 +172,7 @@ exit; # sub msg { - print STDERR shift, "\n"; + print STDERR "docbook-fixup:", shift, "\n"; } sub strip_tag($$) { diff --git a/Docs/Support/docbook-prefix.pl b/Docs/Support/docbook-prefix.pl new file mode 100755 index 00000000000..e76d84dbfe0 --- /dev/null +++ b/Docs/Support/docbook-prefix.pl @@ -0,0 +1,50 @@ +#!/usr/bin/perl -w + +# Preprocess the input of `makeinfo --docbook` version 4.0c +# Authors: Arjen Lentz and Zak Greant (started by arjen 2002-05-01) + +use strict; + +my $data = ''; + +msg ("-- Pre-processing `makeinfo --docbook` input --"); +msg ("** Written to work with makeinfo version 4.0c **\n"); + +# <> is a magic filehandle - either reading lines from stdin or from file(s) specified on the command line +msg ("Get the data"); +$data = join "", <>; + +msg ("Replacing '\@-' with FIXUPmdashFIXUP"); +$data =~ s/\@-/FIXUPmdashFIXUP/g; + +msg ("Replacing '--' with FIXUPdoubledashFIXUP"); +$data =~ s/--/FIXUPdoubledashFIXUP/g; + +msg ("Turning \@strong{} into LITERAL blocks"); +$data =~ s/\@strong\{(.*?)\}/FIXUPstrongFIXUP$1FIXUPendstrongFIXUP/gs; + +msg ("Turning \@emph{} into LITERAL blocks"); +$data =~ s/\@emph\{(.*?)\}/FIXUPemphFIXUP$1FIXUPendemphFIXUP/gs; + +msg ("Turning \@file{} into LITERAL blocks"); +$data =~ s/\@file\{(.*?)\}/FIXUPfileFIXUP$1FIXUPendfileFIXUP/gs; + +msg ("Turning \@samp{} into LITERAL blocks"); +$data =~ s/\@samp\{\@\{\}/FIXUPsampFIXUP\@\{FIXUPendsampFIXUP/g; +$data =~ s/\@samp\{\@\}\}/FIXUPsampFIXUP\@\}FIXUPendsampFIXUP/g; +$data =~ s/\@samp\{\@\{n\@\}\}/FIXUPsampFIXUP\@\{n\@\}FIXUPendsampFIXUP/g; +$data =~ s/\@samp\{(.*?)\}/FIXUPsampFIXUP$1FIXUPendsampFIXUP/gs; + + +msg ("Write the data"); +print STDOUT $data; +exit; + +# +# Definitions for helper sub-routines +# + +sub msg { + print STDERR "docbook-prefix: ", shift, "\n"; +} + diff --git a/Docs/Support/make-docbook b/Docs/Support/make-docbook index 90c1696e92b..93dbc56c0f8 100755 --- a/Docs/Support/make-docbook +++ b/Docs/Support/make-docbook @@ -17,7 +17,8 @@ sed -e 's;MYSQL_TCP_PORT_DEFAULT=;;' >> include.texi # produce DocBook XML - makeinfo --force --no-ifinfo --docbook -o - manual.texi |\ + Support/docbook-prefix.pl < manual.texi |\ + makeinfo --force --no-ifinfo --docbook -o - |\ Support/docbook-fixup.pl > mysql.xml # See if the XML output is well-formed diff --git a/Docs/manual.texi b/Docs/manual.texi index 07cd00766da..0c595c0dff4 100644 --- a/Docs/manual.texi +++ b/Docs/manual.texi @@ -148,13 +148,13 @@ for that version. The @code{MySQL (TM)} software delivers a very fast, multi-threaded, multi-user, and robust @code{SQL} (@code{Structured Query Language}) database server. -@code{MySQL Server} is intended for mission-critical, heavy load +@code{MySQL Server} is intended for mission-critical, heavy-load production systems as well as for embedding into mass-deployed software. @code{MySQL} is a trademark of @code{MySQL AB}. -The @code{MySQL} software has @code{Dual Licensing}, you can use +The @code{MySQL} software has @code{Dual Licensing}, which means you can use the @code{MySQL} software free of charge under the -@code{GNU GENERAL PUBLIC LICENSE} (@uref{http://www.gnu.org/licenses/}). +@code{GNU General Public License} (@uref{http://www.gnu.org/licenses/}). You can also purchase commercial @code{MySQL} licenses from @code{MySQL AB} if you do not wish to be bound by the terms of the @code{GPL}. @@ -163,7 +163,7 @@ You can also purchase commercial @code{MySQL} licenses from The @code{MySQL} web site (@uref{http://www.mysql.com/}) provides the latest information about the @code{MySQL} software. -The following list describes some useful sections of the manual: +The following list describes some sections of particular interest in this manual: @itemize @bullet @item @@ -210,7 +210,7 @@ For future plans, see @ref{TODO}. For a list of all the contributors to this project, see @ref{Credits}. @end itemize -@strong{IMPORTANT:} +@strong{Important}: Reports of errors (often called bugs), as well as questions and comments, should be sent to the mailing list at @email{mysql@@lists.mysql.com}. @@ -238,7 +238,7 @@ security bug in @code{MySQL Server}, you should send an e-mail to * MySQL Information Sources:: MySQL Information Sources * Compatibility:: How Standards-compatible Is MySQL? * TODO:: MySQL and the future (The TODO) -* Comparisons:: How MySQL Compares to Other Open Source Databases +* Comparisons:: How MySQL Compares to Other @code{Open Source} Databases @end menu @@ -253,18 +253,18 @@ Version @value{mysql_version}. Being a reference manual, it does not provide general instruction on @code{SQL} or relational database concepts. -As the @code{MySQL Database Software} is under continuous development, +As the @code{MySQL Database Software} is under constant development, the manual is also updated frequently. The most recent version of this manual is available at @uref{http://www.mysql.com/documentation/} in many different formats, -currently there are Texinfo, plain text, Info, HTML, PostScript, PDF, +including Texinfo, plain text, Info, HTML, PostScript, PDF, and Windows HLP versions. The primary document is the Texinfo file. The HTML version is produced automatically using a modified version of @code{texi2html}. The plain text and Info versions are produced with @code{makeinfo}. -The Postscript version is produced using @code{texi2dvi} and @code{dvips}. +The PostScript version is produced using @code{texi2dvi} and @code{dvips}. The PDF version is produced with @code{pdftex}. If you have a hard time finding information in the manual, you can try @@ -290,7 +290,9 @@ The copyright (2002) to this manual is owned by the Swedish company @node Manual conventions, , Manual-info, Manual-info @subsection Conventions Used in This Manual -This manual uses certain typographical conventions: +This manual uses British English spelling. + +Certain typographical conventions are followed: @cindex manual, typographical conventions @cindex typographical conventions @@ -299,7 +301,7 @@ This manual uses certain typographical conventions: @table @asis @item @code{constant} Constant-width font is used for command names and options; SQL statements; -database, table and column names; C and Perl code; and environment variables. +database, table, and column names; C and Perl code; and environment variables. Example: ``To see how @code{mysqladmin} works, invoke it with the @code{--help} option.'' @@ -368,7 +370,7 @@ your own database, table, and column names, perhaps like this: mysql> SELECT author_name FROM biblio_db.author_list; @end example -SQL keywords are not case sensitive and may be written in uppercase or +SQL keywords are not case-sensitive and may be written in uppercase or lowercase. This manual uses uppercase. In syntax descriptions, square brackets (@samp{[} and @samp{]}) are used @@ -432,18 +434,18 @@ A relational database stores data in separate tables rather than putting all the data in one big storeroom. This adds speed and flexibility. The tables are linked by defined relations making it possible to combine data from several tables on request. The @code{SQL} part of -``@code{MySQL}'' stands for ``@code{Structured Query Language}'' -- the most common standardised language used to access databases. +``@code{MySQL}'' stands for ``@code{Structured Query Language}''@-the +most common standardised language used to access databases. @cindex relational databases, defined @cindex SQL, defined -@item MySQL Software is Open Source. +@item MySQL software is @code{Open Source}. @code{Open Source} means that it is possible for anyone to use and modify. Anybody can download the @code{MySQL} software from the Internet and use it without paying anything. Anybody so inclined can study the source code and change it to fit their needs. The @code{MySQL} software uses the -@code{GPL} (@code{GNU General Public License}) +@code{GPL} (@code{GNU General Public License}), @uref{http://www.gnu.org/licenses/}, to define what you may and may not do with the software in different situations. If you feel uncomfortable with the @code{GPL} or need to embed @@ -451,7 +453,7 @@ If you feel uncomfortable with the @code{GPL} or need to embed commercially licensed version from us. @xref{MySQL licenses}. -@cindex Open Source, defined +@cindex @code{Open Source}, defined @cindex General Public License @item Why use the MySQL Database Server? @@ -467,7 +469,7 @@ of @code{MySQL Server} to some other database managers on our benchmark page. much faster than existing solutions and has been successfully used in highly demanding production environments for several years. Though under constant development, @code{MySQL Server} today offers a rich and -useful set of functions. The connectivity, speed, and security make +useful set of functions. Its connectivity, speed, and security make @code{MySQL Server} highly suited for accessing databases on the Internet. @item The technical features of MySQL Server @@ -479,7 +481,7 @@ several different client programs and libraries, administrative tools, and a wide range of programming interfaces (@code{API}s). We also provide @code{MySQL Server} as a multi-threaded library which you -can link into your application to get a smaller, faster, easier to manage +can link into your application to get a smaller, faster, easier-to-manage product. @item There is a large amount of contributed MySQL software available. @@ -550,10 +552,10 @@ a commercial memory leakage detector. @item Works on many different platforms. @xref{Which OS}. @item -Uses GNU Automake (1.4), Autoconf (Ver 2.52 or newer), and Libtool for +Uses GNU Automake (1.4), Autoconf (Version 2.52 or newer), and Libtool for portability. @item -APIs for C, C++, Eiffel, Java, Perl, PHP, Python and Tcl. @xref{Clients}. +APIs for C, C++, Eiffel, Java, Perl, PHP, Python, and Tcl. @xref{Clients}. @item Fully multi-threaded using kernel threads. This means it can easily use multiple CPUs if available. @@ -602,9 +604,12 @@ mysql> SELECT CONCAT(first_name, " ", last_name) @end example @item -Full support for SQL @code{GROUP BY} and @code{ORDER BY} clauses. Support -for group functions (@code{COUNT()}, @code{COUNT(DISTINCT ...)}, -@code{AVG()}, @code{STD()}, @code{SUM()}, @code{MAX()} and @code{MIN()}). +Full support for SQL @code{GROUP BY} and +@code{ORDER BY} clauses. Support +for group functions (@code{COUNT()}, +@code{COUNT(DISTINCT ...)}, +@code{AVG()}, @code{STD()}, +@code{SUM()}, @code{MAX()}, and @code{MIN()}). @item Support for @code{LEFT OUTER JOIN} and @code{RIGHT OUTER JOIN} with ANSI SQL and ODBC syntax. @@ -641,8 +646,8 @@ password traffic is encrypted when you connect to a server. @itemize @bullet @item Handles large databases. We are using @code{MySQL Server} with some -databases that contain 50,000,000 records and we know of users that -uses @code{MySQL Server} with 60,000 tables and about 5,000,000,000 rows. +databases that contain 50 million records and we know of users that +use @code{MySQL Server} with 60,000 tables and about 5,000,000,000 rows. @item Up to 32 indexes per table are allowed. Each index may consist of 1 to 16 columns or parts of columns. The maximum index width is 500 bytes @@ -673,13 +678,13 @@ the Scandinavian characters 'å', 'ä' and 'ö' are allowed in table and column names. @item All data is saved in the chosen character set. All comparisons for normal -string columns are case insensitive. +string columns are case-insensitive. @item Sorting is done according to the chosen character set (the Swedish way by default). It is possible to change this when the @code{MySQL} server is started. To see an example of very advanced sorting, look at the Czech sorting code. @code{MySQL Server} supports many different -character sets that can be specified at compile and run time. +character sets that can be specified at compile and runtime. @end itemize @item Clients and Tools @@ -709,8 +714,8 @@ questions that concern many potential users. The information in this section is based on data gathered from the mailing list, which is very active in identifying problems as well as reporting types of use. -Original code stems back from the early 80s, providing a stable code -base, and the ISAM table format remains backwards compatible. +Original code stems back from the early '80s, providing a stable code +base, and the ISAM table format remains backward-compatible. At TcX, the predecessor of @code{MySQL AB}, @code{MySQL} code has worked in projects since mid-1996, without any problems. When the @code{MySQL Database Software} was released to a wider public, @@ -731,7 +736,7 @@ exception of those listed in the bugs section, which are things that are design-related. @xref{Bugs}. The @code{MySQL Server} design is multi-layered with independent modules. -Some of the newer modules are listed below with an indication of how +Some of the newer modules are listed here with an indication of how well-tested each of them is: @cindex modules, list of @@ -745,7 +750,7 @@ in @code{MySQL} 4.0. @item @code{InnoDB} tables -- Stable (in 3.23 from 3.23.49) The @code{InnoDB} transactional table handler has now been declared stable in the @code{MySQL} 3.23 tree, starting from version 3.23.49. -@code{InnoDB} is being used in large, heavy load production systems. +@code{InnoDB} is being used in large, heavy-load production systems. @item @code{BDB} tables -- Gamma The @code{Berkeley DB} code is very stable, but we are still improving @@ -759,7 +764,7 @@ Important enhancements are being implemented for @code{MySQL} 4.0. @item @code{MyODBC 2.50} (uses ODBC SDK 2.5) -- Gamma Increasingly in wide use. Some issues brought up appear to be -application related and independent of the ODBC driver or underlying +application-related and independent of the ODBC driver or underlying database server. @item Automatic recovery of @code{MyISAM} tables -- Gamma @@ -776,7 +781,7 @@ This is very system-dependent. On some systems there are big problems using standard OS locking (@code{fcntl()}). In these cases, you should run @code{mysqld} with the @code{--skip-locking} flag. Problems are known to occur on some Linux systems, and on SunOS when -using NFS-mounted file systems. +using NFS-mounted filesystems. @end table @@ -791,19 +796,19 @@ bugs, there is almost always a new release. @cindex tables, maximum size @cindex size of tables -@cindex operating systems, file size limits -@cindex limits, file size +@cindex operating systems, file-size limits +@cindex limits, file-size @cindex files, size limits @code{MySQL} Version 3.22 has a 4G limit on table size. With the new @code{MyISAM} table type in @code{MySQL} Version 3.23, the maximum table size is pushed up to 8 million terabytes (2 ^ 63 bytes). -Note, however, that operating systems have their own file size +Note, however, that operating systems have their own file-size limits. Here are some examples: @multitable @columnfractions .30 .50 -@item @strong{Operating System} @tab @strong{File Size Limit} +@item @strong{Operating System} @tab @strong{File-Size Limit} @item Linux-Intel 32 bit @tab 2G, 4G or more, depends on Linux version @item Linux-Alpha @tab 8T (?) @item Solaris 2.5.1 @tab 2G (possible 4G with patch) @@ -813,7 +818,7 @@ limits. Here are some examples: @end multitable On Linux 2.2 you can get bigger tables than 2G by using the LFS patch for -the ext2 file system. On Linux 2.4 there exists also patches for ReiserFS +the ext2 filesystem. On Linux 2.4 patches also exist for ReiserFS to get support for big files. This means that the table size for @code{MySQL} databases is normally @@ -861,8 +866,8 @@ until @code{2069}; all 2-digit years are regarded to be in the range @code{year} column, @code{MySQL Server} treats it as @code{2001}. @item -All @code{MySQL} date functions are stored in one file @file{sql/time.cc} -and coded very carefully to be year 2000-safe. +All @code{MySQL} date functions are stored in one file, @file{sql/time.cc}, +and are coded very carefully to be year 2000-safe. @item In @code{MySQL} Version 3.22 and later, the new @code{YEAR} column type @@ -876,7 +881,7 @@ or manipulate years using 2-digit values (which are ambiguous) rather than 4-digit values. This problem may be compounded by applications that use values such as @code{00} or @code{99} as ``missing'' value indicators. -Unfortunately, these problems may be difficult to fix, because different +Unfortunately, these problems may be difficult to fix because different applications may be written by different programmers, each of whom may use a different set of conventions and date-handling functions. @@ -954,16 +959,16 @@ year values). @code{MySQL AB} is the company of the @code{MySQL} founders and main developers. @code{MySQL AB} was originally established in Sweden by -David Axmark, Allan Larsson and Michael @code{Monty} Widenius. +David Axmark, Allan Larsson, and Michael @code{Monty} Widenius. All the developers of the @code{MySQL} server are employed by the company. We are a virtual organisation with people in a dozen countries around -the world. We communicate extensively over the net every day with each +the world. We communicate extensively over the Net every day with each other and with our users, supporters and partners. We are dedicated to developing the @code{MySQL} software and spreading our database to new users. @code{MySQL AB} owns the copyright to the -@code{MySQL} source code, the @code{MySQL} logo and trademark and this +@code{MySQL} source code, the @code{MySQL} logo and trademark, and this manual. @xref{What-is}. @menu @@ -993,8 +998,8 @@ Free from bugs. @code{MySQL AB} and the people at @code{MySQL AB}: @itemize @bullet @item -Promote @code{Open Source} Philosophy and support the -@code{Open Source} Community. +Promote @code{Open Source} philosophy and support the +@code{Open Source} community. @item Aim to be good citizens. @item @@ -1018,7 +1023,7 @@ One of the most common questions we encounter is: ``@emph{How can you make a living from something you give away for free?}'' This is how. -@code{MySQL AB} makes money on support, services, commercial licenses +@code{MySQL AB} makes money on support, services, commercial licenses, and royalties, and we use these revenues to fund product development and to expand the @code{MySQL} business. @@ -1059,7 +1064,7 @@ To order support at various levels, please visit the order section at @cindex certification @cindex MySQL certification @code{MySQL AB} delivers @code{MySQL} and related training worldwide. -We offer both open courses and In-House courses tailored to the +We offer both open courses and in-house courses tailored to the specific needs of your company. @code{MySQL Training} is also available through our partners, the @code{Authorised MySQL Training Centers}. @@ -1082,7 +1087,7 @@ Reduce or eliminate the need for additional hardware, decreasing cost. @item Enhance security. @item -Increase customers and co-workers satisfaction. +Increase customers' and co-workers' satisfaction. @item Prepare yourself for @code{MySQL Certification}. @end itemize @@ -1092,7 +1097,7 @@ as a training partner, please visit the training section at @uref{http://www.mysql.com/training/} or contact us at: @email{training@@mysql.com}. -We plan to release the @code{MySQL Certification Program} in 2002, for +We plan to release the @code{MySQL Certification Program} in 2002. For details see @uref{http://www.mysql.com/training/certification.html}. If you would like to be kept informed about the @code{MySQL Certification Program}, @@ -1114,12 +1119,12 @@ applications, and more. We also help customers embed @code{MySQL Server} in their products and applications for large-scale deployment. -Our consultants work in close collaboration with our development team +Our consultants work in close collaboration with our development team, which ensures the technical quality of our professional services. -Consulting assignments range from 2-day power start sessions to -projects that span weeks and months. Our expertise does not only cover -@code{MySQL Server}, but extends into programming and scripting -languages such as PHP, Perl and more. +Consulting assignments range from 2-day power-start sessions to +projects that span weeks and months. Our expertise not only covers +@code{MySQL Server}, but also extends into programming and scripting +languages such as PHP, Perl, and more. If you are interested in our consulting services or want to become a consulting partner, please visit the consulting section of our web site @@ -1138,7 +1143,7 @@ as well), you may purchase a commercial license for the same product from @code{MySQL AB} at @uref{https://order.mysql.com/}. Since @code{MySQL AB} owns the copyright to the @code{MySQL} source code, we are able to employ @code{Dual Licensing} which means that the same -product is available both under @code{GPL} and under a commercial +product is available under @code{GPL} and under a commercial license. This does not in any way affect the @code{Open Source} commitment of @code{MySQL AB}. For details about when a commercial license is required, please see @ref{MySQL licenses}. @@ -1154,14 +1159,14 @@ key support, and more. @xref{InnoDB}. @subsubsection Partnering @cindex partnering with MySQL AB @code{MySQL AB} has a worldwide partner programme that covers training -courses, Consulting & Support, publications plus reselling and +courses, consulting & support, publications plus reselling and distributing @code{MySQL} and related products. @code{MySQL AB Partners} get visibility on the @uref{http://www.mysql.com/} web site and the right to use special versions of the @code{MySQL} trademarks to identify their products and promote their business. If you are interested in becoming a @code{MySQL AB Partner}, please e-mail -to @email{partner@@mysql.com}. +@email{partner@@mysql.com}. The word @code{MySQL} and the @code{MySQL} dolphin logo are trademarks of @code{MySQL AB}. @xref{MySQL AB Logos and Trademarks}. @@ -1174,13 +1179,13 @@ founders have built over the years. The @code{MySQL} web site (@uref{http://www.mysql.com/}) is popular among developers and users. In October 2001, we served 10 million page views. Our visitors represent a group that makes purchase decisions and -recommendations for both software and hardware. Twelve per cent of our -visitors authorise purchase decisions, and only nine per cent are not +recommendations for both software and hardware. Twelve percent of our +visitors authorise purchase decisions, and only nine percent are not involved in purchase decisions at all. More than 65% have made one or more online business purchase within the last half-year, and 70% plan to make one in the next months. -If you are interested in placing banner ads on our web site +If you are interested in placing banner ads on our web site, @uref{http://www.mysql.com/}, please send an e-mail message to @email{advertising@@mysql.com}. @@ -1202,7 +1207,7 @@ For press service and inquiries not covered in our News releases (@uref{http://www.mysql.com/news/}), please send e-mail to @email{press@@mysql.com}. -If you have a valid support contract with @code{MySQL AB}; you will +If you have a valid support contract with @code{MySQL AB}, you will get timely, precise answers to your technical questions about the @code{MySQL} software. For more information, see @ref{Support}. You can order your support contract at @@ -1258,7 +1263,7 @@ please send an e-mail message to @email{jobs@@mysql.com}. Please do not send your CV as an attachment, but rather as plain text at the end of your e-mail message. -For general discussion amongst our many users, please direct your +For general discussion among our many users, please direct your attention to the appropriate mailing list. @xref{Questions}. @@ -1297,7 +1302,7 @@ For all other inquires, please send e-mail to @email{info@@mysql.com}. @cindex licensing terms @cindex support terms -This section describes @code{MySQL} support and licensing arrangements: +This section describes @code{MySQL} support and licensing arrangements. @menu * Support:: Support Offered by MySQL AB @@ -1328,13 +1333,13 @@ important to you. Typically customers seek help on how to get different commands and utilities to work, remove performance bottlenecks, restore crashed systems, understand operating system or networking impacts on @code{MySQL}, -set-up best practices for backup and recovery, utilise @code{API}s, etc. +set up best practices for backup and recovery, utilise @code{API}s, etc. Our support covers only the @code{MySQL} server and our own utilities, not third-party products that access the @code{MySQL} server, though we try to help with these where we can. Detailed information about our various support options is given at -@uref{https://order.mysql.com/} where support contracts can also be +@uref{https://order.mysql.com/}, where support contracts can also be ordered online. If you have restricted access to the Internet, contact our sales staff at @email{sales@@mysql.com}. @@ -1356,21 +1361,21 @@ yourself. You may need immediate access to the most experienced @code{MySQL AB} owns the copyright to the @code{MySQL} source code, the @code{MySQL} logos and trademarks and this manual. @xref{What is MySQL AB}. -There are several different licenses relevant to the @code{MySQL} +Several different licenses are relevant to the @code{MySQL} distribution: @enumerate @item All the @code{MySQL}-specific source in the server, the @code{mysqlclient} -library and the client, as well as the @code{GNU} @code{readline} library, -is covered by the ``GNU GENERAL PUBLIC LICENSE.'' +library and the client, as well as the @code{GNU} @code{readline} library +is covered by the @code{GNU General Public License}. @xref{GPL license}. The text of this license can also be found as the file @file{COPYING} in the distributions. @item The @code{GNU} @code{getopt} library is covered by the -``GNU LESSER GENERAL PUBLIC LICENSE.'' +@code{GNU Lesser General Public License}. @xref{LGPL license}. @item @@ -1384,7 +1389,7 @@ more strict license See the documentation of the specific version for information. @item -The manual is currently @emph{not} distributed under a @code{GPL} style license. +The manual is currently @strong{not} distributed under a @code{GPL}-style license. Use of the manual is subject to the following terms: @itemize @bullet @item @@ -1437,7 +1442,7 @@ more strict license See the documentation of the specific version for information. Please note that the use of the @code{MySQL} software under commercial -license, @code{GPL} or the old @code{MySQL} license does not +license, @code{GPL}, or the old @code{MySQL} license does not automatically give you the right to use @code{MySQL AB} trademarks. @xref{MySQL AB Logos and Trademarks}. @@ -1467,7 +1472,7 @@ purchasing commercial licenses, you are not using the @code{MySQL} software under @code{GPL} even though it's the same code. @item -When you distribute a non-@code{GPL} application that ONLY works with the +When you distribute a non-@code{GPL} application that @strong{only} works with the @code{MySQL} software and ship it with the @code{MySQL} software. This type of solution is actually considered to be linking even if it's done over a network. @@ -1506,12 +1511,12 @@ You can use the @code{MySQL} software for free under the @code{GPL}: @itemize @bullet @item -When you link a program with code from the @code{MYSQL} software and +When you link a program with code from the @code{MySQL} software and release the resulting product under @code{GPL}. @item When you distribute the @code{MySQL} source code bundled with -other programs that are not linked to or dependant on @code{MySQL Server} +other programs that are not linked to or dependent on @code{MySQL Server} for their functionality even if you sell the distribution commercially. @item @@ -1534,7 +1539,7 @@ to our @code{announce} mailing list so that they can be aware of critical issues that may be relevant for their @code{MySQL} installations. Note that even if an ISP does not have a commercial license for -@code{MySQL} Server, they should at least give their customers read +@code{MySQL Server}, they should at least give their customers read access to the source of the @code{MySQL} installation so that the customers can verify that it is patched correctly. @@ -1542,16 +1547,16 @@ customers can verify that it is patched correctly. @cindex web server, running @cindex running a web server When you use the @code{MySQL} Database Software in conjunction with -a Web server, you do not need a commercial license. This is true even -if you run a commercial Web server that uses @code{MySQL} Server, because +a web server, you do not need a commercial license. This is true even +if you run a commercial web server that uses @code{MySQL Server}, because you are not selling an embedded @code{MySQL} version yourself. However, -in this case we would like you to purchase @code{MySQL} support, because +in this case we would like you to purchase @code{MySQL} support because the @code{MySQL} software is helping your enterprise. @end itemize If your use of @code{MySQL} database software does not require a commercial license, we encourage you to purchase support from @code{MySQL AB} anyway. -This way you contribute towards @code{MySQL} development and also gain +This way you contribute toward @code{MySQL} development and also gain immediate advantages for yourself. @xref{Support}. If you use the @code{MySQL} database software in a commercial context @@ -1571,8 +1576,8 @@ us to provide free support, too.) @cindex trademarks Many users of the @code{MySQL} database want to display the -@code{MySQL AB} dolphin logo on their web sites, on their books or -boxed products. We welcome and encourage this although it should be +@code{MySQL AB} dolphin logo on their web sites, books, or +boxed products. We welcome and encourage this, although it should be noted that the word @code{MySQL} and the @code{MySQL} dolphin logo are trademarks of @code{MySQL AB} and may only be used as stated in our trademark policy at @@ -1595,7 +1600,7 @@ our trademark policy at The @code{MySQL} dolphin logo was designed by the Finnish advertising agency Priority in 2001. The dolphin was chosen as a suitable symbol -for the @code{MySQL} database since it is a smart, fast and lean animal, +for the @code{MySQL} database since it is a smart, fast, and lean animal, effortlessly navigating oceans of data. We also happen to like dolphins. The original @code{MySQL} logo may only be used by representatives of @@ -1611,10 +1616,10 @@ to do so. We have designed a set of special @emph{Conditional Use} logos that may be downloaded from our web site at @uref{http://www.mysql.com/downloads/logos.html} -and used on third party web sites without written permission from +and used on third-party web sites without written permission from @code{MySQL AB}. -The use of these logos is not entirely unrestricted, but as the name -implies subject to our trademark policy that is also available on our +The use of these logos is not entirely unrestricted but, as the name +implies, subject to our trademark policy that is also available on our web site. You should read through the trademark policy if you plan to use them. The requirements are basically: @@ -1639,8 +1644,8 @@ to @uref{http://www.mysql.com/}. @item If you are using the @code{MySQL} database under @code{GPL} in an -application, your application must (i) be @code{Open Source}, -(ii) be able to connect to a @code{MySQL} server. +application, your application must be @code{Open Source} and +be able to connect to a @code{MySQL} server. @end itemize Contact us at @email{trademark@@mysql.com} to inquire about special @@ -1658,11 +1663,11 @@ When displaying any @code{MySQL AB} logo anywhere except on your web site. @item When displaying any @code{MySQL AB} logo except the @emph{Conditional Use} -logos above on web sites or elsewhere. +logos mentioned previously on web sites or elsewhere. @end itemize Out of legal and commercial reasons we have to monitor the use of MySQL -trademarks on products, books etc. We will usually require a fee for +trademarks on products, books, etc. We will usually require a fee for displaying @code{MySQL AB} logos on commercial products, since we think it is reasonable that some of the revenue is returned to fund further development of the @code{MySQL} database. @@ -1684,9 +1689,9 @@ Please see @ref{Business Services Partnering,,Partnering}. @code{MySQL AB} welcomes references to the @code{MySQL} database, but note that the word @code{MySQL} is a trademark of @code{MySQL AB}. -Because of this, you should append the trademark symbol @code{TM} to +Because of this, you should append the trademark symbol (@code{TM}) to the first or most prominent use of the word @code{MySQL} in a text and -where appropriate use a statement that @code{MySQL} is a trademark of +where appropriate, state that @code{MySQL} is a trademark of @code{MySQL AB}. Please refer to our trademark policy at @uref{http://www.mysql.com/company/trademark.html} for details. @@ -1707,9 +1712,9 @@ Long promised by @code{MySQL AB} and long awaited by our users, MySQL Server 4.0 is now available in alpha version for download from @uref{http://www.mysql.com/} and our mirrors. -Main new features of MySQL Server 4.0 are geared towards our existing +Main new features of MySQL Server 4.0 are geared toward our existing business and community users, enhancing the MySQL database software -as the solution for mission-critical, heavy load database systems. +as the solution for mission-critical, heavy-load database systems. Other new features target the users of embedded databases. @menu @@ -1728,7 +1733,7 @@ Other new features target the users of embedded databases. The rollout of MySQL Server 4.0 will come in several steps, with the first version labelled 4.0.0 already containing most of the new features. Additional features will be incorporated into -MySQL 4.0.1, 4.0.2 onwards; very probably within a couple of months, +MySQL 4.0.1, 4.0.2, and onward; very probably within a couple of months, MySQL 4.0 will be labelled beta. Further new features will then be added in MySQL 4.1, which is targeted for alpha release in third quarter 2002. @@ -1756,9 +1761,9 @@ applications. Using the embedded MySQL server library, one can embed MySQL Server into various applications and electronics devices, where the end user has no knowledge of there actually being an underlying database. Embedded MySQL Server is ideal for use behind -the scenes in internet appliances, public kiosks, turn-key -hardware/ software combination units, high performance internet -servers, self-contained databases distributed on CD-ROM etc. +the scenes in internet appliances, public kiosks, turnkey +hardware/software combination units, high performance internet +servers, self-contained databases distributed on CD-ROM, etc. Many users of @code{libmysqld} will benefit from the MySQL @emph{Dual Licensing}. For those not wishing to be bound by the GPL, @@ -1775,7 +1780,7 @@ client library, so it is convenient and easy to use. @xref{libmysqld}. Version 4.0 further increases @emph{the speed of MySQL Server} in a number of areas, such as bulk @code{INSERT}s, searching on packed indexes, creation of -@code{FULLTEXT} indexes as well as @code{COUNT(DISTINCT)}. +@code{FULLTEXT} indexes, as well as @code{COUNT(DISTINCT)}. @item The table handler @code{InnoDB} is now offered as a feature of the @@ -1786,38 +1791,37 @@ and @code{row-level locking}. MySQL Server 4.0 will support secure traffic between the client and the server, greatly increasing security against malicious intrusion and unauthorised access. Web applications being a cornerstone of MySQL use, web developers -have been able to use SSL to secure the traffic between the -the end user browser and the Web application, be it written in -PHP, Perl, ASP or using any other web development tool. However, -the traffic between the development tool and the mysqld server +have been able to use @code{Secure Socket Layer} (@code{SSL}) to secure the +traffic between the the end user browser and the web application, be it +written in PHP, Perl, ASP or using any other web development tool. However, +the traffic between the development tool and the @code{mysqld} server process has been protected only by virtue of them being processes residing on computers within the same firewall. In MySQL Server 4.0, -the @emph{mysqld} server daemon process can itself use -@code{Secure Sockets Layer} (@code{SSL}), +the @code{mysqld} server daemon process can itself use @code{SSL}, thus enabling secure traffic to MySQL databases from, say, a Windows application residing outside the firewall. @item -Our German, Austrian and Swiss users will note that we have a new character -set @code{latin_de} which corrects the @emph{German sorting order}, -placing German Umlauts in the same order as German telephone books. +Our German, Austrian, and Swiss users will note that we have a new character +set, @code{latin_de}, which corrects the @emph{German sorting order}, +placing German umlauts in the same order as German telephone books. @item Features to simplify migration from other database systems to MySQL Server include @code{TRUNCATE TABLE} (like in Oracle) and @code{IDENTITY} as a synonym for automatically incremented keys (like in Sybase). Many users will also be happy to learn that MySQL Server now supports the @code{UNION} statement, -a long awaited standard SQL feature. +a long-awaited standard SQL feature. @item In the process of building features for new users, we have not forgotten requests by the community of loyal users. We have multi-table @code{DELETE} statements. By adding support for @code{symbolic linking} to @code{MyISAM} on the table -level (and not just database level as before), as well as by enabling symlink +level (and not just the database level as before), as well as by enabling symlink handling by default on Windows, we hope to show that we take enhancement requests seriously. -Functions like @code{SQL_CALC_FOUND_ROWS} and @code{FOUND_ROWS()} makes it +Functions like @code{SQL_CALC_FOUND_ROWS} and @code{FOUND_ROWS()} make it possible to know how many rows a query would have returned without a @code{LIMIT} clause. @end itemize @@ -1826,7 +1830,7 @@ possible to know how many rows a query would have returned without a @node Nutshell Future features, Nutshell 4.1 development release, Nutshell Other features, MySQL 4.0 In A Nutshell @subsection Future MySQL 4.0 Features -For the upcoming MySQL Server 4.0 releases (4.0.1, 4.0.2 and onwards), +For the upcoming MySQL Server 4.0 releases (4.0.1, 4.0.2, and onward), expect the following features now still under development: @itemize @bullet @@ -1834,7 +1838,7 @@ expect the following features now still under development: Mission-critical, heavy-load users of MySQL Server will appreciate the additions to our replication system and our online hot backup. Later versions of 4.0 will include @code{fail-safe replication}; -already in existing 4.0.0, the @code{LOAD DATA FROM MASTER} command +already existing in 4.0.0, the @code{LOAD DATA FROM MASTER} command will soon automate slave setup. The @code{online backup} will make it easy to add a new replication slave without taking down the master, and have a very low performance penalty on @@ -1846,9 +1850,9 @@ A convenience feature for Database Administrators is that taking down the servers. @item -The new @code{FULLTEXT} search properties of MySQL Server 4.0 enables the +The new @code{FULLTEXT} search properties of MySQL Server 4.0 enable the use of @code{FULLTEXT} indexing of large text masses with both binary and -natural language searching logic. Users can customise minimal word +natural-language searching logic. Users can customise minimal word length and define their own stop word lists in any human language, enabling a new set of applications to be built on MySQL Server. @@ -1867,7 +1871,7 @@ in the client. Internally, through a new .frm file format for table definitions, MySQL Server 4.0 lays the foundation for the new features of -MySQL Server 4.1 onwards, +MySQL Server 4.1 and onward, such as @code{nested subqueries}, @code{stored procedures}, and @code{foreign key integrity rules}, which form the top of the wish list for many of our customers. Along with those, we will @@ -1915,23 +1919,23 @@ checklist of very demanding buyers. The @code{MySQL Portals} (@uref{http://www.mysql.com/portal/}) represent the ultimate resource to find @code{MySQL AB Partners}, -as well as books, or other @code{MySQL} related solutions that you +as well as books, or other @code{MySQL}-related solutions that you may be looking for. Items are categorised and rated in order to make it easy for you to locate information. -By registering as a user, you will have the ability to comment and +By registering as a user, you will have the ability to comment on and rate items presented in portals. You will also receive relevant newsletters according to your user profile that you may update at any time. -Some of the current @code{MySQL Portal} categories: +Some of the current @code{MySQL Portal} categories include: @table @strong @item Partners Find @code{MySQL AB} partners worldwide. @item Books -Comment, vote, and buy books related to @code{MySQL}. +Comment on, vote for, and buy books related to @code{MySQL}. @item Development Various links to different sites that are using @code{MySQL Server} @@ -1944,7 +1948,7 @@ Let us know about @emph{your} site or success story, too! Visit @uref{http://www.mysql.com/feedback/testimonial.php}. @item Software -Find, buy, download several applications and wrappers that make +Find, buy, and download several applications and wrappers that make use of the @code{MySQL} server. @item Distributions @@ -1994,7 +1998,7 @@ subject line and the body of the message are ignored. @c the last two addresses in this paragraph are not @email because they @c shouldn't be live links. If your reply address is not valid, you can specify your address -explicitly. Adding a hyphen to the subscribe or unsubscribe command +explicitly, by adding a hyphen to the subscribe or unsubscribe command word, followed by your address with the @samp{@@} character in your address replaced by a @samp{=}. For example, to subscribe @code{your_name@@host.domain}, send a message to @@ -2006,13 +2010,13 @@ ezmlm mailing list processor. Information about ezmlm is available at the ezmlm web site (@uref{http://www.ezmlm.org/}). To post a message to the list itself, send your message to -@code{mysql@@lists.mysql.com}. However, please @emph{do not} send mail about -subscribing or unsubscribing to @email{mysql@@lists.mysql.com}, because any +@code{mysql@@lists.mysql.com}. However, please @strong{do not} send mail about +subscribing or unsubscribing to @email{mysql@@lists.mysql.com} because any mail sent to that address is distributed automatically to thousands of other users. Your local site may have many subscribers to @email{mysql@@lists.mysql.com}. -If so, it may have a local mailing list, so that messages sent from +If so, it may have a local mailing list, so messages sent from @code{lists.mysql.com} to your site are propagated to the local list. In such cases, please contact your system administrator to be added to or dropped from the local MySQL list. @@ -2027,7 +2031,7 @@ The following MySQL mailing lists exist: @table @code @item @email{announce-subscribe@@lists.mysql.com} announce This is for announcement of new versions of MySQL and related -programs. This is a low volume list all MySQL users should +programs. This is a low-volume list all MySQL users should subscribe to. @item @email{mysql-subscribe@@lists.mysql.com} mysql @@ -2047,7 +2051,7 @@ Preferably, you should test the problem using the latest stable or development version of MySQL Server before posting! Anyone should be able to repeat the bug by just using @code{mysql test < script} on the included test case. All bugs posted on this list will be corrected or documented in the next -MySQL release! If there are only small code changes involved, we +MySQL release! If only small code changes are needed, we will also post a patch that fixes the problem. @item @email{bugs-digest-subscribe@@lists.mysql.com} bugs-digest @@ -2080,7 +2084,7 @@ All things about connecting to the MySQL server with ODBC. A digest version of the @code{myodbc} list. @item @email{mycc-subscribe@@lists.mysql.com} mycc -All things about the MySQL MyCC graphical client. +All things about the MySQL @code{MyCC} graphical client. @item @email{mycc-digest-subscribe@@lists.mysql.com} mycc-digest A digest version of the @code{mycc} list. @@ -2099,7 +2103,7 @@ A digest version of the @code{msql-mysql-modules} list. @end table You subscribe or unsubscribe to all lists in the same way as described -above. In your subscribe or unsubscribe message, just put the appropriate +previously. In your subscribe or unsubscribe message, just put the appropriate mailing list name rather than @code{mysql}. For example, to subscribe to or unsubscribe from the @code{myodbc} list, send a message to @email{myodbc-subscribe@@lists.mysql.com} or @@ -2109,7 +2113,7 @@ If you can't get an answer for your questions from the mailing list, one option is to pay for support from MySQL AB, which will put you in direct contact with MySQL developers. @xref{Support}. -The following table shows some MySQL mailing in other languages than +The following table shows some MySQL mailing in languages other than English. Note that these are not operated by MySQL AB, so we can't guarantee the quality on these. @@ -2153,7 +2157,7 @@ Search the MySQL mailing list archives: @* @item You can also use @uref{http://www.mysql.com/search.html} to search all the -Web pages (including the manual) that are located at +web pages (including the manual) that are located at @uref{http://www.mysql.com/}. @end itemize @@ -2183,7 +2187,7 @@ or at all. We encourage everyone to use the @code{mysqlbug} script to generate a bug report (or a report about any problem), if possible. @code{mysqlbug} can be -found in the @file{scripts} directory in the source distribution, or, for a +found in the @file{scripts} directory in the source distribution, or for a binary distribution, in the @file{bin} directory under your MySQL installation directory. If you are unable to use @code{mysqlbug}, you should still include all the necessary information listed in this section. @@ -2205,9 +2209,9 @@ MySQL version. Preferably, you should test the problem using the latest stable or development version of MySQL Server before posting! Anyone should be able to repeat the bug by just using ``@code{mysql test < script}'' on the included test case or run the -shell or perl script that is included in the bug report. All bugs +shell or Perl script that is included in the bug report. All bugs posted on the @code{bugs} list will be corrected or documented in the next -MySQL release! If there are only small code changes involved +MySQL release! If only small code changes are needed to correct this problem, we will also post a patch that fixes the problem. @@ -2228,17 +2232,17 @@ the MySQL distribution they are using, or don't indicate what platform they have the MySQL server installed on (including the platform version number). This is highly relevant information, and in 99 cases out of 100 the bug report is useless without it! Very often we get questions like, -``Why doesn't this work for me?'' then we find that the feature +``Why doesn't this work for me?'' Then we find that the feature requested wasn't implemented in that MySQL version, or that a bug described in a report has been fixed already in newer MySQL -versions. Sometimes the error is platform dependent; in such cases, it is +versions. Sometimes the error is platform-dependent; in such cases, it is next to impossible to fix anything without knowing the operating system and the version number of the platform. Remember also to provide information about your compiler, if it is related to the problem. Often people find bugs in compilers and think the problem is MySQL-related. Most compilers are under development all the time and -become better version by version. To determine whether or not your +become better version by version. To determine whether your problem depends on your compiler, we need to know what compiler is used. Note that every compiling problem should be regarded as a bug report and reported accordingly. @@ -2265,7 +2269,7 @@ using the @code{mysql} command line tool, you should therefore use the @code{--vertical} option (or the @code{\G} statement terminator) for output that would exceed the available width for such a display (for example, with the @code{EXPLAIN SELECT} statement; see the -example below). +example later in this section). @cindex bug reports, criteria for Please include the following information in your report: @@ -2337,11 +2341,11 @@ mysql> SHOW STATUS; @end example @item -If a bug or problem occurs while running @strong{mysqld}, try to provide an +If a bug or problem occurs while running @code{mysqld}, try to provide an input script that will reproduce the anomaly. This script should include any necessary source files. The more closely the script can reproduce your situation, the better. If you can make a reproduceable test case, you should -post this to @email{bugs@@lists.mysql.com} for a high priority treatment! +post this to @email{bugs@@lists.mysql.com} for a high-priority treatment! If you can't provide a script, you should at least include the output from @code{mysqladmin variables extended-status processlist} in your mail to @@ -2371,8 +2375,8 @@ These cases are rare, perhaps, but it is better to be safe than sorry. After all, it should be easier for you to provide an example that uses your actual situation, and it is by all means better for us. In case you have data you don't want to show to others, you can use @code{ftp} to transfer it to -@uref{ftp://support.mysql.com/pub/mysql/secret/}. If the data are really top -secret and you don't want to show them even to us, then go ahead and provide +@uref{ftp://support.mysql.com/pub/mysql/secret/}. If the data is really top +secret and you don't want to show it even to us, then go ahead and provide an example using other names, but please regard this as the last choice. @item @@ -2394,9 +2398,9 @@ gives you trouble. @code{mysqlaccess} can be found in the @file{bin} directory under your MySQL installation directory. @item -If you have a patch for a bug, that is good, but don't assume the patch is +If you have a patch for a bug, that is good. But don't assume the patch is all we need, or that we will use it, if you don't provide some necessary -information, such as test cases showing the bug that your patch fixes. We +information such as test cases showing the bug that your patch fixes. We might find problems with your patch or we might not understand it at all; if so, we can't use it. @@ -2406,13 +2410,13 @@ situations that may occur. If we find a borderline case (even a rare one) where the patch won't work, it may be useless. @item -Guesses about what the bug is, why it occurs, or what it depends on, +Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the MySQL team can't guess such things without first using a debugger to determine the real cause of a bug. @item Indicate in your mail message that you have checked the reference manual -and mail archive so others know that you have tried to solve the +and mail archive so that others know you have tried to solve the problem yourself. @item @@ -2448,9 +2452,9 @@ it's much easier for us to provide you with a fix for the problem. @item If possible, download and install the most recent version of MySQL Server -and check whether or not it solves your problem. All versions of +and check whether it solves your problem. All versions of the MySQL software are thoroughly tested and should work without problems. -We believe in making everything as backward compatible as possible, +We believe in making everything as backward-compatible as possible, and you should be able to switch MySQL versions without any hassle. @xref{Which version}. @end itemize @@ -2460,11 +2464,11 @@ and you should be able to switch MySQL versions without any hassle. @cindex customer support, mailing address @cindex mailing address, for customer support If you are a support customer, please cross-post the bug report to -@email{mysql-support@@mysql.com} for higher priority treatment, as well as to +@email{mysql-support@@mysql.com} for higher-priority treatment, as well as to the appropriate mailing list to see if someone else has experienced (and perhaps solved) the problem. -For information on reporting bugs in @strong{MyODBC}, see @ref{ODBC Problems}. +For information on reporting bugs in @code{MyODBC}, see @ref{ODBC Problems}. For solutions to some common problems, see @ref{Problems}. @@ -2505,35 +2509,35 @@ Many users don't read mail with a browser! This section describes how MySQL relates to the ANSI SQL standards. MySQL Server has many extensions to the ANSI SQL standards, and here you -will find out what they are, and how to use them. You will also find +will find out what they are and how to use them. You will also find information about functionality missing from MySQL Server, and how to work around some differences. Our goal is to not, without a very good reason, restrict MySQL Server usability for any usage. Even if we don't have the resources to do development for every possible use, we are always willing to help and offer -suggestions to people that is trying to use MySQL Server in new territories. +suggestions to people who are trying to use MySQL Server in new territories. -One of our main goals with the product is to continue to work towards +One of our main goals with the product is to continue to work toward ANSI 99 compliancy, but without sacrificing speed or reliability. We are not afraid to add extensions to SQL or support for non-SQL -features if this greatly increase the usability of MySQL Server for a big +features if this greatly increases the usability of MySQL Server for a big part of our users. (The new @code{HANDLER} interface in MySQL Server 4.0 is an example of this strategy. @xref{HANDLER, , @code{HANDLER}}.) -We will continue to support transactional and not transactional -databases to satisfy both heavy web/logging usage and mission critical +We will continue to support transactional and non-transactional +databases to satisfy both heavy web/logging usage and mission-critical 24/7 usage. MySQL Server was designed from the start to work with medium size databases -(10-100 million rows / about 100 MB per table) on small computer -systems. We will continue to extend MySQL Server to both work even better -with terabyte size databases, but we are also doing work to make it possible -to compile a reduced MySQL version that is more suitable for hand held +(10-100 million rows, or about 100 MB per table) on small computer +systems. We will continue to extend MySQL Server to work even better +with terabyte-size databases, as well as to make it possible +to compile a reduced MySQL version that is more suitable for hand-held devices and embedded usage. The compact design of the MySQL server makes both of these directions possible without any conflicts in the source tree. -We are currently not targeting real time support or clustered databases +We are currently not targeting realtime support or clustered databases (even if you can already do a lot of things with our replication services). @@ -2542,7 +2546,7 @@ database, but will instead add the XML support our users request from us on the client side. We think it's better to keep the main server code as ``lean and clean'' as possible and instead develop libraries to deal with the complexity on the client side. This is part of the strategy -mentioned above of not sacrificing speed or reliability in the +mentioned previously of not sacrificing speed or reliability in the server. @menu @@ -2557,9 +2561,9 @@ server. @node Standards, ANSI mode, Compatibility, Compatibility @subsection What Standards Does MySQL Follow? -Entry level SQL92. ODBC levels 0-3.51. +Entry-level SQL92. ODBC levels 0-3.51. -We are aiming towards supporting the full ANSI SQL99 standard, +We are aiming toward supporting the full ANSI SQL99 standard, but without concessions to speed and quality of the code. @@ -2585,7 +2589,7 @@ This forces all function names to be treated as reserved words. @samp{`} quote character) and not a string quote character. @item -@code{REAL} will be a synonym for @code{FLOAT} instead of a synonym of +@code{REAL} will be a synonym for @code{FLOAT} instead of a synonym for @code{DOUBLE}. @item @@ -2614,18 +2618,18 @@ statement, but other SQL servers will ignore the extensions. For example: SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ... @end example -If you add a version number after the @code{'!'}, the syntax will only be -executed if the MySQL version is equal to or newer than the used +If you add a version number after the @code{'!'}, the syntax will be +executed only if the MySQL version is equal to or newer than the used version number: @example CREATE /*!32302 TEMPORARY */ TABLE (a int); @end example -The above means that if you have Version 3.23.02 or newer, then MySQL +This means that if you have Version 3.23.02 or newer, MySQL Server will use the @code{TEMPORARY} keyword. -MySQL extensions are listed below: +The following is a list of MySQL extensions: @itemize @bullet @item @@ -2637,7 +2641,7 @@ The field attributes @code{AUTO_INCREMENT}, @code{BINARY}, @code{NULL}, @code{UNSIGNED}, and @code{ZEROFILL}. @item -All string comparisons are case insensitive by default, with sort +All string comparisons are case-insensitive by default, with sort ordering determined by the current character set (ISO-8859-1 Latin1 by default). If you don't like this, you should declare your columns with the @code{BINARY} attribute or use the @code{BINARY} cast, which causes @@ -2659,7 +2663,7 @@ This has a few implications: @itemize @minus @item -Database names and table names are case sensitive in MySQL Server on +Database names and table names are case-sensitive in MySQL Server on operating systems that have case-sensitive filenames (like most Unix systems). @xref{Name case sensitivity}. @@ -2668,7 +2672,7 @@ Database, table, index, column, or alias names may begin with a digit (but may not consist solely of digits). @item -You can use standard system commands to backup, rename, move, delete, and copy +You can use standard system commands to back up, rename, move, delete, and copy tables. For example, to rename a table, rename the @file{.MYD}, @file{.MYI}, and @file{.frm} files to which the table corresponds. @end itemize @@ -2702,7 +2706,7 @@ statement. @xref{CREATE TABLE, , @code{CREATE TABLE}}. Use of @code{TEMPORARY} or @code{IF NOT EXISTS} with @code{CREATE TABLE}. @item -Use of @code{COUNT(DISTINCT list)} where 'list' is more than one element. +Use of @code{COUNT(DISTINCT list)} where @code{list} is more than one element. @item Use of @code{CHANGE col_name}, @code{DROP col_name}, or @code{DROP @@ -2895,7 +2899,7 @@ That is the latest version of the TODO list in this manual. @xref{TODO}. MySQL Server currently only supports nested queries of the form @code{INSERT ... SELECT ...} and @code{REPLACE ... SELECT ...}. -You can however use the function @code{IN()} in other contexts. +You can, however, use the function @code{IN()} in other contexts. Sub-selects are scheduled for implementation in Version 4.x. Meanwhile, you can often rewrite the query without a sub-select: @@ -2904,7 +2908,7 @@ Meanwhile, you can often rewrite the query without a sub-select: SELECT * FROM table1 WHERE id IN (SELECT id FROM table2); @end example -This can be re-written as: +This can be rewritten as: @example SELECT table1.* FROM table1,table2 WHERE table1.id=table2.id; @@ -2925,7 +2929,7 @@ SELECT table1.* FROM table1 LEFT JOIN table2 ON table1.id=table2.id @end example For more complicated subqueries you can often create temporary tables -to hold the subquery. In some cases, however this option will not +to hold the subquery. In some cases, however, this option will not work. The most frequently encountered of these cases arises with @code{DELETE} statements, for which standard SQL does not support joins (except in sub-selects). For this situation there are two options @@ -3002,8 +3006,8 @@ However, the non-transactional table types in MySQL Server such as ``@code{Atomic Operations}.'' Atomic operations often offer equal or even better integrity with much better performance. With MySQL Server supporting both paradigms, the user is able to decide if -they need the speed of atomic operations or if they need to use -transactional features in their applications. This choice can be made +he needs the speed of atomic operations or if he need to use +transactional features in his applications. This choice can be made on a per-table basis. How does one use the features of MySQL Server to maintain rigorous integrity @@ -3013,7 +3017,7 @@ and how do these features compare with the transactional paradigm? @item In the transactional paradigm, if your applications are written in a way that is dependent on the calling of @code{ROLLBACK} instead of -@code{COMMIT} in critical situations, then transactions are more +@code{COMMIT} in critical situations, transactions are more convenient. Transactions also ensure that unfinished updates or corrupting activities are not committed to the database; the server is given the opportunity to do an automatic rollback and your database is @@ -3053,7 +3057,7 @@ users and application developers depend on the ease with which they can code around problems where an abort appears to be, or is necessary. However, even if you are new to the atomic operations paradigm, or more familiar with transactions, do consider the speed benefit that -non-transactional tables can offer, on the order of three to five times +non-transactional tables can offer on the order of three to five times the speed of the fastest and most optimally tuned transactional tables. In situations where integrity is of highest importance, MySQL Server offers @@ -3061,7 +3065,7 @@ transaction-level or better reliability and integrity even for non-transactional tables. If you lock tables with @code{LOCK TABLES}, all updates will stall until any integrity checks are made. If you only obtain a read lock -(as opposed to a write lock), then reads and inserts are still allowed +(as opposed to a write lock), reads and inserts are still allowed to happen. The new inserted records will not be seen by any of the clients that have a read lock until they release their read locks. With @code{INSERT DELAYED} you can queue inserts into a local @@ -3115,16 +3119,16 @@ techniques: For example, when we are doing updates to some customer information, we update only the customer data that has changed and test only that none of -the changed data, or data that depend on the changed data, has changed +the changed data, or data that depends on the changed data, has changed compared to the original row. The test for changed data is done with the @code{WHERE} clause in the @code{UPDATE} statement. If the record wasn't updated, we give the client a message: "Some of the data you have changed -have been changed by another user". Then we show the old row versus the new +has been changed by another user." Then we show the old row versus the new row in a window, so the user can decide which version of the customer record he should use. This gives us something that is similar to column locking but is actually -even better, because we only update some of the columns, using values that +even better because we only update some of the columns, using values that are relative to their current values. This means that typical @code{UPDATE} statements look something like these: @@ -3169,7 +3173,7 @@ UPDATE tbl_name SET row_flag=1 WHERE id=ID; MySQL returns 1 for the number of affected rows if the row was found and @code{row_flag} wasn't already 1 in the original row. -You can think of it as MySQL Server changed the above query to: +You can think of it as though MySQL Server changed the preceding query to: @example UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1; @@ -3185,7 +3189,7 @@ UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1; @cindex triggers, stored A stored procedure is a set of SQL commands that can be compiled and stored -in the server. Once this has been done, clients don't need to keep reissuing +in the server. Once this has been done, clients don't need to keep re-issuing the entire query but can refer to the stored procedure. This provides better performance because the query has to be parsed only once, and less information needs to be sent between the server and the client. You can also raise the @@ -3219,7 +3223,7 @@ SELECT * FROM table1,table2 WHERE table1.id = table2.id; @xref{JOIN, , @code{JOIN}}. @xref{example-Foreign keys}. -In MySQL Server 3.23.44 and up, @code{InnoDB} tables supports checking of +In MySQL Server 3.23.44 and up, @code{InnoDB} tables support checking of foreign key constraints. @xref{InnoDB}. For other table types, MySQL Server does parse the @code{FOREIGN KEY} syntax in @code{CREATE TABLE} commands, but without further action being taken. @@ -3272,7 +3276,7 @@ Disadvantages: @itemize @bullet @item Mistakes, which are easy to make in designing key relations, can cause -severe problems, for example, circular rules, or the wrong combination +severe problems@-for example, circular rules, or the wrong combination of cascading deletes. @item @@ -3283,8 +3287,8 @@ down performance for such an application. @item It is not uncommon for a DBA to make such a complex topology of -relations that it becomes very difficult, and in some cases impossible -to backup or restore individual tables. +relations that it becomes very difficult, and in some cases impossible, +to back up or restore individual tables. @end itemize @@ -3299,13 +3303,13 @@ Views are mostly useful for letting users access a set of relations as one table (in read-only mode). Many SQL databases don't allow one to update any rows in a view, but you have to do the updates in the separate tables. -As MySQL Server is mostly used in applications and on web system where +As MySQL Server is mostly used in applications and on web systems where the application writer has full control on the database usage, most of our users haven't regarded views to be very important. (At least no one has been interested enough in this to be prepared to -finance the implementation of views). +finance the implementation of views.) -One doesn't need views in MySQL Server to restrict access to columns +One doesn't need views in MySQL Server to restrict access to columns, as MySQL Server has a very sophisticated privilege system. @xref{Privilege system}. @@ -3321,7 +3325,7 @@ MySQL Server has @samp{#} as the start comment character. You can also use the C comment style @code{/* this is a comment */} with MySQL Server. @xref{Comments}. -MySQL Server Version 3.23.3 and above supports the @samp{--} comment style, +MySQL Server Version 3.23.3 and above support the @samp{--} comment style, provided the comment is followed by a space. This is because this comment style has caused many problems with automatically generated SQL queries that have used something like the following code, where @@ -3332,7 +3336,7 @@ we automatically insert the value of the payment for UPDATE tbl_name SET credit=credit-!payment! @end example -Think about what happens if the value of @code{payment} is negative? +Think about what happens if the value of @code{payment} is negative. Because @code{1--1} is legal in SQL, the consequences of allowing comments to start with @samp{--} are terrible. @@ -3343,8 +3347,8 @@ Another safe feature is that the @code{mysql} command-line client removes all lines that start with @samp{--}. -The following information is only relevant if you are running a -MySQL version earlier than Version 3.23.3: +The following information is relevant only if you are running a +MySQL version earlier than 3.23.3: If you have a SQL program in a text file that contains @samp{--} comments you should use: @@ -3397,11 +3401,11 @@ see errors like the following in the MySQL error file: @item Don't execute @code{ALTER TABLE} on a @code{BDB} table on which you are -running multi-statement transactions until all those transactions complete -(the transaction will probably be ignored). +running multi-statement transactions until all those transactions complete. +(The transaction will probably be ignored.) @item -@code{ANALYZE TABLE}, @code{OPTIMIZE TABLE} and @code{REPAIR TABLE} may +@code{ANALYZE TABLE}, @code{OPTIMIZE TABLE}, and @code{REPAIR TABLE} may cause problems on tables for which you are using @code{INSERT DELAYED}. @item @@ -3417,7 +3421,7 @@ database if you are not using the @code{-A} option or if you are using cache. @item -Th current replication protocol cannot deal with @code{LOAD DATA INFILE} +The current replication protocol cannot deal with @code{LOAD DATA INFILE} and line terminator characters of more than 1 character. @end itemize @@ -3427,7 +3431,7 @@ The following problems are known and will be fixed in due time: @item When using @code{SET CHARACTER SET}, one can't use translated -characters in database, table and column names. +characters in database, table, and column names. @item @code{DELETE FROM merge_table} used without a @code{WHERE} @@ -3467,7 +3471,7 @@ that in MySQL Server, @code{VARCHAR} columns are treated the same way. You can only have up to 255 @code{ENUM} and @code{SET} columns in one table. @item -@code{safe_mysqld} re-directs all messages from @code{mysqld} to the +@code{safe_mysqld} redirects all messages from @code{mysqld} to the @code{mysqld} log. One problem with this is that if you execute @code{mysqladmin refresh} to close and reopen the log, @code{stdout} and @code{stderr} are still redirected to the old log. @@ -3489,7 +3493,7 @@ This will update @code{KEY} with @code{2} instead of with @code{1}. @item You can't use temporary tables more than once in the same query. -For example, the following doesn't work. +For example, the following doesn't work: @example mysql> SELECT * FROM temporary_table, temporary_table AS t2; @@ -3503,9 +3507,9 @@ mysql> SELECT * FROM temporary_table, temporary_table AS t2; The optimiser may handle @code{DISTINCT} differently if you are using 'hidden' columns in a join or not. In a join, hidden columns are counted as part of the result (even if they are not shown) while in -normal queries hidden columns doesn't participate in the @code{DISTINCT} +normal queries hidden columns don't participate in the @code{DISTINCT} comparison. We will probably change this in the future to never compare -the hidden columns when executing @code{DISTINCT} +the hidden columns when executing @code{DISTINCT}. An example of this is: @@ -3525,17 +3529,17 @@ SELECT DISTINCT band_downloads.mp3id @end example In the second case you may in MySQL Server 3.23.x get two identical rows -in the result set (because the hidden 'id' column may differ). +in the result set (because the hidden @code{id} column may differ). -Note that the this only happens for queries where you don't have the -ORDER BY columns in the result, something that is you are not allowed +Note that this happens only for queries where you don't have the +ORDER BY columns in the result, something that you are not allowed to do in ANSI SQL. @item Because MySQL Server allows you to work with table types that don't support transactions, and thus can't @code{rollback} data, some things behave a little differently in MySQL Server than in other SQL servers. -This is just to ensure that MySQL Server never need to do a rollback +This is just to ensure that MySQL Server never needs to do a rollback for a SQL command. This may be a little awkward at times as column values must be checked in the application, but this will actually give you a nice speed increase as it allows MySQL Server to do some @@ -3558,20 +3562,20 @@ numerical column, MySQL Server will store 0 into it. If you try to store @code{NULL} into a column that doesn't take @code{NULL} values, MySQL Server will store 0 or @code{''} (empty string) in it instead. (This behavior can, however, be changed with the --DDONT_USE_DEFAULT_FIELDS compile option). +-DDONT_USE_DEFAULT_FIELDS compile option.) @item MySQL allows you to store some wrong date values into -@code{DATE} and @code{DATETIME} columns. (Like 2000-02-31 or 2000-02-00). +@code{DATE} and @code{DATETIME} columns (like 2000-02-31 or 2000-02-00). If the date is totally wrong, MySQL Server will store the special 0000-00-00 date value in the column. @item If you set an @code{ENUM} column to an unsupported value, it will be set to -the error value 'empty string', with numeric value 0. +the error value @code{empty string}, with numeric value 0. @item -If you set an @code{SET} column to an unsupported value, the value will +If you set a @code{SET} column to an unsupported value, the value will be ignored. @end itemize @@ -3585,20 +3589,20 @@ Creation of a table of type @code{MERGE} doesn't check if the underlying tables are of compatible types. @item -MySQL Server can't yet handle @code{NaN}, @code{-Inf} and @code{Inf} +MySQL Server can't yet handle @code{NaN}, @code{-Inf}, and @code{Inf} values in double. Using these will cause problems when trying to export and import data. We should as an intermediate solution change @code{NaN} to @code{NULL} (if possible) and @code{-Inf} and @code{Inf} to the -Minimum respective maximum possible @code{double} value. +minimum respective maximum possible @code{double} value. @item @code{LIMIT} on negative numbers are treated as big positive numbers. @item -If you use @code{ALTER TABLE} to first add an @code{UNIQUE} index to a +If you use @code{ALTER TABLE} to first add a @code{UNIQUE} index to a table used in a @code{MERGE} table and then use @code{ALTER TABLE} to add a normal index on the @code{MERGE} table, the key order will be -different for the tables if there was an old not-unique key in the +different for the tables if there was an old key that was not unique in the table. This is because @code{ALTER TABLE} puts @code{UNIQUE} keys before normal keys to be able to detect duplicate keys as early as possible. @end itemize @@ -3618,10 +3622,10 @@ In the following case you can get a core dump: Delayed insert handler has pending inserts to a table. @item -@code{LOCK table} with @code{WRITE} +@code{LOCK table} with @code{WRITE}. @item -@code{FLUSH TABLES} +@code{FLUSH TABLES}. @end itemize @item @@ -3639,7 +3643,7 @@ A workaround is to use: mysql> UPDATE tbl_name SET KEY=KEY+1 WHERE KEY+0 > 100; @end example -This will work because MySQL Server will not use index on expressions in +This will work because MySQL Server will not use an index on expressions in the @code{WHERE} clause. @item @@ -3673,13 +3677,13 @@ tell us what you want to have done more quickly. @xref{Licensing and Support}. The plan is that we in the future will support the full ANSI SQL99 standard, but with a lot of useful extensions. The challenge is to do -this without sacrifying the speed or compromise the code. +this without sacrifying the speed or compromising the code. @node TODO MySQL 4.0, TODO MySQL 4.1, TODO, TODO @subsection Things That Should be in 4.0 -We are now in the final stages one the development of the MySQL Server +We are now in the final stages of the development of the MySQL Server 4.0. server. The target is to quickly implement the rest of the following features and then shift development to MySQL Server 4.1. @xref{MySQL 4.0 In A Nutshell}. @@ -3688,7 +3692,7 @@ The news section for 4.0 includes a list of the features we have already implemented in the 4.0 tree. @xref{News-4.0.x}. This section lists features not yet implemented in the current version -of MySQL Server 4.0, which will however be implemented in later versions +of MySQL Server 4.0, which will, however, be implemented in later versions of MySQL 4.0. This being very volatile information, please consider this list valid only if you are reading it from the MySQL web site (@uref{http://www.mysql.com/}). @@ -3697,20 +3701,20 @@ list valid only if you are reading it from the MySQL web site @item Allow users to change startup options without taking down the server. @item -Better command line argument handling. +Better command-line argument handling. @item New key cache, which will give better performance when using many threads. @item -New table definition file format (@file{.frm} files) This will enable us +New table definition file format (@file{.frm} files). This will enable us to not run out of bits when adding more table options. One will still be able to use the old @file{.frm} file format with 4.0. All newly created tables will, however, use the new format. The new file format will enable us to add new column types, more options -for keys and possible to store and retrieve @code{FOREIGN KEY} definitions. +for keys, and possibly to store and retrieve @code{FOREIGN KEY} definitions. @item @code{SHOW COLUMNS FROM table_name} (used by @code{mysql} client to allow -expansions of column names) should not open the table, but only the +expansions of column names) should not open the table, only the definition file. This will require less memory and be much faster. @item @code{SET SQL_DEFAULT_TABLE_TYPE=[MyISAM | INNODB | BDB | HEAP]}. @@ -3720,7 +3724,7 @@ definition file. This will require less memory and be much faster. @node TODO MySQL 4.1, TODO future, TODO MySQL 4.0, TODO @subsection Things That Should be in 4.1 -The following features is the ones we plan that should be in MySQL 4.1. +The following features are planned for inclusion into MySQL 4.1. Note that because we have many developers that are working on different projects, there will also be many additional features. There is also a small chance that some of these features will be added to MySQL 4.0. @@ -3741,7 +3745,7 @@ Online backup with very low performance penalty. The online backup will make it easy to add a new replication slave without taking down the master. @item -Derived tables. +Derived tables: @example SELECT a.col1, b.col2 FROM (SELECT MAX(col1) AS col1 FROM root_table) a, @@ -3758,19 +3762,19 @@ the @file{.MYD} file. @item When using @code{SET CHARACTER SET} we should translate the whole query at once and not only strings. This will enable users to use the translated -characters in database, table and column names. +characters in database, table, and column names. @item Add @code{record_in_range()} method to @code{MERGE} tables to be -able to choose the right index when there is many to choose from. We should +able to choose the right index when there are many to choose from. We should also extend the info interface to get the key distribution for each index, -if @code{analyze} is run on all sub tables. +if @code{analyze} is run on all subtables. @item @code{RENAME TABLE} on a table used in an active @code{MERGE} table may corrupt the table. @item -A faster, smaller embedded MySQL library. (Compatible with the old one) +A faster, smaller embedded MySQL library. (Compatible with the old one.) @item -Stable openssl support. (MySQL 4.0 supports rudimentary, not 100 % tested +Stable openssl support. (MySQL 4.0 supports rudimentary, not 100% tested, support for openssl). @item Add support for sorting on @code{UNICODE}. @@ -3780,7 +3784,7 @@ Character set casts and syntax for handling multiple character sets. Help for all commands from the client. @item New faster client/server protocol which will support prepared statements, -bound parameters and bound result columns, binary transfer of data, +bound parameters, and bound result columns, binary transfer of data, warnings... @item Add database and real table name (in case of alias) to the MYSQL_FIELD @@ -3801,14 +3805,14 @@ we do with the @code{RENAME} command. Drop the old database. @end itemize @item -Add true @code{VARCHAR} support (There is already support for this in +Add true @code{VARCHAR} support (there is already support for this in @code{MyISAM}). @item Optimise @code{BIT} type to take 1 bit (now @code{BIT} takes 1 char). @item New internal file interface change. This will make all file handling much -more general and make it easier to add extensions like RAID -(the current implementation is a hack). +more general and make it easier to add extensions like RAID. +(the current implementation is a hack.) @item Better in-memory (@code{HEAP}) tables: @itemize @bullet @@ -3827,7 +3831,7 @@ Faster row handling (less copying) @itemize @bullet @item -Atomic multi-table updates, eg @code{update items,month set +Atomic multi-table updates@-e.g., @code{update items,month set items.price=month.price where items.id=month.id;}; @item Don't allow more than a defined number of threads to run MyISAM recover @@ -3843,7 +3847,7 @@ Multiple result sets. Make it possible to specify @code{long_query_time} with a granularity in microseconds. @item -Add a configurable prompt to the @code{mysql} command line client, with +Add a configurable prompt to the @code{mysql} command-line client, with options like database in use, time and date... @item Link the @code{myisampack} code into the server. @@ -3861,11 +3865,11 @@ If you perform an @code{ALTER TABLE} on a table that is symlinked to another disk, create temporary tables on this disk. @item Implement a @code{DATE/DATETIME} type that handles time zone information -properly, so that dealing with dates in different time zones is easier. +properly so that dealing with dates in different time zones is easier. @item -FreeBSD and MIT-pthreads; Do sleeping threads take CPU? +FreeBSD and MIT-pthreads; do sleeping threads take CPU time? @item -Check if locked threads take any CPU. +Check if locked threads take any CPU time. @item Fix configure so that one can compile all libraries (like @code{MyISAM}) without threads. @@ -3878,9 +3882,9 @@ Allow join on key parts (optimisation issue). @code{INSERT SQL_CONCURRENT} and @code{mysqld --concurrent-insert} to do a concurrent insert at the end of the file if the file is read-locked. @item -Server side cursors. +Server-side cursors. @item -Check if @code{lockd} works with modern Linux kernels; If not, we have +Check if @code{lockd} works with modern Linux kernels; if not, we have to fix @code{lockd}! To test this, start @code{mysqld} with @code{--enable-locking} and run the different fork* test suits. They shouldn't give any errors if @code{lockd} works. @@ -3888,7 +3892,7 @@ give any errors if @code{lockd} works. Allow SQL variables in @code{LIMIT}, like in @code{LIMIT @@a,@@b}. @item Allow update of variables in @code{UPDATE} statements. For example: -@code{UPDATE TABLE foo SET @@a=a+b,a=@@a, b=@@a+c} +@code{UPDATE TABLE foo SET @@a=a+b,a=@@a, b=@@a+c}. @item Change when user variables are updated so that one can use them with @code{GROUP BY}, as in the following example: @@ -3916,7 +3920,7 @@ touched. @item For tables with primary keys that are missing some part of the key in the incoming data stream, or that have no primary key, the feed is -treated as a @code{LOAD DATA INFILE ... REPLACE INTO} is now. +treated as a @code{LOAD DATA INFILE ... REPLACE INTO} now. @end itemize @item Make @code{LOAD DATA INFILE} understand syntax like: @@ -3928,60 +3932,60 @@ LOAD DATA INFILE 'file_name.txt' INTO TABLE tbl_name IGNORE text_field3 @end example This can be used to skip over extra columns in the text file, -or update columns based on expressions of the read data... +or update columns based on expressions of the read data. @item -@code{LOAD DATA INFILE 'file_name' INTO TABLE 'table_name' ERRORS TO err_table_name} +@code{LOAD DATA INFILE 'file_name' INTO TABLE 'table_name' ERRORS TO err_table_name}. This would cause any errors and warnings to be logged into the @code{err_table_name} table. That table would have a structure like: @example -line_number - line number in data file +line_number - line number in datafile error_message - the error/warning message and maybe -data_line - the line from the data file +data_line - the line from the datafile @end example @item Automatic output from @code{mysql} to Netscape. @item -@code{LOCK DATABASES}. (with various options) +@code{LOCK DATABASES} (with various options.) @item @code{DECIMAL} and @code{NUMERIC} types can't read exponential numbers; @code{Field_decimal::store(const char *from,uint len)} must be recoded to fix this. @item Functions: -ADD_TO_SET(value,set) and REMOVE_FROM_SET(value,set) +ADD_TO_SET(value,set) and REMOVE_FROM_SET(value,set). @item Add use of @code{t1 JOIN t2 ON ...} and @code{t1 JOIN t2 USING ...} Currently, you can only use this syntax with @code{LEFT JOIN}. @item Many more variables for @code{show status}. Records reads and -updated. Selects on 1 table and selects with joins. Mean number of +updates. Selects on 1 table and selects with joins. Mean number of tables in select. Number of @code{ORDER BY} and @code{GROUP BY} queries. @item If you abort @code{mysql} in the middle of a query, you should open another connection and kill the old running query. Alternatively, an attempt should be made to detect this in the server. @item -Add a handler interface for table information so you can use it as a system +Add a handler interface for table information so that you can use it as a system table. This would be a bit slow if you requested information about all tables, but very flexible. @code{SHOW INFO FROM tbl_name} for basic table information should be implemented. @item @code{NATURAL JOIN}. @item -Allow @code{SELECT a FROM crash_me LEFT JOIN crash_me2 USING (a)}; In this +Allow @code{SELECT a FROM crash_me LEFT JOIN crash_me2 USING (a)}; in this case @code{a} is assumed to come from the @code{crash_me} table. @item -Fix that @code{ON} and @code{USING} works with the @code{JOIN} +Fix so that @code{ON} and @code{USING} works with the @code{JOIN} join type. @item -Oracle like @code{CONNECT BY PRIOR ...} to search hierarchy structures. +Oracle-like @code{CONNECT BY PRIOR ...} to search hierarchy structures. @item -@code{mysqladmin copy database new-database}; Requires @code{COPY} -command to be added to @code{mysqld} +@code{mysqladmin copy database new-database}; requires @code{COPY} +command to be added to @code{mysqld}. @item -Processlist should show number of queries/thread. +Processlist should show number of queries/threads. @item @code{SHOW HOSTS} for printing information about the hostname cache. @item @@ -3994,35 +3998,35 @@ Add all missing ANSI92 and ODBC 3.0 types. @item Change table names from empty strings to @code{NULL} for calculated columns. @item -Don't use 'Item_copy_string' on numerical values to avoid +Don't use @code{Item_copy_string} on numerical values to avoid number->string->number conversion in case of: @code{SELECT COUNT(*)*(id+0) FROM table_name GROUP BY id} @item Make it possible to use the new GNU regexp library instead of the current -one (The GNU library should be much faster than the old one). +one (the GNU library should be much faster than the old one). @item -Change that @code{ALTER TABLE} doesn't abort clients that executes -@code{INSERT DELAYED}. +Change so that @code{ALTER TABLE} doesn't abort clients +that execute @code{INSERT DELAYED}. @item -Fix that when columns referenced in an @code{UPDATE} clause contains the old -values before the update started. +Fix so that when columns are referenced in an @code{UPDATE} clause, +they contain the old values from before the update started. @item Add simulation of @code{pread()}/@code{pwrite()} on Windows to enable concurrent inserts. @item -A logfile analyser that could parsed out information about which tables +A logfile analyser that could parse out information about which tables are hit most often, how often multi-table joins are executed, etc. It should help users identify areas or table design that could be optimised to execute much more efficient queries. @item -Add @code{SUM(DISTINCT)} +Add @code{SUM(DISTINCT)}. @item -Add @code{ANY()},@code{EVERY()} and @code{SOME()} group functions. In -ANSI SQL these only works on boolean columns, but we can extend these to +Add @code{ANY()}, @code{EVERY()}, and @code{SOME()} group functions. In +ANSI SQL these work only on boolean columns, but we can extend these to work on any columns/expressions by applying: value == 0 -> FALSE and value <> 0 -> TRUE. @item -Fix that the type for @code{MAX(column)} is the same as the column type. +Fix that the type for @code{MAX(column)} is the same as the column type: @example mysql> CREATE TABLE t1 (a DATE); mysql> INSERT INTO t1 VALUES (NOW()); @@ -4031,8 +4035,8 @@ mysql> SHOW COLUMNS FROM t2; @end example @item Come up with a nice syntax for a statement that will @code{UPDATE} the row -if it exists and @code{INSERT} a new row if the row didn't exist. -(Like @code{REPLACE} works with @code{INSERT} / @code{DELETE}) +if it exists and @code{INSERT} a new row if the row didn't exist +(like @code{REPLACE} works with @code{INSERT} / @code{DELETE}). @end itemize @@ -4041,15 +4045,15 @@ if it exists and @code{INSERT} a new row if the row didn't exist. @itemize @bullet @item -Implement function: @code{get_changed_tables(timeout,table1,table2,...)} +Implement function: @code{get_changed_tables(timeout,table1,table2,...)}. @item Change reading through tables to use memmap when possible. Now only compressed tables use memmap. @item -Add a new privilege @strong{'Show_priv'} for @code{SHOW} commands. +Add a new privilege @code{Show_priv} for @code{SHOW} commands. @item Make the automatic timestamp code nicer. Add timestamps to the update -log with @code{SET TIMESTAMP=#;} +log with @code{SET TIMESTAMP=#;}. @item Use read/write mutex in some places to get more speed. @item @@ -4058,7 +4062,7 @@ language first. @item Simple views (first on one table, later on any expression). @item -Automatically close some tables if a table, temporary table or temporary files +Automatically close some tables if a table, temporary table, or temporary files gets error 23 (not enough open files). @item When one finds a field=#, change all occurrences of field to #. Now this @@ -4077,10 +4081,10 @@ better error messages (5 days). Change the parser to use only one rule per different number of arguments in function. @item -Use of full calculation names in the order part. (For ACCESS97) +Use of full calculation names in the order part (for ACCESS97). @item -@code{MINUS}, @code{INTERSECT} and @code{FULL OUTER JOIN}. -(Currently @code{UNION} (in 4.0) and @code{LEFT OUTER JOIN} are supported) +@code{MINUS}, @code{INTERSECT}, and @code{FULL OUTER JOIN}. +(Currently @code{UNION} [in 4.0] and @code{LEFT OUTER JOIN} are supported.) @item @code{SQL_OPTION MAX_SELECT_TIME=#} to put a time limit on a query. @item @@ -4115,7 +4119,7 @@ Use @code{NULL} instead. @item Add full support for @code{JOIN} with parentheses. @item -As an alternative for one thread / connection manage a pool of threads +As an alternative for one thread/connection manage a pool of threads to handle the queries. @item Allow one to get more than one lock with @code{GET_LOCK}. When doing this, @@ -4130,7 +4134,7 @@ Time is given according to amount of work, not real time. @itemize @bullet @item -Nothing; We aim towards full ANSI 92 / ANSI 99 compliancy. +Nothing; we aim toward full ANSI 92/ANSI 99 compliancy. @end itemize @@ -4143,12 +4147,12 @@ Nothing; We aim towards full ANSI 92 / ANSI 99 compliancy. Our users have successfully run their own benchmarks against a number of @code{Open Source} and traditional database servers. We are aware of tests against @code{Oracle} server, @code{DB/2} server, -@code{Microsoft SQL Server} and other commercial products. +@code{Microsoft SQL Server}, and other commercial products. Due to legal reasons we are restricted from publishing some of those benchmarks in our reference manual. This section includes a comparison with @code{mSQL} for historical -reasons and with @code{PostgreSQL} as it is also an Open Source +reasons and with @code{PostgreSQL} as it is also an @code{Open Source} database. If you have benchmark results that we can publish, please contact us at @email{benchmarks@@mysql.com}. @@ -4208,7 +4212,7 @@ Retrieving large results (MySQL Server has a better, faster, and safer protocol). @item -Tables with variable-length strings, because MySQL Server has more efficient +Tables with variable-length strings because MySQL Server has more efficient handling and can have indexes on @code{VARCHAR} columns. @item @@ -4237,7 +4241,7 @@ next can be served, while all the others wait again, etc. Joins. @code{mSQL} can become pathologically slow if you change the order of tables in a @code{SELECT}. In the benchmark suite, a time more than -15000 times slower than MySQL Server was seen. This is due to @code{mSQL}'s +15,000 times slower than MySQL Server was seen. This is due to @code{mSQL}'s lack of a join optimiser to order tables in the optimal order. However, if you put the tables in exactly the right order in @code{mSQL}2 and the @code{WHERE} is simple and uses index columns, @@ -4279,7 +4283,7 @@ mysql> UPDATE SET x=x*10+y WHERE x<20; MySQL Server has column aliasing. @item Qualifying column names. -In MySQ ServerL, if a column name is unique among the tables used in a +In MySQL Server, if a column name is unique among the tables used in a query, you do not have to use the full qualifier. @item @code{SELECT} with functions. @@ -4290,10 +4294,10 @@ MySQL Server has many functions (too many to list here; see @ref{Functions}). @item Disk Space Efficiency That is, how small can you make your tables? -MySQ ServerL has very precise types, so you can create tables that take +MySQL Server has very precise types, so you can create tables that take very little space. An example of a useful MySQL datatype is the -@code{MEDIUMINT} that is 3 bytes long. If you have 100,000,000 -records, saving even one byte per record is very important. +@code{MEDIUMINT} that is 3 bytes long. If you have 100 million +records, saving even 1 byte per record is very important. @code{mSQL2} has a more limited set of column types, so it is more difficult to get small tables. @@ -4320,28 +4324,28 @@ MySQL Server currently has a lot of different JDBC drivers: @itemize @bullet @item -The mm driver: A type 4 JDBC driver by Mark Matthews +The mm driver: a type 4 JDBC driver by Mark Matthews @email{mmatthew@@ecn.purdue.edu}. This is released under the LGPL. @item -The Resin driver. This is a commercial JDBC driver released under open +The Resin driver: this is a commercial JDBC driver released under open source. @uref{http://www.caucho.com/projects/jdbc-mysql/index.xtp} @item -The gwe driver: A Java interface by GWE technologies (not supported anymore). +The gwe driver: a Java interface by GWE technologies (not supported anymore). @item -The jms driver: An improved gwe driver by Xiaokun Kelvin ZHU +The jms driver: an improved gwe driver by Xiaokun Kelvin ZHU @email{X.Zhu@@brad.ac.uk} (not supported anymore). @item -The twz driver: A type 4 JDBC driver by Terrence W. Zellers +The twz driver: a type 4 JDBC driver by Terrence W. Zellers @email{zellert@@voicenet.com}. This is commercial but is free for private and educational use (not supported anymore). @end itemize The recommended driver is the mm driver. The Resin driver may also be -good (at least the benchmarks looks good), but we haven't received that +good (at least the benchmarks look good), but we haven't received that much information about this yet. We know that @code{mSQL} has a JDBC driver, but we have too little @@ -4361,7 +4365,7 @@ most rapidly. Both @code{mSQL} and MySQL Server have many interesting third-party tools. Because it is very easy to port upward (from @code{mSQL} to MySQL Server), almost all the interesting applications that are available for -@code{mSQL} are also available for MySQ ServerL. +@code{mSQL} are also available for MySQL Server. MySQL Server comes with a simple @code{msql2mysql} program that fixes differences in spelling between @code{mSQL} and MySQL Server for the @@ -4442,7 +4446,7 @@ There are enough differences that it is impossible (or at least not easy) to support both. The most significant ways in which the MySQL protocol differs -from the @code{mSQL} protocol are listed below: +from the @code{mSQL} protocol are listed here: @itemize @bullet @item @@ -4498,7 +4502,7 @@ MySQL Server also supports the following additional type attributes: @itemize @bullet @item -@code{UNSIGNED} option for integer and floating point columns. +@code{UNSIGNED} option for integer and floating-point columns. @item @code{ZEROFILL} option for integer columns. @item @@ -4509,7 +4513,7 @@ the following additional type attributes: @code{DEFAULT} value for all columns. @end itemize @item mSQL2 -@code{mSQL} column types correspond to the MySQL types shown below: +@code{mSQL} column types correspond to the MySQL types shown in the following table: @multitable @columnfractions .15 .70 @item @code{mSQL} @strong{type} @tab @strong{Corresponding MySQL type} @item @code{CHAR(len)} @tab @code{CHAR(len)} @@ -4633,7 +4637,7 @@ Retains trailing space. @item MySQL Server MySQL correctly prioritises everything (@code{AND} is evaluated before @code{OR}). To get @code{mSQL} behavior in MySQL Server, use -parentheses (as shown in an example below). +parentheses (as shown in an example later in this section). @item mSQL Evaluates everything from left to right. This means that some logical calculations with more than three arguments cannot be expressed in any @@ -4670,18 +4674,18 @@ users. When reading the following, please note that both products are continually evolving. We at MySQL AB and the PostgreSQL developers are both working -on making our respective database as good as possible, so we are both a +on making our respective databases as good as possible, so we are both a serious alternative to any commercial database. The following comparison is made by us at MySQL AB. We have tried to be -as accurate and fair as possible, but because while we know MySQL Server thorougly +as accurate and fair as possible, but although we know MySQL Server thoroughly, we don't have a full knowledge of all PostgreSQL features, so we may have -got some things wrong. We will however correct these when they come to our +got some things wrong. We will, however, correct these when they come to our attention. We would first like to note that PostgreSQL and MySQL Server are both widely used products, but with different design goals, even if we are both striving -towards ANSI SQL compliancy. This means that for some applications MySQL Server +toward ANSI SQL compliancy. This means that for some applications MySQL Server is more suited, while for others PostgreSQL is more suited. When choosing which database to use, you should first check if the database's feature set satisfies your application. If you need raw speed, MySQL Server is probably your @@ -4712,7 +4716,7 @@ MySQL server. We at MySQL AB believe in frequent releases to be able to push out new features quickly to our users. Because of this we do a new small release about every three weeks, and a major branch every year. All releases are -throughly tested with our testing tools on a lot of different platforms. +thoroughly tested with our testing tools on a lot of different platforms. PostgreSQL is based on a kernel with lots of contributors. In this setup it makes sense to prioritise adding a lot of new features, instead of @@ -4720,18 +4724,18 @@ implementing them optimally, because one can always optimise things later if there arises a need for this. Another big difference between MySQL Server and PostgreSQL is that -nearly all of the code in the MySQL server are coded by developers that +nearly all of the code in the MySQL server is coded by developers that are employed by MySQL AB and are still working on the server code. The -exceptions are the transaction engines, and the regexp library. +exceptions are the transaction engines and the regexp library. -This is in sharp contrast to the PostgreSQL code where the majority of -the code is coded by a big group of people with different backgrounds. +This is in sharp contrast to the PostgreSQL code, the majority of +which is coded by a big group of people with different backgrounds. It was only recently that the PostgreSQL developers announced that their current developer group had finally had time to take a look at all the code in the current PostgreSQL release. -Both of the above development methods have their own merits and drawbacks. -We here at MySQL AB think of course that our model is better because our +Both of the aforementioned development methods have their own merits and drawbacks. +We here at MySQL AB think, of course, that our model is better because our model gives better code consistency, more optimal and reusable code, and in our opinion, fewer bugs. Because we are the authors of the MySQL server code, we are better able to coordinate new features and releases. @@ -4745,10 +4749,10 @@ code, we are better able to coordinate new features and releases. On the crash-me page (@uref{http://www.mysql.com/information/crash-me.php}) you can find a list of those database constructs and limits that -one can detect automatically with a program. Note however that a lot of -the numerical limits may be changed with startup options for respective -database. The above web page is however extremely useful when you want to -ensure that your applications works with many different databases or +one can detect automatically with a program. Note, however, that a lot of +the numerical limits may be changed with startup options for their respective +databases. This web page is, however, extremely useful when you want to +ensure that your applications work with many different databases or when you want to convert your application from one database to another. MySQL Server offers the following advantages over PostgreSQL: @@ -4760,11 +4764,11 @@ MySQL Server offers the following advantages over PostgreSQL: mostly-read-only sites many times. @item -MySQL has a much larger user base than PostgreSQL, therefore the code is -more tested and has historically proven more stable than PostgreSQL. -MySQL Server is more used in production environments than PostgreSQL, -mostly thanks to that MySQL AB, formerly TCX DataKonsult AB, has -provided top quality commercial support for MySQL Server from the day it +MySQL has a much larger user base than PostgreSQL. Therefore, the code is +tested more and has historically proven more stable than PostgreSQL. +MySQL Server is used more in production environments than PostgreSQL, +mostly thanks to the fact that MySQL AB, formerly TCX DataKonsult AB, has +provided top-quality commercial support for MySQL Server from the day it was released, whereas until recently PostgreSQL was unsupported. @item @@ -4779,7 +4783,7 @@ MySQL has more APIs to other languages and is supported by more existing programs than PostgreSQL. @xref{Contrib}. @item -MySQL Server works on 24/7 heavy duty systems. In most circumstances +MySQL Server works on 24/7 heavy-duty systems. In most circumstances you never have to run any cleanups on MySQL Server. PostgreSQL doesn't yet support 24/7 systems because you have to run @code{VACUUM} once in a while to reclaim space from @code{UPDATE} and @code{DELETE} @@ -4788,8 +4792,8 @@ good performance with PostgreSQL. @code{VACUUM} is also needed after adding a lot of new rows to a table. On a busy system with lots of changes, @code{VACUUM} must be run very frequently, in the worst cases even many times a day. During the @code{VACUUM} run, which may take hours -if the database is big, the database is from a production standpoint, -practically dead. Please note: In PostgreSQL version 7.2, basic vacuuming +if the database is big, the database is, from a production standpoint, +practically dead. Please note: in PostgreSQL version 7.2, basic vacuuming no longer locks tables, thus allowing normal user access during the vacuum. A new @code{VACUUM FULL} command does old-style vacuum by locking the table and shrinking the on-disk copy of the table. @@ -4810,14 +4814,14 @@ as a benchmark suite. The test system is actively updated with code to test each new feature and almost all reproduceable bugs that have come to our attention. We test MySQL Server with these on a lot of platforms before every release. These tests are more sophisticated than anything we have -seen from PostgreSQL, and they ensures that the MySQL Server is kept to a high +seen from PostgreSQL, and they ensure that the MySQL Server is kept to a high standard. @item There are far more books in print about MySQL Server than about PostgreSQL. O'Reilly, SAMS, Que, and New Riders are all major publishers with books -about MySQL. All MySQL features are also documented in the MySQL on-line -manual, because when a new feature is implemented, the MySQL developers +about MySQL. All MySQL features are also documented in the MySQL online +manual because when a new feature is implemented, the MySQL developers are required to document it before it's included in the source. @item @@ -4828,12 +4832,12 @@ MySQL Server has a much more sophisticated @code{ALTER TABLE}. @item MySQL Server has support for tables without transactions for applications that -need all speed they can get. The tables may be memory based, @code{HEAP} +need all the speed they can get. The tables may be memory-based, @code{HEAP} tables or disk based @code{MyISAM}. @xref{Table types}. @item MySQL Server has support for two different table handlers that support -transactions, @code{InnoDB} and @code{BerkeleyDB}. Because every +transactions, @code{InnoDB}, and @code{BerkeleyDB}. Because every transaction engine performs differently under different conditions, this gives the application writer more options to find an optimal solution for his or her setup, if need be per individual table. @xref{Table types}. @@ -4841,7 +4845,7 @@ his or her setup, if need be per individual table. @xref{Table types}. @item @code{MERGE} tables gives you a unique way to instantly make a view over a set of identical tables and use these as one. This is perfect for -systems where you have log files that you order for example by month. +systems where you have log files that you order, for example, by month. @xref{MERGE}. @item @@ -4854,14 +4858,14 @@ reads. This is very useful when you are archiving things. MySQL Server has internal support for full-text search. @xref{Fulltext Search}. @item -You can access many databases from the same connection (depending of course +You can access many databases from the same connection (depending, of course, on your privileges). @item -MySQL Server is coded from the start to be multi-threaded while +MySQL Server is coded from the start to be multi-threaded, while PostgreSQL uses processes. Context switching and access to common storage areas is much faster between threads than between separate -processes, this gives MySQL Server a big speed advantage in multi-user +processes. This gives MySQL Server a big speed advantage in multi-user applications and also makes it easier for MySQL Server to take full advantage of symmetric multiprocessor (SMP) systems. @@ -4870,7 +4874,7 @@ MySQL Server has a much more sophisticated privilege system than PostgreSQL. While PostgreSQL only supports @code{INSERT}, @code{SELECT}, and @code{UPDATE/DELETE} grants per user on a database or a table, MySQL Server allows you to define a full set of different -privileges on database, table and column level. MySQL Server also +privileges on the database, table, and column level. MySQL Server also allows you to specify the privilege on host and user combinations. @xref{GRANT}. @@ -4886,13 +4890,13 @@ type can be optimised for different performance characteristics. @item All MySQL table types (except @code{InnoDB}) are implemented as files -(one table per file), which makes it really easy to backup, move, delete +(one table per file), which makes it really easy to back up, move, delete, and even symlink databases and tables, even when the server is down. @item Tools to repair and optimise @code{MyISAM} tables (the most common MySQL table type). A repair tool is only needed when a physical corruption -of a data file happens, usually from a hardware failure. It allows a +of a datafile happens, usually from a hardware failure. It allows a majority of the data to be recovered. @item @@ -4917,20 +4921,20 @@ optimal binary that works in all cases. @item Table locking, as used by the non-transactional @code{MyISAM} tables, is -in many cases faster than page locks, row locks or versioning. The -drawback however is that if one doesn't take into account how table +in many cases faster than page locks, row locks, or versioning. The +drawback, however, is that if one doesn't take into account how table locks work, a single long-running query can block a table for updates for a long time. This can usually be avoided when designing the application. If not, one can always switch the trouble table to use one of the transactional table types. @xref{Table locking}. @item -With UDF (user defined functions) one can extend MySQL Server with both normal +With UDF (user-defined functions) one can extend MySQL Server with both normal SQL functions and aggregates, but this is not yet as easy or as flexible as in PostgreSQL. @xref{Adding functions}. @item -Updates that run over multiple tables is harder to do in MySQL Server. +Updates that run over multiple tables are harder to do in MySQL Server. This will, however, be fixed in MySQL Server 4.0.2 with multi-table @code{UPDATE} and in MySQL Server 4.1 with subselects. In MySQL Server 4.0 one can use multi-table deletes to delete from many tables at the @@ -4941,7 +4945,7 @@ PostgreSQL currently offers the following advantages over MySQL Server: Note that because we know the MySQL road map, we have included in the following table the version when MySQL Server should support this feature. -Unfortunately we couldn't do this for previous comparison, because we +Unfortunately we couldn't do this for previous comparisons, because we don't know the PostgreSQL roadmap. @multitable @columnfractions .30 .30 @@ -4960,7 +4964,7 @@ don't know the PostgreSQL roadmap. @item Extensible type system @tab Not planned @end multitable -Other reasons someone may consider for using PostgreSQL: +Other reasons someone may consider using PostgreSQL: @itemize @bullet @item @@ -5008,7 +5012,7 @@ in this section. @cindex PostgreSQL vs. MySQL, benchmarks -The only open source benchmark that we know of that can be used to +The only @code{Open Source} benchmark that we know of that can be used to benchmark MySQL Server and PostgreSQL (and other databases) is our own. It can be found at @uref{http://www.mysql.com/information/benchmarks.html}. @@ -5016,7 +5020,7 @@ We have many times asked the PostgreSQL developers and some PostgreSQL users to help us extend this benchmark to make it the definitive benchmark for databases, but unfortunately we haven't gotten any feedback for this. -We the MySQL developers have, because of this, spent a lot of hours to get +We, the MySQL developers, have, because of this, spent a lot of hours to get maximum performance from PostgreSQL for the benchmarks, but because we don't know PostgreSQL intimately, we are sure that there are things that we have missed. We have on the benchmark page documented exactly how we @@ -5040,65 +5044,65 @@ When running with PostgreSQL 7.1.1 we could, however, not run with @code{--fast} because during the @code{INSERT} test, the postmaster (the PostgreSQL deamon) died and the database was so corrupted that it was impossible to restart postmaster. After this happened twice, we decided -to postpone the @code{--fast} test until next PostgreSQL release. The -details about the machine we run the benchmark can be found on the +to postpone the @code{--fast} test until the next PostgreSQL release. The +details about the machine we run the benchmark on can be found on the benchmark page. Before going to the other benchmarks we know of, we would like to give -some background on benchmarks: +some background on benchmarks. It's very easy to write a test that shows @strong{any} database to be the best database in the world, by just restricting the test to something the database is very good at and not testing anything that the database is -not good at. If one, after doing this, summarises the result with as +not good at. If one, after doing this, summarises the result as a single figure, things are even easier. This would be like us measuring the speed of MySQL Server compared to PostgreSQL by looking at the summary time of the MySQL benchmarks on our web page. Based on this MySQL Server would be more than 40 times faster than PostgreSQL, -something that is of course not true. We could make things even worse +something that is, of course, not true. We could make things even worse by just taking the test where PostgreSQL performs worst and claim that MySQL Server is more than 2000 times faster than PostgreSQL. The case is that MySQL does a lot of optimisations that PostgreSQL -doesn't do. This is of course also true the other way around. An SQL -optimiser is a very complex thing, and a company could spend years on +doesn't do. This is, of course, also true the other way around. An SQL +optimiser is a very complex thing, and a company could spend years just making the optimiser faster and faster. When looking at the benchmark results you should look for things that you do in your application and just use these results to decide which database would be best suited for your application. The benchmark -results also shows things a particular database is not good at and should +results also show things a particular database is not good at and should give you a notion about things to avoid and what you may have to do in other ways. -We know of two benchmark tests that claims that PostgreSQL performs better +We know of two benchmark tests that claim that PostgreSQL performs better than MySQL Server. These both where multi-user tests, a test that we here at MySQL AB haven't had time to write and include in the benchmark suite, -mainly because it's a big task to do this in a manner that is fair against +mainly because it's a big task to do this in a manner that is fair to all databases. One is the benchmark paid for by Great Bridge, the company that for 16 months attempted to build a business based on PostgreSQL but now has ceased -operations. This is the probably worst benchmark we have ever seen anyone +operations. This is probably the worst benchmark we have ever seen anyone conduct. This was not only tuned to only test what PostgreSQL is absolutely -best at, it was also totally unfair against every other database involved in +best at, but it was also totally unfair to every other database involved in the test. @strong{Note}: We know that even some of the main PostgreSQL developers did not like the way Great Bridge conducted the benchmark, so we don't blame the PostgreSQL team for the way the benchmark was done. -This benchmark has been condemned in a lot of postings and newsgroups so -we will here just shortly repeat some things that were wrong with it. +This benchmark has been condemned in a lot of postings and newsgroups, so +here we will just briefly repeat some things that were wrong with it. @itemize @bullet @item -The tests were run with an expensive commercial tool, that makes it -impossible for an open source company like us to verify the benchmarks, +The tests were run with an expensive commercial tool that makes it +impossible for an @code{Open Source} company like us to verify the benchmarks, or even check how the benchmarks were really done. The tool is not even a true benchmark tool, but an application/setup testing tool. To refer -this as a ``standard'' benchmark tool is to stretch the truth a long way. +to this as a ``standard'' benchmark tool is to stretch the truth a long way. @item Great Bridge admitted that they had optimised the PostgreSQL database @@ -5108,17 +5112,17 @@ say ``This process optimises indexes and frees up disk space a bit. The optimised indexes boost performance by some margin.'' Our benchmarks clearly indicate that the difference in running a lot of selects on a database with and without @code{VACUUM} can easily differ by a factor -of ten. +of 10. @item The test results were also strange. The AS3AP test documentation mentions that the test does ``selections, simple joins, projections, -aggregates, one-tuple updates, and bulk updates''. +aggregates, one-tuple updates, and bulk updates.'' PostgreSQL is good at doing @code{SELECT}s and @code{JOIN}s (especially -after a @code{VACUUM}, but doesn't perform as well on @code{INSERT}s or +after a @code{VACUUM}), but doesn't perform as well on @code{INSERT}s or @code{UPDATE}s. The benchmarks seem to indicate that only @code{SELECT}s -were done (or very few updates). This could easily explain they good results +were done (or very few updates). This could easily explain the good results for PostgreSQL in this test. The bad results for MySQL will be obvious a bit down in this document. @@ -5133,12 +5137,12 @@ database itself. When running the database against Oracle and MS-SQL (Great Bridge has indirectly indicated the databases they used in the test), they didn't use the native protocol but instead ODBC. Anyone that has ever -used Oracle knows that all real application uses the native interface +used Oracle knows that all real applications use the native interface instead of ODBC. Doing a test through ODBC and claiming that the results had anything to do with using the database in a real-world situation can't be regarded as fair. They should have done two tests with and without ODBC -to provide the right facts (after having got experts to tune all involved -databases of course). +to provide the right facts (after having gotten experts to tune all involved +databases, of course). @item They refer to the TPC-C tests, but they don't mention anywhere that the @@ -5167,7 +5171,7 @@ Using an old MySQL version when there was a recommended newer one available @item Not starting MySQL Server with the right options for heavy multi-user use (the -default installation of MySQL Server is tuned for minimal resource use). +default installation of MySQL Server is tuned for minimal resource use) @end itemize Great Bridge did run a new test, with our optimised ODBC driver and with @@ -5177,15 +5181,15 @@ statically linked with a fixed glibc library. According to what we know, Great Bridge did nothing to ensure that the other databases were set up correctly to run well in their test -environment. We are sure however that they didn't contact Oracle or -Microsoft to ask for their advice in this matter ;) +environment. We are sure, however, that they didn't contact Oracle or +Microsoft to ask for their advice in this matter. ;) @item The benchmark was paid for by Great Bridge, and they decided to publish only partial, chosen results (instead of publishing it all). @end itemize -Tim Perdue, a long time PostgreSQL fan and a reluctant MySQL user +Tim Perdue, a long-time PostgreSQL fan and a reluctant MySQL user, published a comparison on PHPbuilder (@uref{http://www.phpbuilder.com/columns/tim20001112.php3}). @@ -5203,8 +5207,8 @@ how to fix this and Tim should be aware of this problem. The other possible problem could have been an old glibc library and that Tim didn't use a MySQL binary from our site, which is linked with -a corrected glibc library, but had compiled a version of his own with. -In any of the above cases, the symptom would have been exactly what Tim +a corrected glibc library, but had compiled a version of his own. +In any of these cases, the symptom would have been exactly what Tim had measured. We asked Tim if we could get access to his data so that we could repeat @@ -5212,41 +5216,42 @@ the benchmark and if he could check the MySQL version on the machine to find out what was wrong and he promised to come back to us about this. He has not done that yet. -Because of this we can't put any trust in this benchmark either :( +Because of this we can't put any trust in this benchmark either. :( -Over time things also changes and the above benchmarks are not that +Over time things also change and the preceding benchmarks are not that relevant anymore. MySQL Server now has a couple of different table handlers with different speed/concurrency tradeoffs. @xref{Table types}. It would be interesting to see how the above tests would run with the -different transactional table types in MySQL Server. PostgreSQL has of course -also got new features since the test was made. As the above test are +different transactional table types in MySQL Server. PostgreSQL +has, of course, +also got new features since the test was made. As these tests are not publicly available there is no way for us to know how the -database would preform in the same tests today. +database would perform in the same tests today. Conclusion: The only benchmarks that exist today that anyone can download and run -against MySQL Server and PostgreSQL is the MySQL benchmarks. +against MySQL Server and PostgreSQL are the MySQL benchmarks. We here at MySQL AB -believe that open source databases should be tested with open source tools! +believe that @code{Open Source} databases should be tested with @code{Open Source} tools! This is the only way to ensure that no one does tests that nobody can -reproduce and use this to claim that a database is better than another. +reproduce and use this to claim that one database is better than another. Without knowing all the facts it's impossible to answer the claims of the tester. The thing we find strange is that every test we have seen about PostgreSQL, that is impossible to reproduce, claims that PostgreSQL is better in most cases while our tests, which anyone can reproduce, -clearly shows otherwise. With this we don't want to say that PostgreSQL +clearly show otherwise. With this we don't want to say that PostgreSQL isn't good at many things (it is!) or that it isn't faster than MySQL Server under certain conditions. We would just like to see a fair test where PostgreSQL performs very well, so that we could get some friendly competition going! -For more information about our benchmarks suite, see @ref{MySQL Benchmarks}. +For more information about our benchmark suite, see @ref{MySQL Benchmarks}. -We are working on an even better benchmark suite, including multi user +We are working on an even better benchmark suite, including multi-user tests, and a better documentation of what the individual tests really do and how to add more tests to the suite. @@ -5275,8 +5280,8 @@ For a list of sites from which you can obtain MySQL, see @item To see which platforms are supported, see @ref{Which OS}. Please note that -not all supported system are equally good for running MySQL on them. -On some it is much more robust and efficient than others - see @ref{Which OS} +not all supported systems are equally good for running MySQL on them. +On some it is much more robust and efficient than others@-see @ref{Which OS} for details. @item @@ -5289,7 +5294,7 @@ use the binary distribution. @item Installation instructions for binary and source distributions are described -in @ref{Installing binary} and @ref{Installing source}. Each set of +in @ref{Installing binary}, and @ref{Installing source}. Each set of instructions includes a section on system-specific problems you may run into. @@ -5322,7 +5327,7 @@ file. The MySQL RPMs are currently being built on a RedHat Version and use @code{glibc}. If you have problems with an RPM file, for example, if you receive the error -``@code{Sorry, the host 'xxxx' could not be looked up}'', see +``@code{Sorry, the host 'xxxx' could not be looked up}''@-see @ref{Binary notes-Linux}. The RPM files you may want to use are: @@ -5349,7 +5354,7 @@ MySQL clients, such as the Perl modules. @item @code{MySQL-VERSION.src.rpm} -This contains the source code for all of the above packages. It can also +This contains the source code for all of the previous packages. It can also be used to try to build RPMs for other architectures (for example, Alpha or SPARC). @end itemize @@ -5393,7 +5398,7 @@ The MySQL server for Windows is available in two distribution types: @enumerate @item The binary distribution contains a setup program which installs -everything you need so you can start the server immediately. +everything you need so that you can start the server immediately. @item The source distribution contains all the code and support files for building the executables using the VC++ 6.0 compiler. @@ -5405,12 +5410,12 @@ Generally speaking, you should use the binary distribution. You will need the following: @itemize @bullet @item -A 32 bits Windows Operating System such as 9x, Me, NT, 2000 or XP. +A 32-bit Windows Operating System such as 9x, Me, NT, 2000, or XP. The NT family (NT, Windows 2000 and XP) permits running the MySQL server as a service. @xref{NT start}. If you want to use tables bigger than 4G, you should install MySQL -on NTFS or newer file system. Don't forget to use @code{MAX_ROWS} and +on an NTFS or newer filesystem. Don't forget to use @code{MAX_ROWS} and @code{AVG_ROW_LENGTH} when you create the table. @xref{CREATE TABLE}. @item TCP/IP protocol support. @@ -5419,12 +5424,12 @@ A copy of the MySQL binary or distribution for Windows, which can be downloaded from @uref{http://www.mysql.com/downloads/}. Note: The distribution files are supplied with a zipped format -and we recommended the use of an adequate FTP client with resume +and we recommend the use of an adequate FTP client with resume feature to avoid corruption of files during the download process. @item -A @code{ZIP} program to unpacked the distribution file. +A @code{ZIP} program to unpack the distribution file. @item -Enough space on the hard drive to unpack, install and to create the +Enough space on the hard drive to unpack, install, and create the databases in accorandance with your requirements. @item If you plan to connect to the MySQL server via @code{ODBC}, you @@ -5462,7 +5467,7 @@ C:\mysql\bin> mysqladmin -u root shutdown @item On NT/2000/XP machines, if you want to change the server executable -(e.g. -max or -nt), it is also necessary to remove the service: +(e.g., -max or -nt), it is also necessary to remove the service: @example C:\mysql\bin> mysqld-max-nt --remove @@ -5491,7 +5496,7 @@ Here is a list of the different MySQL servers you can use: @item @strong{Binary} @tab @strong{Description} @item @code{mysqld} @tab Compiled with full debugging and automatic memory allocation -checking, symbolic links, InnoDB and BDB tables. +checking, symbolic links, InnoDB, and BDB tables. @item @code{mysqld-opt} @tab Optimised binary with no support for transactional tables. @item @code{mysqld-nt} @tab @@ -5508,14 +5513,14 @@ Like @code{mysqld-max}, but compiled with support for named pipes. Starting from 3.23.50, named pipes are only enabled if one starts mysqld with @code{--enable-named-pipe}. -All of the above binaries are optimised for the Pentium Pro +All of the preceding binaries are optimised for the Pentium Pro processor but should work on any Intel processor >= i386. You will need to use an option file to specify your MySQL configuration under the following circumstances: @itemize @bullet @item -The installation or data directories are different than the default +The installation or data directories are different from the default locations (@file{c:\mysql} and @file{c:\mysql\data}). @item You want to use one of these servers: @@ -5533,9 +5538,9 @@ option file @code{my.ini}. In this case you don't have to worry about the following section. There are two option files with the same function: @file{my.cnf} and -@file{my.ini} file. However, to avoid confusion, it's best if you use only +@file{my.ini}. However, to avoid confusion, it's best if you use only of one them. Both files are plain text. The @file{my.cnf} file, if used, -should be created in the root directory of drive C. The @file{my.ini} +should be created in the root directory of the C drive. The @file{my.ini} file, if used, should be created in the Windows system directory. (This directory is typically something like @file{C:\WINDOWS} or @file{C:\WINNT}. You can determine its exact location from the value of the @code{windir} @@ -5543,7 +5548,7 @@ environment variable.) MySQL looks first for the @code{my.ini} file, then for the @file{my.cnf} file. If your PC uses a boot loader where the C drive isn't the boot drive, -then your only option is to use the @file{my.ini} file. Also note that +your only option is to use the @file{my.ini} file. Also note that if you use the @code{WinMySQLAdmin} tool, it uses only the @file{my.ini} file. The @file{\mysql\bin} directory contains a help file with instructions for using this tool. @@ -5565,13 +5570,13 @@ Note that Windows pathnames should be specified in option files using forward slashes rather than backslashes. If you do use backslashes, you must double them. -If you would like to use a data directory different than the default of +If you would like to use a data directory different from the default of @file{c:\mysql\data}, you must copy the entire contents of the @file{c:\mysql\data} directory to the new location. If you want to use the @code{InnoDB} transactional tables, you need to manually create two new directories to hold the InnoDB -data and log files, e.g. @file{c:\ibdata} and @file{c:\iblogs}. +data and log files@-e.g., @file{c:\ibdata} and @file{c:\iblogs}. You will also need to add some extra lines to the option file. @xref{InnoDB start}. @@ -5599,7 +5604,7 @@ C:\mysql\bin> mysqld-max --standalone You should see the following messages as the server starts up: @example -InnoDB: The first specified data file c:\ibdata\ibdata1 did not exist: +InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200 InnoDB: Database physically writes the file full: wait... @@ -5659,10 +5664,10 @@ Our main download mirror is located at: If you are interested in becoming a MySQL mirror site, you may anonymously rsync with: @code{rsync://sunsite.dk/ftp/mirrors/mysql/}. Please send e-mail to @email{webmaster@@mysql.com} notifying us of your mirror to be -added to the list below. +added to the following list. If you have problems downloading from our main site, try using one of the -mirrors listed below. +following mirrors. Please report bad or out-of-date mirrors to @email{webmaster@@mysql.com}. @@ -5719,7 +5724,7 @@ Mac OS X Server. @xref{Mac OS X}. @item NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (Requires GNU make). @xref{NetBSD}. @item -OpenBSD > 2.5 with native therads. OpenBSD < 2.5 with the included +OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the included MIT-pthreads package. @xref{OpenBSD}. @item OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4. @xref{OS/2}. @@ -5742,7 +5747,7 @@ Windows 9x, Me, NT, 2000 and XP. @xref{Windows}. Note that not all platforms are suited equally well for running MySQL. How well a certain platform is suited for a high-load -mission critical MySQL server is determined by the following +mission-critical MySQL server is determined by the following factors: @itemize @bullet @@ -5762,15 +5767,15 @@ CPU than the original process. The ability of the kernel and/or the thread library to run many threads which acquire/release a mutex over a short critical region frequently without excessive context switches. In other words, if the implementation of -@code{pthread_mutex_lock()} is too anxious to yield CPU, this will hurt +@code{pthread_mutex_lock()} is too anxious to yield CPU time, this will hurt MySQL tremendously. If this issue is not taken care of, adding extra CPUs will actually make MySQL slower. @item -General file system stability/performance. +General filesystem stability/performance. @item -Ability of the file system to deal with large files at all and deal with them +Ability of the filesystem to deal with large files at all and deal with them efficiently, if your tables are big. @item @@ -5785,11 +5790,11 @@ The amount of testing of similar configurations we have done internally. @item The number of users that have successfully run MySQL on that platform in similar configurations. If this number is high, the chances of -hitting some platform-specific surprise are much smaller. +hitting some platform-specific surprises are much smaller. @end itemize -Based on the above criteria, the best platforms for running -MySQL at this point are x86 with SuSE Linux 7.1, 2.4 kernel and +Based on the preceding criteria, the best platforms for running +MySQL at this point are x86 with SuSE Linux 7.1, 2.4 kernel, and ReiserFS (or any similar Linux distribution) and SPARC with Solaris 2.7 or 2.8. FreeBSD comes third, but we really hope it will join the top club once the thread library is improved. We also hope that at some @@ -5803,15 +5808,15 @@ development, and need more detailed instructions on what MySQL needs to run better, send an e-mail to @email{internals@@lists.mysql.com}. -Please note that the comparison above is not to say that one OS is better or +Please note that the preceding comparison is not to say that one OS is better or worse than the other in general. We are talking about choosing a particular OS -for a dedicated purpose - running MySQL, and compare platforms in that +for a dedicated purpose@-running MySQL, and compare platforms in that regard only. With this in mind, the result of this comparison would be different if we included more issues into it. And in some cases, the reason one OS is better than the other could simply be that we have put forth more effort into testing on and optimising for that particular platform. -We are just stating our observations to help you make a -decision on which platform to use MySQL on in your setup. +We are just stating our observations to help you decide on which +platform to use MySQL on in your setup. @node Which version, Installation layouts, Which OS, General Installation Issues @@ -5830,7 +5835,7 @@ release or the last stable release: @item Normally, if you are beginning to use MySQL for the first time or trying to port it to some system for which there is no binary distribution, we -recommend going with the stable release (currently Version 3.23. Note +recommend going with the stable release (currently version 3.23). Note that all MySQL releases are checked with the MySQL benchmarks and an extensive test suite before each release (even the development releases). @@ -5859,8 +5864,8 @@ to get even more flexibility). @item To be able to satisfy different user requirements, we are providing two -different binary versions; One compiled with the non-transactional table -handlers, (a small, fast binary), and one configured with the most +different binary versions: one compiled with the non-transactional table +handlers (a small, fast binary), and one configured with the most important extended options like transaction-safe tables. Both versions are compiled from the same source distribution. All native @code{MySQL} clients can connect to both MySQL versions. @@ -5888,12 +5893,12 @@ common extra options that you may want to use: @item The default binary distribution is normally compiled with support -for all characters sets and should work on a variety of processors from +for all character sets and should work on a variety of processors from the same processor family. If you want a faster MySQL server you may want to recompile it with support for only the character sets you need, use a better compiler -(like @code{pgcc}) or use compiler options that are better optimised for your +(like @code{pgcc}), or use compiler options that are better optimised for your processor. @item @@ -5924,7 +5929,7 @@ releases have the same file format. The second number (@code{21}) is the release level. Normally there are two to choose from. One is the release/stable branch (currently @code{23}) and the other is the development branch (currently @code{4.0}). Normally both are -stable, but the development version may have quirks, missing documentation on +stable, but the development version may have quirks, may be missing documentation on new features, or may fail to compile on some systems. @item @@ -6090,7 +6095,7 @@ versions, the second number in the version string is incremented. When the file format changes, the first number is increased. @item -Stable tested releases are meant to appear about 1-2 times a year, but +Stable-tested releases are meant to appear about 1-2 times a year, but if small bugs are found, a release with only bug fixes will be released. @item @@ -6117,14 +6122,14 @@ release as soon as possible. We would like other companies to do this, too. @end itemize -The current stable release is Version 3.23; We have already moved active +The current stable release is Version 3.23; we have already moved active development to Version 4.0. Bugs will still be fixed in the stable version. We don't believe in a complete freeze, as this also leaves out bug fixes and things that ``must be done.'' ``Somewhat frozen'' means that we may add small things that ``almost surely will not affect anything that's already working.'' -MySQL uses a little different naming scheme that most other products. +MySQL uses a slightly different naming scheme from most other products. In general it's relatively safe to use any version that has been out for a couple of weeks without being replaced with a new version. @xref{Which version}. @@ -6179,8 +6184,8 @@ and are configured with the following compilers and options: @code{CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex} @end table -Anyone who has more optimal options for any of the configurations listed -above can always mail them to the developer's mailing list at +Anyone who has more optimal options for any of the preceding +configurations listed can always mail them to the developer's mailing list at @email{internals@@lists.mysql.com}. RPM distributions prior to MySQL Version 3.22 are user-contributed. @@ -6188,7 +6193,7 @@ Beginning with Version 3.22, the RPMs are generated by us at MySQL AB. If you want to compile a debug version of MySQL, you should add -@code{--with-debug} or @code{--with-debug=full} to the above configure lines +@code{--with-debug} or @code{--with-debug=full} to the preceding configure lines and remove any @code{-fomit-frame-pointer} options. For the Windows distribution, please see @ref{Windows installation}. @@ -6257,15 +6262,15 @@ you install the @code{DBI} and @code{Msql-Mysql-modules} Perl modules. A more detailed description follows. -To install a binary distribution, follow the steps below, then proceed +To install a binary distribution, follow these steps, then proceed to @ref{Post-installation}, for post-installation setup and testing: @enumerate @item Pick the directory under which you want to unpack the distribution, and move -into it. In the example below, we unpack the distribution under +into it. In the following example, we unpack the distribution under @file{/usr/local} and create a directory @file{/usr/local/mysql} into which -MySQL is installed. (The following instructions therefore assume +MySQL is installed. (The following instructions, therefore, assume you have permission to create files in @file{/usr/local}. If that directory is protected, you will need to perform the installation as @code{root}.) @@ -6406,8 +6411,7 @@ You can start the MySQL server with the following command: shell> bin/safe_mysqld --user=mysql & @end example -@xref{safe_mysqld, , @code{safe_mysqld}}. - +Now proceed to @ref{safe_mysqld, , @code{safe_mysqld}}, and @xref{Post-installation}. @@ -6420,7 +6424,7 @@ shell> bin/safe_mysqld --user=mysql & Before you proceed with the source installation, check first to see if our binary is available for your platform and if it will work for you. We -put in a lot of effort into making sure that our binaries are built with the +put a lot of effort into making sure that our binaries are built with the best possible options. You need the following tools to build and install MySQL from source: @@ -6441,8 +6445,8 @@ using @code{gcc}. @code{gcc} 2.7.x has a bug that makes it impossible to compile some perfectly legal C++ files, such as @file{sql/sql_base.cc}. If you only have @code{gcc} 2.7.x, you must upgrade your @code{gcc} to be able to compile MySQL. @code{gcc} -2.8.1 is also known to have problems on some platforms so it should be -avoided if there exists a new compiler for the platform.. +2.8.1 is also known to have problems on some platforms, so it should be +avoided if a new compiler exists for the platform. @code{gcc} >= 2.95.2 is recommended when compiling MySQL Version 3.23.x. @@ -6453,7 +6457,7 @@ sometimes required. If you have problems, we recommend trying GNU @code{make} 3.75 or newer. @end itemize -If you are using a recent version of @strong{gcc}, recent enough to understand +If you are using a recent version of @code{gcc}, recent enough to understand the @code{-fno-exceptions} option, it is @strong{very important} that you use it. Otherwise, you may compile a binary that crashes randomly. We also recommend that you use @code{-felide-constructors} and @code{-fno-rtti} along @@ -6514,12 +6518,12 @@ shell> /usr/local/mysql/bin/mysqld_safe --user=mysql & if you are running MySQL 4.x. @end example -If you want have support for InnoDB tables, you should edit the +If you want to have support for InnoDB tables, you should edit the @code{/etc/my.cnf} file and remove the @code{#} character before the -parameters that starts with @code{innodb_...}. @xref{Option -files}. @xref{InnoDB start}. +parameter that starts with @code{innodb_...}. +@xref{Option files}, and @ref{InnoDB start}. -If you start from a source RPM, then do the following: +If you start from a source RPM, do the following: @example shell> rpm --rebuild MySQL-VERSION.src.rpm @@ -6532,7 +6536,7 @@ you install the @code{DBI} and @code{Msql-Mysql-modules} Perl modules. A more detailed description follows. -To install a source distribution, follow the steps below, then proceed +To install a source distribution, follow these steps, then proceed to @ref{Post-installation}, for post-installation initialisation and testing: @enumerate @@ -6562,7 +6566,7 @@ shell> groupadd mysql shell> useradd -g mysql mysql @end example -These commands add the @code{mysql} group, and the @code{mysql} user. The +These commands add the @code{mysql} group and the @code{mysql} user. The syntax for @code{useradd} and @code{groupadd} may differ slightly on different versions of Unix. They may also be called @code{adduser} and @code{addgroup}. You may wish to call the user and group something else instead of @code{mysql}. @@ -6583,7 +6587,7 @@ shell> cd mysql-VERSION @end example Note that currently you must configure and build MySQL from -this top-level directory. You can not build it in a different +this top-level directory. You cannot build it in a different directory. @item @@ -6664,12 +6668,12 @@ distribution: shell> /usr/local/mysql/bin/safe_mysqld --user=mysql & @end example -If that command fails immediately with @code{mysqld daemon ended} then you can +If that command fails immediately with @code{mysqld daemon ended}, you can find some information in the file @file{mysql-data-directory/'hostname'.err}. The likely reason is that you already have another @code{mysqld} server running. @xref{Multiple servers}. -@xref{Post-installation}. +Now proceed to @ref{Post-installation}. @node Applying patches, configure options, Quick install, Installing source @@ -6693,7 +6697,8 @@ shell> make clean @end example Patches from the FTP site are distributed as plain text files or as files -compressed with @code{gzip}. Apply a plain patch as shown above for +compressed with @code{gzip}. Apply a plain patch as shown +previously for mailing list patches. To apply a compressed patch, change into the top-level directory of your MySQL source tree and run these commands: @@ -6726,7 +6731,7 @@ the version that is currently executing. The @code{configure} script gives you a great deal of control over how you configure your MySQL distribution. Typically you do this -using options on the @code{configure} command line. You can also affect +using options on the @code{configure} command-line. You can also affect @code{configure} using certain environment variables. @xref{Environment variables}. For a list of options supported by @code{configure}, run this command: @@ -6735,7 +6740,7 @@ this command: shell> ./configure --help @end example -Some of the more commonly-used @code{configure} options are described below: +Some of the more commonly-used @code{configure} options are described here: @itemize @bullet @item @@ -6757,7 +6762,7 @@ warnings about @file{mysql.cc}. (If @code{make} stops, try @code{make -k} to tell it to continue with the rest of the build even if errors occur.) @item -If you want to get a embedded MySQL library (@code{libmysqld.a}) you should +If you want to get an embedded MySQL library (@code{libmysqld.a}) you should use the @code{--with-embedded-server} option. @item @@ -6828,7 +6833,7 @@ shell> CC=gcc CXX=gcc ./configure When you use @code{gcc} as your C++ compiler, it will not attempt to link in @code{libg++} or @code{libstdc++}. -Here is some common environment variables to set depending on +Here are some common environment variables to set depending on the compiler you are using: @tindex CXXFLAGS environment variable @@ -6849,7 +6854,7 @@ CXXFLAGS="-O3 -mpentiumpro -mstack-align-double -felide-constructors \ @end multitable In most cases you can get a reasonably optimal MySQL binary by -using the options from the above and adding the following options to the +using the options from the preceding table and adding the following options to the configure line: @example @@ -6857,7 +6862,7 @@ configure line: --with-mysqld-ldflags=-all-static @end example -The full configure line would in other words be something like the +The full configure line would, in other words, be something like the following for all recent gcc versions: @example @@ -6917,7 +6922,7 @@ you should take a look at the @code{SET OPTION CHARACTER SET} command. @xref{SET OPTION, , @code{SET OPTION}}. @cindex @code{myisamchk} -@strong{Warning:} If you change character sets after having created any +@strong{Warning}: If you change character sets after having created any tables, you will have to run @code{myisamchk -r -q} on every table. Your indexes may be sorted incorrectly otherwise. (This can happen if you install MySQL, create some tables, then reconfigure @@ -6926,8 +6931,9 @@ MySQL to use a different character set and reinstall it.) With the option @code{--with-extra-charset=LIST} you can define which additional character sets should be incompiled in the server. -Here @code{LIST} is either a list of character set separated with space, -@code{complex} to include all characters that can't be dynamically loaded +Here @code{LIST} is either a list of character +sets separated with spaces, +@code{complex} to include all characters that can't be dynamically loaded, or @code{all} to include all character sets into the binaries. @item @@ -6961,7 +6967,7 @@ system-specific section of this manual. @cindex BitKeeper tree @cindex cvs tree -@strong{Caution:} You should read this section only if you are interested +@strong{Caution}: You should read this section only if you are interested in helping us test our new code. If you just want to get MySQL up and running on your system, you should use a standard release distribution (either a source or binary distribution will do). @@ -6970,15 +6976,15 @@ To obtain our most recent development source tree, use these instructions: @enumerate @item -Download @strong{BitKeeper} from +Download @code{BitKeeper} from @uref{http://www.bitmover.com/cgi-bin/download.cgi}. You will need -@strong{Bitkeeper} 2.0 or newer to access our repository. +@code{Bitkeeper} 2.0 or newer to access our repository. @item Follow the instructions to install it. @item -After @strong{BitKeeper} is installed, first go to the directory you +After @code{BitKeeper} is installed, first go to the directory you want to work from, and then use this command if you want to clone the MySQL 3.23 branch: @@ -6992,7 +6998,7 @@ To clone the 4.0 branch, use this command instead: shell> bk clone bk://work.mysql.com:7001 mysql-4.0 @end example -In the above examples the source tree will be set up in the @file{mysql/} +In the preceding examples the source tree will be set up in the @file{mysql/} or @file{mysql-4.0/} subdirectory of your current directory. The initial download of the source tree may take a while, depending on the @@ -7018,7 +7024,7 @@ shell> make A collection of our standard configure scripts is located in the @file{BUILD/} subdirectory. If you are lazy, you can use @file{BUILD/compile-pentium-debug}. To compile on a different architecture, -modify the script removing flags that are Pentium-specific. +modify the script by removing flags that are Pentium-specific. @item When the build is done, run @code{make install}. Be careful with this @@ -7040,7 +7046,7 @@ crash trying to process our configuration files, please report that also. However, if you execute @code{aclocal} and get a @code{command not found} error or a similar problem, do not report it. Instead, make sure all the necessary tools are installed and that your @code{PATH} variable is -set correctly so your shell can find them. +set correctly so that your shell can find them. @item After the initial @code{bk clone} operation to get the source tree, you @@ -7057,7 +7063,7 @@ to the source. If you do not have the time to code your idea, just send a description. @item -@strong{BitKeeper} has a nice help utility that you can access via +@code{BitKeeper} has a nice help utility that you can access via @code{bk helptool}. @end enumerate @@ -7075,8 +7081,8 @@ a description. All MySQL programs compile cleanly for us with no warnings on Solaris using @code{gcc}. On other systems, warnings may occur due to differences in system include files. See @ref{MIT-pthreads} for warnings -that may occur when using MIT-pthreads. For other problems, check the list -below. +that may occur when using MIT-pthreads. For other problems, check +the following list. The solution to many problems involves reconfiguring. If you do need to reconfigure, take note of the following: @@ -7097,7 +7103,7 @@ when you reconfigure. @item Each time you run @code{configure}, you must run @code{make} again to recompile. However, you may want to remove old object files from previous -builds first, because they were compiled using different configuration options. +builds first because they were compiled using different configuration options. @end itemize To prevent old configuration information or object files from being used, @@ -7110,7 +7116,7 @@ shell> make clean Alternatively, you can run @code{make distclean}. -The list below describes some of the problems compiling MySQL +The following list describes some of the problems when compiling MySQL that have been found to occur most often: @itemize @bullet @@ -7122,7 +7128,7 @@ that have been found to occur most often: @cindex virtual memory, problems while compiling @cindex configure option, --with-low-memory If you get errors when compiling @file{sql_yacc.cc}, such as the ones shown -below, you have probably run out of memory or swap space: +here, you have probably run out of memory or swap space: @example Internal compiler error: program cc1plus got fatal signal 11 @@ -7180,7 +7186,7 @@ This works because @code{gcc} compiles C++ sources as well as @code{g++} does, but does not link in @code{libg++} or @code{libstdc++} by default. Another way to fix these problems, of course, is to install @code{g++}, -@code{libg++} and @code{libstdc++}. +@code{libg++}, and @code{libstdc++}. @item If your compile fails with errors, such as any of the following, @@ -7241,7 +7247,7 @@ client/libmysql.c:273: parse error before `__attribute__' @code{egcs} 1.0.3a instead. @item -If you get errors such as those shown below when compiling @code{mysqld}, +If you get errors such as those shown here when compiling @code{mysqld}, @code{configure} didn't correctly detect the type of the last argument to @code{accept()}, @code{getsockname()}, or @code{getpeername()}: @@ -7262,12 +7268,12 @@ To fix this, edit the @file{config.h} file (which is generated by Change @code{XXX} to @code{size_t} or @code{int}, depending on your operating system. (Note that you will have to do this each time you run -@code{configure}, because @code{configure} regenerates @file{config.h}.) +@code{configure} because @code{configure} regenerates @file{config.h}.) @item The @file{sql_yacc.cc} file is generated from @file{sql_yacc.yy}. Normally the build process doesn't need to create @file{sql_yacc.cc}, because -MySQL comes with an already-generated copy. However, if you do need +MySQL comes with an already generated copy. However, if you do need to re-create it, you might encounter this error: @example @@ -7293,7 +7299,7 @@ link your clients with the new client library. @xref{Debugging client}. This section describes some of the issues involved in using MIT-pthreads. -Note that on Linux you should NOT use MIT-pthreads but install LinuxThreads! +Note that on Linux you should @strong{not} use MIT-pthreads but install LinuxThreads! @xref{Linux}. If your system does not provide native thread support, you will need to @@ -7311,13 +7317,13 @@ shell> ./configure --with-mit-threads @end example Building in a non-source directory is not supported when using -MIT-pthreads, because we want to minimise our changes to this code. +MIT-pthreads because we want to minimise our changes to this code. @item -The checks that determine whether or not to use MIT-pthreads occur only +The checks that determine whether to use MIT-pthreads occur only during the part of the configuration process that deals with the server code. If you have configured the distribution using @code{--without-server} -to build only the client code, clients will not know whether or not +to build only the client code, clients will not know whether MIT-pthreads is being used and will use Unix socket connections by default. Because Unix sockets do not work under MIT-pthreads, this means you will need to use @code{-h} or @code{--host} when you run client programs. @@ -7397,9 +7403,9 @@ Building MySQL @enumerate @item -Create a work directory (e.g.: workdir). +Create a work directory (e.g., workdir). @item -Unpack the source distribution in the above directory. +Unpack the source distribution in the aforementioned directory. @item Start the VC++ 6.0 compiler. @item @@ -7413,7 +7419,7 @@ select the @code{Set Active Configuration} menu. Click over the screen selecting @code{mysqld - Win32 Debug} and click OK. @item -Press @code{F7} to begin the build of the debug server, libs and +Press @code{F7} to begin the build of the debug server, libs, and some client applications. @item When the compilation finishes, copy the libs and the executables @@ -7421,7 +7427,7 @@ to a separate directory. @item Compile the release versions that you want, in the same way. @item -Create the directory for the MySQL stuff: e.g. @file{c:\mysql} +Create the directory for the MySQL stuff: e.g., @file{c:\mysql} @item From the workdir directory copy for the c:\mysql directory the following directories: @@ -7486,7 +7492,7 @@ shell> ./bin/safe_mysqld --user=mysql & This creates the @code{mysql} database which will hold all database privileges, the @code{test} database which you can use to test -MySQL and also privilege entries for the user that run +MySQL, and also privilege entries for the user that run @code{mysql_install_db} and a @code{root} user (without any passwords). This also starts the @code{mysqld} server. @@ -7501,7 +7507,7 @@ distribution. For a binary distribution, this is your installation directory distribution, this is the main directory of your MySQL source tree. @cindex testing, the server -In the commands shown below in this section and in the following +In the commands shown in this section and in the following subsections, @code{BINDIR} is the path to the location in which programs like @code{mysqladmin} and @code{safe_mysqld} are installed. For a binary distribution, this is the @file{bin} directory within the @@ -7513,7 +7519,7 @@ installed. For a binary distribution, this is the same as @code{BINDIR}. For a source distribution, @code{EXECDIR} is probably @file{/usr/local/libexec}. -Testing is described in detail below: +Testing is described in detail: @cindex testing, installation @enumerate @@ -7538,7 +7544,7 @@ you are unsure of what to do, you can always run @code{mysql_install_db}.) @code{mysql} database. A description of the initial privileges is given in @ref{Default privileges}. Briefly, these privileges allow the MySQL @code{root} user to do anything, and allow anybody to create or use databases -with a name of @code{'test'} or starting with @code{'test_'}. +with a name of @code{test} or starting with @code{test_}. If you don't set up the grant tables, the following error will appear in the log file when you start the server: @@ -7548,13 +7554,13 @@ log file when you start the server: mysqld: Can't find file: 'host.frm' @end example -The above may also happen with a binary MySQL distribution if you +This may also happen with a binary MySQL distribution if you don't start MySQL by executing exactly @code{./bin/safe_mysqld}! @xref{safe_mysqld, , @code{safe_mysqld}}. You might need to run @code{mysql_install_db} as @code{root}. However, if you prefer, you can run the MySQL server as an unprivileged -(non-@code{root}) user, provided that user can read and write files in +(non-@code{root}) user, provided that the user can read and write files in the database directory. Instructions for running MySQL as an unprivileged user are given in @ref{Changing MySQL user, , Changing MySQL user}. @@ -7610,15 +7616,14 @@ shell> BINDIR/mysqladmin variables @end example The output from @code{mysqladmin version} varies slightly depending on your -platform and version of MySQL, but should be similar to that shown -below: +platform and version of MySQL, but should be similar to that shown here: @example shell> BINDIR/mysqladmin version mysqladmin Ver 8.14 Distrib 3.23.32, for linux on i586 Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB This software comes with ABSOLUTELY NO WARRANTY. This is free software, -and you are welcome to modify and redistribute it under the GPL license +and you are welcome to modify and redistribute it under the GPL license. Server version 3.23.32-debug Protocol version 10 @@ -7662,7 +7667,7 @@ see @ref{Starting server}. @item Run some simple tests to verify that the server is working. -The output should be similar to what is shown below: +The output should be similar to what is shown here: @example shell> BINDIR/mysqlshow @@ -7777,7 +7782,7 @@ example, for testing, or perhaps you simply want to run two installations at the same time). Generally the problem that occurs when you try to run the second server is that it tries to use the same socket and port as the old one. In this case you will get the error message: @code{Can't start server: Bind on -TCP/IP port: Address already in use} or @code{Can't start server : Bind on +TCP/IP port: Address already in use} or @code{Can't start server: Bind on unix socket...}. @xref{Installing many servers}. @item You don't have write access to @file{/tmp} @@ -7802,7 +7807,7 @@ shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysqld.sock shell> export TMPDIR MYSQL_UNIX_PORT @end example -@xref{Problems with mysql.sock}. +See @ref{Problems with mysql.sock}. @file{some_tmp_dir} should be the path to some directory for which you have write permission. @xref{Environment variables}. @@ -7868,7 +7873,7 @@ For Windows NT/2000/XP, please see @ref{NT start}. By invoking @code{mysqld} directly. @end itemize -When the @code{mysqld} daemon starts up, it changes directory to the +When the @code{mysqld} daemon starts up, it changes the directory to the data directory. This is where it expects to write log files and the pid (process ID) file, and where it expects to find databases. @@ -7884,7 +7889,7 @@ defaults by specifying the correct pathnames as command-line arguments to Normally you should need to tell @code{mysqld} only the base directory under which MySQL is installed. You can do this with the @code{--basedir} option. You can also use @code{--help} to check the effect of changing path -options (note that @code{--help} @emph{must} be the final option of the +options (note that @code{--help} @strong{must} be the final option of the @code{mysqld} command). For example: @example @@ -7898,7 +7903,7 @@ Whichever method you use to start the server, if it fails to start up correctly, check the log file to see if you can find out why. Log files are located in the data directory (typically @file{/usr/local/mysql/data} for a binary distribution, -@file{/usr/local/var} for a source distribution, +@file{/usr/local/var} for a source distribution, and @file{\mysql\data\mysql.err} on Windows). Look in the data directory for files with names of the form @file{host_name.err} and @file{host_name.log} where @code{host_name} is the name of your server @@ -7909,7 +7914,7 @@ shell> tail host_name.err shell> tail host_name.log @end example -If you find something like the following in the log file: +Look for something like the following in the log file: @example 000729 14:50:10 bdb: Recovery function for LSN 1 27595 failed 000729 14:50:10 bdb: warning: ./test/t1.db: No such file or directory @@ -7920,7 +7925,7 @@ This means that you didn't start @code{mysqld} with @code{--bdb-no-recover} and Berkeley DB found something wrong with its log files when it tried to recover your databases. To be able to continue, you should move away the old Berkeley DB log file from the database directory to -some other place, where you can later examine these. The log files are +some other place, where you can later examine it. The log files are named @file{log.0000000001}, where the number will increase over time. If you are running @code{mysqld} with BDB table support and @code{mysqld} core @@ -8012,7 +8017,7 @@ shell> mysql.server stop under the MySQL installation directory or in the @file{support-files} directory of the MySQL source tree. -Before @code{mysql.server} starts the server, it changes directory to +Before @code{mysql.server} starts the server, it changes the directory to the MySQL installation directory, then invokes @code{safe_mysqld}. You might need to edit @code{mysql.server} if you have a binary distribution that you've installed in a non-standard location. Modify it to @code{cd} @@ -8025,7 +8030,7 @@ You can take down the server manually by executing @code{mysqladmin shutdown}. You might want to add these start and stop commands to the appropriate places in your @file{/etc/rc*} files when you start using MySQL for -production applications. Note that if you modify @code{mysql.server}, then +production applications. Note that if you modify @code{mysql.server}, and then upgrade MySQL sometime, your modified version will be overwritten, so you should make a copy of your edited version that you can reinstall. @@ -8073,15 +8078,15 @@ read from option files: @cindex upgrading @cindex downgrading -You can always move the MySQL form and data files between +You can always move the MySQL form and datafiles between different versions on the same architecture as long as you have the same base version of MySQL. The current base version is 3. If you change the character set when running MySQL (which may also change the sort order), you must run @code{myisamchk -r -q} on all -tables. Otherwise your indexes may not be ordered correctly. +tables. Otherwise, your indexes may not be ordered correctly. If you are afraid of new versions, you can always rename your old -@code{mysqld} to something like @code{mysqld}-'old-version-number'. If +@code{mysqld} to something like @code{mysqld-old-version-number}. If your new @code{mysqld} then does something unexpected, you can simply shut it down and restart with your old @code{mysqld}! @@ -8119,7 +8124,7 @@ dumping core after you upgrade MySQL. @node Upgrading-from-3.23, Upgrading-from-3.22, Upgrade, Upgrade @subsection Upgrading From Version 3.23 to Version 4.0 -You can use your old data files without any modification with Version 4.0. +You can use your old datafiles without any modification with Version 4.0. If you want to move your data from a MySQL 4.0 server to an older server, you have to use @code{mysqldump}. @@ -8131,11 +8136,11 @@ version 4.0; @itemize @bullet @item @code{DOUBLE} and @code{FLOAT} columns are now honoring the -@code{UNSIGNED} flag on storage (before @code{UNSIGNED} was ignored for +@code{UNSIGNED} flag on storage (before, @code{UNSIGNED} was ignored for these columns). @item Use @code{ORDER BY column DESC} now always sorts @code{NULL} values -first; In 3.23 this was not always consistent. +first; in 3.23 this was not always consistent. @item @code{SHOW INDEX} has 2 columns more (@code{Null} and @code{Index_type}) than it had in 3.23. @@ -8143,11 +8148,11 @@ than it had in 3.23. @code{SIGNED} is a reserved word. @item The result of all bitwise operators @code{|}, @code{&}, @code{<<}, -@code{>>} and @code{~} is now unsigned. This may cause problems if you +@code{>>}, and @code{~} is now unsigned. This may cause problems if you are using them in a context where you want a signed result. @xref{Cast Functions}. @item -@strong{NOTE:} When you use subtraction between integer values where +@strong{Note}: when you use subtraction between integer values where one is of type @code{UNSIGNED}, the result will be unsigned! In other words, before upgrading to MySQL 4.0, you should check your application for cases where you are subtracting a value from an unsigned entity and @@ -8160,11 +8165,11 @@ To use @code{MATCH ... AGAINST (... IN BOOLEAN MODE)} with your tables, you need to rebuild them with @code{ALTER TABLE table_name TYPE=MyISAM}, @strong{even} if they are of @code{MyISAM} type. @item -@code{LOCATE()} and @code{INSTR()} are case sensitive if one of the +@code{LOCATE()} and @code{INSTR()} are case-sensitive if one of the arguments is a binary string. @item @code{STRCMP()} now uses the current character set when doing comparisons, -which means that the default comparison behavior now is case insensitive. +which means that the default comparison behavior now is case-insensitive. @item @code{HEX(string)} now returns the characters in string converted to hexadecimal. If you want to convert a number to hexadecimal, you should @@ -8176,18 +8181,18 @@ don't specify @code{IGNORE}. @item @file{safe_mysqld} is renamed to @file{mysqld_safe}. @item -The old C API functions @code{mysql_drop_db}, @code{mysql_create_db} and +The old C API functions @code{mysql_drop_db}, @code{mysql_create_db}, and @code{mysql_connect} are not supported anymore, unless you compile MySQL with @code{CFLAGS=-DUSE_OLD_FUNCTIONS}. Instead of doing this, it is preferable to change the client to use the new 4.0 API. @item -In the @code{MYSQL_FIELD} structure, @code{length} and @code{max_length} has +In the @code{MYSQL_FIELD} structure, @code{length} and @code{max_length} have changed from @code{unsigned int} to @code{unsigned long}. This should not cause any other problems than some warnings if you use these to @code{printf()} type function. @item You should use @code{TRUNCATE TABLE} when you want to delete all rows -from a table and you don't care of how many rows where deleted. +from a table and you don't care how many rows were deleted. (Because @code{TRUNCATE TABLE} is faster than @code{DELETE FROM table_name}). @item You will get an error if you have an active @code{LOCK TABLES} or @@ -8195,21 +8200,20 @@ transaction when trying to execute @code{TRUNCATE TABLE} or @code{DROP DATABASE}. @item You should use integers to store values in BIGINT columns (instead of using -strings as you did in MySQL 3.23). Using strings will still work, but using +strings, as you did in MySQL 3.23). Using strings will still work, but using integers is more efficient. @item Format of @code{SHOW OPEN TABLE} has changed. @item -Multithreaded clients should use @code{mysql_thread_init()} and +Multi-threaded clients should use @code{mysql_thread_init()} and @code{mysql_thread_end()}. @xref{Threaded clients}. @item If you want to recompile the Perl DBD::mysql module, you must get -Msql-Mysql-modules version 1.2218 or newer, because the older DBD modules +Msql-Mysql-modules version 1.2218 or newer because the older DBD modules used the deprecated @code{drop_db()} call. @item @code{RAND(seed)} returns a different random number series in 4.0 than in -3.23; This was done to get @code{RAND(seed)} and @code{RAND(seed+1)} more -different. +3.23; this was done to further differentiate @code{RAND(seed)} and @code{RAND(seed+1)}. @end itemize @node Upgrading-from-3.22, Upgrading-from-3.21, Upgrading-from-3.23, Upgrade @@ -8229,18 +8233,18 @@ or the Perl script @code{mysql_convert_table_format}. Version 3.22 and 3.21 clients will work without any problems with a Version 3.23 server. -The following lists tell what you have to watch out for when upgrading to +The following list tells what you have to watch out for when upgrading to Version 3.23: @itemize @bullet @item -All tables that uses the @code{tis620} character set must be fixed +All tables that use the @code{tis620} character set must be fixed with @code{myisamchk -r} or @code{REPAIR TABLE}. @item If you do a @code{DROP DATABASE} on a symbolic linked database, both the -link and the original database is deleted. (This didn't happen in 3.22 -because configure didn't detect the @code{readlink} system call). +link and the original database are deleted. (This didn't happen in 3.22 +because configure didn't detect the @code{readlink} system call.) @item @code{OPTIMIZE TABLE} now only works for @code{MyISAM} tables. @@ -8251,12 +8255,12 @@ During @code{OPTIMIZE TABLE} the table is now locked from other threads. The MySQL client @code{mysql} is now by default started with the option @code{--no-named-commands (-g)}. This option can be disabled with @code{--enable-named-commands (-G)}. This may cause incompatibility problems in -some cases, for example in SQL scripts that use named commands without a +some cases@-for example, in SQL scripts that use named commands without a semicolon! Long format commands still work from the first line. @item -Date functions that work on part of dates (like @code{MONTH()}) will now -return 0 for @code{0000-00-00} dates. (MySQL 3.22 returned @code{NULL}). +Date functions that work on parts of dates (like @code{MONTH()}) will now +return 0 for @code{0000-00-00} dates. (MySQL 3.22 returned @code{NULL}.) @item If you are using the @code{german} character sort order, you must repair @@ -8270,13 +8274,13 @@ and not only the first argument. @item @code{AUTO_INCREMENT} will not work with negative numbers. The reason for this is that negative numbers caused problems when wrapping from -1 to 0. -@code{AUTO_INCREMENT} is now for MyISAM tables handled at a lower level and +@code{AUTO_INCREMENT} for MyISAM tables is no handled at a lower level and is much faster than before. For MyISAM tables old numbers are also not reused anymore, even if you delete some rows from the table. @item @code{CASE}, @code{DELAYED}, @code{ELSE}, @code{END}, @code{FULLTEXT}, -@code{INNER}, @code{RIGHT}, @code{THEN} and @code{WHEN} are now reserved words. +@code{INNER}, @code{RIGHT}, @code{THEN}, and @code{WHEN} are now reserved words. @item @code{FLOAT(X)} is now a true floating-point type and not a value with a @@ -8289,15 +8293,15 @@ includes a place for the sign or the decimal point. @item A @code{TIME} string must now be of one of the following formats: @code{[[[DAYS] [H]H:]MM:]SS[.fraction]} or -@code{[[[[[H]H]H]H]MM]SS[.fraction]} +@code{[[[[[H]H]H]H]MM]SS[.fraction]}. @item @code{LIKE} now compares strings using the same character comparison rules -as @code{'='}. If you require the old behavior, you can compile +as @code{=}. If you require the old behavior, you can compile MySQL with the @code{CXXFLAGS=-DLIKE_CMP_TOUPPER} flag. @item -@code{REGEXP} is now case insensitive for normal (not binary) strings. +@code{REGEXP} is now case-insensitive for normal (not binary) strings. @item When you check/repair tables you should use @code{CHECK TABLE} @@ -8321,8 +8325,8 @@ it returns a pointer to a @code{MYSQL_FIELD} instead of a @item @code{mysql_num_fields()} can no longer be used on a @code{MYSQL*} object (it's -now a function that takes @code{MYSQL_RES*} as an argument. You should now -use @code{mysql_field_count()} instead. +now a function that takes @code{MYSQL_RES*} as an argument, so you should +use @code{mysql_field_count()} instead). @item In MySQL Version 3.22, the output of @code{SELECT DISTINCT ...} was @@ -8330,8 +8334,8 @@ almost always sorted. In Version 3.23, you must use @code{GROUP BY} or @code{ORDER BY} to obtain sorted output. @item -@code{SUM()} now returns @code{NULL}, instead of 0, if there is no matching -rows. This is according to ANSI SQL. +@code{SUM()} now returns @code{NULL}, instead of 0, if +there are no matching rows. This is according to ANSI SQL. @item An @code{AND} or @code{OR} with @code{NULL} values will now return @@ -8348,7 +8352,7 @@ than the length argument. @cindex compatibility, between MySQL versions @cindex upgrading, 3.21 to 3.22 -Nothing that affects compatibility has changed between Version 3.21 and 3.22. +Nothing that affects compatibility has changed between versions 3.21 and 3.22. The only pitfall is that new tables that are created with @code{DATE} type columns will use the new way to store the date. You can't access these new fields from an old version of @code{mysqld}. @@ -8395,7 +8399,7 @@ If you are @strong{not} using the @code{--old-protocol} option to @itemize @bullet @item All client code must be recompiled. If you are using ODBC, you must get -the new @strong{MyODBC} 2.x driver. +the new @code{MyODBC} 2.x driver. @item The script @code{scripts/add_long_password} must be run to convert the @code{Password} field in the @code{mysql.user} table to @code{CHAR(16)}. @@ -8428,7 +8432,7 @@ The new Perl @code{DBI}/@code{DBD} interface also supports the old @code{mysqlperl} interface. The only change you have to make if you use @code{mysqlperl} is to change the arguments to the @code{connect()} function. The new arguments are: @code{host}, @code{database}, @code{user}, -@code{password} (the @code{user} and @code{password} arguments have changed +and @code{password} (the @code{user} and @code{password} arguments have changed places). @xref{Perl DBI Class, , Perl @code{DBI} Class}. @@ -8453,7 +8457,7 @@ There are some new reserved words. The most notable are @code{DATE}, If you are using MySQL Version 3.23, you can copy the @file{.frm}, @file{.MYI}, and @file{.MYD} files between different architectures that support the same floating-point format. (MySQL takes care of any -byte swapping issues.) +byte-swapping issues.) The MySQL @code{ISAM} data and index files (@file{.ISD} and @file{*.ISM}, respectively) are architecture-dependent and in some cases @@ -8511,7 +8515,7 @@ shell> gunzip < db_name.contents.gz | mysql db_name You can also use @code{mysqldump} and @code{mysqlimport} to accomplish the database transfer. For big tables, this is much faster than simply using @code{mysqldump}. -In the commands shown below, @code{DUMPDIR} represents the full pathname +In the following commands, @code{DUMPDIR} represents the full pathname of the directory you use to store the output from @code{mysqldump}. First, create the directory for the output files and dump the database: @@ -8531,7 +8535,7 @@ shell> cat DUMPDIR/*.sql | mysql db_name # create tables in database shell> mysqlimport db_name DUMPDIR/*.txt # load data into tables @end example -Also, don't forget to copy the @code{mysql} database, because that's where the +Also, don't forget to copy the @code{mysql} database because that's where the grant tables (@code{user}, @code{db}, @code{host}) are stored. You may have to run commands as the MySQL @code{root} user on the new machine until you have the @code{mysql} database in place. @@ -8570,13 +8574,13 @@ information. * Linux-IA64:: Linux IA64 Notes @end menu -The notes below regarding @strong{glibc} apply only to the situation +The following notes regarding @code{glibc} apply only to the situation when you build MySQL yourself. If you are running Linux on an x86 machine, in most cases it is much better for you to just use our binary. We link our binaries against -the best patched version of @strong{glibc} we can come up with and with the +the best patched version of @code{glibc} we can come up with and with the best compiler options, in an attempt to make it suitable for a high-load -server. So if you read the text below, and are in doubt about +server. So if you read the following text, and are in doubt about what you should do, try our binary first to see if it meets your needs, and worry about your own build only after you have discovered that our binary is not good enough. In that case, we would appreciate a note about it, so we @@ -8589,14 +8593,14 @@ Linux version that doesn't have @code{glibc2}, you must install LinuxThreads before trying to compile MySQL. You can get LinuxThreads at @uref{http://www.mysql.com/Downloads/Linux/}. -@strong{Note:} We have seen some strange problems with Linux 2.2.14 and -MySQL on SMP systems; If you have a SMP system, we recommend -you to upgrade to Linux 2.4 as soon as possible! Your system will be +@strong{Note}: we have seen some strange problems with Linux 2.2.14 and +MySQL on SMP systems. If you have a SMP system, we recommend +you upgrade to Linux 2.4 as soon as possible! Your system will be faster and more stable by doing this! Note that @code{glibc} versions before and including Version 2.1.1 have a fatal bug in @code{pthread_mutex_timedwait} handling, which is used -when you do @code{INSERT DELAYED}. We recommend you to not use +when you do @code{INSERT DELAYED}. We recommend that you not use @code{INSERT DELAYED} before upgrading glibc. If you plan to have 1000+ concurrent connections, you will need to make @@ -8608,11 +8612,11 @@ relative to the root of @code{glibc} Note that MySQL will not be stable with around 600-1000 connections if @code{STACK_SIZE} is the default of 2 MB. -If you have a problem with that MySQL can't open enough files, +If MySQL can't open enough files, or connections, it may be that you haven't configured Linux to handle enough files. -In Linux 2.2 and forwards, you can check the number of allocated +In Linux 2.2 and onward, you can check the number of allocated file handlers by doing: @example @@ -8621,7 +8625,7 @@ cat /proc/sys/fs/dquot-max cat /proc/sys/fs/super-max @end example -If you have more than 16M of memory, you should add something like the +If you have more than 16 MB of memory, you should add something like the following in your boot script (@file{/etc/rc/boot.local} on SuSE): @example @@ -8630,8 +8634,8 @@ echo 8192 > /proc/sys/fs/dquot-max echo 1024 > /proc/sys/fs/super-max @end example -You can also run the above from the command line as root, but in this case -your old limits will be used next time your computer reboots. +You can also run the preceding commands from the command-line as root, but in this case +your old limits will be used the next time your computer reboots. You should also add /etc/my.cnf: @@ -8640,12 +8644,12 @@ You should also add /etc/my.cnf: open-files-limit=8192 @end example -The above should allow MySQL to create up to 8192 connections + files. +This should allow MySQL to create up to 8192 connections + files. The @code{STACK_SIZE} constant in LinuxThreads controls the spacing of thread stacks in the address space. It needs to be large enough so that there will be plenty of room for the stack of each individual thread, but small enough -to keep the stack of some thread from running into the global @code{mysqld} +to keep the stack of some threads from running into the global @code{mysqld} data. Unfortunately, the Linux implementation of @code{mmap()}, as we have experimentally discovered, will successfully unmap an already mapped region if you ask it to map out an address already in use, zeroing out the data @@ -8661,7 +8665,7 @@ If you build MySQL yourself and do not want to mess with patching LinuxThreads, you should set @code{max_connections} to a value no higher than 500. It should be even less if you have a large key buffer, large heap tables, or some other things that make @code{mysqld} allocate a lot -of memory or if you are running a 2.2 kernel with a 2GB patch. If you are +of memory, or if you are running a 2.2 kernel with a 2GB patch. If you are using our binary or RPM version 3.23.25 or later, you can safely set @code{max_connections} at 1500, assuming no large key buffer or heap tables with lots of data. The more you reduce @code{STACK_SIZE} in LinuxThreads @@ -8672,14 +8676,14 @@ If you use a lot of concurrent connections, you may suffer from a "feature" in the 2.2 kernel that penalises a process for forking or cloning a child in an attempt to prevent a fork bomb attack. This will cause MySQL not to scale well as you increase the number of concurrent clients. On -single CPU systems, we have seen this manifested in a very slow thread +single-CPU systems, we have seen this manifested in a very slow thread creation, which means it may take a long time to connect to MySQL (as long as 1 minute), and it may take just as long to shut it down. On -multiple CPU systems, we have observed a gradual drop in query speed as +multiple-CPU systems, we have observed a gradual drop in query speed as the number of clients increases. In the process of trying to find a solution, we have received a kernel patch from one of our users, who -claimed it made a lot of difference for his site. The patch is available here -(@uref{http://www.mysql.com/Downloads/Patches/linux-fork.patch}). We have +claimed it made a lot of difference for his site. The patch is available at +@uref{http://www.mysql.com/Downloads/Patches/linux-fork.patch}. We have now done rather extensive testing of this patch on both development and production systems. It has significantly improved @code{MySQL} performance without causing any problems and we now @@ -8690,12 +8694,12 @@ the current performance of your system, rather than patching your 2.2 kernel, it might be easier to just upgrade to 2.4, which will also give you a nice SMP boost in addition to fixing this fairness bug. -We have tested MySQL on the 2.4 kernel on a 2 CPU machine and -found MySQL scales MUCH better - there was virtually no slowdown -on query throughput all the way up -to 1000 clients, and MySQL scaling factor ( computed as the ratio of +We have tested MySQL on the 2.4 kernel on a 2-CPU machine and +found MySQL scales @strong{much} better@-there was virtually no slowdown +on queries throughput all the way up +to 1000 clients, and the MySQL scaling factor (computed as the ratio of maximum throughput to the throughput with one client) was 180%. -We have observed similar results on a 4-CPU system - virtually no +We have observed similar results on a 4-CPU system@-virtually no slowdown as the number of clients was increased up to 1000, and 300% scaling factor. So for a high-load SMP server we would definitely recommend the 2.4 kernel at this point. We @@ -8714,19 +8718,19 @@ include them in the manual. There is another issue that greatly hurts MySQL performance, especially on SMP systems. The implementation of mutex in -LinuxThreads in @strong{glibc-2.1} is very bad for programs with many +LinuxThreads in @code{glibc-2.1} is very bad for programs with many threads that only hold the mutex for a short time. On an SMP system, ironic as it is, if -you link MySQL against unmodified @strong{LinuxThreads}, +you link MySQL against unmodified @code{LinuxThreads}, removing processors from the machine improves MySQL performance -in many cases. We have made a patch available for @strong{glibc 2.1.3} +in many cases. We have made a patch available for @code{glibc 2.1.3} to correct this behavior (@uref{http://www.mysql.com/Downloads/Linux/linuxthreads-2.1-patch}). -With @strong{glibc-2.2.2} +With @code{glibc-2.2.2} MySQL version 3.23.36 will use the adaptive mutex, which is much -better than even the patched one in @strong{glibc-2.1.3}. Be warned, however, -that under some conditions, the current mutex code in @strong{glibc-2.2.2} +better than even the patched one in @code{glibc-2.1.3}. Be warned, however, +that under some conditions, the current mutex code in @code{glibc-2.2.2} overspins, which hurts MySQL performance. The chance of this condition can be reduced by renicing @code{mysqld} process to the highest priority. We have also been able to correct the overspin behavior with @@ -8835,7 +8839,7 @@ CC=fcc CFLAGS="-O -K fast -K lib -K omitfp -Kpreex -D_GNU_SOURCE \ MySQL needs at least Linux Version 2.0. -@strong{WARNING}: +@strong{Warning}: We have reports from some MySQL users that they have got serious stability problems with MySQL with Linux kernel 2.2.14. If you are using this kernel you should upgrade to 2.2.19 (or newer) or to a 2.4 @@ -8878,7 +8882,7 @@ You can solve this problem in one of the following ways: Get a MySQL source distribution (an RPM or the @code{tar.gz} distribution) and install this instead. @item -Execute @code{mysql_install_db --force}; This will not execute the +Execute @code{mysql_install_db --force}; this will not execute the @code{resolveip} test in @code{mysql_install_db}. The downside is that you can't use host names in the grant tables; you must use IP numbers instead (except for @code{localhost}). If you are using an old MySQL @@ -8920,11 +8924,11 @@ kernel will fix this problem in the future. MySQL requires @code{libc} Version 5.4.12 or newer. It's known to work with @code{libc} 5.4.46. @code{glibc} Version 2.0.6 and later should also work. There have been some problems with the @code{glibc} RPMs from -RedHat, so if you have problems, check whether or not there are any updates! +RedHat, so if you have problems, check whether there are any updates! The @code{glibc} 2.0.7-19 and 2.0.7-29 RPMs are known to work. If you are using gcc 3.0 and above to compile MySQL, you must install -the @code{libstdc++v3} library before compiling MySQL; If you don't do +the @code{libstdc++v3} library before compiling MySQL; if you don't do this you will get an error about a missing @code{__cxa_pure_virtual} symbol during linking! @@ -8939,7 +8943,7 @@ See the Installation chapter in the Reference Manual. Just do what the error message says and add an extra underscore to the @code{_P} macro that has only one underscore, then try again. -You may get some warnings when compiling; those shown below can be ignored: +You may get some warnings when compiling; those shown here can be ignored: @example mysqld.cc -o objs-thread/mysqld.o @@ -9021,7 +9025,7 @@ You can find the above compilers at @uref{http://www.support.compaq.com/alpha-tools/}). By using these compilers, instead of gcc, we get about 9-14 % better performance with MySQL. -Note that the configure line optimised the binary for the current CPU; This +Note that the configure line optimised the binary for the current CPU; this means you can only use our binary if you have an Alpha EV6 processor. We also compile statically to avoid library problems. @@ -9156,7 +9160,7 @@ allow named pipe connections. You should use either If @code{mysqld} doesn't start, please check the @file{\mysql\data\mysql.err} file to see if the server wrote any message there to indicate the cause of the problem. You can also -try to start the server with @code{mysqld --standalone}; In this +try to start the server with @code{mysqld --standalone}; in this case, you may get some useful information on the screen that may help solve the problem. @@ -9308,7 +9312,7 @@ started with @code{--enable-named-pipe}. This is because some users have experienced problems shutting down the MySQL server when one uses named pipes. -You can test whether or not MySQL is working by executing the +You can test whether MySQL is working by executing the following commands: @example @@ -9388,7 +9392,7 @@ MySQL server with SSH (by David Carlson @email{dcarlson@@mplcomm.com}): Install an SSH client on your Windows machine. As a user, the best non-free one I've found is from @code{SecureCRT} from @uref{http://www.vandyke.com/}. Another option is @code{f-secure} from @uref{http://www.f-secure.com/}. You -can also find some free ones on @strong{Google} at +can also find some free ones on @code{Google} at @uref{http://directory.google.com/Top/Computers/Security/Products_and_Tools/Cryptography/SSH/Clients/Windows/}. @item @@ -9413,7 +9417,7 @@ On your Windows machine, start some ODBC application (such as Access). @item Create a new file in Windows and link to MySQL using the ODBC driver the same way you normally do, except type in @code{localhost} -for the MySQL host server --- not @code{yourmysqlservername}. +for the MySQL host server@-not @code{yourmysqlservername}. @end itemize You should now have an ODBC connection to MySQL, encrypted using SSH. @@ -9543,8 +9547,8 @@ You can't kill MySQL from the task manager or with the shutdown utility in Windows 95. You must take it down with @code{mysqladmin shutdown}. @item Case-insensitive names -Filenames are case insensitive on Windows, so database and table names -are also case insensitive in MySQL for Windows. The only +Filenames are case-insensitive on Windows, so database and table names +are also case-insensitive in MySQL for Windows. The only restriction is that database and table names must be specified using the same case throughout a given statement. @xref{Name case sensitivity}. @@ -9638,7 +9642,7 @@ Add some nice start and shutdown icons to the MySQL installation. @item When registering @code{mysqld} as a service with @code{--install} (on NT) -it would be nice if you could also add default options on the command line. +it would be nice if you could also add default options on the command-line. For the moment, the workaround is to list the parameters in the @file{C:\my.cnf} file instead. @@ -9647,7 +9651,7 @@ It would be real nice to be able to kill @code{mysqld} from the task manager. For the moment, you must use @code{mysqladmin shutdown}. @item -Port @code{readline} to Windows for use in the @code{mysql} command line tool. +Port @code{readline} to Windows for use in the @code{mysql} command-line tool. @item GUI versions of the standard MySQL clients (@code{mysql}, @@ -9764,7 +9768,7 @@ If you turn on @code{__STDC__} with the @code{-Xc} option, the Sun compiler can't compile with the Solaris @file{pthread.h} header file. This is a Sun bug (broken compiler or broken include file). -If @code{mysqld} issues the error message shown below when you run it, you have +If @code{mysqld} issues the error message shown here when you run it, you have tried to compile MySQL with the Sun compiler without enabling the multi-thread option (@code{-mt}): @@ -10035,11 +10039,11 @@ Versions 3 and up. It is possible to run with native threads on some late The MySQL @file{Makefile}s require GNU make (@code{gmake}) to work. If you want to compile MySQL you need to install GNU @code{make} first. -Be sure to have your name resolver setup correct. Otherwise you may +Be sure to have your name resolver setup correct. Otherwise, you may experience resolver delays or failures when connecting to @code{mysqld}. Make sure that the @code{localhost} entry in the @file{/etc/hosts} file is -correct (otherwise you will have problems connecting to the database). The +correct (otherwise, you will have problems connecting to the database). The @file{/etc/hosts} file should start with a line: @example @@ -10096,7 +10100,7 @@ that are marked @code{-RELEASE}. @node NetBSD, OpenBSD, FreeBSD, BSD Notes @subsubsection NetBSD notes -To compile on NetBSD you need GNU @code{make}. Otherwise the compile will +To compile on NetBSD you need GNU @code{make}. Otherwise, the compile will crash when @code{make} tries to run @code{lint} on C++ files. @@ -10255,7 +10259,7 @@ CC=gcc CFLAGS="-O2 -fomit-frame-pointer" CXX=gcc CXXFLAGS="-O2 \ @end example You might want to also add aliases to your shell's resource file to -access @code{mysql} and @code{mysqladmin} from the command line: +access @code{mysql} and @code{mysqladmin} from the command-line: @example alias mysql '/usr/local/mysql/bin/mysql' @@ -10314,7 +10318,7 @@ HP 9000/7xx or 8xx running HP-UX 10.x where x < 2 HP 9000/7xx or 8xx running HP-UX 9.x @end itemize -To install the distribution, use one of the commands below, where +To install the distribution, use one of the commands here, where @code{/path/to/depot} is the full pathname of the depot file: @itemize @bullet @@ -10558,19 +10562,19 @@ option generates faster code, we recommend that you should always use this option with @code{egcs / gcc}. If you get a problem with assembler code try changing the -mcpu=xxx to -match your cpu. Typically power2, power, or powerpc may need to be used, +match your CPU. Typically power2, power, or powerpc may need to be used, alternatively you might need to use 604 or 604e. I'm not positive but I would think using "power" would likely be safe most of the time, even on a power2 machine. -If you don't know what your cpu is then do a "uname -m", this will give +If you don't know what your CPU is then do a "uname -m", this will give you back a string that looks like "000514676700", with a format of xxyyyyyymmss where xx and ss are always 0's, yyyyyy is a unique system id and mm is the id of the CPU Planar. A chart of these values can be found at @uref{http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm}. This will give you a machine type and a machine model you can use to -determine what type of cpu you have. +determine what type of CPU you have. If you have problems with signals (MySQL dies unexpectedly under high load) you may have found an OS bug with threads and @@ -10664,7 +10668,7 @@ accept(int,sockadddr *, int *)' You can safely ignore these warnings. They occur because @code{configure} can detect only errors, not warnings. -If you start the server directly from the command line, you may have problems +If you start the server directly from the command-line, you may have problems with it dying when you log out. (When you log out, your outstanding processes receive a @code{SIGHUP} signal.) If so, try starting the server like this: @@ -11013,8 +11017,8 @@ In FSU Pthreads, the following system calls are pthreads-aware: @code{read()}, @item The CSSA-2001-SCO.35.2 (the patch is listed in custom as -erg711905-dscr_remap security patch (ver 2.0.0) breaks FSU threads and -makes mysqld instable. You have to remove this one if you want to run +erg711905-dscr_remap security patch (version 2.0.0) breaks FSU threads and +makes mysqld unstable. You have to remove this one if you want to run mysqld on an OpenServer 5.0.6 machine. @end itemize @@ -11112,11 +11116,11 @@ gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \ mv example.dll example.udf @end example -@strong{Note:} Due to limitations in OS/2, UDF module name stems must not +@strong{Note}: Due to limitations in OS/2, UDF module name stems must not exceed 8 characters. Modules are stored in the @file{/mysql2/udf} directory; the @code{safe-mysqld.cmd} script will put this directory in the @code{BEGINLIBPATH} environment variable. When using UDF modules, -specified extensions are ignored --- it is assumed to be @file{.udf}. +specified extensions are ignored@-it is assumed to be @file{.udf}. For example, in Unix, the shared module might be named @file{example.so} and you would load a function from it like this: @@ -11195,7 +11199,7 @@ The Perl distributions are provided as compressed @code{tar} archives and have names like @file{MODULE-VERSION.tar.gz}, where @code{MODULE} is the module name and @code{VERSION} is the version number. You should get the @code{Data-Dumper}, @code{DBI}, and @code{Msql-Mysql-modules} distributions -and install them in that order. The installation procedure is shown below. +and install them in that order. The installation procedure is shown here. The example shown is for the @code{Data-Dumper} module, but the procedure is the same for all three distributions: @@ -11297,7 +11301,7 @@ ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd The above should work at least with ActiveState Perl Version 5.6. If you can't get the above to work, you should instead install the -@strong{MyODBC} driver and connect to MySQL server through +@code{MyODBC} driver and connect to MySQL server through ODBC: @example @@ -11500,7 +11504,7 @@ shell> mysql --help This chapter assumes that @code{mysql} is installed on your machine and that a MySQL server is available to which you can connect. If this is -not true, contact your MySQL administrator. (If @emph{you} are the +not true, contact your MySQL administrator. (If @strong{you} are the administrator, you will need to consult other sections of this manual.) This chapter describes the entire process of setting up and using a @@ -11593,7 +11597,7 @@ principles of entering commands, using several queries you can try out to familiarise yourself with how @code{mysql} works. Here's a simple command that asks the server to tell you its version number -and the current date. Type it in as shown below following the @code{mysql>} +and the current date. Type it in as shown here following the @code{mysql>} prompt and press Enter: @example @@ -11798,7 +11802,7 @@ is ready for a new command. It's important to know what the @code{'>} and @code{">} prompts signify, because if you mistakenly enter an unterminated string, any further lines you -type will appear to be ignored by @code{mysql} --- including a line +type will appear to be ignored by @code{mysql}@-including a line containing @code{QUIT}! This can be quite confusing, especially if you don't know that you need to supply the terminating quote before you can cancel the current command. @@ -11911,7 +11915,7 @@ yourself: mysql> CREATE DATABASE menagerie; @end example -Under Unix, database names are case sensitive (unlike SQL keywords), so you +Under Unix, database names are case-sensitive (unlike SQL keywords), so you must always refer to your database as @code{menagerie}, not as @code{Menagerie}, @code{MENAGERIE}, or some other variant. This is also true for table names. (Under Windows, this restriction does not apply, although @@ -11929,7 +11933,7 @@ Database changed Your database needs to be created only once, but you must select it for use each time you begin a @code{mysql} session. You can do this by issuing a @code{USE} statement as shown above. Alternatively, you can select the -database on the command line when you invoke @code{mysql}. Just specify its +database on the command-line when you invoke @code{mysql}. Just specify its name after any connection parameters that you might need to provide. For example: @@ -11939,10 +11943,10 @@ Enter password: ******** @end example Note that @code{menagerie} is not your password on the command just shown. -If you want to supply your password on the command line after the @code{-p} +If you want to supply your password on the command-line after the @code{-p} option, you must do so with no intervening space (for example, as @code{-pmypassword}, not as @code{-p mypassword}). However, putting your -password on the command line is not recommended, because doing so exposes it +password on the command-line is not recommended, because doing so exposes it to snooping by other users logged in on your machine. @@ -12062,9 +12066,9 @@ the columns in your table or what types they are. After creating your table, you need to populate it. The @code{LOAD DATA} and @code{INSERT} statements are useful for this. -Suppose your pet records can be described as shown below. +Suppose your pet records can be described as shown here. (Observe that MySQL expects dates in @code{YYYY-MM-DD} format; -this may be different than what you are used to.) +this may be different from what you are used to.) @multitable @columnfractions .10 .10 .10 .05 .15 .15 @item @strong{name} @tab @strong{owner} @tab @strong{species} @tab @strong{sex} @tab @strong{birth} @tab @strong{death} @@ -12188,7 +12192,7 @@ mysql> SELECT * FROM pet; This form of @code{SELECT} is useful if you want to review your entire table, for instance, after you've just loaded it with your initial dataset. As it -happens, the output just shown reveals an error in your data file: Bowser +happens, the output just shown reveals an error in your datafile: Bowser appears to have been born after he died! Consulting your original pedigree papers, you find that the correct birth year is 1989, not 1998. @@ -12244,7 +12248,7 @@ mysql> SELECT * FROM pet WHERE name = "Bowser"; The output confirms that the year is correctly recorded now as 1989, not 1998. -String comparisons are normally case insensitive, so you can specify the +String comparisons are normally case-insensitive, so you can specify the name as @code{"bowser"}, @code{"BOWSER"}, etc. The query result will be the same. @@ -12562,7 +12566,7 @@ mysql> SELECT name, birth, CURRENT_DATE, @end example A similar query can be used to determine age at death for animals that have -died. You determine which animals these are by checking whether or not the +died. You determine which animals these are by checking whether the @code{death} value is @code{NULL}. Then, for those with non-@code{NULL} values, compute the difference between the @code{death} and @code{birth} values: @@ -12714,8 +12718,8 @@ by Unix utilities such as @code{vi}, @code{grep}, and @code{sed}. SQL pattern matching allows you to use @samp{_} to match any single character and @samp{%} to match an arbitrary number of characters (including -zero characters). In MySQL, SQL patterns are case insensitive by -default. Some examples are shown below. Note that you do not use @code{=} +zero characters). In MySQL, SQL patterns are case-insensitive by +default. Some examples are shown here. Note that you do not use @code{=} or @code{<>} when you use SQL patterns; use the @code{LIKE} or @code{NOT LIKE} comparison operators instead. @@ -12803,7 +12807,7 @@ pattern. @end itemize To demonstrate how extended regular expressions work, the @code{LIKE} queries -shown above are rewritten below to use @code{REGEXP}. +shown previously are rewritten here to use @code{REGEXP}. To find names beginning with @samp{b}, use @samp{^} to match the beginning of the name: @@ -12818,7 +12822,7 @@ mysql> SELECT * FROM pet WHERE name REGEXP "^b"; +--------+--------+---------+------+------------+------------+ @end example -Prior to MySQL Version 3.23.4, @code{REGEXP} is case sensitive, +Prior to MySQL Version 3.23.4, @code{REGEXP} is case-sensitive, and the previous query will return no rows. To match either lowercase or uppercase @samp{b}, use this query instead: @@ -12827,7 +12831,7 @@ mysql> SELECT * FROM pet WHERE name REGEXP "^[bB]"; @end example From MySQL 3.23.4 on, to force a @code{REGEXP} comparison to -be case sensitive, use the @code{BINARY} keyword to make one of the +be case-sensitive, use the @code{BINARY} keyword to make one of the strings a binary string. This query will match only lowercase @samp{b} at the beginning of a name: @@ -13217,8 +13221,8 @@ mysql> DESCRIBE pet; @end example @code{Field} indicates the column name, @code{Type} is the data type for -the column, @code{NULL} indicates whether or not the column can contain -@code{NULL} values, @code{Key} indicates whether or not the column is +the column, @code{NULL} indicates whether the column can contain +@code{NULL} values, @code{Key} indicates whether the column is indexed, and @code{Default} specifies the column's default value. If you have indexes on a table, @@ -13239,7 +13243,7 @@ article (item number) for certain traders (dealers). Supposing that each trader has a single fixed price per article, then (@code{article}, @code{dealer}) is a primary key for the records. -Start the command line tool @code{mysql} and select a database: +Start the command-line tool @code{mysql} and select a database: @example mysql your-database-name @@ -13709,7 +13713,7 @@ characters in the file that causes problems, you can do: dos> mysql -e "source batch-file" @end example -If you need to specify connection parameters on the command line, the +If you need to specify connection parameters on the command-line, the command might look like this: @example @@ -13721,7 +13725,7 @@ When you use @code{mysql} this way, you are creating a script file, then executing the script. If you want the script to continue even if you have errors, you should -use the @code{--force} command line option. +use the @code{--force} command-line option. Why use a script? Here are a few reasons: @@ -13796,7 +13800,7 @@ If you want to get the interactive output format in batch mode, use @code{mysql -t}. To echo to the output the commands that are executed, use @code{mysql -vvv}. -You can also use scripts in the @code{mysql} command line prompt by +You can also use scripts in the @code{mysql} command-line prompt by using the @code{source} command: @example @@ -13827,7 +13831,7 @@ environmental risk factors. More information about Twin studies can be found at: @uref{http://www.imm.ki.se/TWIN/TWINUKW.HTM} -The latter part of the project is administered with a Web interface +The latter part of the project is administered with a web interface written using Perl and MySQL. Each night all data from the interviews are moved into a MySQL @@ -13978,7 +13982,7 @@ The current number of records in the tables used above: @subsection Show a Table on Twin Pair Status Each interview ends with a status code called @code{event}. The query -shown below is used to display a table over all twin pairs combined by +shown here is used to display a table over all twin pairs combined by event. This indicates in how many pairs both twins are finished, in how many pairs one twin is finished and the other refused, and so on. @@ -14149,7 +14153,7 @@ Enable support for named pipes (only on NT/Win2000/XP). @item -T, --exit-info This is a bit mask of different flags one can use for debugging the -mysqld server; One should not use this option if one doesn't know +mysqld server; one should not use this option if one doesn't know exactly what it does! @item --flush @@ -14219,7 +14223,7 @@ The following options affects how the repair works. @item DEFAULT @tab The same as not giving any option to @code{--myisam-recover}. @item BACKUP @tab If the data table was changed during recover, save a - backup of the @file{table_name.MYD} data file as + backup of the @file{table_name.MYD} datafile as @file{table_name-datetime.BAK}. @item FORCE @tab Run recover even if we will loose more than one row from the .MYD file. @@ -14231,7 +14235,7 @@ Before a table is automatically repaired, MySQL will add a note about this in the error log. If you want to be able to recover from most things without user intervention, you should use the options @code{BACKUP,FORCE}. This will force a repair of a table even if some rows -would be deleted, but it will keep the old data file as a backup so that +would be deleted, but it will keep the old datafile as a backup so that you can later examine what happened. @item --pid-file=path @@ -14275,7 +14279,7 @@ Ignore the @code{delay_key_write} option for all tables. @item --skip-grant-tables This option causes the server not to use the privilege system at all. This -gives everyone @emph{full access} to all databases! (You can tell a running +gives everyone @strong{full access} to all databases! (You can tell a running server to start using the grant tables again by executing @code{mysqladmin flush-privileges} or @code{mysqladmin reload}.) @@ -14345,7 +14349,7 @@ directory resides on a partition too small to hold temporary tables. @item -u, --user= [user_name | userid] Run @code{mysqld} daemon as user @code{user_name} or @code{userid} (numeric). -This option is @emph{mandatory} when starting @code{mysqld} as root. +This option is @strong{mandatory} when starting @code{mysqld} as root. @item -V, --version Output version information and exit. @@ -14402,9 +14406,9 @@ Note that on Windows, you should specify all paths with @code{/} instead of MySQL tries to read option files in the order listed above. If multiple option files exist, an option specified in a file read later takes precedence over the same option specified in a file read earlier. Options -specified on the command line take precedence over options specified in any +specified on the command-line take precedence over options specified in any option file. Some options can be specified using environment variables. -Options specified on the command line or in option files take precedence over +Options specified on the command-line or in option files take precedence over environment variable values. @xref{Environment variables}. The following programs support option files: @code{mysql}, @@ -14412,7 +14416,7 @@ The following programs support option files: @code{mysql}, @code{mysqldump}, @code{mysqlimport}, @code{mysqlshow}, @code{mysqlcheck}, @code{myisamchk}, and @code{myisampack}. -Any long option that may be given on the command line when running a MySQL +Any long option that may be given on the command-line when running a MySQL program can be given in an option file as well (without the leading double dash). Run the program with @code{--help} to get a list of available options. @@ -14429,13 +14433,13 @@ apply to the named group until the end of the option file or another group line is given. @item option -This is equivalent to @code{--option} on the command line. +This is equivalent to @code{--option} on the command-line. @item option=value -This is equivalent to @code{--option=value} on the command line. +This is equivalent to @code{--option=value} on the command-line. @item set-variable = variable=value -This is equivalent to @code{--set-variable variable=value} on the command line. +This is equivalent to @code{--set-variable variable=value} on the command-line. This syntax must be used to set a @code{mysqld} variable. @end table @@ -14503,7 +14507,7 @@ following options: @item --defaults-extra-file=full-path-to-default-file @tab Read this configuration file after the global configuration file but before the user configuration file. @end multitable -Note that the above options must be first on the command line to work! +Note that the above options must be first on the command-line to work! @code{--print-defaults} may however be used directly after the @code{--defaults-xxx-file} commands. @@ -14633,9 +14637,9 @@ shell> ./configure --with-tcp-port=port_number \ --prefix=/usr/local/mysql-3.22.9 @end example -Here @code{port_number} and @code{file_name} should be different than the +Here @code{port_number} and @code{file_name} should be different from the default port number and socket file pathname, and the @code{--prefix} value -should specify an installation directory different than the one under which +should specify an installation directory different from the one under which the existing MySQL installation is located. You can check the socket used by any currently executing MySQL server @@ -14654,7 +14658,7 @@ MySQL, including the socket name. You don't have to recompile a new MySQL server just to start with a different port and socket. You can change the port and socket to be used -by specifying them at run time as options to @code{safe_mysqld}: +by specifying them at runtime as options to @code{safe_mysqld}: @example shell> /path/to/safe_mysqld --socket=file_name --port=port_number @@ -14670,7 +14674,7 @@ files to @code{safe_mysqld} with @code{--log}, @code{--log-update}, or @code{--log-slow-queries}. Otherwise, both servers may be trying to write to the same log file. -@strong{Warning}: Normally you should never have two servers that update +@strong{Warning}: normally you should never have two servers that update data in the same database! If your OS doesn't support fault-free system locking, this may lead to unpleasant surprises! @@ -14852,7 +14856,7 @@ connection is refused, everything is OK; the port is blocked. @item Do not trust any data entered by your users. They can try to trick your -code by entering special or escaped character sequences in Web forms, +code by entering special or escaped character sequences in web forms, URLs, or whatever application you have built. Be sure that your application remains secure if a user enters something like ``@code{; DROP DATABASE mysql;}''. This is an extreme example, but large security leaks @@ -14872,10 +14876,10 @@ strips all non-numeric symbols from it. Checklist: @itemize @minus @item -All Web applications: +All web applications: @itemize @bullet @item -Try to enter @samp{'} and @samp{"} in all your Web forms. If you get any kind +Try to enter @samp{'} and @samp{"} in all your web forms. If you get any kind of MySQL error, investigate the problem right away. @item Try to modify any dynamic URLs by adding @code{%22} (@samp{"}), @code{%23} @@ -14934,7 +14938,7 @@ SSH port-forwarding can be used to create an encrypted (and compressed) tunnel for the communication. @item Learn to use the @code{tcpdump} and @code{strings} utilities. For most cases, -you can check whether or not MySQL data streams are unencrypted +you can check whether MySQL data streams are unencrypted by issuing a command like the following: @example @@ -14967,7 +14971,7 @@ All other information is transferred as text that can be read by anyone who is able to watch the connection. If you are concerned about this, you can use the compressed protocol (in MySQL Version 3.22 and above) to make things much harder. To make things even more secure you should use -@code{ssh}. You can find an Open Source @code{ssh} client at +@code{ssh}. You can find an @code{Open Source} @code{ssh} client at @uref{http://www.openssh.org/}, and a commercial @code{ssh} client at @uref{http://www.ssh.com/}. With this, you can get an encrypted TCP/IP connection between a MySQL server and a MySQL client. @@ -15045,7 +15049,7 @@ in and check things even if all normal connections are in use. @item Don't give the @strong{file} privilege to all users. Any user that has this -privilege can write a file anywhere in the file system with the privileges of +privilege can write a file anywhere in the filesystem with the privileges of the @code{mysqld} daemon! To make this a bit safer, all files generated with @code{SELECT ... INTO OUTFILE} are readable to everyone, and you cannot overwrite existing files. @@ -15100,7 +15104,7 @@ but has to use the @code{GRANT} command to give privileges to other users. @item --skip-grant-tables This option causes the server not to use the privilege system at all. This -gives everyone @emph{full access} to all databases! (You can tell a running +gives everyone @strong{full access} to all databases! (You can tell a running server to start using the grant tables again by executing @code{mysqladmin flush-privileges} or @code{mysqladmin reload}.) @@ -15145,7 +15149,7 @@ If you don't configure MySQL with @code{--enable-local-infile}, then calls @code{mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0)} in the client. @xref{mysql_options, , @code{mysql_options()}}. -For the @code{mysql} command line client, @code{LOAD DATA LOCAL} can be +For the @code{mysql} command-line client, @code{LOAD DATA LOCAL} can be enabled by specifying the option @code{--local-infile[=1]}, or disabled with @code{--local-infile=0}. @@ -15205,11 +15209,11 @@ MySQL access control involves two stages: @itemize @bullet @item -Stage 1: The server checks whether or not you are even allowed to connect. +Stage 1: The server checks whether you are even allowed to connect. @item Stage 2: Assuming you can connect, the server checks each request you issue -to see whether or not you have sufficient privileges to perform it. For +to see whether you have sufficient privileges to perform it. For example, if you try to select rows from a table in a database or drop a table from the database, the server makes sure you have the @strong{select} privilege for the table or the @strong{drop} privilege for the database. @@ -15217,7 +15221,7 @@ privilege for the table or the @strong{drop} privilege for the database. The server uses the @code{user}, @code{db}, and @code{host} tables in the @code{mysql} database at both stages of access control. The fields in these -grant tables are shown below: +grant tables are shown here: @multitable @columnfractions .20 .20 .20 .20 @item @strong{Table name} @tab @code{user} @tab @code{db} @tab @code{host} @@ -15245,7 +15249,7 @@ grant tables are shown below: For the second stage of access control (request verification), the server may, if the request involves tables, additionally consult the @code{tables_priv} and @code{columns_priv} tables. The fields in these -tables are shown below: +tables are shown here: @multitable @columnfractions .20 .20 .20 @item @strong{Table name} @tab @code{tables_priv} @tab @code{columns_priv} @@ -15279,9 +15283,9 @@ to which each entry applies. @cindex case sensitivity, in access checking For access-checking purposes, comparisons of @code{Host} values are -case insensitive. @code{User}, @code{Password}, @code{Db}, and -@code{Table_name} values are case sensitive. -@code{Column_name} values are case insensitive in MySQL Version +case-insensitive. @code{User}, @code{Password}, @code{Db}, and +@code{Table_name} values are case-sensitive. +@code{Column_name} values are case-insensitive in MySQL Version 3.22.12 or later. Privilege fields indicate the privileges granted by a table entry, that is, @@ -15289,7 +15293,7 @@ what operations can be performed. The server combines the information in the various grant tables to form a complete description of a user's privileges. The rules used to do this are described in @ref{Request access}. -Scope fields are strings, declared as shown below; the default value for +Scope fields are strings, declared as shown here; the default value for each is the empty string: @multitable @columnfractions .20 .15 .65 @@ -15304,7 +15308,7 @@ each is the empty string: @end multitable In the @code{user}, @code{db} and @code{host} tables, -all privilege fields are declared as @code{ENUM('N','Y')} --- each can have a +all privilege fields are declared as @code{ENUM('N','Y')}@-each can have a value of @code{'N'} or @code{'Y'}, and the default value is @code{'N'}. In the @code{tables_priv} and @code{columns_priv} tables, the privilege @@ -15363,7 +15367,7 @@ etc.) are specified only in the @code{user} table. This is because administrative operations are operations on the server itself and are not database-specific, so there is no reason to list such privileges in the other grant tables. In fact, only the @code{user} table need -be consulted to determine whether or not you can perform an administrative +be consulted to determine whether you can perform an administrative operation. The @strong{file} privilege is specified only in the @code{user} table, too. @@ -15401,7 +15405,7 @@ MySQL server reads the contents of these tables when it starts up and under the circumstances indicated in @ref{Privilege changes}. The names used in this manual to refer to the privileges provided by -MySQL are shown below, along with the table column name associated +MySQL are shown here, along with the table column name associated with each privilege in the grant tables and the context in which the privilege applies: @@ -15458,7 +15462,7 @@ OUTFILE} statements. Any user to whom this privilege is granted can read or write any file that the MySQL server can read or write. The remaining privileges are used for administrative operations, which are -performed using the @code{mysqladmin} program. The table below shows which +performed using the @code{mysqladmin} program. The table here shows which @code{mysqladmin} commands each administrative privilege allows you to execute: @@ -15562,12 +15566,12 @@ Alternate forms of the @code{-h}, @code{-u}, and @code{-p} options are @code{--password=your_pass}. Note that there is @emph{no space} between @code{-p} or @code{--password=} and the password following it. -@strong{Note:} Specifying a password on the command line is not secure! +@strong{Note}: Specifying a password on the command-line is not secure! Any user on your system may then find out your password by typing a command like: @code{ps auxww}. @xref{Option files}. @code{mysql} uses default values for connection parameters that are missing -from the command line: +from the command-line: @itemize @bullet @item @@ -15592,7 +15596,7 @@ shell> mysql Other MySQL clients behave similarly. On Unix systems, you can specify different default values to be used when you -make a connection, so that you need not enter them on the command line each +make a connection, so that you need not enter them on the command-line each time you invoke a client program. This can be done in a couple of ways: @itemize @bullet @@ -15635,7 +15639,7 @@ Windows only). The password can be specified using @code{MYSQL_PWD} @cindex testing, connection to the server When you attempt to connect to a MySQL server, the server accepts or -rejects the connection based on your identity and whether or not you can +rejects the connection based on your identity and whether you can verify your identity by supplying the correct password. If not, the server denies access to you completely. Otherwise, the server accepts the connection, then enters Stage 2 and waits for requests. @@ -15722,7 +15726,7 @@ point of view the encrypted password is the REAL password, so you should not give anyone access to it! In particular, don't give normal users read access to the tables in the @code{mysql} database! -The examples below show how various combinations of @code{Host} and +The examples here show how various combinations of @code{Host} and @code{User} values in @code{user} table entries apply to incoming connections: @@ -15923,7 +15927,7 @@ the @code{Host}, @code{Db}, and @code{User} fields. This is similar to @code{db} table sorting, although the sorting is simpler because only the @code{Host} field may contain wildcards. -The request verification process is described below. (If you are familiar +The request verification process is described here. (If you are familiar with the access-checking source code, you will notice that the description here differs slightly from the algorithm used in the code. The description is equivalent to what the code actually does; it differs only to make the @@ -15964,7 +15968,7 @@ access to the database. In this case, a further lookup is done in the @code{host} table to find a match on the @code{Host} and @code{Db} fields. If no @code{host} table entry matches, access is denied. If there is a match, the user's database-specific privileges are computed as the -intersection (@emph{not} the union!) of the privileges in the @code{db} and +intersection (@strong{not} the union!) of the privileges in the @code{db} and @code{host} table entries, that is, the privileges that are @code{'Y'} in both entries. (This way you can grant general privileges in the @code{db} table entry and then selectively restrict them on a host-by-host basis using the @@ -16009,7 +16013,7 @@ The @code{host} table can be used to maintain a list of secure servers. At TcX, the @code{host} table contains a list of all machines on the local network. These are granted all privileges. -You can also use the @code{host} table to indicate hosts that are @emph{not} +You can also use the @code{host} table to indicate hosts that are @strong{not} secure. Suppose you have a machine @code{public.your.domain} that is located in a public area that you do not consider secure. You can allow access to all hosts on your network except that machine by using @code{host} table @@ -16039,7 +16043,7 @@ actually set up the way you think they are. @subsection Causes of @code{Access denied} Errors If you encounter @code{Access denied} errors when you try to connect to the -MySQL server, the list below indicates some courses of +MySQL server, the following list indicates some courses of action you can take to correct the problem: @itemize @bullet @@ -16242,7 +16246,7 @@ an entry to the @code{user} table that contains the IP number of your host as the @code{Host} column value. (Alternatively, you could add an entry to the @code{user} table with a @code{Host} value that contains a wildcard---for example, @code{'tcx.%'}. However, use of hostnames ending with @samp{%} is -@emph{insecure} and is @emph{not} recommended!) +@strong{insecure} and is @strong{not} recommended!) @item If @code{mysql -u user_name test} works but @code{mysql -u user_name @@ -16295,7 +16299,7 @@ probably doesn't have the @strong{file} privilege enabled. Remember that client programs will use connection parameters specified in configuration files or environment variables. @xref{Environment variables}. If a client seems to be sending the wrong default -connection parameters when you don't specify them on the command line, +connection parameters when you don't specify them on the command-line, check your environment and the @file{.my.cnf} file in your home directory. You might also check the system-wide MySQL configuration files, though it is far less likely that client connection @@ -16309,7 +16313,7 @@ If you make changes to the grant tables directly (using an @code{INSERT} or @code{UPDATE} statement) and your changes seem to be ignored, remember that you must issue a @code{FLUSH PRIVILEGES} statement or execute a @code{mysqladmin flush-privileges} command to cause the server to re-read -the privilege tables. Otherwise your changes have no effect until the +the privilege tables. Otherwise, your changes have no effect until the next time the server is restarted. Remember that after you set the @code{root} password with an @code{UPDATE} command, you won't need to specify it until after you flush the privileges, because the server @@ -16328,10 +16332,10 @@ prompt you for the password.) @item For testing, start the @code{mysqld} daemon with the @code{--skip-grant-tables} option. Then you can change the MySQL -grant tables and use the @code{mysqlaccess} script to check whether or not +grant tables and use the @code{mysqlaccess} script to check whether your modifications have the desired effect. When you are satisfied with your changes, execute @code{mysqladmin flush-privileges} to tell the @code{mysqld} -server to start using the new grant tables. @strong{Note:} Reloading the +server to start using the new grant tables. @strong{Note}: reloading the grant tables overrides the @code{--skip-grant-tables} option. This allows you to tell the server to begin using the grant tables again without bringing it down and restarting it. @@ -16460,8 +16464,8 @@ you use a @code{column_list} clause) are @code{SELECT}, @code{INSERT}, and You can set global privileges by using @code{ON *.*} syntax. You can set database privileges by using @code{ON db_name.*} syntax. If you specify @code{ON *} and you have a current database, you will set the privileges for -that database. (@strong{Warning:} If you specify @code{ON *} and you -@emph{don't} have a current database, you will affect the global privileges!) +that database. (@strong{Warning}: if you specify @code{ON *} and you +@strong{don't} have a current database, you will affect the global privileges!) In order to accommodate granting rights to users from arbitrary hosts, MySQL supports specifying the @code{user_name} value in the form @@ -16482,7 +16486,7 @@ defined by inserting entries with @code{User=''} into the @code{mysql.user} table or creating an user with an empty name with the @code{GRANT} command. -@strong{Note:} If you allow anonymous users to connect to the MySQL +@strong{Note}: if you allow anonymous users to connect to the MySQL server, you should also grant privileges to all local users as @code{user@@localhost} because otherwise the anonymous user entry for the local host in the @code{mysql.user} table will be used when the user @@ -16536,7 +16540,7 @@ If you don't want to send the password in clear text you can use the function @code{PASSWORD()} or the C API function @code{make_scrambled_password(char *to, const char *password)}. -@strong{Warning:} If you create a new user but do not specify an +@strong{Warning}: if you create a new user but do not specify an @code{IDENTIFIED BY} clause, the user has no password. This is insecure. Passwords can also be set with the @code{SET PASSWORD} command. @@ -16618,7 +16622,7 @@ you have to revoke these yourself if needed. @item In MySQL, if you have the @strong{insert} privilege on only some of the columns in a table, you can execute @code{INSERT} statements on the -table; The columns for which you don't have the @strong{insert} privilege +table; the columns for which you don't have the @strong{insert} privilege will be set to their default values. ANSI SQL requires you to have the @strong{insert} privilege on all columns. @@ -16674,7 +16678,7 @@ the MySQL server! MySQL users and their privileges are normally created with the @code{GRANT} command. @xref{GRANT}. -When you login to a MySQL server with a command line client you +When you login to a MySQL server with a command-line client you should specify the password with @code{--password=your-password}. @xref{Connecting}. @@ -16721,7 +16725,7 @@ Modifications to the grant tables that you perform using @code{GRANT}, If you modify the grant tables manually (using @code{INSERT}, @code{UPDATE}, etc.), you should execute a @code{FLUSH PRIVILEGES} statement or run @code{mysqladmin flush-privileges} or @code{mysqladmin reload} to tell the -server to reload the grant tables. Otherwise your changes will have @emph{no +server to reload the grant tables. Otherwise, your changes will have @emph{no effect} until you restart the server. If you change the grant tables manually but forget to reload the privileges, you will be wondering why your changes don't seem to make any difference! @@ -16767,7 +16771,7 @@ of privileges: The MySQL @code{root} user is created as a superuser who can do anything. Connections must be made from the local host. -@strong{Note:} +@strong{Note}: The initial @code{root} password is empty, so anyone can connect as @code{root} @emph{without a password} and be granted all privileges. @@ -16783,7 +16787,7 @@ Other privileges are denied. For example, normal users can't use @code{mysqladmin shutdown} or @code{mysqladmin processlist}. @end itemize -@strong{Note:} The default privileges are different for Windows. +@strong{Note}: the default privileges are different for Windows. @xref{Windows running}. Because your installation is initially wide open, one of the first things you @@ -16832,7 +16836,7 @@ See the @code{scripts/mysql_install_db} script to see how it sets up the default privileges. You can use this as a basis to see how to add other users. -If you want the initial privileges to be different than those just described +If you want the initial privileges to be different from those just described above, you can modify @code{mysql_install_db} before you run it. @cindex grant tables, re-creating @@ -16844,7 +16848,7 @@ the database directory, which is listed when you run @code{mysqld --help}.) Then run the @code{mysql_install_db} script, possibly after editing it first to have the privileges you want. -@strong{Note:} For MySQL versions older than Version 3.22.10, +@strong{Note}: for MySQL versions older than Version 3.22.10, you should not delete the @file{.frm} files. If you accidentally do this, you should copy them back from your MySQL distribution before running @code{mysql_install_db}. @@ -16868,15 +16872,14 @@ more concise and less error-prone. @xref{GRANT}. There are also a lot of contributed programs like @code{phpmyadmin} that can be used to create and administrate users. @xref{Portals}. -The examples below show how to use the @code{mysql} client to set up new +The following examples show how to use the @code{mysql} client to set up new users. These examples assume that privileges are set up according to the defaults described in the previous section. This means that to make changes, you must be on the same machine where @code{mysqld} is running, you must connect as the MySQL @code{root} user, and the @code{root} user must have the @strong{insert} privilege for the @code{mysql} database and the @strong{reload} administrative privilege. Also, if you have changed the -@code{root} user password, you must specify it for the @code{mysql} commands -below. +@code{root} user password, you must specify it for the @code{mysql} commands here. You can add new users by issuing @code{GRANT} statements: @@ -16913,7 +16916,7 @@ This allows the user to execute the @code{mysqladmin reload}, @item dummy A user who can connect without a password, but only from the local host. The -global privileges are all set to @code{'N'} --- the @strong{usage} privilege +global privileges are all set to @code{'N'}@-the @strong{usage} privilege type allows you to create a user with no privileges. It is assumed that you will grant database-specific privileges later. @end table @@ -17118,7 +17121,7 @@ or shell> mysqladmin -u jeffrey password biscuit @end example -@strong{NOTE:} @code{PASSWORD()} does not perform password encryption in the +@strong{Note}: @code{PASSWORD()} does not perform password encryption in the same way that Unix passwords are encrypted. You should not assume that if your Unix password and your MySQL password are the same, that @code{PASSWORD()} will result in the same encrypted value as is stored in the @@ -17130,7 +17133,7 @@ Unix password file. @xref{User names}. It is inadvisable to specify your password in a way that exposes it to discovery by other users. The methods you can use to specify your password -when you run client programs are listed below, along with an assessment of +when you run client programs are listed here, along with an assessment of the risks of each method: @itemize @bullet @@ -17145,7 +17148,7 @@ with your other applications). Use a @code{-pyour_pass} or @code{--password=your_pass} option on the command line. This is convenient but insecure, because your password becomes visible to system status programs (such as @code{ps}) that may be invoked by other -users to display command lines. (MySQL clients typically overwrite +users to display command-lines. (MySQL clients typically overwrite the command-line argument with zeroes during their initialisation sequence, but there is still a brief interval during which the value is visible.) @@ -17164,7 +17167,7 @@ Enter password: ******** The @samp{*} characters represent your password. It is more secure to enter your password this way than to specify it on the -command line because it is not visible to other users. However, this method +command-line because it is not visible to other users. However, this method of entering a password is suitable only for programs that you run interactively. If you want to invoke a client from a script that runs non-interactively, there is no opportunity to enter the password from the @@ -17481,7 +17484,7 @@ If you get performance problems in making backups on your system, you can solve this by setting up replication and do the backups on the slave instead of on the master. @xref{Replication Intro}. -If you are using a Veritas file system, you can do: +If you are using a Veritas filesystem, you can do: @enumerate @item @@ -17625,19 +17628,19 @@ CHECK TABLE test_table FAST QUICK; Which would simply do a quick check on the table to see whether it was closed properly. -@strong{Note:} that in some case @code{CHECK TABLE} will change the +@strong{Note}: that in some case @code{CHECK TABLE} will change the table! This happens if the table is marked as 'corrupted' or 'not closed properly' but @code{CHECK TABLE} didn't find any problems in the table. In this case @code{CHECK TABLE} will mark the table as okay. If a table is corrupted, then it's most likely that the problem is in the indexes and not in the data part. All of the above check types -checks the indexes throughly and should thus find most errors. +checks the indexes thoroughly and should thus find most errors. If you just want to check a table that you assume is okay, you should use no check options or the @code{QUICK} option. The latter should be used when you are in a hurry and can take the very small risk that -@code{QUICK} didn't find an error in the data file. (In most cases +@code{QUICK} didn't find an error in the datafile. (In most cases MySQL should find, under normal usage, any error in the data file. If this happens then the table will be marked as 'corrupted', in which case the table can't be used until it's repaired.) @@ -17714,7 +17717,7 @@ If @code{QUICK} is given then MySQL will try to do a @code{REPAIR} of only the index tree. If you use @code{EXTENDED} then MySQL will create the index row -by row instead of creating one index at a time with sorting; This may be +by row instead of creating one index at a time with sorting; this may be better than sorting on fixed-length keys if you have long @code{char()} keys that compress very good. @@ -17752,7 +17755,7 @@ flushing tables. @xref{OPTIMIZE TABLE, , @code{OPTIMIZE TABLE}}. Even that the repair in @code{myisamchk} is quite secure, it's always a -good idea to make a backup BEFORE doing a repair (or anything that could +good idea to make a backup @emph{before} doing a repair (or anything that could make a lot of changes to a table) @menu @@ -17779,20 +17782,20 @@ shell> myisamchk [options] tbl_name @end example The @code{options} specify what you want @code{myisamchk} to do. They are -described below. (You can also get a list of options by invoking +described here. (You can also get a list of options by invoking @code{myisamchk --help}.) With no options, @code{myisamchk} simply checks your table. To get more information or to tell @code{myisamchk} to take corrective -action, specify options as described below and in the following sections. +action, specify options as described here and in the following sections. @code{tbl_name} is the database table you want to check/repair. If you run @code{myisamchk} somewhere other than in the database directory, you must specify the path to the file, because @code{myisamchk} has no idea where your -database is located. Actually, @code{myisamchk} doesn't care whether or not +database is located. Actually, @code{myisamchk} doesn't care whether the files you are working on are located in a database directory; you can copy the files that correspond to a database table into another location and perform recovery operations on them there. -You can name several tables on the @code{myisamchk} command line if you +You can name several tables on the @code{myisamchk} command-line if you wish. You can also specify a name as an index file name (with the @file{.MYI} suffix), which allows you to specify all tables in a directory by using the pattern @file{*.MYI}. @@ -17979,9 +17982,9 @@ The following options are used if you start @code{myisamchk} with @table @code @item -D # or --data-file-length=# -Max length of data file (when re-creating data file when it's 'full'). +Max length of datafile (when re-creating datafile when it's 'full'). @item -e or --extend-check -Try to recover every possible row from the data file. +Try to recover every possible row from the datafile. Normally this will also find a lot of garbage rows. Don't use this option if you are not totally desperate. @item -f or --force @@ -18002,7 +18005,7 @@ Can fix almost anything except unique keys that aren't unique If you want to recover a table, this is the option to try first. Only if myisamchk reports that the table can't be recovered by @code{-r}, you should then try @code{-o}. (Note that in the unlikely case that @code{-r} -fails, the data file is still intact.) +fails, the datafile is still intact.) If you have lots of memory, you should increase the size of @code{sort_buffer_size}! @item -o or --safe-recover @@ -18027,7 +18030,7 @@ Change the character set used by the index Path for storing temporary files. If this is not set, @code{myisamchk} will use the environment variable @code{TMPDIR} for this. @item -q or --quick -Faster repair by not modifying the data file. One can give a second +Faster repair by not modifying the datafile. One can give a second @code{-q} to force @code{myisamchk} to modify the original datafile in case of duplicate keys @item -u or --unpack @@ -18087,7 +18090,7 @@ shell> myisamchk -O sort=16M -O key=16M -O read=1M -O write=1M ... Using @code{-O sort=16M} should probably be enough for most cases. Be aware that @code{myisamchk} uses temporary files in @code{TMPDIR}. If -@code{TMPDIR} points to a memory file system, you may easily get out of +@code{TMPDIR} points to a memory filesystem, you may easily get out of memory errors. If this happens, set @code{TMPDIR} to point at some directory with more space and restart @code{myisamchk}. @@ -18162,12 +18165,12 @@ directory: @multitable @columnfractions .20 .30 @item @strong{File} @tab @strong{Purpose} @item @file{tbl_name.frm} @tab Table definition (form) file -@item @file{tbl_name.MYD} @tab Data file +@item @file{tbl_name.MYD} @tab Datafile @item @file{tbl_name.MYI} @tab Index file @end multitable Each of these three file types is subject to corruption in various ways, but -problems occur most often in data files and index files. +problems occur most often in datafiles and index files. @code{myisamchk} works by creating a copy of the @file{.MYD} (data) file row by row. It ends the repair stage by removing the old @file{.MYD} @@ -18197,7 +18200,7 @@ To check a MyISAM table, use the following commands: @table @code @item myisamchk tbl_name This finds 99.99% of all errors. What it can't find is corruption that -involves @strong{only} the data file (which is very unusual). If you want +involves @strong{only} the datafile (which is very unusual). If you want to check a table, you should normally run @code{myisamchk} without options or with either the @code{-s} or @code{--silent} option. @@ -18280,7 +18283,7 @@ ALTER TABLE table MAX_ROWS=xxx AVG_ROW_LENGTH=yyy; In the other cases, you must repair your tables. @code{myisamchk} can usually detect and fix most things that go wrong. -The repair process involves up to four stages, described below. Before you +The repair process involves up to four stages, described here. Before you begin, you should @code{cd} to the database directory and check the permissions of the table files. Make sure they are readable by the Unix user that @code{mysqld} runs as (and to you, because you need to access the files @@ -18297,7 +18300,7 @@ The manual section about table maintenance includes the options to The following section is for the cases where the above command fails or if you want to use the extended features that @code{isamchk}/@code{myisamchk} provides. -If you are going to repair a table from the command line, you must first +If you are going to repair a table from the command-line, you must first take down the @code{mysqld} server. Note that when you do @code{mysqladmin shutdown} on a remote server, the @code{mysqld} server will still be alive for a while after @code{mysqladmin} returns, until @@ -18328,18 +18331,18 @@ memory) to all @code{isamchk/myisamchk} commands. First, try @code{myisamchk -r -q tbl_name} (@code{-r -q} means ``quick recovery mode''). This will attempt to repair the index file without -touching the data file. If the data file contains everything that it +touching the datafile. If the datafile contains everything that it should and the delete links point at the correct locations within the -data file, this should work, and the table is fixed. Start repairing the +datafile, this should work, and the table is fixed. Start repairing the next table. Otherwise, use the following procedure: @enumerate @item -Make a backup of the data file before continuing. +Make a backup of the datafile before continuing. @item Use @code{myisamchk -r tbl_name} (@code{-r} means ``recovery mode''). This will -remove incorrect records and deleted records from the data file and +remove incorrect records and deleted records from the datafile and reconstruct the index file. @item @@ -18361,7 +18364,7 @@ follows: @enumerate @item -Move the data file to some safe place. +Move the datafile to some safe place. @item Use the table description file to create new (empty) data and index files: @@ -18377,7 +18380,7 @@ If your SQL version doesn't have @code{TRUNCATE TABLE}, use @code{DELETE FROM table_name} instead. @item -Copy the old data file back onto the newly created data file. +Copy the old datafile back onto the newly created datafile. (Don't just move the old file back onto the new file; you want to retain a copy in case something goes wrong.) @end enumerate @@ -18403,10 +18406,10 @@ should start with @code{myisamchk -r}. @item If you don't have a backup but know exactly how the table was created, create -a copy of the table in another database. Remove the new data file, then move +a copy of the table in another database. Remove the new datafile, then move the description and index files from the other database to your crashed database. This gives you new description and index files, but leaves -the data file alone. Go back to Stage 2 and attempt to reconstruct +the datafile alone. Go back to Stage 2 and attempt to reconstruct the index file. @end enumerate @@ -18517,7 +18520,7 @@ myisamchk -r --silent --sort-index -O sort_buffer_size=16M */*.MYI @cindex tables, information To get a description of a table or statistics about it, use the commands shown -below. We explain some of the information in more detail later: +here. We explain some of the information in more detail later: @itemize @bullet @item myisamchk -d tbl_name @@ -18683,7 +18686,7 @@ preceding examples: @end example Explanations for the types of information @code{myisamchk} produces are -given below. The ``keyfile'' is the index file. ``Record'' and ``row'' +given here. The ``keyfile'' is the index file. ``Record'' and ``row'' are synonymous: @itemize @bullet @@ -18694,10 +18697,10 @@ Name of the ISAM (index) file. Version of ISAM format. Currently always 2. @item Creation time -When the data file was created. +When the datafile was created. @item Recover time -When the index/data file was last reconstructed. +When the index/datafile was last reconstructed. @item Data records How many records are in the table. @@ -18707,7 +18710,7 @@ How many deleted blocks still have reserved space. You can optimise your table to minimise this space. @xref{Optimisation}. -@item Datafile: Parts +@item Data file: Parts For dynamic record format, this indicates how many data blocks there are. For an optimised table without fragmented records, this is the same as @code{Data records}. @@ -18717,8 +18720,8 @@ How many bytes of non-reclaimed deleted data there are. You can optimise your table to minimise this space. @xref{Optimisation}. -@item Datafile pointer -The size of the data file pointer, in bytes. It is usually 2, 3, 4, or 5 +@item Data file pointer +The size of the datafile pointer, in bytes. It is usually 2, 3, 4, or 5 bytes. Most tables manage with 2 bytes, but this cannot be controlled from MySQL yet. For fixed tables, this is a record address. For dynamic tables, this is a byte address. @@ -18729,7 +18732,7 @@ bytes. Most tables manage with 2 bytes, but this is calculated automatically by MySQL. It is always a block address. @item Max datafile length -How long the table's data file (@file{.MYD} file) can become, in bytes. +How long the table's datafile (@file{.MYD} file) can become, in bytes. @item Max keyfile length How long the table's key file (@file{.MYI} file) can become, in bytes. @@ -18760,7 +18763,7 @@ length of the indexed column, because you can index a prefix of a string column. @item Index -@code{unique} or @code{multip.} (multiple). Indicates whether or not one value +@code{unique} or @code{multip.} (multiple). Indicates whether one value can exist multiple times in this index. @item Type @@ -18813,10 +18816,10 @@ MySQL strips spaces from the end of strings. The @code{Packed} value indicates the percentage of savings achieved by doing this. @item Recordspace used -What percentage of the data file is used. +What percentage of the datafile is used. @item Empty space -What percentage of the data file is unused. +What percentage of the datafile is unused. @item Blocks/Record Average number of blocks per record (that is, how many links a fragmented @@ -18833,10 +18836,10 @@ of records. How many blocks (links) are deleted. @item Recorddata -How many bytes in the data file are used. +How many bytes in the datafile are used. @item Deleted data -How many bytes in the data file are deleted (unused). +How many bytes in the datafile are deleted (unused). @item Lost space If a record is updated to a shorter length, some space is lost. This is @@ -18885,7 +18888,7 @@ table or if you have made many changes to a table with variable-length rows (tables that have @code{VARCHAR}, @code{BLOB}, or @code{TEXT} columns). Deleted records are maintained in a linked list and subsequent @code{INSERT} operations reuse old record positions. You can use @code{OPTIMIZE TABLE} to -reclaim the unused space and to defragment the data file. +reclaim the unused space and to defragment the datafile. For the moment, @code{OPTIMIZE TABLE} only works on @code{MyISAM} and @code{BDB} tables. For @code{BDB} tables, @code{OPTIMIZE TABLE} is @@ -19005,7 +19008,7 @@ memory. This command will not remove any queries from the cache, unlike @item @code{[TABLE | TABLES] tbl_name [,tbl_name...]} @tab Flushes only the given tables. -@item @code{TABLES WITH READ LOCK} @tab Closes all open tables and locks all tables for all databases with a read until one executes @code{UNLOCK TABLES}. This is very convenient way to get backups if you have a file system, like Veritas,that can take snapshots in time. +@item @code{TABLES WITH READ LOCK} @tab Closes all open tables and locks all tables for all databases with a read until one executes @code{UNLOCK TABLES}. This is very convenient way to get backups if you have a filesystem, like Veritas,that can take snapshots in time. @item @code{STATUS} @tab Resets most status variables to zero. This is something one should only use when debugging a query. @end multitable @@ -19171,7 +19174,7 @@ host. You can also get this list using the @code{mysqlshow} command. @code{SHOW TABLES} lists the tables in a given database. You can also get this list using the @code{mysqlshow db_name} command. -@strong{Note:} If a user doesn't have any privileges for a table, the table +@strong{Note}: if a user doesn't have any privileges for a table, the table will not show up in the output from @code{SHOW TABLES} or @code{mysqlshow db_name}. @@ -19181,7 +19184,7 @@ how many times the table is @code{cached} and @code{in_use}. @code{SHOW COLUMNS} lists the columns in a given table. If you specify the @code{FULL} option, you will also get the privileges you have for -each column. If the column types are different than you expect them to +each column. If the column types are different from what you expect them to be based on a @code{CREATE TABLE} statement, note that MySQL sometimes changes column types. @xref{Silent column changes}. @@ -19250,13 +19253,13 @@ The following columns are returned: @item @code{Row_format} @tab The row storage format (Fixed, Dynamic, or Compressed). @item @code{Rows} @tab Number of rows. @item @code{Avg_row_length} @tab Average row length. -@item @code{Data_length} @tab Length of the data file. -@item @code{Max_data_length} @tab Max length of the data file. +@item @code{Data_length} @tab Length of the datafile. +@item @code{Max_data_length} @tab Max length of the datafile. @item @code{Index_length} @tab Length of the index file. @item @code{Data_free} @tab Number of allocated but not used bytes. @item @code{Auto_increment} @tab Next autoincrement value. @item @code{Create_time} @tab When the table was created. -@item @code{Update_time} @tab When the data file was last updated. +@item @code{Update_time} @tab When the datafile was last updated. @item @code{Check_time} @tab When the table was last checked. @item @code{Create_options} @tab Extra options used with @code{CREATE TABLE}. @item @code{Comment} @tab The comment used when creating the table (or some information why MySQL couldn't access the table information). @@ -19272,7 +19275,7 @@ in the table comment. @cindex @code{mysqladmin} @code{SHOW STATUS} provides server status information (like @code{mysqladmin extended-status}). The output resembles that shown -below, though the format and numbers probably differ: +here, though the format and numbers probably differ: @example +--------------------------+------------+ @@ -19429,7 +19432,7 @@ If @code{Threads_created} is big, you may want to increase the with @code{Threads_created}/@code{Connections}. @item If @code{Created_tmp_disk_tables} is big, you may want to increase the -@code{tmp_table_size} variable to get the temporary tables memory based +@code{tmp_table_size} variable to get the temporary tables memory-based instead of disk based. @end itemize @@ -19447,7 +19450,7 @@ variables} command. If the default values are unsuitable, you can set most of these variables using command-line options when @code{mysqld} starts up. @xref{Command-line options}. -The output resembles that shown below, though the format and numbers may +The output resembles that shown here, though the format and numbers may differ somewhat: @example @@ -19540,7 +19543,7 @@ differ somewhat: +------------------------------+---------------------------+ @end example -Each option is described below. Values for buffer sizes, lengths, and stack +Each option is described here. Values for buffer sizes, lengths, and stack sizes are given in bytes. You can specify values with a suffix of @samp{K} or @samp{M} to indicate kilobytes or megabytes. For example, @code{16M} indicates 16 megabytes. The case of suffix letters does not matter; @@ -19847,7 +19850,7 @@ MySQL uses special tree-like cache to make bulk inserts (that is, @code{LOAD DATA INFILE}) faster. This variable limits the size of the cache tree in bytes per thread. Setting it to 0 will disable this optimization. -@strong{Note:} This cache is only used when adding data to non-empty table. +@strong{Note}: this cache is only used when adding data to non-empty table. Default value is 8 MB. @item @code{myisam_recover_options} @@ -19863,14 +19866,14 @@ If the temporary file used for fast index creation would be bigger than using the key cache by the amount specified here, then prefer the key cache method. This is mainly used to force long character keys in large tables to use the slower key cache method to create the index. -@strong{NOTE} that this parameter is given in megabytes! +@strong{Note} that this parameter is given in megabytes! @item @code{myisam_max_sort_file_size} The maximum size of the temporary file MySQL is allowed to use while recreating the index (during @code{REPAIR}, @code{ALTER TABLE} -or @code{LOAD DATA INFILE}. If the file size would be bigger than this, +or @code{LOAD DATA INFILE}. If the file-size would be bigger than this, the index will be created through the key cache (which is slower). -@strong{NOTE} that this parameter is given in megabytes! +@strong{Note} that this parameter is given in megabytes! @item @code{net_buffer_length} The communication buffer is reset to this size between queries. This @@ -20092,7 +20095,7 @@ in very heavy use. Slave connecting to master. @item @code{Copying to tmp table on disk} The temporary result set was larger than @code{tmp_table_size} and the -thread is now changing the in memory based temporary table to a disk +thread is now changing the in memory-based temporary table to a disk based one to save memory. @item @code{Creating tmp table} The thread is creating a temporary table to hold a part of the result for @@ -20175,7 +20178,7 @@ Most states are very quick operations. If threads last in any of these states for many seconds, there may be a problem around that needs to be investigated. -There are some other states that are not mentioned above, but most of +There are some other states that are not mentioned previously, but most of these are only useful to find bugs in @code{mysqld}. @node SHOW GRANTS, SHOW CREATE TABLE, SHOW PROCESSLIST, SHOW @@ -20262,7 +20265,7 @@ character set configuration files listed in If you change the character set when running MySQL (which may also change the sort order), you must run @code{myisamchk -r -q} on all -tables. Otherwise your indexes may not be ordered correctly. +tables. Otherwise, your indexes may not be ordered correctly. When a client connects to a MySQL server, the server sends the default character set in use to the client. The client will switch to @@ -20508,7 +20511,7 @@ to_upper['a'] should contain 'A' @code{sort_order[]} is a map indicating how characters should be ordered for comparison and sorting purposes. For many character sets, this is the same as -@code{to_upper[]} (which means sorting will be case insensitive). +@code{to_upper[]} (which means sorting will be case-insensitive). MySQL will sort characters based on the value of @code{sort_order[character]}. For more complicated sorting rules, see the discussion of string collating below. @xref{String collating}. @@ -20663,7 +20666,7 @@ Use of @code{MYSQL_PWD} is insecure. @tindex @code{HOME} environment variable @tindex environment variable, @code{HOME} @cindex history file -@cindex command line history +@cindex command-line history @tindex .mysql_history file The @file{mysql} client uses the file named in the @code{MYSQL_HISTFILE} environment variable to save the command-line history. The default value for @@ -20678,7 +20681,7 @@ to get a full description of the program's different options. For example, try You can override default options for all standard client programs with an option file. @ref{Option files}. -The list below briefly describes the MySQL programs: +The following list briefly describes the MySQL programs: @table @code @@ -20772,7 +20775,7 @@ If you don't use @code{--mysqld=#} or @code{--mysqld-version=#} @code{safe_mysqld} will use an executable named @code{mysqld-max} if it exists. If not, @code{safe_mysqld} will start @code{mysqld}. This makes it very easy to test to use @code{mysqld-max} instead of -@code{mysqld}; Just copy @code{mysqld-max} to where you have +@code{mysqld}; just copy @code{mysqld-max} to where you have @code{mysqld} and it will be used. Normally one should never edit the @code{safe_mysqld} script, but @@ -20782,7 +20785,7 @@ file. @code{safe_mysqld} will read all options from the @code{[mysqld]}, @code{[server]} and @code{[safe_mysqld]} sections from the option files. @xref{Option files}. -Note that all options on the command line to @code{safe_mysqld} are passed +Note that all options on the command-line to @code{safe_mysqld} are passed to @code{mysqld}. If you wants to use any options in @code{safe_mysqld} that @code{mysqld} doesn't support, you must specify these in the option file. @@ -20876,12 +20879,12 @@ processes running in different Unix sockets and TCP/IP ports. The program will search for group(s) named [mysqld#] from my.cnf (or the given --config-file=...), where # can be any positive number starting from 1. These groups should be the same as the usual @code{[mysqld]} -group (e.g. options to mysqld, see MySQL manual for detailed -information about this group), but with those port, socket etc. options +group (e.g., options to @code{mysqld}, see the MySQL manual for detailed +information about this group), but with those port, socket, etc. options that are wanted for each separate @code{mysqld} processes. The number in the group name has another function; it can be used for starting, stopping, or reporting some specific @code{mysqld} servers with this -program. See the usage and options below for more information. +program. See the usage and options here for more information. @example Usage: mysqld_multi [OPTIONS] @{start|stop|report@} [GNR,GNR,GNR...] @@ -20966,7 +20969,7 @@ You will have to do the above for each @code{mysqld} running in each data directory, that you have (just change the socket, -S=...). @item @code{pid-file} is very important, if you are using @code{safe_mysqld} -to start @code{mysqld} (e.g. --mysqld=safe_mysqld) Every @code{mysqld} +to start @code{mysqld} (e.g., @code{--mysqld=safe_mysqld}) Every @code{mysqld} should have its own @code{pid-file}. The advantage using @code{safe_mysqld} instead of @code{mysqld} directly here is, that @code{safe_mysqld} 'guards' every @code{mysqld} process and will restart @@ -21088,7 +21091,7 @@ The information needed to decompress columns is read into memory when the table is opened. This results in much better performance when accessing individual records, because you only have to uncompress exactly one record, not a much larger disk block as when using Stacker on MS-DOS. -Usually, @code{myisampack} packs the data file 40%-70%. +Usually, @code{myisampack} packs the datafile 40%-70%. MySQL uses memory mapping (@code{mmap()}) on compressed tables and falls back to normal read/write file usage if @code{mmap()} doesn't work. @@ -21136,7 +21139,7 @@ it finds that @file{tbl_name.TMD} exists. With @code{--force}, Display a help message and exit. @item -j big_tbl_name, --join=big_tbl_name -Join all tables named on the command line into a single table +Join all tables named on the command-line into a single table @code{big_tbl_name}. All tables that are to be combined @strong{must} be identical (same column names and types, same indexes, etc.). @@ -21173,7 +21176,7 @@ packing process. @end table @cindex examples, compressed tables -The sequence of commands shown below illustrates a typical table compression +The sequence of commands shown here illustrates a typical table compression session: @example @@ -21352,7 +21355,7 @@ Field Start Length Type Huff tree Bits 57 831 4 no zeros, zerofill(1) 2 9 @end example -The information printed by @code{myisampack} is described below: +The information printed by @code{myisampack} is described here: @table @code @item normal @@ -21592,7 +21595,7 @@ Use of @code{MYSQL_PWD} is insecure. @tindex @code{HOME} environment variable @tindex environment variable, @code{HOME} @cindex history file -@cindex command line history +@cindex command-line history @tindex .mysql_history file The @file{mysql} client uses the file named in the @code{MYSQL_HISTFILE} environment variable to save the command-line history. The default value for @@ -21607,7 +21610,7 @@ to get a full description of the program's different options. For example, try You can override default options for all standard client programs with an option file. @ref{Option files}. -The list below briefly describes the MySQL programs: +The following list briefly describes the MySQL programs: @table @code @@ -21688,8 +21691,8 @@ shell> replace a b b a -- file1 file2 ... @node mysql, mysqladmin, Client-Side Overview, Client-Side Scripts @subsection The Command-line Tool -@cindex command line tool -@cindex tools, command line +@cindex command-line tool +@cindex tools, command-line @cindex scripts @cindex @code{mysql} @@ -21713,9 +21716,9 @@ Using @code{mysql} is very easy. Just start it as follows: @code{mysql database} or @code{mysql --user=user_name --password=your_password database}. Type a SQL statement, end it with @samp{;}, @samp{\g}, or @samp{\G} and press Enter. -@cindex @code{mysql} command line options -@cindex command line options, @code{mysql} -@cindex options, command line, @code{mysql} +@cindex @code{mysql} command-line options +@cindex command-line options, @code{mysql} +@cindex options, command-line, @code{mysql} @cindex startup parameters, @code{mysql} @code{mysql} supports the following options: @@ -21831,7 +21834,7 @@ also. This option does not work in batch mode. Pager works only in Unix. @cindex @code{password}, @code{mysql} option @item -p[password], --password[=...] Password to use when connecting to server. If a password is not given on -the command line, you will be prompted for it. Note that if you use the +the command-line, you will be prompted for it. Note that if you use the short form @code{-p} you can't have a space between the option and the password. @@ -21910,7 +21913,7 @@ You can also set the following variables with @code{-O} or @item max_join_size @tab 1000000 @tab Automatic limit for rows in a join when using --i-am-a-dummy. @end multitable -If you type 'help' on the command line, @code{mysql} will print out the +If you type 'help' on the command-line, @code{mysql} will print out the commands that it supports: @cindex commands, list of @@ -21966,7 +21969,7 @@ SET SQL_SAFE_UPDATES=1,SQL_SELECT_LIMIT=#select_limit#, @end example where @code{#select_limit#} and @code{#max_join_size#} are variables that -can be set from the @code{mysql} command line. @xref{SET OPTION, @code{SET}}. +can be set from the @code{mysql} command-line. @xref{SET OPTION, @code{SET}}. The effect of the above is: @@ -22005,7 +22008,7 @@ mail_from: Monty txt: >>>>> "Thimble" == Thimble Smith writes: Thimble> Hi. I think this is a good idea. Is anyone familiar with UTF-8 -Thimble> or Unicode? Otherwise I'll put this on my TODO list and see what +Thimble> or Unicode? Otherwise, I'll put this on my TODO list and see what Thimble> happens. Yes, please do that. @@ -22020,14 +22023,14 @@ Monty @itemize @bullet @item For logging, you can use the @code{tee} option. The @code{tee} can be -started with option @code{--tee=...}, or from the command line +started with option @code{--tee=...}, or from the command-line interactively with command @code{tee}. All the data displayed on the screen will also be appended into a given file. This can be very useful for debugging purposes also. The @code{tee} can be disabled from the -command line with command @code{notee}. Executing @code{tee} again +command-line with command @code{notee}. Executing @code{tee} again starts logging again. Without a parameter the previous file will be used. Note that @code{tee} will flush the results into the file after -each command, just before the command line appears again waiting for the +each command, just before the command-line appears again waiting for the next command. @item @@ -22035,7 +22038,7 @@ Browsing, or searching the results in the interactive mode in Unix less, more, or any other similar program, is now possible with option @code{--pager[=...]}. Without argument, @code{mysql} client will look for environment variable PAGER and set @code{pager} to that. -@code{pager} can be started from the interactive command line with +@code{pager} can be started from the interactive command-line with command @code{pager} and disabled with command @code{nopager}. The command takes an argument optionally and the @code{pager} will be set to that. Command @code{pager} can be called without an argument, but this @@ -22287,7 +22290,7 @@ Use compression in server/client protocol. @item -?, --help Display this help message and exit. @item -B, --databases -To check several databases. Note the difference in usage; In this case +To check several databases. Note the difference in usage; in this case no tables are given. All name arguments are regarded as database names. @item --default-character-set=... Set the default character set @@ -22469,7 +22472,7 @@ Overrides option --databases (-B). @item -T, --tab=path-to-some-directory Creates a @code{table_name.sql} file, that contains the SQL CREATE commands, and a @code{table_name.txt} file, that contains the data, for each give table. -@strong{NOTE}: This only works if @code{mysqldump} is run on the same +@strong{Note}: This only works if @code{mysqldump} is run on the same machine as the @code{mysqld} daemon. The format of the @file{.txt} file is made according to the @code{--fields-xxx} and @code{--lines--xxx} options. @item -u user_name, --user=user_name @@ -22547,7 +22550,7 @@ mysqldump --all-databases > all_databases.sql @cindex tables, dumping @cindex backing up, databases -@code{mysqlhotcopy} is a perl script that uses @code{LOCK TABLES}, +@code{mysqlhotcopy} is a Perl script that uses @code{LOCK TABLES}, @code{FLUSH TABLES} and @code{cp} or @code{scp} to quickly make a backup of a database. It's the fastest way to make a backup of the database, of single tables but it can only be run on the same machine where the @@ -22633,7 +22636,7 @@ directly to the same options to @code{LOAD DATA INFILE}. shell> mysqlimport [options] database textfile1 [textfile2 ...] @end example -For each text file named on the command line, +For each text file named on the command-line, @code{mysqlimport} strips any extension from the filename and uses the result to determine which table to import the file's contents into. For example, files named @file{patient.txt}, @file{patient.text}, and @file{patient} would @@ -22796,7 +22799,7 @@ If the last argument contains a shell or SQL wildcard (@code{*}, @code{?}, This may cause some confusion when you try to display the columns for a table with a @code{_} as in this case @code{mysqlshow} only shows you the table names that match the pattern. This is easily fixed by -adding an extra @code{%} last on the command line (as a separate +adding an extra @code{%} last on the command-line (as a separate argument). @@ -22846,7 +22849,7 @@ shell> mysql database However, it's also possible to put your SQL commands in a file and tell @code{mysql} to read its input from that file. To do so, create a text file @file{text_file} that contains the commands you wish to execute. -Then invoke @code{mysql} as shown below: +Then invoke @code{mysql} as shown here: @example shell> mysql database < text_file @@ -22941,7 +22944,7 @@ remove the @code{-l} option from @code{mysql.server} or change it to @code{--log-bin}. The entries in this log are written as @code{mysqld} receives the questions. -This may be different than the order in which the statements are executed. +This may be different from the order in which the statements are executed. This is in contrast to the update log and the binary log which are written after the query is executed, but before any locks are released. @@ -22952,7 +22955,7 @@ after the query is executed, but before any locks are released. @cindex update log @cindex files, update log -@strong{Note}: The update log is replaced by the binary +@strong{Note}: the update log is replaced by the binary log. @xref{Binary log}. With this you can do anything that you can do with the update log. @@ -22966,7 +22969,7 @@ extension, @code{mysqld} will create log file names like so: time you execute @code{mysqladmin refresh}, execute @code{mysqladmin flush-logs}, execute the @code{FLUSH LOGS} statement, or restart the server. -@strong{Note:} For the above scheme to work, you must not create +@strong{Note}: for the above scheme to work, you must not create your own files with the same filename as the update log + some extensions that may be regarded as a number, in the directory used by the update log! @@ -23117,7 +23120,7 @@ more than @code{long_query_time} to execute. The time to get the initial table locks are not counted as execution time. The slow query log is logged after the query is executed and after all -locks has been released. This may be different than the order in which +locks has been released. This may be different from the order in which the statements are executed. If no file name is given, it defaults to the name of the host machine @@ -23210,7 +23213,7 @@ and then take a backup and remove @file{mysql.old}. This section describes the various replication features in MySQL. It serves as a reference to the options available with replication. You will be introduced to replication and learn how to implement it. -Towards the end, there are some frequently asked questions and descriptions +Toward the end, there are some frequently asked questions and descriptions of problems and how to solve them. We suggest that you visit our website at @uref{http://www.mysql.com/} @@ -23283,7 +23286,7 @@ Due to the above limitation, we recommend that at this point you use small, or if a prolonged read lock on the master is acceptable. While the actual speed of @code{LOAD DATA FROM MASTER} may vary from system to system, a good rule for a rough estimate of how long it is going to take is 1 second -per 1 MB of the data file. You will get close to the estimate if both master +per 1 MB of the datafile. You will get close to the estimate if both master and slave are equivalent to 700 MHz Pentium, are connected through 100 MBit/s network, and your index file is about half the size of your data file. Of course, your mileage will vary from system to system, the above rule @@ -23305,11 +23308,11 @@ The next section explains the master/slave setup process in more detail. @node Replication HOWTO, Replication Features, Replication Implementation, Replication @subsection How To Set Up Replication -Below is a quick description of how to set up complete replication on +Here is a quick description of how to set up complete replication on your current MySQL server. It assumes you want to replicate all your databases and have not configured replication before. You will need to shutdown your master server briefly to complete the steps outlined -below. +here. While this method is the most straightforward way to set up a slave, it is not the only one. For example, if you already have a snapshot @@ -23448,7 +23451,7 @@ it is preferred that you use @code{CHANGE MASTER TO} command. @cindex @file{my.cnf} file @cindex files,@file{my.cnf} -Below is an explanation of what is supported and what is not: +Here is an explanation of what is supported and what is not: @itemize @bullet @item @@ -23617,7 +23620,7 @@ it happens to affect your application -- use @code{slave-skip-errors}. If you are using replication, we recommend that you use MySQL Version 3.23.30 or later. Older versions work, but they do have some bugs and are -missing some features. Some of the options below may not be available in +missing some features. Some of the options mentioned here may not be available in your version if it is not the most recent one. For all options specific to the 4.0 branch, there is a note indicating so. Otherwise, if you discover that the option you are interested in is not available in your 3.23 version, @@ -23634,7 +23637,7 @@ This sets an unique replication id. You should pick a unique value in the range between 1 to 2^32-1 for each master and slave. Example: @code{server-id=3} -The following table describes the options you can use for the @strong{MASTER}: +The following table describes the options you can use for the @code{MASTER}: @multitable @columnfractions .38 .62 @item @strong{Option} @tab @strong{Description} @@ -23679,7 +23682,7 @@ database. Example: @code{binlog-ignore-db=accounting} @end multitable -The following table describes the options you can use for the @strong{SLAVE}: +The following table describes the options you can use for the @code{SLAVE}: @multitable @columnfractions .38 .62 @item @strong{Option} @tab @strong{Description} @@ -23878,7 +23881,7 @@ the read. @cindex commands, replication @cindex replication, commands -Replication can be controlled through the SQL interface. Below is the +Replication can be controlled through the SQL interface. Here is the summary of commands: @multitable @columnfractions .45 .55 @@ -23957,7 +23960,7 @@ automatically be reset to an empty string and 0, respectively (the start values). Note that if you restart the slave, it will remember its last master. If this is not desirable, you should delete the @file{master.info} file before restarting, and the slave will read its master from @file{my.cnf} or the -command line. +command-line. This command is useful for setting up a slave when you have the snapshot of the master and have recorded the log and the offset on the master that the @@ -24179,7 +24182,7 @@ for client A to make an update to co-master 1, and in the meantime, before it propagates to co-master 2, client B could make an update to co-master 2 that will make the update of client A work differently than it did on co-master 1. Thus when the update of client A will make it -to co-master 2, it will produce tables that will be different than +to co-master 2, it will produce tables that will be different from what you have on co-master 1, even after all the updates from co-master 2 have also propagated. So you should not co-chain two servers in a two-way replication relationship, unless you are sure that you updates @@ -24249,7 +24252,7 @@ written a lot of code already, you may want to automate the conversion task by using Monty's @code{replace} utility, which comes with the standard distribution of MySQL, or just write your own Perl script. Hopefully, your code follows some recognisable pattern. If not, then -you are probably better off re-writing it anyway, or at least going +you are probably better off rewriting it anyway, or at least going through and manually beating it into a pattern. Note that, of course, you can use different names for the @@ -24273,7 +24276,7 @@ of your site, you need to know your query patterns, and empirically (by benchmarking) determine the relationship between the throughput on reads (reads per second, or @code{max_reads}) and on writes @code{max_writes}) on a typical master and a typical slave. The -example below will show you a rather simplified calculation of what you +example here will show you a rather simplified calculation of what you can get with replication for our imagined system. Let's say our system load consists of 10% writes and 90% reads, and we @@ -24664,7 +24667,7 @@ MySQL-specific keywords to a query. The code inside servers. If high performance is more important than exactness, as in some -Web applications, it is possibile to create an application layer that +web applications, it is possibile to create an application layer that caches all results to give you even higher performance. By letting old results 'expire' after a while, you can keep the cache reasonably fresh. This provides a method to handle high load spikes, in which case @@ -24700,8 +24703,8 @@ We solved this by storing all information per month in compressed 'transaction' tables. We have a set of simple macros (script) that generates summary tables grouped by different criteria (product group, customer id, store ...) from the transaction tables. The reports are -Web pages that are dynamically generated by a small Perl script that -parses a Web page, executes the SQL statements in it, and inserts the +web pages that are dynamically generated by a small Perl script that +parses a web page, executes the SQL statements in it, and inserts the results. We would have used PHP or mod_perl instead but they were not available at that time. @@ -24879,7 +24882,7 @@ system setup you have, the more overhead you get. If you do not have any @code{GRANT} statements done, MySQL will optimise the permission checking somewhat. So if you have a very high -volume it may be worth the time to avoid grants. Otherwise more +volume it may be worth the time to avoid grants. Otherwise, more permission check results in a larger overhead. If your problem is with some explicit MySQL function, you can @@ -25066,7 +25069,7 @@ If you want to get your queries as fast as possible, you should look out for @code{Using filesort} and @code{Using temporary}. @end table -The different join types are listed below, ordered from best to worst type: +The different join types are listed here, ordered from best to worst type: @cindex system table @cindex tables, system @@ -25106,7 +25109,7 @@ The @code{ref} column will be NULL for this type. @item index This is the same as @code{ALL}, except that only the index tree is scanned. This is usually faster than @code{ALL}, as the index file is usually -smaller than the data file. +smaller than the datafile. @item ALL A full table scan will be done for each combination of rows from the @@ -25127,7 +25130,7 @@ variable. The following example shows how a @code{JOIN} can be optimised progressively using the information provided by @code{EXPLAIN}. -Suppose you have the @code{SELECT} statement shown below, that you examine +Suppose you have the @code{SELECT} statement shown here, that you examine using @code{EXPLAIN}: @example @@ -25161,7 +25164,7 @@ The columns being compared have been declared as follows: @end multitable @item -The tables have the indexes shown below: +The tables have the indexes shown here: @multitable @columnfractions .10 .30 @item @strong{Table} @tab @strong{Index} @@ -25235,7 +25238,7 @@ mysql> ALTER TABLE tt MODIFY AssignedPC VARCHAR(15), -> MODIFY ClientID VARCHAR(15); @end example -Now @code{EXPLAIN} produces the output shown below: +Now @code{EXPLAIN} produces the output shown here: @example table type possible_keys key key_len ref rows Extra @@ -25324,7 +25327,7 @@ the data grows. @xref{Server parameters}. @cindex speed, of queries In general, when you want to make a slow @code{SELECT ... WHERE} faster, the -first thing to check is whether or not you can add an index. @xref{MySQL +first thing to check is whether you can add an index. @xref{MySQL indexes, , MySQL indexes}. All references between different tables should usually be done with indexes. You can use the @code{EXPLAIN} command to determine which indexes are used for a @code{SELECT}. @@ -25367,7 +25370,7 @@ they are mostly used with @code{SELECT}, but the same optimisations apply for Also note that this section is incomplete. MySQL does many optimisations, and we have not had time to document them all. -Some of the optimisations performed by MySQL are listed below: +Some of the optimisations performed by MySQL are listed here: @itemize @bullet @item @@ -25442,7 +25445,7 @@ Each table index is queried, and the best index that spans fewer than 30% of the rows is used. If no such index can be found, a quick table scan is used. @item In some cases, MySQL can read rows from the index without even -consulting the data file. If all columns used from the index are numeric, +consulting the datafile. If all columns used from the index are numeric, then only the index tree is used to resolve the query. @item Before each record is output, those that do not match the @code{HAVING} clause @@ -25597,7 +25600,7 @@ SELECT * FROM t1 ORDER BY key_part1 DESC,key_part2 DESC SELECT * FROM t1 WHERE key_part1=1 ORDER BY key_part1 DESC,key_part2 DESC @end example -Some cases where MySQL can NOT use indexes to resolve the @code{ORDER +Some cases where MySQL can @strong{not} use indexes to resolve the @code{ORDER BY}: (Note that MySQL will still use indexes to find the rows that matches the @code{WHERE} clause): @@ -25823,7 +25826,7 @@ flush-tables}. @end enumerate Note that @code{LOAD DATA INFILE} also does the above optimization if -you insert into an empty table; The main difference with the above +you insert into an empty table; the main difference with the above procedure is that you can let myisamchk allocate much more temporary memory for the index creation that you may want MySQL to allocate for every index recreation. @@ -26040,9 +26043,9 @@ using a dynamic table format. @xref{OPTIMIZE TABLE, , @code{OPTIMIZE TABLE}}. Use @code{HEAP} tables to get more speed when possible. @xref{Table types}. @item -When using a normal Web server setup, images should be stored as +When using a normal web server setup, images should be stored as files. That is, store only a file reference in the database. The main -reason for this is that a normal Web server is much better at caching +reason for this is that a normal web server is much better at caching files than database contents. So it it's much easier to get a fast system if you are using files. @item @@ -26357,7 +26360,7 @@ Choosing the right table format may give you a big performance gain. @xref{Table types}. You can get better performance on a table and minimise storage space -using the techniques listed below: +using the techniques listed here: @itemize @bullet @item @@ -26422,7 +26425,7 @@ fast. Without an index MySQL has to start with the first record and then read through the whole table until it finds the relevant rows. The bigger the table, the more this costs. If the table has an index for the columns in question, MySQL can quickly get a position to -seek to in the middle of the data file without having to look at all the +seek to in the middle of the datafile without having to look at all the data. If a table has 1000 rows, this is at least 100 times faster than reading sequentially. Note that if you need to access almost all 1000 rows it is faster to read sequentially because we then avoid disk seeks. @@ -26459,7 +26462,7 @@ parts are followed by @code{DESC}. @xref{ORDER BY optimisation}. @item In some cases a query can be optimised to retrieve values without -consulting the data file. If all used columns for some table are numeric +consulting the datafile. If all used columns for some table are numeric and form a leftmost prefix for some key, the values may be retrieved from the index tree for greater speed: @@ -26491,7 +26494,7 @@ search capabilities on @code{(col1)}, @code{(col1,col2)}, and MySQL can't use a partial index if the columns don't form a leftmost prefix of the index. Suppose you have the @code{SELECT} -statements shown below: +statements shown here: @example mysql> SELECT * FROM tbl_name WHERE col1=val1; @@ -26603,7 +26606,7 @@ index a column prefix looks like this: KEY index_name (col_name(length)) @end example -The example below creates an index for the first 10 characters of the +The example here creates an index for the first 10 characters of the @code{name} column: @example @@ -26697,12 +26700,12 @@ Uptime: 426 Running threads: 1 Questions: 11082 Reloads: 1 Open tables: 12 This can be somewhat perplexing if you only have 6 tables. -MySQL is multithreaded, so it may have many queries on the same table +MySQL is multi-threaded, so it may have many queries on the same table simultaneously. To minimise the problem with two threads having different states on the same file, the table is opened independently by each concurrent thread. This takes some memory but will normaly increase performance. Wth ISAM and MyISAM tables this also requires one extra file -descriptor for the data file. With these table types the index file +descriptor for the datafile. With these table types the index file descriptor is shared between all threads. You can read more about this topic in the next section. @xref{Table cache}. @@ -26842,13 +26845,13 @@ nice to have a feeling about how much one could gain by changing things at this level. The default OS to use is really important! To get the most use of -multiple CPU machines one should use Solaris (because the threads works +multiple-CPU machines one should use Solaris (because the threads works really nice) or Linux (because the 2.2 kernel has really good SMP -support). Also on 32-bit machines Linux has a 2G file size limit by +support). Also on 32-bit machines Linux has a 2G file-size limit by default. Hopefully this will be fixed soon when new filesystems are released (XFS/Reiserfs). If you have a desperate need for files bigger than 2G on Linux-intel 32 bit, you should get the LFS patch for the ext2 -file system. +filesystem. Because we have not run MySQL in production on that many platforms, we advice you to test your intended platform before choosing it, if possible. @@ -27022,7 +27025,7 @@ shell> mysqld -O key_buffer=32m --help @end example Make sure that the @code{--help} option is last; otherwise, the effect of any -options listed after it on the command line will not be reflected in the +options listed after it on the command-line will not be reflected in the output. @@ -27115,7 +27118,7 @@ Running with @code{--log-bin} makes @strong{[MySQL} 1 % slower. @item Compiling on Linux-x86 using gcc without frame pointers @code{-fomit-frame-pointer} or @code{-fomit-frame-pointer -ffixed-ebp} -@code{mysqld} 1-4% faster. +makes @code{mysqld} 1-4% faster. @end itemize The MySQL-Linux distribution provided by MySQL AB used @@ -27132,14 +27135,14 @@ Linux binary is linked statically to get it faster and more portable. @cindex memory use -The list below indicates some of the ways that the @code{mysqld} server +The following list indicates some of the ways that the @code{mysqld} server uses memory. Where applicable, the name of the server variable relevant to the memory use is given: @itemize @bullet @item The key buffer (variable @code{key_buffer_size}) is shared by all -threads; Other buffers used by the server are allocated as +threads; other buffers used by the server are allocated as needed. @xref{Server parameters}. @item @@ -27202,7 +27205,7 @@ unexpectedly large strings (this is done with @code{malloc()} and @code{free()}). @item -Each index file is opened once and the data file is opened once for each +Each index file is opened once and the datafile is opened once for each concurrently running thread. For each concurrent thread, a table structure, column structures for each column, and a buffer of size @code{3 * n} is allocated (where @code{n} is the maximum row length, not counting @code{BLOB} @@ -27450,7 +27453,7 @@ the disks. @table @strong @item Using symbolic links -This means that you symlink the index and/or data file(s) from the +This means that you symlink the index and/or datafile(s) from the normal data directory to another disk (that may also be striped). This makes both the seek and read times better (if the disks are not used for other things). @xref{Symbolic links}. @@ -27485,8 +27488,8 @@ and logs) on a RAID 0+1 or RAID N disk. RAID N can be a problem if you have many writes because of the time to update the parity bits. @item -You may also set the parameters for the file system that the database -uses. One easy change is to mount the file system with the noatime +You may also set the parameters for the filesystem that the database +uses. One easy change is to mount the filesystem with the noatime option. That makes it skip the updating of the last access time in the inode and by this will avoid some disk seeks. @@ -27508,13 +27511,13 @@ filesystem corruption may result. Backup everything before experimenting! @item On many operating systems you can mount the disks with the 'async' flag to -set the file system to be updated asynchronously. If your computer is +set the filesystem to be updated asynchronously. If your computer is reasonable stable, this should give you more performance without sacrificing too much reliability. (This flag is on by default on Linux.) @item If you don't need to know when a file was last accessed (which is not -really useful on a database server), you can mount your file systems +really useful on a database server), you can mount your filesystems with the noatime flag. @end itemize @@ -27620,7 +27623,7 @@ In the data directory you will always have the table definition file and the data/index files. @item -You can symlink the index file and the data file to different directories +You can symlink the index file and the datafile to different directories independent of the other. @item @@ -27834,7 +27837,7 @@ and need not be doubled or escaped. In the same way, @samp{"} inside a string quoted with @samp{'} needs no special treatment. @end itemize -The @code{SELECT} statements shown below demonstrate how quoting and +The @code{SELECT} statements shown here demonstrate how quoting and escaping work: @example @@ -28075,12 +28078,12 @@ programs prefix table names with a @samp{.} character. In MySQL, databases and tables correspond to directories and files within those directories. Consequently, the case sensitivity of the underlying operating system determines the case sensitivity of database and -table names. This means database and table names are case insensitive in -Windows, and case sensitive in most varieties of Unix (Mac OS X being an +table names. This means database and table names are case-insensitive in +Windows, and case-sensitive in most varieties of Unix (Mac OS X being an exception). @xref{Extensions to ANSI}. -@strong{NOTE:} Although database and table names are case insensitive for +@strong{Note}: although database and table names are case-insensitive for Windows, you should not refer to a given database or table using different cases within the same query. The following query would not work because it refers to a table both as @code{my_table} and as @code{MY_TABLE}: @@ -28089,9 +28092,9 @@ refers to a table both as @code{my_table} and as @code{MY_TABLE}: mysql> SELECT * FROM my_table WHERE MY_TABLE.col=1; @end example -Column names and column aliases are case insensitive in all cases. +Column names and column aliases are case-insensitive in all cases. -Aliases on tables are case sensitive. The following query would not work +Aliases on tables are case-sensitive. The following query would not work because it refers to the alias both as @code{a} and as @code{A}: @example @@ -28158,7 +28161,7 @@ this does not currently include contexts where a number is explicitly required, such as in the @code{LIMIT} clause of a @code{SELECT} statement, or the @code{IGNORE number LINES} clause of a @code{LOAD DATA} statement. -@strong{NOTE:} In a @code{SELECT} statement, each expression is evaluated +@strong{Note}: in a @code{SELECT} statement, each expression is evaluated only when it's sent to the client. This means that in the @code{HAVING}, @code{GROUP BY}, or @code{ORDER BY} clause, you can't refer to an expression that involves variables that are set in the @code{SELECT} part. For example, @@ -28500,7 +28503,7 @@ that are optional. Note that if you specify @code{ZEROFILL} for a column, MySQL will automatically add the @code{UNSIGNED} attribute to the column. -@strong{Warning:} You should be aware that when you use subtraction +@strong{Warning}: you should be aware that when you use subtraction between integer values where one is of type @code{UNSIGNED}, the result will be unsigned! @xref{Cast Functions}. @@ -28756,7 +28759,7 @@ This is a synonym for @code{CHAR(1)}. @tindex VARCHAR @item [NATIONAL] VARCHAR(M) [BINARY] -A variable-length string. @strong{Note:} Trailing spaces are removed when +A variable-length string. @strong{Note}: trailing spaces are removed when the value is stored (this differs from the ANSI SQL specification). The range of @code{M} is 0 to 255 characters (1 to 255 prior to MySQL Version 4.0.2). @code{VARCHAR} values are sorted and compared in case-insensitive fashion @@ -29022,7 +29025,7 @@ When MySQL encounters a value for a date or time type that is out of range or otherwise illegal for the type (see the start of this section), it converts the value to the ``zero'' value for that type. (The exception is that out-of-range @code{TIME} values are clipped to -the appropriate endpoint of the @code{TIME} range.) The table below +the appropriate endpoint of the @code{TIME} range.) The following table shows the format of the ``zero'' value for each type: @multitable @columnfractions .15 .55 @@ -29040,8 +29043,8 @@ explicitly using the values shown in the table. You can also do this using the values @code{'0'} or @code{0}, which are easier to write. @item -``Zero'' date or time values used through @strong{MyODBC} are converted -automatically to @code{NULL} in @strong{MyODBC} Version 2.50.12 and above, +``Zero'' date or time values used through @code{MyODBC} are converted +automatically to @code{NULL} in @code{MyODBC} Version 2.50.12 and above, because ODBC can't handle such values. @end itemize @@ -29132,7 +29135,7 @@ You explicitly set the @code{TIMESTAMP} column to @code{NULL}. @code{TIMESTAMP} columns other than the first may also be set to the current date and time. Just set the column to @code{NULL} or to @code{NOW()}. -You can set any @code{TIMESTAMP} column to a value different than the current +You can set any @code{TIMESTAMP} column to a value different from the current date and time by setting it explicitly to the desired value. This is true even for the first @code{TIMESTAMP} column. You can use this property if, for example, you want a @code{TIMESTAMP} to be set to the current date and @@ -29158,7 +29161,7 @@ the year 2037, with a resolution of one second. Values are displayed as numbers. The format in which MySQL retrieves and displays @code{TIMESTAMP} -values depends on the display size, as illustrated by the table below. The +values depends on the display size, as illustrated by the following table. The `full' @code{TIMESTAMP} format is 14 digits, but @code{TIMESTAMP} columns may be created with shorter display sizes: @@ -29253,7 +29256,7 @@ as though padded with leading zeros to the closest length. @cindex strings, non-delimited Values specified as non-delimited strings are interpreted using their length as given. If the string is 8 or 14 characters long, the year is assumed to -be given by the first 4 characters. Otherwise the year is assumed to be +be given by the first 4 characters. Otherwise, the year is assumed to be given by the first 2 characters. The string is interpreted from left to right to find year, month, day, hour, minute, and second values, for as many parts as are present in the string. This means you should not use strings @@ -29448,9 +29451,9 @@ As a two-digit number in the range @code{1} to @code{99}. Values in the ranges @code{1} to @code{69} and @code{70} to @code{99} are converted to @code{YEAR} values in the ranges @code{2001} to @code{2069} and @code{1970} to @code{1999}. Note that the range for two-digit numbers is slightly -different than the range for two-digit strings, because you cannot specify zero +different from the range for two-digit strings, because you cannot specify zero directly as a number and have it be interpreted as @code{2000}. You -@emph{must} specify it as a string @code{'0'} or @code{'00'} or it will be +@strong{must} specify it as a string @code{'0'} or @code{'00'} or it will be interpreted as @code{0000}. @item @@ -29507,7 +29510,7 @@ SQL specification.) If you assign a value to a @code{CHAR} or @code{VARCHAR} column that exceeds the column's maximum length, the value is truncated to fit. -The table below illustrates the differences between the two types of columns +The following table illustrates the differences between the two types of columns by showing the result of storing various string values into @code{CHAR(4)} and @code{VARCHAR(4)} columns: @@ -29587,7 +29590,7 @@ when values are stored, as there is for @code{VARCHAR} columns. @code{BLOB} and @code{TEXT} columns cannot have @code{DEFAULT} values. @end itemize -@strong{MyODBC} defines @code{BLOB} values as @code{LONGVARBINARY} and +@code{MyODBC} defines @code{BLOB} values as @code{LONGVARBINARY} and @code{TEXT} values as @code{LONGVARCHAR}. Because @code{BLOB} and @code{TEXT} values may be extremely long, you @@ -29678,7 +29681,7 @@ The index of the @code{NULL} value is @code{NULL}. @end itemize For example, a column specified as @code{ENUM("one", "two", "three")} can -have any of the values shown below. The index of each value is also shown: +have any of the values shown here. The index of each value is also shown: @multitable @columnfractions .10 .10 @item @strong{Value} @tab @strong{Index} @@ -29840,7 +29843,7 @@ and convert results back to floating-point values only when necessary. @cindex columns, other types To make it easier to use code written for SQL implementations from other -vendors, MySQL maps column types as shown in the table below. These +vendors, MySQL maps column types as shown in the following table. These mappings make it easier to move table definitions from other database engines to MySQL: @@ -29874,7 +29877,7 @@ MySQL types. @cindex columns, storage requirements The storage requirements for each of the column types supported by -MySQL are listed below by category. +MySQL are listed by category. @cindex numeric types @cindex types, numeric @@ -29981,7 +29984,7 @@ An expression that contains @code{NULL} always produces a @code{NULL} value unless otherwise indicated in the documentation for the operators and functions involved in the expression. -@strong{Note:} There must be no whitespace between a function name and the +@strong{Note}: there must be no whitespace between a function name and the parentheses following it. This helps the MySQL parser distinguish between function calls and references to tables or columns that happen to have the same name as a function. Spaces around arguments are permitted, @@ -30109,7 +30112,7 @@ By default, string comparisons are done in case-independent fashion using the current character set (ISO-8859-1 Latin1 by default, which also works excellently for English). -The examples below illustrate conversion of strings to numbers for comparison +The following examples illustrate conversion of strings to numbers for comparison operations: @example @@ -30207,7 +30210,7 @@ mysql> SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL; @findex IS NOT NULL @item IS NULL @itemx IS NOT NULL -Test whether or not a value is or is not @code{NULL}: +Test whether a value is or is not @code{NULL}: @example mysql> SELECT 1 IS NULL, 0 IS NULL, NULL IS NULL; -> 0 0 1 @@ -30346,7 +30349,7 @@ mysql> SELECT INTERVAL(22, 23, 30, 44, 200); @end example @end table -If you are comparing case sensitive string with any of the standard +If you are comparing case-sensitive string with any of the standard operators (@code{=}, @code{<>}..., but not @code{LIKE}) end space will be ignored. @@ -30499,8 +30502,8 @@ stored into a temporary table) is calculated in MySQL Version @item expr2 or expr3 returns an integer @tab integer @end multitable -If expr2 and expr3 are strings, then the result is case sensitive if -both strings are case sensitive. (Starting from 3.23.51) +If expr2 and expr3 are strings, then the result is case-sensitive if +both strings are case-sensitive. (Starting from 3.23.51) @findex CASE @item CASE value WHEN [compare-value] THEN result [WHEN [compare-value] THEN result ...] [ELSE result] END @@ -30727,7 +30730,7 @@ mysql> SELECT LOCATE('xbar', 'foobar'); @end example This function is multi-byte safe. In MySQL 3.23 this function is case -insensitive, while in 4.0 it's only case insensitive if either argument is +insensitive, while in 4.0 it's only case-insensitive if either argument is a binary string. @findex LOCATE() @@ -30742,7 +30745,7 @@ mysql> SELECT LOCATE('bar', 'foobarbar',5); @end example This function is multi-byte safe. In MySQL 3.23 this function is case -insensitive, while in 4.0 it's only case insensitive if either argument is +insensitive, while in 4.0 it's only case-insensitive if either argument is a binary string. @findex INSTR() @@ -30759,7 +30762,7 @@ mysql> SELECT INSTR('xbar', 'foobar'); @end example This function is multi-byte safe. In MySQL 3.23 this function is case -insensitive, while in 4.0 it's only case insensitive if either argument is +insensitive, while in 4.0 it's only case-insensitive if either argument is a binary string. @findex LPAD() @@ -31128,7 +31131,7 @@ a binary string. This only affects comparisons. @cindex case sensitivity, in string comparisons @cindex string comparisons, case sensitivity -Normally, if any expression in a string comparison is case sensitive, the +Normally, if any expression in a string comparison is case-sensitive, the comparison is performed in case-sensitive fashion. @table @code @@ -31177,7 +31180,7 @@ mysql> SELECT 'David_' LIKE 'David|_' ESCAPE '|'; @end example The following two statements illustrate that string comparisons are -case insensitive unless one of the operands is a binary string: +case-insensitive unless one of the operands is a binary string: @example mysql> SELECT 'abc' LIKE 'ABC'; @@ -31218,7 +31221,7 @@ returns @code{0}. @code{RLIKE} is a synonym for @code{REGEXP}, provided for @code{mSQL} compatibility. Note: Because MySQL uses the C escape syntax in strings (for example, @samp{\n}), you must double any @samp{\} that you use in your @code{REGEXP} strings. As of MySQL Version 3.23.4, -@code{REGEXP} is case insensitive for normal (not binary) strings: +@code{REGEXP} is case-insensitive for normal (not binary) strings: @example mysql> SELECT 'Monty!' REGEXP 'm%y%%'; @@ -31282,7 +31285,7 @@ positive floating-point number. Zero relevance means no similarity. @findex BINARY @item @code{BINARY} The @code{BINARY} operator casts the string following it to a binary string. -This is an easy way to force a column comparison to be case sensitive even +This is an easy way to force a column comparison to be case-sensitive even if the column isn't defined as @code{BINARY} or @code{BLOB}: @example mysql> SELECT "a" = "A"; @@ -31493,7 +31496,7 @@ mysql> SELECT ROUND(1.58); Note that the behavior of @code{ROUND()} when the argument is half way between two integers depends on the C library implementation. Some round to the nearest even number, -always up, always down, or always towards zero. If you need +always up, always down, or always toward zero. If you need one kind of rounding, you should use a well-defined function like @code{TRUNCATE()} or @code{FLOOR()} instead. @@ -31796,7 +31799,7 @@ See @ref{Date and time types} for a description of the range of values each type has and the valid formats in which date and time values may be specified. -Here is an example that uses date functions. The query below selects +Here is an example that uses date functions. The following query selects all records with a @code{date_col} value from within the last 30 days: @example @@ -31964,7 +31967,7 @@ mysql> SELECT SECOND('10:05:03'); Adds @code{N} months to period @code{P} (in the format @code{YYMM} or @code{YYYYMM}). Returns a value in the format @code{YYYYMM}. -Note that the period argument @code{P} is @emph{not} a date value: +Note that the period argument @code{P} is @strong{not} a date value: @example mysql> SELECT PERIOD_ADD(9801,2); @@ -31976,7 +31979,7 @@ mysql> SELECT PERIOD_ADD(9801,2); Returns the number of months between periods @code{P1} and @code{P2}. @code{P1} and @code{P2} should be in the format @code{YYMM} or @code{YYYYMM}. -Note that the period arguments @code{P1} and @code{P2} are @emph{not} +Note that the period arguments @code{P1} and @code{P2} are @strong{not} date values: @example @@ -32000,7 +32003,7 @@ Version 3.22. @code{ADDDATE()} and @code{SUBDATE()} are synonyms for In MySQL Version 3.23, you can use @code{+} and @code{-} instead of @code{DATE_ADD()} and @code{DATE_SUB()} if the expression on the right side is -a date or datetime column. (See example) +a date or datetime column. (See example below.) @code{date} is a @code{DATETIME} or @code{DATE} value specifying the starting date. @code{expr} is an expression specifying the interval value to be added @@ -32035,7 +32038,7 @@ MySQL allows any punctuation delimiter in the @code{expr} format. Those shown in the table are the suggested delimiters. If the @code{date} argument is a @code{DATE} value and your calculations involve only @code{YEAR}, @code{MONTH}, and @code{DAY} parts (that is, no time parts), the -result is a @code{DATE} value. Otherwise the result is a @code{DATETIME} +result is a @code{DATE} value. Otherwise, the result is a @code{DATETIME} value: @example @@ -32098,7 +32101,7 @@ mysql> SELECT DATE_ADD('1998-01-30', INTERVAL 1 MONTH); @end example Note from the preceding example that the word @code{INTERVAL} and the -@code{type} keyword are not case sensitive. +@code{type} keyword are not case-sensitive. @findex EXTRACT() @item EXTRACT(type FROM date) @@ -32380,19 +32383,19 @@ CREATE TABLE new_table SELECT CAST('2000-01-01' AS DATE); @code{CAST(string AS BINARY} is the same thing as @code{BINARY string}. To cast a string to a numeric value, you don't normally have to do -anything; Just use the string value as it would be a number: +anything; just use the string value as it would be a number: @example mysql> SELECT 1+'1'; -> 2 @end example -MySQL supports arithmetic with both signed and unsigned 64 bit values. +MySQL supports arithmetic with both signed and unsigned 64-bit values. If you are using an numerical operations (like @code{+}) and one of the operands are @code{unsigned integer}, then the result will be unsigned. You can override this by using the @code{SIGNED} and @code{UNSIGNED} -cast operators, which will cast the operation to signed respective -unsigned 64 bit integer. +cast operators, which will cast the operation to a signed or +unsigned 64-bit integer, respectively. @example mysql> SELECT CAST(1-2 AS UNSIGNED) @@ -32401,9 +32404,9 @@ mysql> SELECT CAST(CAST(1-2 AS UNSIGNED) AS SIGNED); -> -1 @end example -Note that if either operation is a floating point value (In this context -@code{DECIMAL()} is regarded as a floating point value) the result will -be a floating point value and is not affected by the above rule. +Note that if either operation is a floating-point value (In this context +@code{DECIMAL()} is regarded as a floating-point value) the result will +be a floating-point value and is not affected by the above rule. @example mysql> SELECT CAST(1 AS UNSIGNED) -2.0 @@ -32411,7 +32414,7 @@ mysql> SELECT CAST(1 AS UNSIGNED) -2.0 @end example If you are using a string in an arithmetic operation, this is converted -to a floating point number. +to a floating-point number. The @code{CAST()} and @code{CONVERT()} functions were added in MySQL 4.0.2. @@ -32425,7 +32428,7 @@ result when subtracting two unsigned integer columns: SELECT (unsigned_column_1+0.0)-(unsigned_column_2+0.0); @end example -The idea is that the columns are converted to floating point before doing +The idea is that the columns are converted to floating-point before doing the subtraction. If you get a problem with @code{UNSIGNED} columns in your old MySQL @@ -32464,7 +32467,7 @@ mysql> SELECT 29 | 15; -> 31 @end example -The result is an unsigned 64 bit integer. +The result is an unsigned 64-bit integer. @findex & (bitwise AND) @findex AND, bitwise @@ -32475,7 +32478,7 @@ mysql> SELECT 29 & 15; -> 13 @end example -The result is an unsigned 64 bit integer. +The result is an unsigned 64-bit integer. @findex << (left shift) @item << @@ -32485,7 +32488,7 @@ mysql> SELECT 1 << 2; -> 4 @end example -The result is an unsigned 64 bit integer. +The result is an unsigned 64-bit integer. @findex >> (right shift) @item >> @@ -32495,7 +32498,7 @@ mysql> SELECT 4 >> 2; -> 1 @end example -The result is an unsigned 64 bit integer. +The result is an unsigned 64-bit integer. @findex ~ @item ~ @@ -32505,7 +32508,7 @@ mysql> SELECT 5 & ~1; -> 4 @end example -The result is an unsigned 64 bit integer. +The result is an unsigned 64-bit integer. @findex BIT_COUNT() @item BIT_COUNT(N) @@ -32550,7 +32553,7 @@ mysql> SELECT USER(); In MySQL Version 3.22.11 or later, this includes the client hostname as well as the user name. You can extract just the user name part like this -(which works whether or not the value includes a hostname part): +(which works whether the value includes a hostname part): @example mysql> SELECT SUBSTRING_INDEX(USER(),"@@",1); @@ -32876,7 +32879,7 @@ mysql> SELECT INET_ATON("209.207.224.40"); -> 3520061480 @end example -The generated number is always in network byte order; For example the +The generated number is always in network byte order; for example the above number is calculated as @code{209*256^3 + 207*256^2 + 224*256 +40}. @findex MASTER_POS_WAIT() @@ -32938,7 +32941,7 @@ mysql> SELECT student.student_name,COUNT(*) @end example @code{COUNT(*)} is somewhat different in that it returns a count of -the number of rows retrieved, whether or not they contain @code{NULL} +the number of rows retrieved, whether they contain @code{NULL} values. @code{COUNT(*)} is optimised to @@ -33644,18 +33647,21 @@ it accessible via subsequent @code{HANDLER ... READ} statements. This table object is not shared by other threads and will not be closed until the thread calls @code{HANDLER tbl_name CLOSE} or the thread dies. -The second form fetches one (or, specified by @code{LIMIT} clause) row +@c FIX The sentence below needs to be rewritten. The reference to "the condition" is not clear. +@c FIX Also all mentions of the LIMIT clause need to be clarified in various sentences below. + +The second form fetches one row (or more, specified by @code{LIMIT} clause) where the index specified complies to the condition and @code{WHERE} condition is met. If the index consists of several parts (spans over several columns) the values are specified in comma-separated list, providing values only for few first columns is possible. -The third form fetches one (or, specified by @code{LIMIT} clause) row +The third form fetches one row (or more, specified by @code{LIMIT} clause) from the table in index order, matching @code{WHERE} condition. -The fourth form (without index specification) fetches one (or, specified -by @code{LIMIT} clause) row from the table in natural row order (as stored -in data file) matching @code{WHERE} condition. It is faster than +The fourth form (without index specification) fetches one row (or more, specified +by @code{LIMIT} clause) from the table in natural row order (as stored +in datafile) matching @code{WHERE} condition. It is faster than @code{HANDLER tbl_name READ index_name} when a full table scan is desired. @code{HANDLER ... CLOSE} closes a table that was opened with @@ -33767,7 +33773,7 @@ with the @code{mysql_insert_id} function. If you use @code{INSERT ... SELECT} or an @code{INSERT ... VALUES} statement with multiple value lists, you can use the C API function @code{mysql_info()} to get information about the query. The format of the -information string is shown below: +information string is shown here: @example Records: 100 Duplicates: 0 Warnings: 0 @@ -33877,7 +33883,7 @@ Version 3.22.15. It is a MySQL extension to ANSI SQL92. @code{INSERT DELAYED} only works with @code{ISAM} and @code{MyISAM} tables. Note that as @code{MyISAM} tables supports concurrent @code{SELECT} and @code{INSERT}, if there is no free blocks in the -middle of the data file, you very seldom need to use @code{INSERT +middle of the datafile, you very seldom need to use @code{INSERT DELAYED} with @code{MyISAM}. @xref{MyISAM}. When you use @code{INSERT DELAYED}, the client will get an OK at once @@ -33905,7 +33911,7 @@ thread is created to process all @code{DELAYED} statements for the table, if no such handler already exists. @item -The thread checks whether or not the handler has acquired a @code{DELAYED} +The thread checks whether the handler has acquired a @code{DELAYED} lock already; if not, it tells the handler thread to do so. The @code{DELAYED} lock can be obtained even if other threads have a @code{READ} or @code{WRITE} lock on the table. However, the handler will wait for all @@ -33932,7 +33938,7 @@ the first row is inserted. @item After every @code{delayed_insert_limit} rows are written, the handler checks -whether or not any @code{SELECT} statements are still pending. If so, it +whether any @code{SELECT} statements are still pending. If so, it allows these to execute before continuing. @cindex delayed_insert_limit @@ -33958,7 +33964,6 @@ table before exiting. During this time it will not accept any new @code{INSERT} commands from another thread. If you execute an @code{INSERT DELAYED} command after this, a new handler thread will be created. -@item Note that the above means that @code{INSERT DELAYED} commands have higher priority than normal @code{INSERT} commands if there is an @code{INSERT DELAYED} handler already running! Other update commands will have to wait @@ -34002,7 +34007,7 @@ UPDATE [LOW_PRIORITY] [IGNORE] tbl_name @code{UPDATE} updates columns in existing table rows with new values. The @code{SET} clause indicates which columns to modify and the values they should be given. The @code{WHERE} clause, if given, specifies -which rows should be updated. Otherwise all rows are updated. If the +which rows should be updated. Otherwise, all rows are updated. If the @code{ORDER BY} clause is specified, the rows will be updated in the order that is specified. @@ -34096,7 +34101,7 @@ deletes. In @code{MyISAM} tables, deleted records are maintained in a linked list and subsequent @code{INSERT} operations reuse old record positions. To -reclaim unused space and reduce file sizes, use the @code{OPTIMIZE +reclaim unused space and reduce file-sizes, use the @code{OPTIMIZE TABLE} statement or the @code{myisamchk} utility to reorganise tables. @code{OPTIMIZE TABLE} is easier, but @code{myisamchk} is faster. See @ref{OPTIMIZE TABLE, , @code{OPTIMIZE TABLE}} and @ref{Optimisation}. @@ -34159,8 +34164,8 @@ TRUNCATE TABLE table_name In 3.23 @code{TRUNCATE TABLE} is mapped to @code{COMMIT ; DELETE FROM table_name}. @xref{DELETE}. -The differences between @code{TRUNCATE TABLE} and @code{DELETE FROM ...} -are: +@code{TRUNCATE TABLE} differs from @code{DELETE FROM ...} +in the following ways: @itemize @bullet @item @@ -34271,9 +34276,9 @@ example the output from gunzip), use @code{LOAD DATA LOCAL INFILE} instead. @cindex @code{mysqlimport} -You can also load data files by using the @code{mysqlimport} utility; it +You can also load datafiles by using the @code{mysqlimport} utility; it operates by sending a @code{LOAD DATA INFILE} command to the server. The -@code{--local} option causes @code{mysqlimport} to read data files from the +@code{--local} option causes @code{mysqlimport} to read datafiles from the client host. You can specify the @code{--compress} option to get better performance over slow networks if the client and server support the compressed protocol. @@ -34417,7 +34422,7 @@ mysql> LOAD DATA INFILE 'data.txt' INTO TABLE table2 -> FIELDS TERMINATED BY ','; @end example -If instead you tried to read in the file with the statement shown below, it +If instead you tried to read in the file with the statement shown here, it wouldn't work because it instructs @code{LOAD DATA INFILE} to look for tabs between fields: @@ -34432,7 +34437,7 @@ a single field. @code{LOAD DATA INFILE} can be used to read files obtained from external sources, too. For example, a file in dBASE format will have fields separated by commas and enclosed in double quotes. If lines in -the file are terminated by newlines, the command shown below +the file are terminated by newlines, the command shown here illustrates the field and line handling options you would use to load the file: @@ -34465,7 +34470,7 @@ LINES TERMINATED BY "\n%%\n" (joke); output (@code{SELECT ... INTO OUTFILE}), if you omit the word @code{OPTIONALLY}, all fields are enclosed by the @code{ENCLOSED BY} character. An example of such output (using a comma as the field -delimiter) is shown below: +delimiter) is shown here: @example "1","a string","100.20" @@ -34489,7 +34494,7 @@ field value are escaped by prefixing them with the @code{ESCAPED BY} character. Also note that if you specify an empty @code{ESCAPED BY} value, it is possible to generate output that cannot be read properly by @code{LOAD DATA INFILE}. For example, the output just shown above would -appear as shown below if the escape character is empty. Observe that the +appear as shown here if the escape character is empty. Observe that the second field in the fourth line contains a comma following the quote, which (erroneously) appears to terminate the field: @@ -34501,14 +34506,14 @@ second field in the fourth line contains a comma following the quote, which @end example For input, the @code{ENCLOSED BY} character, if present, is stripped from the -ends of field values. (This is true whether or not @code{OPTIONALLY} is +ends of field values. (This is true whether @code{OPTIONALLY} is specified; @code{OPTIONALLY} has no effect on input interpretation.) Occurrences of the @code{ENCLOSED BY} character preceded by the @code{ESCAPED BY} character are interpreted as part of the current field value. In addition, duplicated @code{ENCLOSED BY} characters occurring within fields are interpreted as single @code{ENCLOSED BY} characters if the field itself starts with that character. For example, if @code{ENCLOSED BY -'"'} is specified, quotes are handled as shown below: +'"'} is specified, quotes are handled as shown here: @example "The ""BIG"" boss" -> The "BIG" boss @@ -34681,7 +34686,7 @@ specified as strings! @findex mysql_info() If you are using the C API, you can get information about the query by calling the API function @code{mysql_info()} when the @code{LOAD DATA INFILE} -query finishes. The format of the information string is shown below: +query finishes. The format of the information string is shown here: @example Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 @@ -34902,7 +34907,7 @@ allowable table names are given in @ref{Legal names}. An error occurs if there is no current database or if the table already exists. In MySQL Version 3.22 or later, the table name can be specified as -@code{db_name.tbl_name}. This works whether or not there is a current +@code{db_name.tbl_name}. This works whether there is a current database. In MySQL Version 3.23, you can use the @code{TEMPORARY} keyword when @@ -34923,7 +34928,7 @@ directory. In the case of MyISAM-type tables you will get: @multitable @columnfractions .20 .30 @item @strong{File} @tab @strong{Purpose} @item @code{tbl_name.frm} @tab Table definition (form) file -@item @code{tbl_name.MYD} @tab Data file +@item @code{tbl_name.MYD} @tab Datafile @item @code{tbl_name.MYI} @tab Index file @end multitable @@ -34950,7 +34955,7 @@ If you delete the row containing the maximum value for an with @code{DELETE FROM table_name} (without a @code{WHERE}) in @code{AUTOCOMMIT} mode, the sequence starts over for all table types. -@strong{NOTE:} There can be only one @code{AUTO_INCREMENT} column per +@strong{Note}: there can be only one @code{AUTO_INCREMENT} column per table, and it must be indexed. MySQL Version 3.23 will also only work properly if the @code{AUTO_INCREMENT} column only has positive values. Inserting a negative number is regarded as inserting a very large @@ -35240,9 +35245,9 @@ original tables, MySQL will not allow concurrent inserts during @code{CREATE TABLE ... SELECT}. @item The @code{RAID_TYPE} option will help you to break the 2G/4G limit for -the MyISAM data file (not the index file) on operating systems that +the MyISAM datafile (not the index file) on operating systems that don't support big files. Note that this option is not recommended for -file system that supports big files! +filesystem that supports big files! You can get more speed from the I/O bottleneck by putting @code{RAID} directories on different physical disks. @code{RAID_TYPE} will work on @@ -35254,7 +35259,7 @@ If you specify @code{RAID_TYPE=STRIPED} for a @code{MyISAM} table, @code{MyISAM} will create @code{RAID_CHUNKS} subdirectories named 00, 01, 02 in the database directory. In each of these directories @code{MyISAM} will create a @code{table_name.MYD}. When writing data -to the data file, the @code{RAID} handler will map the first +to the datafile, the @code{RAID} handler will map the first @code{RAID_CHUNKSIZE} *1024 bytes to the first file, the next @code{RAID_CHUNKSIZE} *1024 bytes to the next file and so on. @item @@ -35331,7 +35336,7 @@ MySQL maps certain column types used by other SQL database vendors to MySQL types. @xref{Other-vendor column types}. @end itemize -If you want to see whether or not MySQL used a column type other +If you want to see whether MySQL used a column type other than the one you specified, issue a @code{DESCRIBE tbl_name} statement after creating or altering your table. @@ -35525,7 +35530,7 @@ specific order. Note that the table will not remain in this order after inserts and deletes. In some cases, it may make sorting easier for MySQL if the table is in order by the column that you wish to order it by later. This option is mainly useful when you know that you -are mostly going to query the rows in a certain order; By using this +are mostly going to query the rows in a certain order; by using this option after big changes to the table, you may be able to get higher performance. @@ -35561,7 +35566,7 @@ that create tables with references. @end itemize Here is an example that shows some of the uses of @code{ALTER TABLE}. We -begin with a table @code{t1} that is created as shown below: +begin with a table @code{t1} that is created as shown here: @example mysql> CREATE TABLE t1 (a INTEGER,b CHAR(10)); @@ -35724,7 +35729,7 @@ columns. For @code{CHAR} and @code{VARCHAR} columns, indexes can be created that use only part of a column, using @code{col_name(length)} syntax. (On @code{BLOB} and @code{TEXT} columns the length is required.) The -statement shown below creates an index using the first 10 characters of +statement shown here creates an index using the first 10 characters of the @code{name} column: @example @@ -35798,8 +35803,8 @@ mysql> SELECT COUNT(*) FROM mytable; # selects from db2.mytable @end example Making a particular database current by means of the @code{USE} statement -does not preclude you from accessing tables in other databases. The example -below accesses the @code{author} table from the @code{db1} database and the +does not preclude you from accessing tables in other databases. The following example +accesses the @code{author} table from the @code{db1} database and the @code{editor} table from the @code{db2} database: @example @@ -35830,7 +35835,7 @@ The @code{USE} statement is provided for Sybase compatibility. may be a column name or a string containing the SQL @samp{%} and @samp{_} wildcard characters. -If the column types are different than you expect them to be based on a +If the column types are different from what you expect them to be based on a @code{CREATE TABLE} statement, note that MySQL sometimes changes column types. @xref{Silent column changes}. @@ -36014,7 +36019,7 @@ each SQL statement). This speeds up inserting/updateing/deletes on If you are using a table handler in MySQL that doesn't support transactions, you must use @code{LOCK TABLES} if you want to ensure that no other thread comes between a @code{SELECT} and an @code{UPDATE}. The -example shown below requires @code{LOCK TABLES} in order to execute safely: +example shown here requires @code{LOCK TABLES} in order to execute safely: @example mysql> LOCK TABLES trans READ, customer WRITE; @@ -36043,7 +36048,7 @@ See @ref{Internal locking}, for more information on locking policy. You can lock all tables in all databases with read locks with the @code{FLUSH TABLES WITH READ LOCK} command. @xref{FLUSH}. This is very -convenient way to get backups if you have a file system, like Veritas, +convenient way to get backups if you have a filesystem, like Veritas, that can take snapshots in time. @strong{NOTE}: @code{LOCK TABLES} is not transaction-safe and will @@ -36366,7 +36371,7 @@ To: @end example Then recompile MySQL. There is no need to rebuild the indexes in this case. -@strong{Note:} by doing this you @strong{severely} decrease MySQL's ability +@strong{Note}: by doing this you @strong{severely} decrease MySQL's ability to provide adequate relevance values for the @code{MATCH()} function. If you really need to search for such common words, it would be better to search using @code{IN BOOLEAN MODE} instead, which does not observe the 50% @@ -36393,7 +36398,7 @@ the user wants to treat as words, examples are "C++", "AS/400", "TCP/IP", etc. @item Support for multi-byte charsets. @item Make stopword list to depend of the language of the data. @item Stemming (dependent of the language of the data, of course). -@item Generic user-suppliable UDF (?) preparser. +@item Generic user-suppliable UDF preparser. @item Make the model more flexible (by adding some adjustable parameters to @code{FULLTEXT} in @code{CREATE/ALTER TABLE}). @end itemize @@ -36489,7 +36494,7 @@ A query cannot be cached if it contains one of the functions: @multitable @columnfractions .25 .25 .25 .25 @item @strong{Function} @tab @strong{Function} @tab @strong{Function} @tab @strong{Function} -@item @code{User Defined Functions} @tab @code{CONNECTION_ID} +@item @code{User-Defined Functions} @tab @code{CONNECTION_ID} @tab @code{FOUND_ROWS} @tab @code{GET_LOCK} @item @code{RELEASE_LOCK} @tab @code{LOAD_FILE} @tab @code{MASTER_POS_WAIT} @tab @code{NOW} @@ -36523,7 +36528,7 @@ tables. If this is not the case, the cached result will not be used. The query cache adds a few @code{MySQL} system variables for @code{mysqld} which may be set in a configuration file, on the -command line when starting @code{mysqld}. +command-line when starting @code{mysqld}. @itemize @item @code{query_cache_limit} @@ -36731,13 +36736,13 @@ The following is new in @code{MyISAM}: @itemize @bullet @item -There is a flag in the @code{MyISAM} file that indicates whether or not +There is a flag in the @code{MyISAM} file that indicates whether the table was closed correctly. If @code{mysqld} is started with @code{--myisam-recover}, @code{MyISAM} tables will automatically be checked and/or repaired on open if the table wasn't closed properly. @item You can @code{INSERT} new rows in a table that doesn't have free blocks -in the middle of the data file, at the same time other threads are +in the middle of the datafile, at the same time other threads are reading from the table (concurrent insert). An free block can come from an update of a dynamic length row with much data to a row with less data or when deleting rows. When all free blocks are used up, all future @@ -36754,7 +36759,7 @@ mainstream machines). The only area of machines that may not support binary compatibility are embedded systems (because they sometimes have peculiar processors). -There is no big speed penalty in storing data low byte first; The bytes +There is no big speed penalty in storing data low byte first; the bytes in a table row is normally unaligned and it doesn't take that much more power to read an unaligned byte in order than in reverse order. The actual fetch-column-value code is also not time critical compared to @@ -36810,7 +36815,7 @@ will be able to use in the near future: @itemize @bullet @item -Support for a true @code{VARCHAR} type; A @code{VARCHAR} column starts +Support for a true @code{VARCHAR} type; a @code{VARCHAR} column starts with a length stored in 2 bytes. @item Tables with @code{VARCHAR} may have fixed or dynamic record length. @@ -36826,7 +36831,7 @@ can't search on a @code{UNIQUE} computed index, however.) Note that index files are usually much smaller with @code{MyISAM} than with @code{ISAM}. This means that @code{MyISAM} will normally use less -system resources than @code{ISAM}, but will need more CPU when inserting +system resources than @code{ISAM}, but will need more CPU time when inserting data into a compressed index. The following options to @code{mysqld} can be used to change the behavior of @@ -36853,10 +36858,10 @@ count variable for the table is not 0 and you are running with The table is checked for errors. @item If we found an error, try to do a fast repair (with sorting and without -re-creating the data file) of the table. +re-creating the datafile) of the table. @item -If the repair fails because of an error in the data file (for example a -duplicate key error), we try again, but this time we re-create the data file. +If the repair fails because of an error in the datafile (for example a +duplicate key error), we try again, but this time we re-create the datafile. @item If the repair fails, retry once more with the old repair option method (write row by row without sorting) which should be able to repair any @@ -37207,7 +37212,7 @@ Many @code{mysqld} servers are using the table and one has done a @code{REPAIR} or @code{CHECK} of the table while it was in use by another server. In this setup the @code{CHECK} is safe to do (even if you will get the warning from other servers), but @code{REPAIR} should -be avoided as it currently replaces the data file with a new one, which +be avoided as it currently replaces the datafile with a new one, which is not signaled to the other servers. @end itemize @@ -37278,7 +37283,7 @@ If you have a set of tables that you join to a big table on demand or batch, you should instead create a @code{MERGE} table on them on demand. This is much faster and will save a lot of disk space. @item -Go around the file size limit for the operating system. +Go around the file-size limit for the operating system. @item You can create an alias/synonym for a table by just using MERGE over one table. There shouldn't be any really notable performance impacts of doing this @@ -37297,7 +37302,7 @@ You can only use identical @code{MyISAM} tables for a @code{MERGE} table. @item @code{MERGE} tables uses more file descriptors. If you are using a @strong{MERGE} that maps over 10 tables and 10 users are using this, you -are using 10*10 + 10 file descriptors. (10 data files for 10 users +are using 10*10 + 10 file descriptors. (10 datafiles for 10 users and 10 shared index files.) @item Key reads are slower. When you do a read on a key, the @code{MERGE} @@ -37599,7 +37604,7 @@ memory. InnoDB stores its tables and indexes in a tablespace, which may consist of several files. This is different from, for example, MyISAM tables where each table is stored as a separate file. InnoDB tables can be of any size also on those operating -systems where file size is limited to 2 GB. +systems where file-size is limited to 2 GB. You can find the latest information about InnoDB at @uref{http://www.innodb.com/}. The most up-to-date version of the @@ -37652,7 +37657,7 @@ innodb_data_file_path=ibdata:30M @end example but to get good performance it is best that you specify options -like recommended below in the section 'InnoDB startup options'. +as recommended. @xref{InnoDB start}. InnoDB is distributed under the GNU GPL License Version 2 (of June 1991). In the source distribution of MySQL, InnoDB appears as a subdirectory. @@ -37672,27 +37677,27 @@ At the minimum, in 3.23 you must specify @code{innodb_data_file_path}. In MySQL-4.0 you do not need to specify even @code{innodb_data_file_path}: the default for it is to create an auto-extending 16 MB file @file{ibdata1} to the @code{datadir} -of MySQL. (In MySQL-4.0.0 and 4.0.1 the data file is 64 MB and not +of MySQL. (In MySQL-4.0.0 and 4.0.1 the datafile is 64 MB and not auto-extending.) But to get good performance you MUST explicitly set the InnoDB parameters -listed below in the examples. +listed in the following examples. Starting from versions 3.23.50 and 4.0.2 InnoDB allows the last -data file on the @code{innodb_data_file_path} line +datafile on the @code{innodb_data_file_path} line to be specified as @strong{auto-extending}. The syntax for @code{innodb_data_file_path} is then the following: @example pathtodatafile:sizespecification;pathtodatafile:sizespecification;... ... ;pathtodatafile:sizespecification[:autoextend[:max:sizespecification]] @end example -If you specify the last data file with the autoextend option, InnoDB -will extend the last data file if it runs out of free space in the +If you specify the last datafile with the autoextend option, InnoDB +will extend the last datafile if it runs out of free space in the tablespace. The increment is 8 MB at a time. An example: @example innodb_data_file_path = /ibdata/ibdata1:100M:autoextend @end example -instructs InnoDB to create just a single data file whose initial size is +instructs InnoDB to create just a single datafile whose initial size is 100 MB and which is extended in 8 MB blocks when space runs out. If the disk becomes full you may want to add another data file to another disk, for example. Then you have to look the size @@ -37700,20 +37705,20 @@ of @file{ibdata1}, round the size downward to the closest multiple of 1024 * 1024 bytes (= 1 MB), and specify the rounded size of @file{ibdata1} explicitly in @code{innodb_data_file_path}. -After that you can add another data file: +After that you can add another datafile: @example innodb_data_file_path = /ibdata/ibdata1:988M;/disk2/ibdata2:50M:autoextend @end example -Be cautious on file systems where the maximum file size is 2 GB! -InnoDB is not aware of the OS maximum file size. On those file systems -you might want to specify the max size for the data file: +Be cautious on filesystems where the maximum file-size is 2 GB! +InnoDB is not aware of the OS maximum file-size. On those filesystems +you might want to specify the max size for the datafile: @example innodb_data_file_path = /ibdata/ibdata1:100M:autoextend:max:2000M @end example Suppose you have a Windows NT computer with 128 MB RAM and a single 10 GB hard disk. -Below is an example of possible configuration parameters in +Following is an example of possible configuration parameters in @file{my.cnf} or @file{my.ini} for InnoDB: @example @@ -37722,7 +37727,7 @@ Below is an example of possible configuration parameters in # ... # innodb_data_home_dir = c:\ibdata -# Data files must be able to +# Datafiles must be able to # hold your data and indexes innodb_data_file_path = ibdata1:2000M;ibdata2:2000M # Set buffer pool size to 50 - 80 % @@ -37735,7 +37740,7 @@ innodb_log_group_home_dir = c:\iblogs innodb_log_arch_dir = c:\iblogs innodb_log_archive=0 set-variable = innodb_log_files_in_group=3 -# Set the log file size to about +# Set the log file-size to about # 15 % of the buffer pool size set-variable = innodb_log_file_size=10M set-variable = innodb_log_buffer_size=8M @@ -37754,13 +37759,13 @@ the data and log group home directories. Check also that the MySQL server has @strong{the rights to create files} in the directories you specify. -Note that data files must be < 2G in -some file systems! The combined size of data files +Note that datafiles must be < 2G in +some filesystems! The combined size of datafiles must be >= 10 MB. The combined size of the log files must be < 4G. If you do not specify @code{innodb_data_home_dir}, then -the default is that InnoDB creates its data files to the +the default is that InnoDB creates its datafiles to the @code{datadir} of MySQL. Then you cannot use absolute file paths in @code{innodb_data_file_path}. @@ -37773,8 +37778,8 @@ For example, in Windows you can start @file{mysqld-max.exe} with: @example your-path-to-mysqld>mysqld-max --standalone --console @end example -See the manual section `Creating an InnoDB database' about what -the printout should look like. +For information about what the printout should look like, +see @ref{InnoDB init}. @strong{Where to put @file{my.cnf} or @file{my.ini} in Windows?} The rules for Windows are the following: @@ -37812,7 +37817,7 @@ option to the server: Suppose you have a Linux computer with 512 MB RAM and three 20 GB hard disks (at directory paths @file{`/'}, @file{`/dr2'} and @file{`/dr3'}). -Below is an example of possible configuration parameters +Here is an example of possible configuration parameters in @file{my.cnf} for InnoDB: @@ -37822,7 +37827,7 @@ InnoDB: # ... # innodb_data_home_dir = / -# Data files must be able to +# Datafiles must be able to # hold your data and indexes innodb_data_file_path = ibdata/ibdata1:2000M;dr2/ibdata/ibdata2:2000M # Set buffer pool size to 50 - 80 % @@ -37837,7 +37842,7 @@ innodb_log_group_home_dir = /dr3/iblogs innodb_log_arch_dir = /dr3/iblogs innodb_log_archive=0 set-variable = innodb_log_files_in_group=3 -# Set the log file size to about +# Set the log file-size to about # 15 % of the buffer pool size set-variable = innodb_log_file_size=50M set-variable = innodb_log_buffer_size=8M @@ -37852,22 +37857,22 @@ set-variable = innodb_lock_wait_timeout=50 #set-variable = innodb_thread_concurrency=5 @end example -Note that we have placed the two data files on different disks. +Note that we have placed the two datafiles on different disks. The reason for the name @code{innodb_data_file_path} is that -you can also specify paths to your data files, and +you can also specify paths to your datafiles, and @code{innodb_data_home_dir} is just textually catenated -before your data file paths, adding a possible slash or +before your datafile paths, adding a possible slash or backslash in between. InnoDB will fill the tablespace -formed by the data files from bottom up. In some cases it will +formed by the datafiles from bottom up. In some cases it will improve the performance of the database if all data is not placed on the same physical disk. Putting log files on a different disk from data is very often beneficial for performance. You can also use @strong{raw disk partitions} (raw devices) -as data files. In some Unixes +as datafiles. In some Unixes they speed up I/O. See the manual section on InnoDB file space management about how to specify them in @file{my.cnf}. -@strong{Warning:} on Linux x86 you must be careful you @strong{do not set memory usage +@strong{Warning}: on Linux x86 you must be careful you @strong{do not set memory usage too high}. glibc will allow the process heap to grow over thread stacks, which will crash your server. It is a risk if the value of @example @@ -37905,16 +37910,16 @@ The meanings of the configuration parameters are the following: @multitable @columnfractions .35 .65 @item @strong{Option} @tab @strong{Description} @item @code{innodb_data_home_dir} @tab -The common part of the directory path for all InnoDB data files. +The common part of the directory path for all InnoDB datafiles. The default for this parameter is the @code{datadir} of MySQL. @item @code{innodb_data_file_path} @tab -Paths to individual data files and their sizes. The full directory path -to each data file is acquired by concatenating innodb_data_home_dir to -the paths specified here. The file sizes are specified in megabytes, +Paths to individual datafiles and their sizes. The full directory path +to each datafile is acquired by concatenating innodb_data_home_dir to +the paths specified here. The file-sizes are specified in megabytes, hence the 'M' after the size specification above. InnoDB also understands the abbreviation 'G', 1G meaning 1024M. Starting from -3.23.44 you can set the file size bigger than 4 GB on those +3.23.44 you can set the file-size bigger than 4 GB on those operating systems which support big files. On some operating systems files must be < 2 GB. The sum of the sizes of the files must be at least 10 MB. @@ -37993,22 +37998,22 @@ Another option is @code{O_DSYNC}. Suppose you have installed MySQL and have edited @file{my.cnf} so that it contains the necessary InnoDB configuration parameters. Before starting MySQL you should check that the directories you have -specified for InnoDB data files and log files exist and that you have +specified for InnoDB datafiles and log files exist and that you have access rights to those directories. InnoDB cannot create directories, only files. Check also you have enough disk space for the data and log files. -When you now start MySQL, InnoDB will start creating your data files +When you now start MySQL, InnoDB will start creating your datafiles and log files. InnoDB will print something like the following: @example ~/mysqlm/sql > mysqld -InnoDB: The first specified data file /home/heikki/data/ibdata1 +InnoDB: The first specified datafile /home/heikki/data/ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file /home/heikki/data/ibdata1 size to 134217728 InnoDB: Database physically writes the file full: wait... -InnoDB: Data file /home/heikki/data/ibdata2 did not exist: +InnoDB: datafile /home/heikki/data/ibdata2 did not exist: new to be created InnoDB: Setting file /home/heikki/data/ibdata2 size to 262144000 InnoDB: Database physically writes the file full: wait... @@ -38037,7 +38042,7 @@ InnoDB: Starting shutdown... InnoDB: Shutdown completed @end example -You can now look at the data files and logs directories and you +You can now look at the datafiles and logs directories and you will see the files created. The log directory will also contain a small file named @file{ib_arch_log_0000000000}. That file resulted from the database creation, after which InnoDB switched off @@ -38068,14 +38073,14 @@ directories. @item @file{mysqld} does not read the right @file{my.cnf} or @file{my.ini} file, and consequently does not see the options you specified. @item The disk is full or a disk quota is exceeded. -@item You have created a subdirectory whose name is equal to a data file +@item You have created a subdirectory whose name is equal to a datafile you specified. @item There is a syntax error in @code{innodb_data_home_dir} or @code{innodb_data_file_path}. @end itemize If something goes wrong in an InnoDB database creation, you should -delete all files created by InnoDB. This means all data files, all log +delete all files created by InnoDB. This means all datafiles, all log files, the small archived log file, and in the case you already did create some InnoDB tables, delete also the corresponding @file{.frm} files for these tables from the MySQL database @@ -38095,7 +38100,7 @@ CREATE TABLE CUSTOMER (A INT, B CHAR (20), INDEX (A)) TYPE = InnoDB; @end example This SQL command will create a table and an index on column @code{A} -into the InnoDB tablespace consisting of the data files you specified +into the InnoDB tablespace consisting of the datafiles you specified in @file{my.cnf}. In addition MySQL will create a file @file{CUSTOMER.frm} to the MySQL database directory @file{test}. Internally, InnoDB will add to its own data dictionary an entry @@ -38281,13 +38286,13 @@ or other special options on the constraints. @node Adding and removing, Backing up, Using InnoDB tables, InnoDB @subsection Adding and Removing InnoDB Data and Log Files -You cannot increase the size of an InnoDB data file. To add more into -your tablespace you have to add a new data file. To do this you have to +You cannot increase the size of an InnoDB datafile. To add more into +your tablespace you have to add a new datafile. To do this you have to shut down your MySQL database, edit the @file{my.cnf} file, adding a new file to @code{innodb_data_file_path}, and then start MySQL again. -Currently you cannot remove a data file from InnoDB. To decrease the +Currently you cannot remove a datafile from InnoDB. To decrease the size of your database you have to use @file{mysqldump} to dump all your tables, create a new database, and import your tables to the new database. @@ -38323,7 +38328,7 @@ a 'binary' backup of your database you have to do the following: @item Shut down your MySQL database and make sure it shuts down without errors. @item -Copy all your data files into a safe place. +Copy all your datafiles into a safe place. @item Copy all your InnoDB log files to a safe place. @item @@ -38333,7 +38338,7 @@ Copy all the @file{.frm} files for your InnoDB tables into a safe place. @end itemize -There is currently no on-line or incremental backup tool available for +There is currently no online or incremental backup tool available for InnoDB, though they are in the TODO list. In addition to taking the binary backups described above, @@ -38436,14 +38441,14 @@ because there will be more log to apply to the database. @subsection Moving an InnoDB Database to Another Machine InnoDB data and log files are binary-compatible on all platforms -if the floating point number format on the machines is the same. +if the floating-point number format on the machines is the same. You can move an InnoDB database simply by copying all the relevant files, which we already listed in the previous section on backing up -a database. If the floating point formats on the machines are +a database. If the floating-point formats on the machines are different but you have not used @code{FLOAT} or @code{DOUBLE} data types in your tables then the procedure is the same: just copy the relevant files. If the formats are different and your tables -contain floating point data, you have to use @file{mysqldump} +contain floating-point data, you have to use @file{mysqldump} and @file{mysqlimport} to move those tables. A performance tip is to switch off the auto commit when you import @@ -38678,11 +38683,12 @@ constraint fails, InnoDB sets these locks. @code{LOCK TABLES ... } : sets table locks. In the implementation the MySQL layer of code sets these locks. The automatic deadlock detection of InnoDB cannot detect deadlocks where such table locks are involved: -see the next section below. See also section 13 'InnoDB restrictions' -about the following: since MySQL does know about row level locks, +see the following section. +Also, since MySQL does know about row level locks, it is possible that you get a table lock on a table where another user currently has row level locks. But that does not put transaction integerity into danger. +@xref{InnoDB restrictions}. @end itemize @@ -38996,7 +39002,7 @@ that the workload is disk I/O-bound. @item Section BUFFER POOL gives you statistics on pages read and written. You can calculate from these -numbers how many data file I/Os your queries are +numbers how many datafile I/Os your queries are currently doing. @end itemize @@ -39257,19 +39263,19 @@ It adds safety to crash recovery after an operating system crash or a power outage, and improves performance on most Unix flavors by reducing the need for fsync operations. -Doublewrite means that InnoDB before writing pages to a data file +Doublewrite means that InnoDB before writing pages to a datafile first writes them to a contiguous tablespace area called the doublewrite buffer. Only after the write and the flush to the doublewrite buffer has completed, InnoDB writes the pages to their proper -positions in the data file. If the operating system crashes in the +positions in the datafile. If the operating system crashes in the middle of a page write, InnoDB will in recovery find a good copy of the page from the doublewrite buffer. Starting from 3.23.41 -you can also use a raw disk partition as a data file, though this has -not been tested yet. When you create a new data file you have +you can also use a raw disk partition as a datafile, though this has +not been tested yet. When you create a new datafile you have to put the keyword @code{newraw} immediately after the data -file size in @code{innodb_data_file_path}. The partition must be +file-size in @code{innodb_data_file_path}. The partition must be >= than you specify as the size. Note that 1M in InnoDB is 1024 x 1024 bytes, while in disk specifications 1 MB usually means 1000 000 bytes. @@ -39279,7 +39285,7 @@ innodb_data_file_path=hdd1:5Gnewraw;hdd2:2Gnewraw @end example When you start the database again you @strong{must} change the keyword -to @code{raw}. Otherwise InnoDB will write over your +to @code{raw}. Otherwise, InnoDB will write over your partition! @example @@ -39301,7 +39307,7 @@ reads to the I/O system. @node InnoDB File space, InnoDB File Defragmenting, InnoDB Disk I/O, File space management @subsubsection File Space Management -The data files you define in the configuration file form the tablespace +The datafiles you define in the configuration file form the tablespace of InnoDB. The files are simply catenated to form the tablespace, there is no striping in use. Currently you cannot directly instruct where the space is allocated @@ -39331,10 +39337,9 @@ allocated to segments as a whole, but only as individual pages. When you issue a query @code{SHOW TABLE STATUS FROM ... LIKE ...} to ask for available free space in the tablespace, InnoDB will -report you the space which is certainly usable in totally free extents -of the tablespace. InnoDB always reserves some extents for -clean-up and other internal purposes; these reserved extents are not -included in the free space. +report the extents which are definitely free in the tablespace. +InnoDB always reserves some extents for clean-up and other internal +purposes; these reserved extents are not included in the free space. When you delete data from a table, InnoDB will contract the corresponding B-tree indexes. It depends on the pattern of deletes if that frees @@ -39409,8 +39414,8 @@ they roll back the corresponding SQL statement. @itemize @bullet @item -@strong{WARNING:} Do @strong{NOT} convert MySQL system tables from -MyISAM TO InnoDB tables! This is not supported; If you do this MySQL +@strong{Warning}: do @strong{NOT} convert MySQL system tables from +MyISAM TO InnoDB tables! This is not supported; if you do this MySQL will not restart until you restore the old system tables from a backup or re-generate them with the mysql_install_db script. @@ -39462,7 +39467,7 @@ pages. After InnoDB has modified the row by storing long fields on separate pages, the remaining length of the row must be less than half a database page. The maximun key length is 7000 bytes. @item -On some operating systems data files must be < 2 GB. The combined +On some operating systems datafiles must be < 2 GB. The combined size of log files must be < 4 GB on 32-bit computers. @item The maximum tablespace size is 4 billion database pages. This is also @@ -39658,7 +39663,7 @@ Internal locking in @code{BDB} tables is done on page level. maintain a count of the number of rows in the table. @item Scanning is slower than with @code{MyISAM} tables as one has data in BDB -tables stored in B-trees and not in a separate data file. +tables stored in B-trees and not in a separate datafile. @item The application must always be prepared to handle cases where any change of a @code{BDB} table may make an automatic rollback and any @@ -39697,8 +39702,8 @@ wait for enough free disk before continuing. @itemize @bullet @item It's very slow to open many BDB tables at the same time. If you are -going to use BDB tables, you should not have a very big table cache (> -256 ?) and you should use @code{--no-auto-rehash} with the @code{mysql} +going to use BDB tables, you should not have a very big table cache +(like >256) and you should use @code{--no-auto-rehash} with the @code{mysql} client. We plan to partly fix this in 4.0. @item @code{SHOW TABLE STATUS} doesn't yet provide that much information for BDB @@ -39724,8 +39729,8 @@ Can't init dtabases This means that @code{BDB} tables are not supported for your architecture. In this case you have to rebuild MySQL without BDB table support. -NOTE: The following list is not complete; We will update this as we get -more information about this. +Note: The following list is not complete; we will update it as we +receive more information about this. Currently we know that BDB tables works with the following operating system. @@ -39758,7 +39763,7 @@ Here follows the restrictions you have when using BDB tables: @itemize @bullet @item BDB tables store in the .db file the path to the file as it was created -(My guess is that this is to be able to detect locks in a multi-user +This was done to be able to detect locks in a multi-user environment that supports symlinks). The effect of this is that BDB tables are not movable between directories! @@ -39840,9 +39845,9 @@ other APIs. @cindex PHP API PHP is a server-side, HTML-embedded scripting language that may be used to -create dynamic Web pages. It contains support for accessing several +create dynamic web pages. It contains support for accessing several databases, including MySQL. PHP may be run as a separate program -or compiled as a module for use with the Apache Web server. +or compiled as a module for use with the Apache web server. The distribution and documentation are available at the PHP web site (@uref{http://www.php.net/}). @@ -39856,7 +39861,7 @@ The distribution and documentation are available at the PHP web site @itemize @bullet @item Error: "Maximum Execution Time Exceeded" -This is a PHP limit; Go into the @file{php3.ini} file and set the maximum +This is a PHP limit; go into the @file{php3.ini} file and set the maximum execution time up from 30 seconds to something higher, as needed. It is also not a bad idea to double the ram allowed per script to 16MB instead of 8 MB. @@ -39901,7 +39906,7 @@ without change. You need a DataBase Driver (DBD) defined for each database type. For MySQL, this driver is called @code{DBD::mysql}. -For more information on the Perl5 DBI, please visit the @code{DBI} Web +For more information on the Perl5 DBI, please visit the @code{DBI} web page and read the documentation: @example @uref{http://www.symbolstone.org/technology/perl/DBI/} @@ -40088,7 +40093,7 @@ affected. If no rows are affected, @code{execute} returns @code{"0E0"}, which Perl treats as zero but regards as true. If an error occurs, @code{execute} returns @code{undef}. For @code{SELECT} statements, @code{execute} only starts the SQL query in the database; you need to use one -of the @code{fetch_*} methods described below to retrieve the data. +of the @code{fetch_*} methods described here to retrieve the data. Example: @example $rv = $sth->execute @@ -40253,7 +40258,7 @@ handle (and any future children of the handle). Setting @code{$trace_level} to 2 provides detailed trace information. Setting @code{$trace_level} to 0 disables tracing. Trace output goes to the standard error output by default. If @code{$trace_filename} is specified, the file is opened in -append mode and output for @emph{all} traced handles is written to that +append mode and output for @strong{all} traced handles is written to that file. Example: @example DBI->trace(2); # trace everything @@ -40275,11 +40280,11 @@ environment variable. Setting it to a numeric value is equivalent to calling @noindent @strong{MySQL-specific Methods} -The methods shown below are MySQL-specific and not part of the +The methods shown here are MySQL-specific and not part of the @code{DBI} standard. Several of them are now deprecated: @code{is_blob}, @code{is_key}, @code{is_num}, @code{is_pri_key}, @code{is_not_null}, @code{length}, @code{max_length}, and @code{table}. -Where @code{DBI}-standard alternatives exist, they are noted below: +Where @code{DBI}-standard alternatives exist, they are noted here: @table @code @findex DBI->@{insertid@} @@ -40416,7 +40421,7 @@ You can also use the @code{pod2man}, @code{pod2html}, etc., tools to translate to other formats. You can find the latest @code{DBI} information at -the @code{DBI} Web page: +the @code{DBI} web page: @example @uref{http://www.symbolstone.org/technology/perl/DBI/} @end example @@ -40434,48 +40439,48 @@ the @code{DBI} Web page: * ODBC administrator:: How to fill in the various fields in the ODBC administrator program * MyODBC connect parameters:: Connect parameters for MyODBC * ODBC Problems:: How to report problems with MySQL ODBC -* MyODBC clients:: Programs known to work with @strong{MyODBC} +* MyODBC clients:: Programs known to work with @code{MyODBC} * ODBC and last_insert_id:: How to get the value of an @code{AUTO_INCREMENT} column in ODBC * MyODBC bug report:: Reporting problems with MyODBC @end menu -MySQL provides support for ODBC by means of the @strong{MyODBC} -program. This chapter will teach you how to install @strong{MyODBC}, +MySQL provides support for ODBC by means of the @code{MyODBC} +program. This chapter will teach you how to install @code{MyODBC}, and how to use it. Here, you will also find a list of common programs that -are known to work with @strong{MyODBC}. +are known to work with @code{MyODBC}. @node Installing MyODBC, ODBC administrator, ODBC, ODBC @subsection How To Install MyODBC -@strong{MyODBC} is a 32-bit ODBC (2.50) level 0 (with level 1 and +@code{MyODBC} is a 32-bit ODBC (2.50) level 0 (with level 1 and level 2 features) driver for connecting an ODBC-aware application -to MySQL. @strong{MyODBC} works on Windows 9x/Me/NT/2000/XP +to MySQL. @code{MyODBC} works on Windows 9x/Me/NT/2000/XP and most Unix platforms. -@strong{MyODBC} is in public domain, and you can find the newest +@code{MyODBC} is in public domain, and you can find the newest version at @uref{http://www.mysql.com/downloads/api-myodbc.html}. -If you have problem with @strong{MyODBC} and your program also works +If you have problem with @code{MyODBC} and your program also works with OLEDB, you should try the OLEDB driver. -Normally you only need to install @strong{MyODBC} on Windows machines. -You only need @strong{MyODBC} for Unix if you have a program like +Normally you only need to install @code{MyODBC} on Windows machines. +You only need @code{MyODBC} for Unix if you have a program like ColdFusion that is running on the Unix machine and uses ODBC to connect to the databases. -If you want to install @strong{MyODBC} on a Unix box, you will also need -an @strong{ODBC} manager. @strong{MyODBC} is known to work with +If you want to install @code{MyODBC} on a Unix box, you will also need +an @code{ODBC} manager. @code{MyODBC} is known to work with most of the Unix ODBC managers. @xref{Portals}. -To install @strong{MyODBC} on Windows, you should download the -appropriate @strong{MyODBC} @file{.zip} file, +To install @code{MyODBC} on Windows, you should download the +appropriate @code{MyODBC} @file{.zip} file, unpack it with @code{WinZIP} or some similar program, and execute the @file{SETUP.EXE} file. On Windows/NT/XP you may get the following error when trying to install -@strong{MyODBC}: +@code{MyODBC}: @example An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart @@ -40490,14 +40495,14 @@ cases you can continue by just pressing @code{Ignore} to copy the rest of the MyODBC files and the final installation should still work. If this doesn't work, the solution is to reboot your computer in ``safe mode`` (Choose this by pressing F8 just before your machine starts -Windows during rebooting), install @strong{MyODBC}, and reboot to normal +Windows during rebooting), install @code{MyODBC}, and reboot to normal mode. @itemize @bullet @item To make a connection to a Unix box from a Windows box, with an ODBC application (one that doesn't support MySQL natively), you must -first install @strong{MyODBC} on the Windows machine. +first install @code{MyODBC} on the Windows machine. @item The user and Windows machine must have the access privileges to the MySQL server on the Unix machine. This is set up with the @@ -40509,7 +40514,7 @@ You must create an ODBC DSN entry as follows: @item Open the Control Panel on the Windows machine. @item -Double-click the ODBC Data Sources 32 bits icon. +Double-click the ODBC Data Sources 32-bit icon. @item Click the tab User DSN. @item @@ -40592,8 +40597,8 @@ You can use all options that are usable by @code{mysql_options()}. @node MyODBC connect parameters, ODBC Problems, ODBC administrator, ODBC @subsection Connect parameters for MyODBC -One can specify the following parameters for @strong{MyODBC} on -the @code{[Servername]} section of an @code{ODBC.INI} file or +One can specify the following parameters for @code{MyODBC} on +the @code{[Servername]} section of an @file{ODBC.INI} file or through the @code{InConnectionString} argument in the @code{SQLDriverConnect()} call. @@ -40602,22 +40607,22 @@ through the @code{InConnectionString} argument in the @item user @tab ODBC (on Windows) @tab The username used to connect to MySQL. @item server @tab localhost @tab The hostname of the MySQL server. @item database @tab @tab The default database -@item option @tab 0 @tab A integer by which you can specify how @strong{MyODBC} should work. See below. +@item option @tab 0 @tab A integer by which you can specify how @code{MyODBC} should work. See below. @item port @tab 3306 @tab The TCP/IP port to use if @code{server} is not @code{localhost}. @item stmt @tab @tab A statement that will be executed when connection to @code{MySQL}. @item password @tab @tab The password for the @code{server} @code{user} combination. @item socket @tab @tab The socket or Windows pipe to connect to. @end multitable -The option argument is used to tell @strong{MyODBC} that the client isn't 100% +The option argument is used to tell @code{MyODBC} that the client isn't 100% ODBC compliant. On Windows, one normally sets the option flag by toggling the different options on the connection screen but one can also set this in the opton argument. The following options are listed in the -same order as they appear in the @strong{MyODBC} connect screen: +same order as they appear in the @code{MyODBC} connect screen: @multitable @columnfractions .10 .90 @item @strong{Bit} @tab @strong{Description} -@item 1 @tab The client can't handle that @strong{MyODBC} returns the real width of a column. +@item 1 @tab The client can't handle that @code{MyODBC} returns the real width of a column. @item 2 @tab The client can't handle that MySQL returns the true value of affected rows. If this flag is set then MySQL returns 'found rows' instead. One must have MySQL 3.21.14 or newer to get this to work. @item 4 @tab Make a debug log in c:\myodbc.log. This is the same as putting @code{MYSQL_DEBUG=d:t:O,c::\myodbc.log} in @file{AUTOEXEC.BAT} @item 8 @tab Don't set any packet limit for results and parameters. @@ -40642,22 +40647,22 @@ example setting option to 12 (4+8) gives you debugging without package limits! The default @file{MYODBC.DLL} is compiled for optimal performance. If -you want to to debug @strong{MyODBC} (for example to enable tracing), -you should instead use @code{MYODBCD.DLL}. To install this file, copy -@file{MYODBCD.DLL} over the installed @code{MYODBC.DLL} file. +you want to to debug @code{MyODBC} (for example to enable tracing), +you should instead use @file{MYODBCD.DLL}. To install this file, copy +@file{MYODBCD.DLL} over the installed @file{MYODBC.DLL} file. @node ODBC Problems, MyODBC clients, MyODBC connect parameters, ODBC @subsection How to Report Problems with MyODBC -@strong{MyODBC} has been tested with Access, Admndemo.exe, C++-Builder, +@code{MyODBC} has been tested with Access, Admndemo.exe, C++-Builder, Borland Builder 4, Centura Team Developer (formerly Gupta SQL/Windows), ColdFusion (on Solaris and NT with svc pack 5), Crystal Reports, DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro, FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox, Powerbuilder, Powerdesigner 32 bit, VC++, and Visual Basic. -If you know of any other applications that work with @strong{MyODBC}, please +If you know of any other applications that work with @code{MyODBC}, please send mail to @email{myodbc@@lists.mysql.com} about this! With some programs you may get an error like: @@ -40681,8 +40686,8 @@ try to figure out why things go wrong. @node MyODBC clients, ODBC and last_insert_id, ODBC Problems, ODBC @subsection Programs Known to Work with MyODBC -Most programs should work with @strong{MyODBC}, but for each of those -listed below, we have tested it ourselves or received confirmation from +Most programs should work with @code{MyODBC}, but for each of those +listed here, we have tested it ourselves or received confirmation from some user that it works: @table @asis @@ -40771,12 +40776,12 @@ This will give you problems if you have values > 127 in the column! @cindex ADO program @item ADO -When you are coding with the ADO API and @strong{MyODBC} you need to put +When you are coding with the ADO API and @code{MyODBC} you need to put attention in some default properties that aren't supported by the MySQL server. For example, using the @code{CursorLocation Property} as @code{adUseServer} will return for the @code{RecordCount Property} a result of -1. To have the right value, you need to set this -property to @code{adUseClient}, like is showing in the VB code below: +property to @code{adUseClient}, like is showing in the VB code here: @example Dim myconn As New ADODB.Connection @@ -40816,10 +40821,10 @@ your tables are big! The following information is taken from the ColdFusion documentation: Use the following information to configure ColdFusion Server for Linux -to use the unixODBC driver with @strong{MyODBC} for MySQL data -sources. Allaire has verified that @strong{MyODBC} Version 2.50.26 +to use the unixODBC driver with @code{MyODBC} for MySQL data +sources. Allaire has verified that @code{MyODBC} Version 2.50.26 works with MySQL Version 3.22.27 and ColdFusion for Linux. (Any -newer version should also work.) You can download @strong{MyODBC} at +newer version should also work.) You can download @code{MyODBC} at @uref{http://www.mysql.com/downloads/api-myodbc.html} @cindex ColdFusion program @@ -40827,7 +40832,7 @@ ColdFusion Version 4.5.1 allows you to us the ColdFusion Administrator to add the MySQL data source. However, the driver is not included with ColdFusion Version 4.5.1. Before the MySQL driver will appear in the ODBC datasources drop-down list, you must build and -copy the @strong{MyODBC} driver to +copy the @code{MyODBC} driver to @file{/opt/coldfusion/lib/libmyodbc.so}. The Contrib directory contains the program @file{mydsn-xxx.zip} which allows @@ -40873,7 +40878,7 @@ For example, create a db with a table containing 2 columns of text: @item Insert rows using the @code{mysql} client command-line tool. @item -Create a DSN file using the MyODBC driver, for example, my for the db above. +Create a DSN file using the ODBC manager, for example, @file{my} for the db above. @item Open the Word application. @item @@ -40913,7 +40918,7 @@ You must use BDE Version 3.2 or newer. Set the @code{Don't optimize column widt option field when connecting to MySQL. Also, here is some potentially useful Delphi code that sets up both an -ODBC entry and a BDE entry for @strong{MyODBC} (the BDE entry requires a BDE +ODBC entry and a BDE entry for @code{MyODBC} (the BDE entry requires a BDE Alias Editor that is free at a Delphi Super Page near you. (Thanks to Bryan Brunton @email{bryan@@flesherfab.com} for this): @@ -41022,28 +41027,28 @@ SELECT * FROM tbl_name WHERE auto IS NULL; @cindex problems, ODBC @cindex MyODBC, reporting problems -If you encounter difficulties with @strong{MyODBC}, you should start by +If you encounter difficulties with @code{MyODBC}, you should start by making a log file from the ODBC manager (the log you get when requesting -logs from ODBCADMIN) and a @strong{MyODBC} log. +logs from ODBCADMIN) and a @code{MyODBC} log. -To get a @strong{MyODBC} log, you need to do the following: +To get a @code{MyODBC} log, you need to do the following: @enumerate @item -Ensure that you are using @code{myodbcd.dll} and not @code{myodbc.dll}. -The easiest way to do this is to get @code{myodbcd.dll} from the MyODBC -distribution and copy it over the @code{myodbc.dll}, which is probably -in your @code{C:\windows\system32} or @code{C:\winnt\system32} directory. +Ensure that you are using @file{myodbcd.dll} and not @file{myodbc.dll}. +The easiest way to do this is to get @file{myodbcd.dll} from the MyODBC +distribution and copy it over the @file{myodbc.dll}, which is probably +in your @file{C:\windows\system32} or @file{C:\winnt\system32} directory. Note that you probably want to restore the old myodbc.dll file when you -have finished testing, as this is a lot faster than @code{myodbcd.dll}. +have finished testing, as this is a lot faster than @file{myodbcd.dll}. @item -Tag the `Trace MyODBC' option flag in the @strong{MyODBC} connect/configure +Tag the `Trace MyODBC' option flag in the @code{MyODBC} connect/configure screen. The log will be written to file @file{C:\myodbc.log}. If the trace option is not remembered when you are going back to the above screen, it means that you are not using the @code{myodbcd.dll} -driver (see above). +driver (see the item above). @item Start your application and try to get it to fail. @end enumerate @@ -41164,7 +41169,7 @@ values may contain null bytes internally.) Rows are obtained by calling @tindex MYSQL_FIELD C type @item MYSQL_FIELD This structure contains information about a field, such as the field's -name, type, and size. Its members are described in more detail below. +name, type, and size. Its members are described in more detail here. You may obtain the @code{MYSQL_FIELD} structures for each field by calling @code{mysql_fetch_field()} repeatedly. Field values are not part of this structure; they are contained in a @code{MYSQL_ROW} structure. @@ -41192,7 +41197,7 @@ printf (Number of rows: %lu\n", (unsigned long) mysql_num_rows(result)); @end table @noindent -The @code{MYSQL_FIELD} structure contains the members listed below: +The @code{MYSQL_FIELD} structure contains the members listed here: @table @code @item char * name @@ -41233,7 +41238,7 @@ The @code{type} value may be one of the following: @item @code{FIELD_TYPE_CHAR} @tab Deprecated; use @code{FIELD_TYPE_TINY} instead @end multitable -You can use the @code{IS_NUM()} macro to test whether or not a field has a +You can use the @code{IS_NUM()} macro to test whether a field has a numeric type. Pass the @code{type} value to @code{IS_NUM()} and it will evaluate to TRUE if the field is numeric: @@ -41280,7 +41285,7 @@ a field rather than an attribute of its type. It is preferable to test @code{FIELD_TYPE_SET}, or @code{FIELD_TYPE_TIMESTAMP} instead. @noindent -The example below illustrates a typical use of the @code{flags} value: +The following example illustrates a typical use of the @code{flags} value: @example if (field->flags & NOT_NULL_FLAG) @@ -41308,8 +41313,8 @@ The number of decimals for numeric fields. @cindex C API, functions @cindex functions, C API -The functions available in the C API are listed below and are described in -greater detail in the next section. +The functions available in the C API are listed here and are described in +greater detail in a later section. @xref{C API functions}. @multitable @columnfractions .32 .68 @@ -41350,7 +41355,7 @@ Drops a database. This function is deprecated; use the SQL command Makes the server write debug information to the log. @item @strong{mysql_eof()} @tab -Determines whether or not the last row of a result set has been read. +Determines whether the last row of a result set has been read. This function is deprecated; @code{mysql_errno()} or @code{mysql_error()} may be used instead. @@ -41438,7 +41443,7 @@ Returns the number of rows in a result set. Sets connect options for @code{mysql_connect()}. @item @strong{mysql_ping()} @tab -Checks whether or not the connection to the server is working, reconnecting +Checks whether the connection to the server is working, reconnecting as necessary. @item @strong{mysql_query()} @tab @@ -41551,7 +41556,7 @@ faster). Disadvantages are that you must process each row quickly to avoid tying up the server, you don't have random access to rows within the result set (you can only access rows sequentially), and you don't know how many rows are in the result set until you have retrieved them all. Furthermore, you -@emph{must} retrieve all the rows even if you determine in mid-retrieval that +@strong{must} retrieve all the rows even if you determine in mid-retrieval that you've found the information you were looking for. The API makes it possible for clients to respond appropriately to @@ -41560,7 +41565,7 @@ not the query is a @code{SELECT}. You can do this by calling @code{mysql_store_result()} after each @code{mysql_query()} (or @code{mysql_real_query()}). If the result set call succeeds, the query was a @code{SELECT} and you can read the rows. If the result set call -fails, call @code{mysql_field_count()} to determine whether or not a +fails, call @code{mysql_field_count()} to determine whether a result was actually to be expected. If @code{mysql_field_count()} returns zero, the query returned no data (indicating that it was an @code{INSERT}, @code{UPDATE}, @code{DELETE}, etc.), and was not @@ -41644,7 +41649,7 @@ when an error occurred and what it was. * mysql_use_result:: @code{mysql_use_result()} @end menu -In the descriptions below, a parameter or return value of @code{NULL} means +In the descriptions here, a parameter or return value of @code{NULL} means @code{NULL} in the sense of the C programming language, not a MySQL @code{NULL} value. @@ -41951,7 +41956,7 @@ None. @subsubheading Example -The call shown below causes the client library to generate a trace file in +The call shown here causes the client library to generate a trace file in @file{/tmp/client.trace} on the client machine: @example @@ -42040,7 +42045,7 @@ An unknown error occurred. This function is deprecated. @code{mysql_errno()} or @code{mysql_error()} may be used instead. -@code{mysql_eof()} determines whether or not the last row of a result +@code{mysql_eof()} determines whether the last row of a result set has been read. If you acquire a result set from a successful call to @@ -42322,7 +42327,7 @@ for(i = 0; i < num_fields; i++) Returns the lengths of the columns of the current row within a result set. If you plan to copy field values, this length information is also useful for optimisation, because you can avoid calling @code{strlen()}. In addition, if -the result set contains binary data, you @emph{must} use this function to +the result set contains binary data, you @strong{must} use this function to determine the size of the data, because @code{strlen()} returns incorrect results for any field containing null characters. @@ -42387,7 +42392,7 @@ The lengths of the field values in the row may be obtained by calling @code{mysql_fetch_lengths()}. Empty fields and fields containing @code{NULL} both have length 0; you can distinguish these by checking the pointer for the field value. If the pointer is @code{NULL}, the field -is @code{NULL}; otherwise the field is empty. +is @code{NULL}; otherwise, the field is empty. @subsubheading Return Values @@ -42441,10 +42446,10 @@ Returns the number of columns for the most recent query on the connection. The normal use of this function is when @code{mysql_store_result()} returned @code{NULL} (and thus you have no result set pointer). In this case, you can call @code{mysql_field_count()} to -determine whether or not @code{mysql_store_result()} should have produced a +determine whether @code{mysql_store_result()} should have produced a non-empty result. This allows the client program to take proper action -without knowing whether or not the query was a @code{SELECT} (or -@code{SELECT}-like) statement. The example shown below illustrates how this +without knowing whether the query was a @code{SELECT} (or +@code{SELECT}-like) statement. The example shown here illustrates how this may be done. @xref{NULL mysql_store_result, , @code{NULL mysql_store_result()}}. @@ -42494,7 +42499,7 @@ else // query succeeded, process any data returned by it An alternative is to replace the @code{mysql_field_count(&mysql)} call with @code{mysql_errno(&mysql)}. In this case, you are checking directly for an error from @code{mysql_store_result()} rather than inferring from the value -of @code{mysql_field_count()} whether or not the statement was a +of @code{mysql_field_count()} whether the statement was a @code{SELECT}. @@ -42652,9 +42657,9 @@ None. @subsubheading Description Retrieves a string providing information about the most recently executed -query, but only for the statements listed below. For other statements, +query, but only for the statements listed here. For other statements, @code{mysql_info()} returns @code{NULL}. The format of the string varies -depending on the type of query, as described below. The numbers are +depending on the type of query, as described here. The numbers are illustrative only; the string will contain values appropriate for the query. @table @code @@ -42695,7 +42700,7 @@ None. Allocates or initialises a @code{MYSQL} object suitable for @code{mysql_real_connect()}. If @code{mysql} is a @code{NULL} pointer, the -function allocates, initialises, and returns a new object. Otherwise the +function allocates, initialises, and returns a new object. Otherwise, the object is initialised and the address of the object is returned. If @code{mysql_init()} allocates a new object, it will be freed when @code{mysql_close()} is called to close the connection. @@ -42946,11 +42951,11 @@ Note that you can get the number of columns either from a pointer to a result set or to a connection handle. You would use the connection handle if @code{mysql_store_result()} or @code{mysql_use_result()} returned @code{NULL} (and thus you have no result set pointer). In this case, you can -call @code{mysql_field_count()} to determine whether or not +call @code{mysql_field_count()} to determine whether @code{mysql_store_result()} should have produced a non-empty result. This allows the client program to take proper action without knowing whether or not the query was a @code{SELECT} (or @code{SELECT}-like) statement. The -example shown below illustrates how this may be done. +example shown here illustrates how this may be done. @xref{NULL mysql_store_result, , @code{NULL mysql_store_result()}}. @@ -43122,11 +43127,11 @@ file. @subsubheading Description -Checks whether or not the connection to the server is working. If it has gone +Checks whether the connection to the server is working. If it has gone down, an automatic reconnection is attempted. This function can be used by clients that remain idle for a long while, -to check whether or not the server has closed the connection and reconnect +to check whether the server has closed the connection and reconnect if necessary. @subsubheading Return Values @@ -43233,7 +43238,7 @@ allows the database administrator to set up the MySQL privilege system in such a way that users get different privileges depending on whether or not they have specified a password. -NOTE: Do not attempt to encrypt the password before calling +Note: Do not attempt to encrypt the password before calling @code{mysql_real_connect()}; password encryption is handled automatically by the client API. @@ -43417,7 +43422,7 @@ Executes the SQL query pointed to by @code{query}, which should be a string You should not add a terminating semicolon (@samp{;}) or @code{\g} to the statement. -You @emph{must} use @code{mysql_real_query()} rather than +You @strong{must} use @code{mysql_real_query()} rather than @code{mysql_query()} for queries that contain binary data, because binary data may contain the @samp{\0} character. In addition, @code{mysql_real_query()} is faster than @code{mysql_query()} because it does not call @code{strlen()} on @@ -43752,9 +43757,9 @@ This will tie up the server and prevent other threads from updating any tables from which the data is being fetched. When using @code{mysql_use_result()}, you must execute -@code{mysql_fetch_row()} until a @code{NULL} value is returned, otherwise the +@code{mysql_fetch_row()} until a @code{NULL} value is returned, otherwise, the unfetched rows will be returned as part of the result set for your next -query. The C API will give the error @code{Commands out of sync; You can't +query. The C API will give the error @code{Commands out of sync; you can't run this command now} if you forget to do this! You may not use @code{mysql_data_seek()}, @code{mysql_row_seek()}, @@ -44002,7 +44007,7 @@ The query returned no data (for example, it was an @code{INSERT}, @code{UPDATE}, or @code{DELETE}). @end itemize -You can always check whether or not the statement should have produced a +You can always check whether the statement should have produced a non-empty result by calling @code{mysql_field_count()}. If @code{mysql_field_count()} returns zero, the result is empty and the last query was a statement that does not return values (for example, an @@ -44124,7 +44129,7 @@ adding @code{-lm} to the end of the compile/link line. @cindex programs, client If you compile MySQL clients that you've written yourself or that -you obtain from a third party, they must be linked using the +you obtain from a third-party, they must be linked using the @code{-lmysqlclient -lz} option on the link command. You may also need to specify a @code{-L} option to tell the linker where to find the library. For example, if the library is installed in @file{/usr/local/mysql/lib}, use @@ -44824,12 +44829,12 @@ The tests are located in @code{mysql-test/t/*.test} @item A test case consists of @code{;} terminated statements and is similar to the -input of @code{mysql} command line client. A statement by default is a query +input of @code{mysql} command-line client. A statement by default is a query to be sent to MySQL server, unless it is recognised as internal command (eg. @code{sleep}). @item -All queries that produce results, e.g. @code{SELECT}, @code{SHOW}, +All queries that produce results@-e.g., @code{SELECT}, @code{SHOW}, @code{EXPLAIN}, etc., must be preceded with @code{@@/path/to/result/file}. The file must contain the expected results. An easy way to generate the result file is to run @code{mysqltest -r < t/test-case-name.test} from @@ -45102,7 +45107,7 @@ The C/C++ functions that you write to implement the interface for @item @code{xxx()} (required) The main function. This is where the function result is computed. The correspondence between the SQL type and return type of your C/C++ -function is shown below: +function is shown here: @multitable @columnfractions .15 .15 @item @strong{SQL type} @tab @strong{C/C++ type} @@ -45128,7 +45133,7 @@ Specify the maximum length of the result. @item Specify (for @code{REAL} functions) the maximum number of decimals. @item -Specify whether or not the result can be @code{NULL}. +Specify whether the result can be @code{NULL}. @end itemize @item @code{xxx_deinit()} (optional) @@ -45189,7 +45194,7 @@ and free it in @code{xxx_deinit()}. @cindex calling sequences for simple functions, UDF -The main function should be declared as shown below. Note that the return +The main function should be declared as shown here. Note that the return type and parameters differ, depending on whether you will declare the SQL function @code{XXX()} to return @code{STRING}, @code{INTEGER}, or @code{REAL} in the @code{CREATE FUNCTION} statement: @@ -45253,7 +45258,7 @@ digits. For real functions, the default is 13 plus the number of decimals indicated by @code{initid->decimals}. (For numeric functions, the length includes any sign or decimal point characters.) -If you want to return a blob, you can set this to 65K or 16M; This +If you want to return a blob, you can set this to 65K or 16M; this memory is not allocated but used to decide which column type to use if there is a need to temporary store the data. @@ -45334,7 +45339,7 @@ will return @code{NULL} as the result for the group function. @cindex processing, arguments The @code{args} parameter points to a @code{UDF_ARGS} structure that has the -members listed below: +members listed here: @table @code @item unsigned int arg_count @@ -45490,7 +45495,7 @@ parameter to @code{1}: If @code{xxx()} sets @code{*error} to @code{1} for any row, the function value is @code{NULL} for the current row and for any subsequent rows processed by the statement in which @code{XXX()} was invoked. (@code{xxx()} -will not even be called for subsequent rows.) @strong{Note:} In +will not even be called for subsequent rows.) @strong{Note}: in MySQL versions prior to 3.22.10, you should set both @code{*error} and @code{*is_null}: @@ -45598,7 +45603,7 @@ You should not use @code{CREATE FUNCTION} to add a function that has already been created. If you need to reinstall a function, you should remove it with @code{DROP FUNCTION} and then reinstall it with @code{CREATE FUNCTION}. You would need to do this, for example, if you recompile a new version of your -function, so that @code{mysqld} gets the new version. Otherwise the server +function, so that @code{mysqld} gets the new version. Otherwise, the server will continue to use the old version. Active functions are reloaded each time the server starts, unless you start @@ -45615,7 +45620,7 @@ one that has been loaded with @code{CREATE FUNCTION} and not removed with @cindex native functions, adding @cindex functions, native, adding -The procedure for adding a new native function is described below. Note +The procedure for adding a new native function is described here. Note that you cannot add native functions to a binary distribution because the procedure involves modifying MySQL source code. You must compile MySQL yourself from a source distribution. Also note @@ -45868,7 +45873,7 @@ If a program fails, it's always useful to know: @item Has the program in question made a segmentation fault (core dumped)? @item -Is the program taking the whole CPU? Check with @code{top}. Let the +Is the program taking up the whole CPU? Check with @code{top}. Let the program run for a while, it may be evaluating something heavy. @item If it's the @code{mysqld} server that is causing problems, can you @@ -46234,7 +46239,7 @@ Note that both the client and the server has it's own you have to increase this variable both in the client and in the server. It's safe to increase this variable as memory is only allocated when -needed; This variable is more a precaution to catch wrong packets +needed; this variable is more a precaution to catch wrong packets between the client/server and also to ensure that you don't accidently use big packets so that you run out of memory. @@ -46386,7 +46391,7 @@ Error code 28: No space left on device @cindex commands out of sync -If you get @code{Commands out of sync; You can't run this command now} +If you get @code{Commands out of sync; you can't run this command now} in your client code, you are calling client functions in the wrong order! This can happen, for example, if you are using @code{mysql_use_result()} and @@ -46400,7 +46405,7 @@ a @code{mysql_use_result()} or @code{mysql_store_result()} in between. If you get the following error: -@code{Found wrong password for user: 'some_user@@some_host'; Ignoring user} +@code{Found wrong password for user: 'some_user@@some_host'; ignoring user} this means that when @code{mysqld} was started or when it reloaded the permissions tables, it found an entry in the @code{user} table with @@ -46445,8 +46450,8 @@ find file: 'xxx' (errno: 2)}, this means that no table exists in the current database with the name @code{xxx}. Note that as MySQL uses directories and files to store databases and -tables, the database and table names are @strong{case sensitive}! -(On Windows the databases and tables names are not case sensitive, but all +tables, the database and table names are @strong{case-sensitive}! +(On Windows the databases and tables names are not case-sensitive, but all references to a given table within a query must use the same case!) You can check which tables you have in the current database with @@ -46695,7 +46700,7 @@ as a Unix user other than @code{root}; just specify the @code{-u root} option to the client program. Note that accessing MySQL as @code{root}, by supplying @code{-u -root} on the command line, has @emph{nothing} to do with MySQL running +root} on the command-line, has @strong{nothing} to do with MySQL running as the Unix @code{root} user, or, indeed, as another Unix user. The access permissions and user names of MySQL are completely separate from Unix user names. The only connection with Unix user names is that if you @@ -46813,11 +46818,11 @@ Someone is manipulating the data/index files outside of @strong{mysqld} without locking the table properly. @item If you are running many @code{mysqld} servers on the same data on a -system that doesn't support good file system locks (normally handled by +system that doesn't support good filesystem locks (normally handled by the @code{lockd} daemon ) or if you are running multiple servers with @code{--skip-locking} @item -You have a crashed index/data file that contains very wrong data that +You have a crashed index/datafile that contains very wrong data that got @code{mysqld} confused. @item You have found a bug in the data storage code. This isn't that likely, @@ -46827,7 +46832,7 @@ repaired copy of the table! @end itemize Because it is very difficult to know why something is crashing, first try to -check whether or not things that work for others crash for you. Please try +check whether things that work for others crash for you. Please try the following things: @itemize @bullet @@ -46839,7 +46844,7 @@ state. @xref{MySQL Database Administration}. @item Use @code{mysqld --log} and try to determine from the information in the log -whether or not some specific query kills the server. About 95% of all bugs are +whether some specific query kills the server. About 95% of all bugs are related to a particular query! Normally this is one of the last queries in the log file just before MySQL restarted. @xref{Query log}. If you can repeatadly kill MySQL with one of the queries, even @@ -47004,7 +47009,7 @@ When a disk-full condition occurs, MySQL does the following: @itemize @bullet @item -It checks once every minute to see whether or not there is enough space to +It checks once every minute to see whether there is enough space to write the current row. If there is enough space, it continues as if nothing had happened. @item @@ -47046,16 +47051,16 @@ unchanged). MySQL uses the value of the @code{TMPDIR} environment variable as the pathname of the directory in which to store temporary files. If you don't have @code{TMPDIR} set, MySQL uses the system default, which is -normally @file{/tmp} or @file{/usr/tmp}. If the file system containing your +normally @file{/tmp} or @file{/usr/tmp}. If the filesystem containing your temporary file directory is too small, you should edit @code{safe_mysqld} to -set @code{TMPDIR} to point to a directory in a file system where you have +set @code{TMPDIR} to point to a directory in a filesystem where you have enough space! You can also set the temporary directory using the @code{--tmpdir} option to @code{mysqld}. MySQL creates all temporary files as hidden files. This ensures that the temporary files will be removed if @code{mysqld} is terminated. The disadvantage of using hidden files is that you will not see a big temporary -file that fills up the file system in which the temporary file directory is +file that fills up the filesystem in which the temporary file directory is located. When sorting (@code{ORDER BY} or @code{GROUP BY}), MySQL normally @@ -47085,14 +47090,14 @@ the original table. If you have problems with the fact that anyone can delete the MySQL communication socket @file{/tmp/mysql.sock}, you can, -on most versions of Unix, protect your @file{/tmp} file system by setting +on most versions of Unix, protect your @file{/tmp} filesystem by setting the @code{sticky} bit on it. Log in as @code{root} and do the following: @example shell> chmod +t /tmp @end example -This will protect your @file{/tmp} file system so that files can be deleted +This will protect your @file{/tmp} filesystem so that files can be deleted only by their owners or the superuser (@code{root}). You can check if the @code{sticky} bit is set by executing @code{ls -ld /tmp}. @@ -47117,7 +47122,7 @@ socket=path-for-socket-file @end example @xref{Option files}. @item -Specifying this on the command line to @code{safe_mysqld} and most +Specifying this on the command-line to @code{safe_mysqld} and most clients with the @code{--socket=path-for-socket-file} option. @item Specify the path to the socket in the @code{MYSQL_UNIX_PORT} environment @@ -47160,7 +47165,7 @@ the server runs, for example, in @code{safe_mysqld} or @code{mysql.server}. * Problems with alias:: Problems with @code{alias} * Deleting from related tables:: Deleting Rows from Related Tables * No matching rows:: Solving Problems with No Matching Rows -* Problems with float:: Problems with floating point comparison +* Problems with float:: Problems with floating-point comparison @end menu @node Case sensitivity, Using DATE, Query Issues, Query Issues @@ -47172,7 +47177,7 @@ the server runs, for example, in @code{safe_mysqld} or @code{mysql.server}. @cindex Big5 Chinese character encoding By default, MySQL searches are case-insensitive (although there are -some character sets that are never case insensitive, such as @code{czech}). +some character sets that are never case-insensitive, such as @code{czech}). That means that if you search with @code{col_name LIKE 'a%'}, you will get all column values that start with @code{A} or @code{a}. If you want to make this search case-sensitive, use something like @code{INSTR(col_name, "A")=1} to @@ -47225,8 +47230,8 @@ makes sense as a date. The special date @code{'0000-00-00'} can be stored and retrieved as @code{'0000-00-00'.} When using a @code{'0000-00-00'} date through -@strong{MyODBC}, it will automatically be converted to @code{NULL} in -@strong{MyODBC} Version 2.50.12 and above, because ODBC can't handle this kind of +@code{MyODBC}, it will automatically be converted to @code{NULL} in +@code{MyODBC} Version 2.50.12 and above, because ODBC can't handle this kind of date. Because MySQL performs the conversions described above, the following @@ -47257,7 +47262,7 @@ mysql> SELECT idate FROM tbl_name WHERE STRCMP(idate,'19970505')=0; a string and performs a string comparison. It does not convert @code{'19970505'} to a date and perform a date comparison. -Note that MySQL does no checking whether or not the date is +Note that MySQL does no checking whether the date is correct. If you store an incorrect date, such as @code{'1998-2-31'}, the wrong date will be stored. If the date cannot be converted to any reasonable value, a @code{0} is stored in the @code{DATE} field. This is mainly a speed @@ -47274,7 +47279,7 @@ the server. The concept of the @code{NULL} value is a common source of confusion for newcomers to SQL, who often think that @code{NULL} is the same thing as an -empty string @code{''}. This is not the case! For example, the following +empty string @code{""}. This is not the case! For example, the following statements are completely different: @example @@ -47453,9 +47458,9 @@ Post the test file using @code{mysqlbug} to @email{mysql@@lists.mysql.com}. @end enumerate @node Problems with float, , No matching rows, Query Issues -@appendixsubsec Problems with Floating Point Comparison +@appendixsubsec Problems with Floating-Point Comparison -Floating point numbers cause confusion sometimes, because these numbers +floating-point numbers cause confusion sometimes, because these numbers are not stored as exact values inside computer architecture. What one can see on the screen usually is not the exact value of the number. @@ -47490,7 +47495,7 @@ difference between the numbers show up around tenth decimal, or so depending on computer architecture. The problem cannot be solved by using ROUND() (or similar function), -because the result is still a floating point number. Example: +because the result is still a floating-point number. Example: @example mysql> SELECT i, ROUND(SUM(d1), 2) AS a, ROUND(SUM(d2), 2) AS b @@ -47524,7 +47529,7 @@ mysql> SELECT i, ROUND(SUM(d1), 2)*1.0000000000000000 AS a, @end example Depending on the computer architecture you may or may not see similar results. -Each CPU may evaluate floating point numbers differently. For example in +Each CPU may evaluate floating-point numbers differently. For example in some machines you may get 'right' results by multiplaying both arguments with 1, an example follows. @@ -47542,14 +47547,14 @@ mysql> SELECT i, ROUND(SUM(d1), 2)*1 AS a, ROUND(SUM(d2), 2)*1 AS b @end example The reason why the above example seems to be working is that on the -particular machine where the test was done, the CPU floating point +particular machine where the test was done, the CPU floating-point arithmetics happens to round the numbers to same, but there is no rule that any CPU should do so, so it cannot be trusted. -The correct way to do floating point number comparison is to first +The correct way to do floating-point number comparison is to first decide on what is the wanted tolerance between the numbers and then do the comparsion against the tolerance number. For example, if we agree on -that floating point numbers should be regarded the same, if they are +that floating-point numbers should be regarded the same, if they are same with precision of one of ten thousand (0.0001), the comparsion should be done like this: @@ -47716,7 +47721,7 @@ tools and add-ons. A list of what is available at @uref{http://www.mysql.com/Downloads/Contrib/} -(or any mirror) is shown below. +(or any mirror) is shown here. Please visit our Software Portal at @uref{http://www.mysql.com/portal/software/}. @@ -47781,7 +47786,7 @@ license. Please check @uref{http://www.worldserver.com/mm.mysql/} for the latest drivers (and other JDBC information) because these drivers may be out of date. @item @uref{http://www.caucho.com/projects/jdbc-mysql/index.xtp} -The Resin commercial JDBC driver, which is released under Open Source. +The Resin commercial JDBC driver, which is released under @code{Open Source}. It claims to be faster than the mm driver, but we haven't received that much information about this yet. @@ -47938,7 +47943,7 @@ By Ken Menzel @email{kenm@@icarz.com}. @item @uref{http://www.mysql.com/Downloads/Contrib/MYSQLX.EXE} MySQL ActiveX Object for directly accessing your MySQL servers from IIS/ASP, VB, VC++ skipping the slower ODBC methods. Fully -updatable, multithreaded with full support for all MySQL fieldtypes +updatable, multi-threaded with full support for all MySQL fieldtypes (version 2001.1.1). By SciBit @uref{http://www.scibit.com/}. @item @uref{http://www.fastflow.it/mylua/} @@ -48073,7 +48078,7 @@ The xmysql homepage is at @uref{http://web.wt.net/~dblhack/} Requires @uref{http://bragg.phys.uwm.edu/xforms/} (xforms 0.88) to work. @item @uref{http://www.tamos.net/sw/dbMetrix/} -dbMatrix is an Open Source client for exploring databases and executing +dbMatrix is an @code{Open Source} client for exploring databases and executing SQL. Supports MySQL, Oracle, PostgreSQL, and mSQL. @item @uref{http://www.multimania.com/bbrox/GtkSQL/} @@ -48103,7 +48108,7 @@ Oracle 8 and MySQL as the back-end databases. It requires JDK 1.3 from JavaSoft. @item @uref{http://www.jetools.com/products/databrowser/} The DataBrowser is a cross-database, cross-platform data access tool. It is more -user friendly than tools like SQL Plus, psql (command line based tools). It is more +user friendly than tools like SQL Plus, psql (command-line based tools). It is more flexible than TOAD, ISQL, PGAccess which are GUI's that are limitied to a single platform or database. @item @uref{http://www.intrex.net/amit/software/} @@ -48131,7 +48136,7 @@ WWW MySQL administrator for the @code{user,} @code{db} and @item @uref{http://www.mysql.com/Downloads/Contrib/mysql-webadmin-1.0a8-rz.tar.gz} A tool written in PHP-FI to administrate MySQL databases -remotely over the web within a Web-Browser. By Peter Kuppelwieser, +remotely over the web within a web-browser. By Peter Kuppelwieser, @email{peter.kuppelwieser@@kantea.it}. Updated by Wim Bonis, @email{bonis@@kiss.de}. Not maintained anymore! @@ -48169,8 +48174,8 @@ This cgi scripts in Perl enables you to edit content of Mysql database. By Tomas Zeman. @item @uref{http://worldcommunity.com/opensource/futuresql/} -FutureSQL by Peter F. Brown, is a free, Open Source rapid application -development Web database administration tool, written in Perl, +FutureSQL by Peter F. Brown, is a free, @code{Open Source} rapid application +development web database administration tool, written in Perl, using MySQL. It uses @code{DBI:DBD} and @code{CGI.pm}. FutureSQL allows one to easily set up config files to view, edit, delete, @@ -48345,13 +48350,13 @@ while converting, quotes @strong{all} special characters in text and binary data, and so on. It will also convert to @code{mSQL} v1 and v2, and is free of charge for anyone. See @uref{http://www.cynergi.net/exportsql/} for the latest version. By -Pedro Freire, @email{support@@cynergi.net}. NOTE: Doesn't work with +Pedro Freire, @email{support@@cynergi.net}. Note: Doesn't work with Access2! @item @uref{http://www.mysql.com/Downloads/Contrib/access_to_mysql.txt} Paste this function into an Access module of a database that has the tables you want to export. See also @code{exportsql}. By Brian Andrews. -NOTE: Doesn't work with Access2! +Note: Doesn't work with Access2! @item @uref{http://www.mysql.com/Downloads/Contrib/importsql.txt} A script that does the exact reverse of @code{exportsql.txt}. That is, @@ -48361,7 +48366,7 @@ use Access for all DB design and administration, and synchronise with your actual MySQL server either way. Free of charge. See @uref{http://www.netdive.com/freebies/importsql/} for any updates. Created by Laurent Bossavit of NetDIVE. -@strong{NOTE:} Doesn't work with Access2! +@strong{Note}: doesn't work with Access2! @item @uref{http://www.mysql.com/Downloads/Contrib/mdb2sql.bas} Converter from Access97 to MySQL by Moshe Gurvich. @@ -48581,7 +48586,7 @@ hashing. In use since 1981 and published around 1984. @item The @code{replace} program (take a look at it, it's @strong{COOL}!). @item -@strong{MyODBC}, the ODBC driver for Windows95. +@code{MyODBC}, the ODBC driver for Windows95. @item Fixing bugs in MIT-pthreads to get it to work for MySQL Server. And also Unireg, a curses-based application tool with many utilities. @@ -49042,7 +49047,7 @@ This appendix lists the changes from version to version in the MySQL source code. Note that we tend to update the manual at the same time we make changes to -MySQL. If you find a version listed below that you can't +MySQL. If you find a version listed here that you can't find on the MySQL download page (@uref{http://www.mysql.com/downloads/}), this means that the version has not yet been released! @@ -49299,7 +49304,7 @@ Added support for @code{MATCH ... AGAINST(... IN BOOLEAN MODE)}. @code{ALTER TABLE tablename TYPE=MyISAM} to be able to use boolean full-text search}. @item -@code{LOCATE()} and @code{INSTR()} are now case sensitive if either +@code{LOCATE()} and @code{INSTR()} are now case-sensitive if either argument is a binary string. @item Changed @code{RAND()} initialisation so that @code{RAND(N)} and @@ -49350,7 +49355,7 @@ now handle signed and unsigned @code{BIGINT} numbers correctly. New character set @code{latin_de} which provides correct German sorting. @item @code{STRCMP()} now uses the current character set when doing comparisons, -which means that the default comparison behavior now is case insensitive. +which means that the default comparison behavior now is case-insensitive. @item @code{TRUNCATE TABLE} and @code{DELETE FROM tbl_name} are now separate functions. One bonus is that @code{DELETE FROM tbl_name} now returns @@ -49535,7 +49540,7 @@ not yet 100% confident in this code. @appendixsubsec Changes in release 3.23.51 @itemize @bullet Fixed the result from @code{IF()} is case in-sensitive if the 2 and -third arguments are case sensitive. +third arguments are case-sensitive. @end itemize @node News-3.23.50, News-3.23.49, News-3.23.51, News-3.23.x @@ -49548,7 +49553,7 @@ Fixed that @code{@@@@unknown_variable} doesn't hang server. @item Added @code{@@@@VERSION} as a synonym for @code{VERSION()}. @item -@code{SHOW VARIABLES LIKE 'xxx'} is now case insensitive. +@code{SHOW VARIABLES LIKE 'xxx'} is now case-insensitive. @item Fixed timeout for @code{GET_LOCK()} on HPUX with DCE threads. @item @@ -49612,7 +49617,7 @@ with @code{GROUP BY}. @itemize @bullet @item -Don't give warning for a statement that is only a comment; This is needed for +Don't give warning for a statement that is only a comment; this is needed for @code{mysqldump --disable-keys} to work. @item Fixed unlikely caching bug when doing a join without keys. In this case @@ -49779,7 +49784,7 @@ date_column was declared as @code{NOT NULL}. @item Fixed bug with @code{BDB} tables and keys on @code{BLOB} columns. @item -Fixed bug in @code{MERGE} tables on OS with 32 bit file pointers. +Fixed bug in @code{MERGE} tables on OS with 32-bit file pointers. @item Fixed bug in @code{TIME_TO_SEC()} when using negative values. @end itemize @@ -49834,7 +49839,7 @@ Foreign keys checking is now done for @code{InnoDB} tables. @item @code{DROP DATABASE} now works also for @code{InnoDB} tables. @item -@code{InnoDB} now supports data files and raw disk partitions bigger +@code{InnoDB} now supports datafiles and raw disk partitions bigger than 4 GB on those operating systems that have big files. @item @code{InnoDB} calculates better table cardinality estimates for the @@ -49843,7 +49848,7 @@ MySQL optimiser. Accent characters in the default character set @code{latin1} are ordered according to the MySQL ordering. -NOTE: if you are using @code{latin1} and have inserted characters whose +Note: if you are using @code{latin1} and have inserted characters whose code is greater than 127 into an indexed @code{CHAR} column, you should run @code{CHECK TABLE} on your table when you upgrade to 3.23.44, and drop and reimport the table if @code{CHECK TABLE} reports an error! @@ -49868,7 +49873,7 @@ multiple-line inserts. Fixed a bug when the case of letters changes in an update of an indexed secondary column. @item -Fixed a hang when there are > 24 data files. +Fixed a hang when there are > 24 datafiles. @item Fixed a crash when @code{MAX(col)} is selected from an empty table, and @code{col} is not the first column in a multi-column index. @@ -50061,7 +50066,7 @@ Fixed a bug when using @code{COUNT(DISTINCT)} with @code{LEFT JOIN} and there weren't any matching rows. @item Removed all documentation referring to the @code{GEMINI} table -type. @code{GEMINI} is not released under an Open Source license. +type. @code{GEMINI} is not released under an @code{Open Source} license. @end itemize @@ -50705,7 +50710,7 @@ debugging and testing of replication. Fixed replication of temporary tables. Handles everything except slave server restart. @item -@code{SHOW KEYS} now shows whether or not key is @code{FULLTEXT}. +@code{SHOW KEYS} now shows whether key is @code{FULLTEXT}. @item New script @code{mysqld_multi}. @xref{mysqld_multi, , @code{mysqld_multi}}. @item @@ -50883,7 +50888,7 @@ new table with the rows in a specific order. @itemize @bullet @item Fixed a bug where the automatic repair of @code{MyISAM} tables sometimes failed -when the data file was corrupt. +when the datafile was corrupt. @item Fixed a bug in @code{SHOW CREATE} when using @code{AUTO_INCREMENT} columns. @item @@ -51097,7 +51102,7 @@ Restored the @code{win1251} character set (it's now only marked deprecated). @itemize @bullet @item -Changed sort order for 'German'; All tables created with 'German' sortorder +Changed sort order for 'German'; all tables created with 'German' sortorder must be repaired with @code{REPAIR TABLE} or @code{myisamchk} before use! @item Added @code{--core-file} option to @code{mysqld} to get a core file on @@ -51355,7 +51360,7 @@ Fixed big/little endian problem in the replication. Fixed a problem from 3.23.17 when choosing character set on the client side. @item Added @code{FLUSH TABLES WITH READ LOCK} to make a global lock suitable for -making a copy of MySQL data files. +making a copy of MySQL datafiles. @item @code{CREATE TABLE ... SELECT ... PROCEDURE} now works. @item @@ -51408,7 +51413,7 @@ Changed protocol to let client know if the server is in @code{AUTOCOMMIT} mode and if there is a pending transaction. If there is a pending transaction, the client library will give an error before reconnecting to the server to let the client know that the server did a rollback. -The protocol is still backward compatible with old clients. +The protocol is still backward-compatible with old clients. @item @code{KILL} now works on a thread that is locked on a 'write' to a dead client. @item @@ -51469,7 +51474,7 @@ Added @code{SQL_LOG_BIN} option. @item To start @code{mysqld} as @code{root}, you must now use the @code{--user=root} option. @item -Added interface to Berkeley DB. (This is not yet functional; Play with it at +Added interface to Berkeley DB. (This is not yet functional; play with it at your own risk!) @item Replication between master and slaves. @@ -51685,7 +51690,7 @@ Fix problem with timezones that have half hour offsets. @item Allow the syntax @code{UNIQUE INDEX} in @code{CREATE} statements. @item -@code{mysqlhotcopy} - fast on-line hot-backup utility for local +@code{mysqlhotcopy} - fast online hot-backup utility for local MySQL databases. By Tim Bunce. @item New more secure @code{mysqlaccess}. Thanks to Steve Harvey for this. @@ -51861,7 +51866,7 @@ FROM pos)}, @code{SUBSTRING_INDEX(str,delim,count)}, @code{RTRIM(str)}, @code{TRIM([[BOTH | TRAILING] [remstr] FROM] str)}, @code{REPLACE(str,from_str,to_str)}, @code{REVERSE(str)}, @code{INSERT(str,pos,len,newstr)}, @code{LCASE(str)}, @code{LOWER(str)}, -@code{UCASE(str)} and @code{UPPER(str)}; Patch by Wei He. +@code{UCASE(str)} and @code{UPPER(str)}; patch by Wei He. @item Fix core dump when releasing a lock from a non-existent table. @item @@ -52034,9 +52039,9 @@ Fixed privilege check for @code{LOAD DATA REPLACE}. @item Automatic fixing of broken include files on Solaris 2.7 @item -Some configure issues to fix problems with big file system detection. +Some configure issues to fix problems with big filesystem detection. @item -@code{REGEXP} is now case insensitive if you use non-binary strings. +@code{REGEXP} is now case-insensitive if you use non-binary strings. @end itemize @@ -52105,7 +52110,7 @@ Added handling of fuzzy dates (dates where day or month is 0), such as @code{'1999-01-00'}. @item Fixed optimisation of @code{SELECT ... WHERE key_part1=const1 AND -key_part_2=const2 AND key_part1=const4 AND key_part2=const4}; Indextype +key_part_2=const2 AND key_part1=const4 AND key_part2=const4}; indextype should be @code{range} instead of @code{ref}. @item Fixed @code{egcs} 1.1.2 optimiser bug (when using @code{BLOB}s) on Linux Alpha. @@ -52222,11 +52227,11 @@ WHERE ... PROCEDURE ANALYSE([max elements,[max memory]]) This procedure is extremely useful when you want to check the data in your table! @item -@code{BINARY} cast to force a string to be compared in case sensitive fashion. +@code{BINARY} cast to force a string to be compared in case-sensitive fashion. @item Added @code{--skip-show-database} option to @code{mysqld}. @item -Check whether or not a row has changed in an @code{UPDATE} now also works +Check whether a row has changed in an @code{UPDATE} now also works with @code{BLOB}/@code{TEXT} columns. @item Added the @code{INNER} join syntax. @strong{NOTE}: This made @code{INNER} @@ -52281,7 +52286,7 @@ All C client API macros are now functions to make shared libraries more reliable. Because of this, you can no longer call @code{mysql_num_fields()} on a @code{MYSQL} object, you must use @code{mysql_field_count()} instead. @item -Added use of @code{LIBEWRAP}; Patch by Henning P . Schmiedehausen. +Added use of @code{LIBEWRAP}; patch by Henning P. Schmiedehausen. @item Don't allow @code{AUTO_INCREMENT} for other than numerical columns. @item @@ -52290,7 +52295,7 @@ Using @code{AUTO_INCREMENT} will now automatically make the column @item Show @code{NULL} as the default value for @code{AUTO_INCREMENT} columns. @item -Added @code{SQL_BIG_RESULT}; @code{SQL_SMALL_RESULT} is now default. +Added @code{SQL_BIG_RESULT}; @code{SQL_SMALL_RESULT} is now default. @item Added a shared library RPM. This enhancement was contributed by David Fox (@email{dsfox@@cogsci.ucsd.edu}). @@ -52378,7 +52383,7 @@ on a table with only one row. @itemize @bullet @item -Fixed problem with @code{GROUP BY} on @code{TINYBLOB} columns; This +Fixed problem with @code{GROUP BY} on @code{TINYBLOB} columns; this caused bugzilla to not show rows in some queries. @item Had to do total recompile of the Windows binary version as VC++ didn't @@ -52406,7 +52411,7 @@ Fixed problem when storing numbers in timestamps. @item Fix problem with timezones that have half hour offsets. @item -Added @code{mysqlhotcopy}, a fast on-line hot-backup utility for local MySQL +Added @code{mysqlhotcopy}, a fast online hot-backup utility for local MySQL databases. By Tim Bunce. @item New more secure @code{mysqlaccess}. Thanks to Steve Harvey for this. @@ -52497,7 +52502,7 @@ Fixed problem with @code{AVG()} and @code{STD()} with @code{NULL} values. @item Fixed prototype in @file{my_ctype.h} when using other character sets. @item -Some configure issues to fix problems with big file system detection. +Some configure issues to fix problems with big filesystem detection. @item Fixed problem when sorting on big @code{BLOB} columns. @item @@ -52675,8 +52680,8 @@ columns. @itemize @bullet @item -Fixes a fatal problem in 3.22.17 on Linux; After @code{shutdown} -all threads didn't die properly. +Fixes a fatal problem in 3.22.17 on Linux; after @code{shutdown} +not all threads died properly. @item Added option @code{-O flush_time=#} to @code{mysqld}. This is mostly useful on Windows and tells how often MySQL should close all @@ -52784,7 +52789,7 @@ Added a patch for @code{localtime_r()} on Windows so that it will not crash anymore if your date is > 2039, but instead will return a time of all zero. @item Names for -user-defined functions are no longer case sensitive. +user-defined functions are no longer case-sensitive. @item Added escape of @code{^Z} (ASCII 26) to @code{\Z} as @code{^Z} doesn't work with pipes on Windows. @@ -53139,7 +53144,7 @@ New better compressed server/client protocol. You can now store values in the range @code{-838:59:59} <= x <= @code{838:59:59} in a @code{TIME} column. @item -@strong{WARNING: INCOMPATIBLE CHANGE!!} +@strong{Warning: incompatible change!!} If you set a @code{TIME} column to too short a value, MySQL now assumes the value is given as: @code{[[[D ]HH:]MM:]SS} instead of @code{HH[:MM[:SS]]}. @@ -53189,13 +53194,13 @@ trailing @samp{;}. @item Fix for corrupted fixed-format output generated by @code{SELECT INTO OUTFILE}. @item -@strong{Warning: Incompatible change!} +@strong{Warning: incompatible change!} Added Oracle @code{GREATEST()} and @code{LEAST()} functions. You must now use these instead of the @code{MAX()} and @code{MIN()} functions to get the largest/smallest value from a list of values. These can now handle @code{REAL}, @code{BIGINT} and string (@code{CHAR} or @code{VARCHAR}) values. @item -@strong{Warning: Incompatible change!} +@strong{Warning: incompatible change!} @code{DAYOFWEEK()} had offset 0 for Sunday. Changed the offset to 1. @item Give an error for queries that mix @code{GROUP BY} columns and fields when @@ -53360,7 +53365,7 @@ matched and updated, and how many ``warnings'' occurred when doing the update. Fixed incorrect result from @code{FORMAT(-100,2)}. @item @code{ENUM} and @code{SET} columns were compared in binary (case-sensitive) -fashion; changed to be case insensitive. +fashion; changed to be case-insensitive. @end itemize @@ -53369,7 +53374,7 @@ fashion; changed to be case insensitive. @itemize @bullet @item -New (backward compatible) connect protocol that allows you to +New (backward-compatible) connect protocol that allows you to specify the database to use when connecting, to get much faster connections to a specific database. @@ -53385,7 +53390,7 @@ Each connection is handled by its own thread, rather than by the master @code{accept()} thread. This fixes permanently the telnet bug that was a topic on the mail list some time ago. @item -All TCP/IP connections are now checked with backward resolution of +All TCP/IP connections are now checked with backward-resolution of the hostname to get better security. @code{mysqld} now has a local hostname resolver cache so connections should actually be faster than before, even with this feature. @@ -53442,7 +53447,7 @@ to join them in a specific order. @item String functions now return @code{VARCHAR} rather than @code{CHAR} and the column type is now @code{VARCHAR} for fields saved as @code{VARCHAR}. -This should make the @strong{MyODBC} driver better, but may break some old +This should make the @code{MyODBC} driver better, but may break some old MySQL clients that don't handle @code{FIELD_TYPE_VARCHAR} the same way as @code{FIELD_TYPE_CHAR}. @item @@ -53597,7 +53602,7 @@ it more easily in the future. @item @code{mysql} now returns an exit code > 0 if the query returned an error. @item -Saving of command line history to file in @code{mysql} client. +Saving of command-line history to file in @code{mysql} client. By Tommy Larsen @email{tommy@@mix.hive.no}. @item Fixed problem with empty lines that were ignored in @file{mysql.cc}. @@ -53805,7 +53810,7 @@ Setting a @code{TIMESTAMP} to @code{NULL} in @code{LOAD DATA INFILE ...} didn't set the current time for the @code{TIMESTAMP}. @item Fix @code{BETWEEN} to recognise binary strings. Now @code{BETWEEN} is -case sensitive. +case-sensitive. @item Added @code{--skip-thread-priority} option to @code{mysqld}, for systems where @code{mysqld}'s thread scheduling doesn't work properly (BSDI 3.1). @@ -53848,7 +53853,7 @@ Fix @code{COUNT(*)} problems when the @code{WHERE} clause didn't match any records. (Bug from 3.21.17.) @item Removed that @code{NULL = NULL} is true. Now you must use @code{IS NULL} -or @code{IS NOT NULL} to test whether or not a value is @code{NULL}. +or @code{IS NOT NULL} to test whether a value is @code{NULL}. (This is according to ANSI SQL but may break old applications that are ported from @code{mSQL}.) You can get the old behavior by compiling with @code{-DmSQL_COMPLIANT}. @@ -54067,7 +54072,7 @@ designed to find as many limits as possible in a SQL server. Tested with @item Fixed bug in range-optimiser that crashed MySQL on some queries. @item -Table and column name completion for @code{mysql} command line tool, by Zeev +Table and column name completion for @code{mysql} command-line tool, by Zeev Suraski and Andi Gutmans. @item Added new command @code{REPLACE} that works like @code{INSERT} but @@ -54389,7 +54394,7 @@ Added more secure password handling. Added new client function @code{mysql_errno()}, to get the error number of the error message. This makes error checking in the client much easier. This makes the new server incompatible with the 3.20.x server when running -without @code{--old-protocol}. The client code is backward compatible. +without @code{--old-protocol}. The client code is backward-compatible. More information can be found in the @file{README} file! @item Fixed some problems when using very long, illegal names. @@ -54759,8 +54764,8 @@ Inserts of timestamps with values didn't always work. @item Added some tests to @code{safe_mysqld} to make it ``safer''. @item -@code{LIKE} was case sensitive in some places and case insensitive in others. -Now @code{LIKE} is always case insensitive. +@code{LIKE} was case-sensitive in some places and case-insensitive in others. +Now @code{LIKE} is always case-insensitive. @item @file{mysql.cc}: Allow @code{'#'} anywhere on the line. @item @@ -55383,7 +55388,7 @@ If you run into problems with a new port, you may have to do some debugging of MySQL! @xref{Debugging server}. -@strong{NOTE:} Before you start debugging @code{mysqld}, first get the test +@strong{Note}: before you start debugging @code{mysqld}, first get the test programs @code{mysys/thr_alarm} and @code{mysys/thr_lock} to work. This will ensure that your thread installation has even a remote chance to work! @@ -55451,7 +55456,7 @@ problems that may be unique to your environment. If you have some very specific problem, you can always try to debug MySQL. To do this you must configure MySQL with the @code{--with-debug} or the @code{--with-debug=full} option. You can check -whether or not MySQL was compiled with debugging by doing: +whether MySQL was compiled with debugging by doing: @code{mysqld --help}. If the @code{--debug} flag is listed with the options then you have debugging enabled. @code{mysqladmin ver} also lists the @code{mysqld} version as @code{mysql ... --debug} in this case. @@ -55524,7 +55529,7 @@ In a DOS window do: mysqld --debug --standalone @end example -After this you can use the @code{mysql.exe} command line tool in a +After this you can use the @code{mysql.exe} command-line tool in a second DOS window to reproduce the problem. You can take down the above @code{mysqld} server with @code{mysqladmin shutdown}. @@ -55717,7 +55722,7 @@ If you are using @code{--log} without a file name, the log is stored in the database directory as 'hostname'.log In most cases it's the last query in the log file that killed @code{mysqld}, but if possible you should verify this by restarting @code{mysqld} and executing the found -query from the @code{mysql} command line tools. If this works, you +query from the @code{mysql} command-line tools. If this works, you should also test all complicated queries that didn't complete. You can also try the command @code{EXPLAIN} on all @code{SELECT} @@ -55897,7 +55902,7 @@ The currently recognised flag characters are: @end multitable Some examples of debug control strings which might appear on a shell -command line (the "-#" is typically used to introduce a control string +command-line (the "-#" is typically used to introduce a control string to an application program) are: @example @@ -55951,7 +55956,7 @@ Cons: @item Takes more memory than page level or table locks. @item -Is slower than page level or table locks when used one a big part of the table, +Is slower than page level or table locks when used on a big part of the table, because one has to do many more locks. @item Is definitely much worse than other locks if you do often do @code{GROUP @@ -55969,7 +55974,7 @@ following cases: @item Mostly reads @item -Read and updates on strict keys; This is where one updates or deletes +Read and updates on strict keys; this is where one updates or deletes a row that can be fetched with one key read: @example UPDATE table_name SET column=value WHERE unique_key# @@ -55991,7 +55996,7 @@ on when one started to access it. Other names for this are time travel, copy on write or copy on demand. Copy on demand is in many case much better than page or row level -locking; The worst case does, however, use much more memory than +locking; the worst case does, however, use much more memory than when using normal locks. Instead of using row level locks one can use application level locks @@ -56000,7 +56005,7 @@ only in well-behaved applications. In many cases one can do an educated guess which locking type is best for the application but generally it's very hard to say that a given -lock type is better than another; Everything depends on the application +lock type is better than another; everything depends on the application and different part of the application may require different lock types. Here are some tips about locking in MySQL: @@ -56187,7 +56192,7 @@ Here is a list of all the environment variables that are used directly or indirectly by MySQL. Most of these can also be found in other places in this manual. -Note that any options on the command line will take precedence over +Note that any options on the command-line will take precedence over values specified in configuration files and environment variables, and values in configuration files take precedence over values in environment variables. @@ -56452,7 +56457,7 @@ mysql> SELECT "weeknights" REGEXP "^(wee|week)(knights|nights)$"; -> 1 @node GPL license, LGPL license, Regexp, Top -@appendix GNU GENERAL PUBLIC LICENSE +@appendix GNU General Public License @cindex GPL, General Public License @cindex GPL, GNU General Public License @@ -56619,7 +56624,7 @@ source code, which must be distributed under the terms of Sections @item Accompany it with a written offer, valid for at least three -years, to give any third party, for a charge no more than your +years, to give any third-party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium @@ -56853,7 +56858,7 @@ Public License instead of this License. @node LGPL license, Function Index, GPL license, Top -@appendix GNU LESSER GENERAL PUBLIC LICENSE +@appendix GNU Lesser General Public License @cindex LGPL, Library General Public License @cindex LGPL, GNU Library General Public License @@ -57148,7 +57153,7 @@ Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, -whether or not they are linked directly with the Library itself. +whether they are linked directly with the Library itself. @item As an exception to the Sections above, you may also combine or @@ -57182,7 +57187,7 @@ to use the modified definitions.) @item Use a suitable shared library mechanism for linking with the Library. A -suitable mechanism is one that (1) uses at run time a copy of the +suitable mechanism is one that (1) uses at runtime a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs |