ChangeLog merging

MySQL Manual style guidelines

Paul DuBois <paul@snake.net>

The following list of guidelines contains items that I've been jotting

down over time as style questions have come up in relation to the

MySQL manual. I wouldn't say they're exactly "official", but they

do reflect current working practice. Arjen asked me to post this

on the list some time ago so that it can be discussed with a view

to adding it (or something like it) to the source tree. So here it is!

MySQL Reference Manual Style Guidelines

The manual is written in UK English, not American English. This means:

colour, not color

behaviour, not behavior

authorise, not authorize

optimise, not optimize

etc.

Write MySQL, not @strong{MySQL} (the manual used to use the latter, but no

more).

Write Unix, not UNIX.

Use uppercase for SQL keywords, functions names, etc., when writing

SQL statement examples.

To write a list of items, add commas after all items preceding the last one:

Correct: Features, products, and services

Incorrect: Features, products and services

How to pluralize keywords that are enclosed in @code:

Correct: @code{SELECT}s

Incorrect: @code{SELECTs} or @code{SELECT}'s or @code{SELECT}:s

Use "its" and "it's" correctly. These words are exceptions to

the normal use of "'s" to indicate possession:

it's = it is (e.g., "one of the strengths of MySQL is that it's fast")

its = possession (e.g., "MySQL is fast, which is one of its strengths")

"a lot" is two words. "alot" is rebarbative.

Write lowercase, not lower case

Write uppercase, not upper case

Write lettercase, not letter case

Write "web site" (two words), not "website", and "web page" rather

than "webpage".

The word "data" is problematic. It's commonly used both in plural and in

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.

Write "press Enter", not "hit Return" or "hit Enter".

When reproducing program output, reproduce it exactly, even if it contains

typos. Don't "fix" it. (If the output is produced by a MySQL program, then

fix the source for the program to write the output correctly without the

typo, then update the manual to match.)

Use "okay" rather than "ok" or "Ok" or "OK" in sentences.

Exceptions:

- When describing instructions for a GUI with buttons that say

"OK", then use "OK". That is, use the label that the GUI uses.

- When showing the output from a program, show the output exactly;

don't change "ok" to "okay", etc.

Write "Open Source", 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

out looking rotten in printed formats.

Exception: quotes in code examples should be written using whatever

contention the program language requires.

Table types should be written using @code{}; write @code{MyISAM}, not

MyISAM.

When possible, use table names that are singular, not plural.

For example, use "item" rather than "items", or "person" rather than

"people". Sometimes you can add "_list" (as in "item_list") to make it

more clear that the name refers to a collection of items.

Some commonly occurring misspelling:

Correct         Incorrect

---------------------------

publicly        publically

statically      staticly

dynamically     dynamicly

automatically   automaticly

There is no hyphen after "ly" words. Write statically linked, not

statically-linked.

To refer to ASCII codes, use ASCII n, not ASCII(n), unless you're

referring to the ASCII() function, which case you use @code{ASCII()}.

ASCII 13             indicates ASCII character code 13

@code{ASCII(13)}     indicates a function call

backup is a noun or adjective (as in "a backup file"), back up is a verb

(as in "to back up a database")

rollback is a noun or adjective (as in "a rollback operation"), roll back

is a verb (as in "roll back a transaction")

core dump is a noun or a verb (as in "a core dump file" or "a program

core dumps when it fails"). In the latter case, however, it's better say

say "a program dumps core when it fails").

Write character set names in @code{}, e.g., @code{latin1}, @code{win1251}.

To prevent problems with various output formats, there should be no link

titles in a @uref{}. So @uref{url} is allowed, @uref{url,blabla} is not.

Use this format:

		@uref{url} (WWW)

Not this format:

		@uref{url, WWW}

Similarly for FTP sites.

URLs ending in a domain name or directory should have a "/" at the end.

(For example, the URLs for all mirror sites should be written that way.)

Privilege names are written using @strong and lowercase, as in "the

@strong{process} privilege". Column names in the grant tables are

written using @code and the lettercase found in the table definition,

as in "the @code{Process_priv} column".

Write "e-mail", not "email". Exceptions are the @email{} construct, and

the Email attribute name in X509 certificate strings.

Write thread-safe, transaction-safe, replication-safe, not thread safe,

transaction safe, replication safe.

Write wildcard, not wild card or wild-card.

@item

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 indices, creation of

@code{FULLTEXT} indices as well as @code{COUNT(DISTINCT)}.

such as bulk @code{INSERT}s, searching on packed indexes, creation of

@code{FULLTEXT} indexes as well as @code{COUNT(DISTINCT)}.

@item

The table handler @code{InnoDB} is now offered as a feature of the

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

don't know the PostgreSQL roadmap.

@multitable @columnfractions .30 .30

@item @strong{Feature}                     @tab @strong{MySQL version}

@item Subselects                           @tab 4.1

@item Foreign keys                         @tab 4.1

@item Views                                @tab 5.0

@item Stored procedures                    @tab 5.0

@item Triggers                             @tab 5.0

@item Unions                               @tab 4.0

@item Full join                            @tab 4.1

@item Constraints                          @tab 4.1 or 5.0

@item Cursors                              @tab 4.1 or 5.0

@item R-trees                              @tab 4.1 (for MyISAM tables)

@item Inherited tables                     @tab Not planned

@item Extensible type system               @tab Not planned

@end multitable

Other reasons someone may consider for using PostgreSQL:

@itemize @bullet

@item

Standard usage in PostgreSQL is closer to ANSI SQL in some cases.

@item

One can speed up PostgreSQL by coding things as stored procedures.

@item

For geographical data, R-trees make PostgreSQL better than MySQL Server.

(note: MySQL version 4.1 will have R-trees for MyISAM tables).

@item

The PostgreSQL optimiser can do some optimisation that the current MySQL

optimiser can't do.  Most notable is doing joins when you don't have the

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://www.rs6000.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm}.

@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.

from this file.

@item --enable-locking

Enable system locking.  Note that if you use this option on a system

which a not fully working lockd() (as on Linux) you will easily get

Enable system locking.  Note that if you use this option on a system on

which @code{lockd} does not fully work (as on Linux), you will easily get

mysqld to deadlock.

@item --enable-named-pipe

If you need to do this more permanently, you should create an option

file for each server. @xref{Option files}.  In your startup script that

is executed at boot time (mysql.server?) you should specify for both

servers:

is executed at boot time you should specify for both servers:

@code{safe_mysqld --default-file=path-to-option-file}

@item

Database privilege changes take effect at the next @code{USE db_name}

command.

@end itemize

Global privilege changes and password changes take effect the next time the

client connects.

@item

Global privilege changes and password changes take effect the next time

the client connects.

@end itemize

@node Default privileges, Adding users, Privilege changes, User Account Management

@enumerate

@item

Execute in a client (perl ?) @code{FLUSH TABLES WITH READ LOCK}

From a client (or Perl), execute: @code{FLUSH TABLES WITH READ LOCK}.

@item

Fork a shell or execute in another client @code{mount vxfs snapshot}.

From another shell, execute: @code{mount vxfs snapshot}.

@item

Execute in the first client @code{UNLOCK TABLES}

From the first client, execute: @code{UNLOCK TABLES}.

@item

Copy files from snapshot

Copy files from snapshot.

@item

Unmount snapshot

Unmount snapshot.

@end enumerate

BACKUP TABLE tbl_name[,tbl_name...] TO '/path/to/backup/directory'

@end example

Make a copy of all the table files to the backup directory that are the

minimum needed to restore it. Currenlty only works for @code{MyISAM}

tables. For @code{MyISAM} table, copies @file{.frm} (definition)  and

Copies to the backup directory the minimum number of table files needed

to restore the table. Currently only works for @code{MyISAM} tables.

For @code{MyISAM} tables, copies @file{.frm} (definition)  and

@file{.MYD} (data) files. The index file can be rebuilt from those two.

Before using this command, please see @ref{Backup}.

@item @code{EXTENDED} @tab Do a full key lookup for all keys for each row.  This ensures that the table is 100 % consistent, but will take a long time!

@end multitable

For dynamic sized @code{MyISAM} tables a started check will always

For dynamically sized @code{MyISAM} tables a started check will always

do a @code{MEDIUM} check. For static size rows we skip the row scan

for @code{QUICK} and @code{FAST} as the rows are very seldom corrupted.

CHECK TABLE test_table FAST QUICK;

@end example

Which only would do a quick check on the table if it wasn't closed properly.

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

table!  This happens if the table is marked as 'corrupted' or 'not

@code{sort_buffer_size}!

@item  -o or --safe-recover

Uses an old recovery method (reads through all rows in order and updates

all index trees based on the found rows); this is a magnitude slower

than @code{-r}, but can handle a couple of very unlikely cases that

all index trees based on the found rows); this is an order of magnitude

slower than @code{-r}, but can handle a couple of very unlikely cases that

@code{-r} cannot handle.  This recovery method also uses much less disk

space than @code{-r}. Normally one should always first repair with

@code{-r}, and only if this fails use @code{-o}.

@end example

You can optimise a table in the same way using the SQL @code{OPTIMIZE TABLE}

statement.  @code{OPTIMIZE TABLE} does a repair of the table, a key

analyses and also sorts the index tree to give faster key lookups.

statement.  @code{OPTIMIZE TABLE} does a repair of the table and a key

analysis, and also sorts the index tree to give faster key lookups.

There is also no possibility of unwanted interaction between a utility

and the server, because the server does all the work when you use

@code{OPTIMIZE TABLE}. @xref{OPTIMIZE TABLE}.

@item Blocks/Record

Average number of blocks per record (that is, how many links a fragmented

record is composed of). This is always 1 for fixed-format tables. This value

should stay as close to 1.0 as possible. If it gets too big, you can

record is composed of). This is always 1.0 for fixed-format tables. This

value should stay as close to 1.0 as possible. If it gets too big, you can

reorganise the table with @code{myisamchk}.

@xref{Optimisation}.

indicates 16 megabytes.  The case of suffix letters does not matter;

@code{16M} and @code{16m} are equivalent:

@c FIX 2002-04-29 arjen / paul

@c FIX Below should be a @multitable just like SHOW STATUS.

@c FIX Has to wait till after O'Reilly printed edition is out the door.

@cindex variables, values

@itemize

@item @code{ansi_mode}.

Increase this to get better index handling (for all reads and multiple

writes) to as much as you can afford; 64M on a 256M machine that mainly

runs MySQL is quite common.  If you, however, make this too big

(more than 50% of your total memory?) your system may start to page and

become extremely slow. Remember that because MySQL does not cache

data read, that you will have to leave some room for the OS filesystem

cache.

(for instance more than 50% of your total memory) your system may start

to page and become extremely slow. Remember that because MySQL does not

cache data reads, you will have to leave some room for the OS

filesystem cache.

You can check the performance of the key buffer by doing @code{show

status} and examine the variables @code{Key_read_requests},

@code{ALTER TABLE}.

@item @code{myisam_max_extra_sort_file_size}.

If the creating of the temporary file for fast index creation would be

this much bigger than using the key cache, then prefer the key cache

method.  This is mainly used to force long character keys in large

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!

to ensure that you should always be able to login and check the system

(assuming you are not giving this privilege to all your users).

Some frequently states in @code{mysqladmin processlist}

Some states commonly seen in @code{mysqladmin processlist}

@itemize @bullet

@item @code{Checking table}

The thread doing an [automatic ?] checking of the table.

The thread is performing [automatic] checking of the table.

@item @code{Closing tables}

Means that the thread is flushing the changed table data to disk and

closing the used tables. This should be a fast operation.  If not, then

the character set into the MySQL library automatically.

The strxfrm_multiply and mbmaxlen lines will be explained in

the following sections.  Only include them if you the string

the following sections.  Only include these if you need the string

collating functions or the multi-byte character set functions,

respectively.

The GNR above means the group number. You can start, stop or report

any GNR, or several of them at the same time. (See --example) The GNRs

list can be comma separated, or a dash combined, of which the latter

list can be comma separated or combined with a dash, of which the latter

means that all the GNRs between GNR1-GNR2 will be affected. Without

GNR argument all the found groups will be either started, stopped, or

reported. Note that you must not have any white spaces in the GNR

@end example

The above test should be successful, or you may encounter problems.

@item

Beware of the dangers starting multiple @code{mysqlds} in the same data

Beware of the dangers starting multiple @code{mysqld}s in the same data

directory.  Use separate data directories, unless you @strong{know} what

you are doing!

@item

to shutdown your master server briefly to complete the steps outlined

below.

While the above method is the most straightforward way to set up a slave,

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

of the master, and

the master already has server id set and binary logging enabled, you can

Temporary tables starting in 3.23.29 are replicated properly with the

exception of the case when you shut down slave server ( not just slave thread),

you have some temporary tables open, and they are used in subsequent updates.

To deal with this problem, to shut down the slave, do @code{SLAVE STOP}, then

To deal with this problem shutting down the slave, do @code{SLAVE STOP},

check @code{Slave_open_temp_tables} variable to see if it is 0, then issue

@code{mysqladmin shutdown}. If the number is not 0, restart the slave thread

with @code{SLAVE START} and see

Because the user could issue the @code{FLUSH LOGS} command, we need to

know which log is currently active and which ones have been rotated out

and in what sequence. This information is stored in the binary log index file.

The default is @file{`hostname`.index}. You can use this option if you want to

be a rebel.

The default is @file{`hostname`.index}. You should not need to change this.

Example: @code{log-bin-index=db.index}

@item @code{master-info-file=filename} @tab

The location of the file that remembers where we left off on the master

during the replication process. The default is @file{master.info} in the data

directory.  Sasha: The only reason I see for ever changing the default

is the desire to be rebellious.

directory. You should not need to change this.

Example: @code{master-info-file=master.info}

 @tab  Available starting in Version 3.23.28. Deletes all the

replication logs that are listed in the log

index as being prior to the specified log, and removes them from the

log index, so that the given log now becomes first. Example:

log index, so that the given log now becomes the first. Example:

@example

PURGE MASTER LOGS TO 'mysql-bin.010'

@end itemize

Afterwards, follow the instructions for the case when you have a snapshot and

have records the log name and offset. You can use the same snapshot to set up

have recorded the log name and offset. You can use the same snapshot to set up

several slaves. As long as the binary logs of the master are left intact, you

can wait as long as several days or in some cases maybe a month to set up a

slave once you have the snapshot of the master. In theory the waiting gap can

@item

To tell a slave to change the master use the @code{CHANGE MASTER TO} command.

@item

A good way to keep your applications informed where the master is by

having a dynamic DNS entry for the master. With @strong{bind} you can

use @code{nsupdate} to dynamically update your DNS.

A good way to keep your applications informed as to the location of the

master is by having a dynamic DNS entry for the master.

With @code{bind} you can use @file{nsupdate} to dynamically update your DNS.

@item

You should run your slaves with the @code{log-bin} option and without

@code{log-slave-updates}. This way the slave will be ready to become a

case like that, you can expect a patch within a day or two in most cases,

although, of course, you mileage may vary depending on a number of factors.

Second best option is a just program with easily configurable connection

arguments for the master and the slave that will demonstrate the problem on our

systems. You can write one in Perl or in C, depending on which language you

know better.

The second best option is to write a simple program with easily configurable

connection arguments for the master and the slave that will demonstrate

the problem on our systems. You can write one in Perl or in C, depending

on which language you know better.

If you have one of the above ways to demonstrate the bug, use

@code{mysqlbug} to prepare a bug report and send it to

Some cases where MySQL can NOT use indexes to resolve the @code{ORDER

BY}: (Note that MySQL will still use indexes to find the rows that

matches the where clause):

matches the @code{WHERE} clause):

@itemize @bullet

@item

@code{SELECT * FROM t1 ORDER BY key1,key2}

@item

You are doing an @code{ORDER BY} on not following key parts.

You are doing an @code{ORDER BY} using non-consecutive key parts.

@code{SELECT * FROM t1 WHERE key2=constant ORDER BY key_part2}

@code{LIMIT 0} will always quickly return an empty set.  This is useful

to check the query and to get the column types of the result columns.

@item

The size of temporary tables uses the @code{LIMIT #} to calculate how much

space is needed to resolve the query.

When the server uses temporary tables to resolve the query, the

@code{LIMIT #} is used to calculate how much space is required.

@end itemize

Use @code{AUTO_INCREMENT} columns to make unique values.

@item

Use @code{OPTIMIZE TABLE} once in a while to avoid fragmentation when

using dynamic table format. @xref{OPTIMIZE TABLE, , @code{OPTIMIZE TABLE}}.

using a dynamic table format. @xref{OPTIMIZE TABLE, , @code{OPTIMIZE TABLE}}.

@item

Use @code{HEAP} tables to get more speed when possible. @xref{Table

@item

Query cache disabled in mysqldump.

@item

Fixed problem on Windows 98 that made sending of results very slow.

@item

Boolean fulltext search weighting scheme changed to something more reasonable.

@item

Fixed bug in boolean fulltext search, that caused MySQL to ignore queries of

Fixed bug in boolean fulltext search that caused MySQL to ignore queries of

@code{ft_min_word_len} characters.

@item

Boolean fulltext search now supports "phrase searches".

Boolean fulltext search now supports ``phrase searches''.

@item

New configure option @code{--without-query-cache}. 

@item

Memory allocation strategy for 'root memory' changed. Block size now grows 

Memory allocation strategy for ``root memory'' changed. Block size now grows 

with number of allocated blocks.

@item

@code{INET_NTOA()} now returns @code{NULL} if you give it an argument that

    exit(EX_MYSQLERR);

  if (opt_auto_repair &&

      init_dynamic_array(&tables4repair, sizeof(char)*(NAME_LEN*2+2),16,64))

      my_init_dynamic_array(&tables4repair, sizeof(char)*(NAME_LEN*2+2),16,64))

  {

    first_error = 1;

    goto end;

** and adapted to mysqldump 05/11/01 by Jani Tolonen

*/

#define DUMP_VERSION "9.01"

#define DUMP_VERSION "9.02"

#include <my_global.h>

#include <my_sys.h>

   0, 0},

  {"result-file", 'r',

   "Direct output to a given file. This option should be used in MSDOS, because it prevents new line '\\n' from being converted to '\\n\\r' (newline + carriage return).",

   (gptr*) &md_result_file, (gptr*) &md_result_file, 0, GET_STR, REQUIRED_ARG,

   0, 0, 0, 0, 0, 0},

   0, 0, 0, GET_STR, REQUIRED_ARG, 0, 0, 0, 0, 0, 0},

  {"socket", 'S', "Socket file to use for connection.",

   (gptr*) &opt_mysql_unix_port, (gptr*) &opt_mysql_unix_port, 0, GET_STR,

   REQUIRED_ARG, 0, 0, 0, 0, 0, 0},

    opt_xml = 1;

    opt_disable_keys=0;

    break;

  default:

    fprintf(stderr,"%s: Illegal option character '%c'\n",my_progname,opterr);

    /* Fall throught */

  case 'I':

  case '?':

    usage();

  file_stack_end = file_stack + MAX_INCLUDE_DEPTH;

  cur_file = file_stack;

  lineno   = lineno_stack;

  init_dynamic_array(&q_lines, sizeof(struct st_query*), INIT_Q_LINES,

  my_init_dynamic_array(&q_lines, sizeof(struct st_query*), INIT_Q_LINES,

		     INIT_Q_LINES);

  memset(block_stack, 0, sizeof(block_stack));

  block_stack_end = block_stack + BLOCK_STACK_DEPTH;