Style/spelling fixups, mainly of new privileges.

* TODO MySQL 4.1::              Things That Should be in 4.1

* TODO future::                 Things That Must be Done in the Near Future

* TODO sometime::               Things That Have to be Done Sometime

* TODO unplanned::              Things We Have No Plans to do

* TODO unplanned::              Things We Don't Plan To Do

@end menu

This appendix lists the features that we plan to implement in MySQL Server.

@node TODO future, TODO sometime, TODO MySQL 4.1, TODO

@subsection Things That Must be Done in the Real Near Future

@subsection Things That Must be Done in the Near Future

@itemize @bullet

@item

@node TODO unplanned,  , TODO sometime, TODO

@subsection Things We Have No Plans to do

@subsection Things We Don't Plan To Do

@itemize @bullet

@item

@xref{GRANT}.

To get these new privileges to work, one must run the

@code{mysql_fix_privilege_tables} scripts.  Until this script is run all

users have the @code{SHOW DATABASES}, @code{CREATE TEMPORARY TABLES},

and @code{LOCK TABLES} privileges. @code{SUPER} and @code{EXECUTE}

privileges takes their value from @code{PROCESS}. @code{REPLICATION

SLAVE} and @code{REPLICATION CLIENT} takes their values from

@code{FILE}.

@code{mysql_fix_privilege_tables} script.  Until this script is run all

users have the @strong{show databases}, @strong{create temporary tables},

and @strong{lock tables} privileges. @strong{super} and @strong{execute}

privileges take their value from @strong{process}.

@strong{replication slave} and @code{replication client} take their

values from @strong{file}.

If you have any scripts that creates new users, you may want to change

them to use the new privileges.  If you are not using @code{GRANT}

commands in the scripits, this is a good time to change the scripts...

commands in the scripts, this is a good time to change your scripts.

In 4.0.2 the option @code{--safe-show-database} doesn't do anything and

should not be used. @xref{Privileges options}.

In version 4.0.2 the option @code{--safe-show-database} is deprecated

(and no longer does anything). @xref{Privileges options}.

If you get access denied errors for new users with MySQL 4.0.2, you

If you get access denied errors for new users in version 4.0.2, you

should check if you need some of the new grants that you didn't need

before.  In particular, you will need @code{REPLICATION SLAVE} (instead

of @code{FILE}) for new slaves.

before.  In particular, you will need @strong{replication slave}

(instead of @strong{file}) for new slaves.

@item

@code{DOUBLE} and @code{FLOAT} columns are now honoring the

@code{UNSIGNED} flag on storage (before, @code{UNSIGNED} was ignored for

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

can build a better binary next time. For a typical user, even for setups with

a lot of concurrent connections and/or tables exceeding 2GB limit, our

a lot of concurrent connections and/or tables exceeding the 2G limit, our

binary in most cases is the best choice.

MySQL uses LinuxThreads on Linux.  If you are using an old

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 2G 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

@file{C:\my.cnf} file instead.

@item

It would be real nice to be able to kill @code{mysqld} from the task manager.

It would be really nice to be able to kill @code{mysqld} from the task manager.

For the moment, you must use @code{mysqladmin shutdown}.

@item

FreeBSD 3.x is recommended for running MySQL since the thread package

is much more integrated.

The easiest and therefor the preferred way to install is to use the

The easiest and therefore the preferred way to install is to use the

mysql-server and mysql-client ports available on

@uref{http://www.freebsd.org/}.

privileges.  The @code{test} database is often provided as a workspace for

users to try things out.

Note that you may not see all databases if you don't have the @code{SHOW

DATABASES} privilege. @xref{GRANT}.

Note that you may not see all databases if you don't have the

@strong{show databases} privilege. @xref{GRANT}.

If the @code{test} database exists, try to access it:

Skip some optimise stages.  Implies @code{--skip-delay-key-write}.

@item --safe-show-database

Don't show databases for which the user doesn't have any privileges.

With this option, the @code{SHOW DATABASES} command returns only those

databases for which the user has some kind of privilege.

From version 4.0.2 this option is deprecated and doesn't do anything

(the option is enabled by default) as we now have the

@strong{show databases} privilege. @xref{GRANT}.

@item --safe-user-create

If this is enabled, a user can't create new users with the GRANT

need memory checking, by using this option.

@item --skip-show-database

Don't allow 'SHOW DATABASE' commands, unless the user has the

@strong{SHOW DATABASE} privilege.  In 4.0.2 this command should not be

need anymore.

Don't allow @code{SHOW DATABASES} command, unless the user has the

@strong{show databases} privilege. From version 4.0.2 you should no longer

need this option, since access can now be granted specifically with the

@strong{show databases} privilege.

@item --skip-stack-trace

Don't write stack traces.  This option is useful when you are running

INFILE}.

@item --safe-show-database

With this option, @code{SHOW DATABASES} returns only those databases for

which the user has some kind of privilege. In 4.0.2 this command doesn't

do anything (the option is enabled by default) as we now have the

@code{SHOWS DATABASES} privilege. @xref{GRANT}.

With this option, the @code{SHOW DATABASES} command returns only those

databases for which the user has some kind of privilege.

From version 4.0.2 this option is deprecated and doesn't do anything

(the option is enabled by default) as we now have the

@strong{show databases} privilege. @xref{GRANT}.

@item --safe-user-create

If this is enabled, an user can't create new users with the @code{GRANT}

support Unix sockets.

@item --skip-show-database

With this option, the

@code{SHOW DATABASES} statement doesn't return anything.

Don't allow @code{SHOW DATABASES} command, unless the user has the

@strong{show databases} privilege. From version 4.0.2 you should no longer

need this option, since access can now be granted specifically with the

@strong{show databases} privilege.

@end table

and under the circumstances indicated in @ref{Privilege changes}.

The names used in this manual to refer to the privileges provided by

MySQL 4.0.2 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:

MySQL version 4.0.2 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:

@c FIX agl 2002-06-13 Long items added, will need to re-measure colwidths!

@multitable @columnfractions .15 .20 .35

@item @strong{Privilege}   @tab @strong{Column}      @tab @strong{Context}

@item @strong{alter}       @tab @code{Alter_priv}    @tab tables

The @code{processlist} command displays information about the threads

executing within the server.  The @code{kill} command kills server

threads.  You can always display or kill your own threads, but you need

the @strong{PROCESS} privilege to display and @code{SUPER} privilege to

the @strong{process} privilege to display and @strong{super} privilege to

kill threads initiated by other users. @xref{KILL}.

It is a good idea in general to grant privileges only to those users who need

For the @code{GRANT} and @code{REVOKE} statements, @code{priv_type} may be

specified as any of the following:

@c FIX agl 2002-06-13 New table, need to measure colwidths!

@multitable @columnfractions .30 .70

@item @code{ALL [PRIVILEGES]} @tab Sets all simple privileges except @code{WITH GRANT OPTION}

@item @code{ALTER}  @tab Allows usage of @code{ALTER TABLE}

@item @code{USAGE} @tab Synonym for ``no privileges.''

@end multitable

@code{USAGE} can be used when you want to create a user that has no privileges.

@strong{usage} can be used when you want to create a user that has no privileges.

The privileges @code{CREATE TEMPORARY TABLE}, @code{EXECUTE},

@code{LOCK TABLES}, @code{REPLICATION ...}, @code{SHOW DATABASES} and

@code{SUPER} are new for MySQL 4.0.2.  To use these, after upgrading to

4.0.2, one has to run the @code{mysql_fix_privilege_tables} script.

The privileges @strong{create temporary table}, @strong{execute},

@strong{lock tables}, @strong{replication ...}, @strong{show databases} and

@strong{super} are new for in version 4.0.2.  To use these new privileges

after upgrading to 4.0.2, you have to run the

@code{mysql_fix_privilege_tables} script.

In older MySQL versions, the @code{PROCESS} privilege gave the same rights

as the new @code{SUPER} privilege.

In older MySQL versions, the @strong{process} privilege gives the same

rights as the new @strong{super} privilege.

To revoke the @strong{grant} privilege from a user, use a @code{priv_type}

value of @code{GRANT OPTION}:

users with different privileges may be able to join privileges!

@code{MAX_QUERIES_PER_HOUR #}, @code{MAX_UPDATES_PER_HOUR #} and

@code{MAX_CONNECTIONS_PER_HOUR #} are new in MySQL 4.0.2.  They limit

the number of queries/updates and logins the user can do during one

hour. If @code{#} is 0 (default), then this means that there is no

limitations for the user. @xref{User resources}.

@code{MAX_CONNECTIONS_PER_HOUR #} are new in MySQL version 4.0.2.

These options limit the number of queries/updates and logins the user can

do during one hour. If @code{#} is 0 (default), then this means that there

are no limitations for that user. @xref{User resources}.

You cannot grant another user a privilege you don't have yourself;

the @strong{grant} privilege allows you to give away only those privileges

@item admin

A user who can connect from @code{localhost} without a password and who is

granted the @strong{reload} and @strong{PROCESS} administrative privileges.

granted the @strong{reload} and @strong{process} administrative privileges.

This allows the user to execute the @code{mysqladmin reload},

@code{mysqladmin refresh}, and @code{mysqladmin flush-*} commands, as well as

@code{mysqladmin processlist} .  No database-related privileges are granted.

which threads are running with the @code{SHOW PROCESSLIST} command and kill

a thread with the @code{KILL thread_id} command.

If you have the @strong{PROCESS} privilege, you can see all threads.

If you have the @code{SUPER} privilege you can kill all threads.

Otherwise, you can see and kill only your own threads.

If you have the @strong{process} privilege, you can see all threads.

If you have the @strong{super} privilege, you can kill all threads.

Otherwise, you can only see and kill your own threads.

You can also use the @code{mysqladmin processlist} and @code{mysqladmin kill}

commands to examine and kill threads.

mysql> SHOW INDEX FROM mydb.mytable;

@end example

@code{SHOW DATABASES} lists the databases on the MySQL server host.  You

can also get this list using the @code{mysqlshow} command.  In MySQL

4.0.2 you will only see those databases for which you have some kind of

privilege, if you don't have the global @code{SHOW DATABASES} privilege.

@code{SHOW DATABASES} lists the databases on the MySQL server host.

You can also get this list using the @code{mysqlshow} command line tool.

In version 4.0.2 you will only see those databases for which you have some

kind of privilege, if you don't have the global @strong{show databases}

privilege.

@code{SHOW TABLES} lists the tables in a given database.  You can also

get this list using the @code{mysqlshow db_name} command.

@item @code{skip_show_database}

This prevents people from doing @code{SHOW DATABASES} if they don't have

the @strong{PROCESS} privilege. This can improve security if you're

the @strong{process} privilege. This can improve security if you're

concerned about people being able to see what databases other users

have. See also @code{safe_show_database}.

@cindex threads, display

@cindex processes, display

@code{SHOW [FULL] PROCESSLIST} shows you which threads are running.  You can

also get this information using the @code{mysqladmin processlist}

command.  If you have the @strong{SUPER} privilege, you can see all

threads.  Otherwise, you can see only your own threads.  @xref{KILL, ,

@code{KILL}}.  If you don't use the @code{FULL} option, then only

the first 100 characters of each query will be shown.

@code{SHOW [FULL] PROCESSLIST} shows you which threads are running.

You can also get this information using the @code{mysqladmin processlist}

command.  If you have the @strong{super} privilege, you can see all

threads.  Otherwise, you can see only your own threads.

@xref{KILL, ,@code{KILL}}.

If you don't use the @code{FULL} option, then only the first 100

characters of each query will be shown.

This command is very useful if you get the 'too many connections' error

message and want to find out what's going on. MySQL reserves

one extra connection for a client with the @strong{SUPER} privilege

one extra connection for a client with the @strong{super} privilege

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

in the latest release.

@item

Set up special a replication user on the master with the @code{FILE} (in

MySQL versions older than 4.0.2) or @code{REPLICATION SLAVE} privilege

in newer MySQL versions.  You must also gived permission to connect from

all the slaves. If the user is only doing replication (which is

recommended), you don't need to grant any additional privileges.

Set up special a replication user on the master with the @strong{file}

(in MySQL versions older than 4.0.2) or @strong{replication slave}

privilege in newer MySQL versions.  You must also have given permission

to connect from all the slaves. If the user is only doing replication

(which is recommended), you don't need to grant any additional privileges.

For example, to create a user named @code{repl} which can access your

master from any host, you might use this command:

@item

Starting in Version 3.23.16, @code{SET SQL_LOG_BIN = 0} will turn off

replication (binary) logging on the master, and @code{SET SQL_LOG_BIN =

1} will turn it back on -- you must have the @strong{SUPER} (in MySQL

4.0.2 and above) or @strong{PROCESS} (in older MySQL versions) privilege

1} will turn it back on -- you must have the @strong{super} (in MySQL

4.0.2 and above) or @strong{process} (in older MySQL versions) privilege

to do this.

@item

Starting in Version 3.23.19, you can clean up stale replication leftovers when

 @tab Stops the slave thread. (Slave)

@item @code{SET SQL_LOG_BIN=0}

@tab Disables update logging if the user has the @strong{SUPER} privilege.

@tab Disables update logging if the user has the @strong{super} privilege.

 Ignored otherwise. (Master)

@item @code{SET SQL_LOG_BIN=1}

 @tab Re-enables update logging if the user has the @strong{SUPER} privilege.

 @tab Re-enables update logging if the user has the @strong{super} privilege.

 Ignored otherwise. (Master)

@item @code{SET SQL_SLAVE_SKIP_COUNTER=n}

@item SQL_LOG_OFF = 0 | 1

If set to @code{1}, no logging will be done to the standard log for this

client, if the client has the @strong{SUPER} privilege.  This does not

client, if the client has the @strong{super} privilege.  This does not

affect the update log!

@item SQL_LOG_UPDATE = 0 | 1

If set to @code{0}, no logging will be done to the update log for the client,

if the client has the @strong{SUPER} privilege.  This does not affect the

if the client has the @strong{super} privilege.  This does not affect the

standard log!

@item SQL_QUOTE_SHOW_CREATE = 0 | 1

the first byte of the encrypted string to determine the DES key number

that was used to encrypt the original string, then reads the key

from the @code{des-key-file} to decrypt the message.  For this to work

the user must have the @strong{SUPER} privilege.

the user must have the @strong{super} privilege.

If you pass this function a @code{key_string} argument, that string

is used as the key for decrypting the message.

connections can both use the same temporary table name without conflicting

with each other or with an existing table of the same name. (The existing table

is hidden until the temporary table is deleted.).  In MySQL 4.0.2 one must

have the @code{CREATE TEMPORARY TABLE} privilege to be able to create

have the @strong{create temporary table} privilege to be able to create

temporary tables.

In MySQL Version 3.23 or later, you can use the keywords

thread issues another @code{LOCK TABLES}, or when the connection to the

server is closed.

To use @code{LOCK TABLES} in MySQL 4.0.2 you need the global @code{LOCK

TABLES} privilege and a @code{SELECT} privilege on the involved tables.

In MySQL 3.23 you need to have @code{SELECT}, @code{INSERT},

@code{DELETE} and @code{UPDATE} privileges for the tables.

To use @code{LOCK TABLES} in MySQL 4.0.2 you need the global

@strong{lock tables} privilege and a @strong{select} privilege on the

involved tables. In MySQL 3.23 you need to have @strong{select},

@code{insert}, @strong{delete} and @strong{update} privileges for the

tables.

The main reasons to use @code{LOCK TABLES} are for emulating transactions

or getting more speed when updating tables.  This is explained in more

The default behavior is to set the isolation level for the next (not

started) transaction.  If you use the @code{GLOBAL} keyword, the statement

sets the default transaction level globally for all new connections

created from that point on.  You will need the @strong{SUPER}

created from that point on.  You will need the @strong{super}

privilege to do do this.  Using the @code{SESSION} keyword sets the

default transaction level for all future transactions performed on the

current connection.

different @code{MERGE} tables active, with possible overlapping files.

@item

More efficient repairs. It's easier to repair the individual files that

are mapped to a @code{MERGE} file than trying to repair a real big file.

are mapped to a @code{MERGE} file than trying to repair a really big file.

@item

Instant mapping of many files as one. A @code{MERGE} table uses the

index of the individual tables. It doesn't need to maintain an index of

The foreign key constraints are listed in the table comment of

the output.

InnoDB does not yet support @code{ON DELETE CASCADE}

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

From version 3.23.50 and 4.0.2 you can specify the last InnoDB datafile

to @code{autoextend}. Alternatively, you can increase to your tablespace

by specifying an additional datafile. To do this you have to shut down

the MySQL server, edit the @file{my.cnf} file adding a new datafile

to @code{innodb_data_file_path}, and then start the MySQL server again.

Currently you cannot remove a datafile from InnoDB. To decrease the

size of your database you have to use @file{mysqldump} to dump

@subsubheading Description

Instructs the server to write some debug information to the log.  The

connected user must have the @strong{SUPER} privilege for this to work.

Instructs the server to write some debug information to the log. For

this to work, the connected user must have the @strong{super} privilege.

@subsubheading Return Values

Note that @code{mysqld} actually allows (@code{max_connections}+1)

clients to connect.  The last connection is reserved for a user with the

@strong{SUPER} privilege.  By not giving this privilege to normal

@strong{super} privilege.  By not giving this privilege to normal

users (they shouldn't need this), an administrator with this privilege

can log in and use @code{SHOW PROCESSLIST} to find out what could be

wrong. @xref{SHOW}.

@itemize @bullet

@item

You are using an older MySQL versions ( < 3.23.0) when an in-memory

temporary table becomes larger than @code{tmp_table_size} bytes. To

avoid this problem, you can use the @code{-O tmp_table_size=#} option to

@code{mysqld} to increase the temporary table size or use the SQL option

@code{SQL_BIG_TABLES} before you issue the problematic query. @xref{SET

OPTION, , @code{SET OPTION}}.

You are using an older MySQL version (before 3.23.0) when an in-memory

temporary table becomes larger than @code{tmp_table_size} bytes.

To avoid this problem, you can use the @code{-O tmp_table_size=#} option

to make @code{mysqld} increase the temporary table size or use the SQL

option @code{SQL_BIG_TABLES} before you issue the problematic query.

@xref{SET OPTION, ,@code{SET OPTION}}.

You can also start @code{mysqld} with the @code{--big-tables} option.

This is exactly the same as using @code{SQL_BIG_TABLES} for all queries.

converted to a disk-based @code{MyISAM} table after the table size gets

bigger than @code{tmp_table_size}.

@item

You are using InnoDB tables and run out of room in the InnoDB tablespace.

In this case the solution is to add extend the InnoDB table space.

You are using @code{InnoDB} tables and run out of room in the

@code{InnoDB} tablespace. In this case the solution is to extend the

@code{InnoDB} tablespace.

@item

You are using ISAM/MyISAM tables on a OS that only supports 2G files

and you have hit this limit for the data or index file.

You are using @code{ISAM} or @code{MyISAM} tables on an OS that only

supports files of 2G in size and you have hit this limit for the data

or index file.

@item

You are using MyISAM tables and the needed data or index size is bigger

than what MySQL has allocated pointers for.  (If you don't specify

You are using @code{MyISAM} tables and the needed data or index size is

bigger than what MySQL has allocated pointers for.  (If you don't specify

@code{MAX_ROWS} to @code{CREATE TABLE} MySQL will only allocate pointers

to hold 4G of data).

One can check the maximum data/index sizes by doing @code{SHOW TABLE

STATUS FROM database LIKE 'table_name} or using @code{myisamchk -dv

database/table_name}.

You can check the maximum data/index sizes by doing

@example

SHOW TABLE STATUS FROM database LIKE 'table_name';

@end example

or using @code{myisamchk -dv database/table_name}.

If this is the problem, you can fix it by doing something like:

@code{ALTER TABLE table_name MAX_ROWS=1000000000 AVG_ROW_LENGTH=XXX}.

@example

ALTER TABLE table_name MAX_ROWS=1000000000 AVG_ROW_LENGTH=nnn;

@end example

You only have to specify @code{AVG_ROW_LENGTH} for tables with BLOB/TEXT

fields as in this case MySQL can't optimise the needed space just based

on the number of rows.

fields as in this case MySQL can't optimise the space required based

only on the number of rows.

@end itemize

@itemize @bullet

@item

Added privileges @code{CREATE TEMPORARY TABLE}, @code{LOCK TABLES},

@code{REPLICATION CLIENT}, @code{REPLICATION SLAVE}, @code{SHOW

DATABASES} and @code{SUPER}. To use these, one must run the

@code{mysql_fix_privilege_tables}.

Added privileges @strong{create temporary table}, @strong{lock tables},

@strong{replication client}, @strong{replication slave},

@strong{show databases} and @strong{super}. To use these, you must have

run the @code{mysql_fix_privilege_tables} script after upgrading.

@item

Fixed query cache align data bug.

@item

and when using keys.

@item

You can now use @code{mysqladmin proc} to display information about your own

threads. Only users with the @strong{PROCESS} privilege can get

information about all threads. (In 4.0.2 one need the @strong{SUPER} privilege for this.)

threads. Only users with the @strong{process} privilege can get

information about all threads.

(In 4.0.2 one needs the @strong{super} privilege for this.)

@item

Added handling of formats @code{YYMMDD}, @code{YYYYMMDD},

@code{YYMMDDHHMMSS} for numbers when using @code{DATETIME} and