Merge work:/home/bk/mysql-4.0 into donna.mysql.fi:/home/my/bk/mysql-4.0

heikki@donna.mysql.fi

jani@hynda.mysql.fi

jani@janikt.pp.saunalahti.fi

jcole@abel.spaceapes.com

jcole@main.burghcom.com

jcole@tetra.spaceapes.com

* InnoDB overview::             InnoDB tables overview

* InnoDB start::                InnoDB startup options

* Creating an InnoDB database:: Creating an InnoDB database.

* InnoDB init::                 Creating InnoDB table space.

* Using InnoDB tables::         Creating InnoDB tables

* Adding and removing::         Adding and removing InnoDB data and log files

* Backing up::                  Backing up and recovering an InnoDB database

* InnoDB restrictions::         Some restrictions on InnoDB tables

* InnoDB contact information::  InnoDB contact information. 

Creating an InnoDB database

Creating InnoDB table space

* Error creating InnoDB::      

* MySQL threads::               MySQL threads

* MySQL test suite::            MySQL test suite

MySQL Test Suite

* running mysqltest::           

* extending mysqltest::         

* Reporting mysqltest bugs::    

Credits

* Developers::                  

@node Windows symbolic links, Windows compiling, Windows and SSH, Windows

@subsection Splitting Data Across Different Disks on Windows

Beginning with @strong{MySQL} Version 3.23.16, the @strong{MySQL}

distribution is compiled with the @code{-DUSE_SYMDIR} option.  This allows

you to put a database on different disk by adding a symbolic link to it

Beginning with @strong{MySQL} Version 3.23.16, the @code{mysqld-max}

and @code{mysql-max-nt} servers in the @strong{MySQL} distribution are

compiled with the @code{-DUSE_SYMDIR} option.  This allows you to put a

database on different disk by adding a symbolic link to it

(in a manner similar to the way that symbolic links work on Unix).

On Windows, you make a symbolic link to a database by creating a file

Ignore the @code{delay_key_write} option for all tables.

@xref{Server parameters}.

@item -Sg, --skip-grant-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

server to start using the grant tables again by executing @code{mysqladmin

@menu

* InnoDB overview::             InnoDB tables overview

* InnoDB start::                InnoDB startup options

* Creating an InnoDB database:: Creating an InnoDB database.

* InnoDB init::                 Creating InnoDB table space.

* Using InnoDB tables::         Creating InnoDB tables

* Adding and removing::         Adding and removing InnoDB data and log files

* Backing up::                  Backing up and recovering an InnoDB database

InnoDB is distributed under the GNU GPL License Version 2 (of June 1991).

In the source distribution of @strong{MySQL}, InnoDB appears as a subdirectory.

@node InnoDB start, Creating an InnoDB database, InnoDB overview, InnoDB

@node InnoDB start, InnoDB init, InnoDB overview, InnoDB

@subsection InnoDB startup options

Beginning from @strong{MySQL}-3.23.37 the prefix of the options is changed

resolve the situation.

@end multitable

@node Creating an InnoDB database, Using InnoDB tables, InnoDB start, InnoDB

@subsection Creating an InnoDB database

@node InnoDB init, Using InnoDB tables, InnoDB start, InnoDB

@subsection Creating InnoDB table space

Suppose you have installed @strong{MySQL} and have edited @file{my.cnf} so that

it contains the necessary InnoDB configuration parameters.

* Error creating InnoDB::      

@end menu

@node Error creating InnoDB,  , Creating an InnoDB database, Creating an InnoDB database

@node Error creating InnoDB,  , InnoDB init, InnoDB init

@subsubsection If something goes wrong in database creation

If something goes wrong in an InnoDB database creation, you should

files for these tables from the @strong{MySQL} database

directories. Then you can try the InnoDB database creation again.

@node Using InnoDB tables, Adding and removing, Creating an InnoDB database, InnoDB

@node Using InnoDB tables, Adding and removing, InnoDB init, InnoDB

@subsection Creating InnoDB tables

Suppose you have started the @strong{MySQL} client with the command

to think of real-world situations in which a similar type of database might

be used.  For example, a database like this could be used by a farmer to keep

track of livestock, or by a veterinarian to keep track of patient records.

A menagerie distribution containing some of the queries and sample data used

in the following sections can be obtained from the @strong{MySQL} Web site.

It's available in either

@uref{http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz,compressed @code{tar} format}

or

@uref{http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip,Zip format}.

Use the @code{SHOW} statement to find out what databases currently exist

on the server:

Add one line to @file{lex.h} that defines the function name in the

@code{sql_functions[]} array.

@item

Add two lines to @file{sql_yacc.yy}. One indicates the preprocessor

symbol that @code{yacc} should define (this should be added at the

beginning of the file). Then define the function parameters and add an

``item'' with these parameters to the @code{simple_expr} parsing rule.

For an example, check all occurrences of @code{SOUNDEX} in

@file{sql_yacc.yy} to see how this is done.

If the function prototype is simple (just takes zero, one, two or three

arguments), you should in lex.h specify SYM(FUNC_ARG#) (where # is the

number of arguments) as the second argument in the

@code{sql_functions[]} array and add a function that creates a function

object in @file{item_create.cc}.  Take a look at @code{"ABS"} and

@code{create_funcs_abs()} for an example of this.

If the function prototype is complicated (for example takes a variable number

of arguments), you should add two lines to @file{sql_yacc.yy}. One

indicates the preprocessor symbol that @code{yacc} should define (this

should be added at the beginning of the file). Then define the function

parameters and add an ``item'' with these parameters to the

@code{simple_expr} parsing rule.  For an example, check all occurrences

of @code{ATAN} in @file{sql_yacc.yy} to see how this is done.

@item

In @file{item_func.h}, declare a class inheriting from @code{Item_num_func} or

@code{Item_str_func}, depending on whether your function returns a number or a

longlong Item_func_newname::val_int()

String  *Item_func_newname::Str(String *str)

@end example

If you inherit your object from any of the standard items (like

@code{Item_num_func} you probably only have to define one of the above

functions and let the parent object take care of the other functions.

For example, the @code{Item_str_func} class defines a @code{val()} function

that executes @code{atof()} on the value returned by @code{::str()}.

@item

You should probably also define the following function:

You should probably also define the following object function:

@example

void Item_func_newname::fix_length_and_dec()

@end example

This function should at least calculate @code{max_length} based on the

given arguments. @code{max_length} is the maximum number of characters

the function may return.  This function should also set @code{maybe_null = 0}

if the main function can't return a @code{NULL} value.  The function can check

if any of the function arguments can return @code{NULL} by checking the

arguments @code{maybe_null} variable.

the function may return.  This function should also set @code{maybe_null

= 0} if the main function can't return a @code{NULL} value.  The

function can check if any of the function arguments can return

@code{NULL} by checking the arguments @code{maybe_null} variable. You

can take a look at @code{Item_func_mod::fix_length_and_dec} for a

typical example of how to do this.

@end enumerate

All functions must be thread safe.

All functions must be thread safe (In other words, don't use any global or

static variables in the functions without protecting them with mutexes).

If you want to return @code{NULL}, from @code{::val()}, @code{::val_int()}

or @code{::str()} you should set @code{null_value} to 1 and return 0.

For @code{::str()} object functions, there are some additional

considerations to be aware of:

For string functions, there are some additional considerations to be aware of:

@itemize @bullet

@item

The @code{String *str} argument provides a string

buffer that may be used to hold the result.

The @code{String *str} argument provides a string buffer that may be

used to hold the result. (For more information about the @code{String} type,

take a look at the @file{sql_string.h} file.)

@item

The function should return the string that holds the result.

The @code{::str()} function should return the string that holds the result or

@code{(char*) 0} if the result is @code{NULL}.

@item

All current string functions try to avoid allocating any memory unless

absolutely necessary!

address this problem, we have created a new test system that is included in

the source and binary distributions starting in Version 3.23.29.

The test system consist of a test language interpreter (@code{mysqltest}),

a shell script to run all tests(@code{mysql-test-run}), the actual test cases

written in a special test language, and their expected results.  To run the

test suite on your system after a build, type @code{mysql-test/mysql-test-run}

from the source root.  If you have installed a binary distribution, @code{cd}

to the install root (eg. @code{/usr/local/mysql}), and do

@code{scripts/mysql-test-run}.  All tests should succeed.  If they do not,

use @code{mysqlbug} to send a bug report to @email{bugs@@lists.mysql.com}.

Make sure to include the output of @code{mysql-test-run}, as well as

contents of all @code{.reject} files in @code{mysql-test/r} directory.

The current set of test cases doesn't test everything in MySQL but, it

should catch most obvious bugs in the SQL processing code, OS/library

issues, and is quite thorough in testing replication.  Our eventual goal

is to have the tests cover 100% of the code.  We welcome contributions

to our test suite.  You may especially want to contribute tests that

examine the functionality critical to your system, as this will ensure

that all future @strong{MySQL} releases will work well with your

applications.

@menu

* running mysqltest::           

* extending mysqltest::         

* Reporting mysqltest bugs::    

@end menu

@node running mysqltest, extending mysqltest, MySQL test suite, MySQL test suite

@subsection Running the MySQL Test Suite

The test system consist of a test language interpreter

(@code{mysqltest}), a shell script to run all

tests(@code{mysql-test-run}), the actual test cases written in a special

test language, and their expected results.  To run the test suite on

your system after a build, type @code{make test} or

@code{mysql-test/mysql-test-run} from the source root.  If you have

installed a binary distribution, @code{cd} to the install root

(eg. @code{/usr/local/mysql}), and do @code{scripts/mysql-test-run}.

All tests should succeed.  If not, you should try to find out why and

report the problem if this is a bug in @strong{MySQL}.

@xref{Reporting mysqltest bugs}.

If you have a copy of @code{mysqld} running on the machine where you want to

run the test suite you do not have to stop it, as long as it is not using

edit @code{mysql-test-run} and change the values of the master and/or slave

port to one that is available.

The current set of test cases is far from comprehensive, as we have not yet

converted all of our private tests to the new format.  However, it should 

already catch most obvious bugs in the SQL processing code, OS/library issues,

and is quite thorough in testing replication.  Our eventual goal is to have 

the tests cover 100% of the code.  We welcome contributions to our test suite.

You may especially want to contribute tests that examine the functionality 

critical to your system, as this will ensure that all future @strong{MySQL} 

releases will work well with your applications.

You can run one individual test case with

@code{mysql-test/mysql-test-run test_name}.

If one test fails, you should test running @code{mysql-test-run} with

the @code{--force} option to check if any other tests fails.

@node extending mysqltest, Reporting mysqltest bugs, running mysqltest, MySQL test suite

@subsection Extending the MySQL Test Suite

You can use the @code{mysqltest} language to write your own test cases.

Unfortunately, we have not yet written full documentation for it - we plan to

them as an example.  The following points should help you get started:

@itemize

@item

The tests are located in @code{mysql-test/t/*.test}

@item

You can run one individual test case with

@code{mysql-test/mysql-test-run test_name}

removing @code{.test} extension from the file name

@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

@code{test_name.b.result}, etc.

@item

Failed test results are put in a file with the same base name as the

result file with the @code{.reject} extension.  If your test case is

failing, you should do a diff on the two files.  If you cannot see how

they are different, examine both with @code{od -c} and also check their

lengths.

@item

You can prefix a query with @code{!} if the test can continue after that query

returns an error.

If a statement returns an error, you should on the line before the statement

specify with the @code{--error error-number}.  The error number can be

a list of possible error numbers separated with @code{','}.

@item

If you are writing a replication test case, you should on the first line of

@end itemize

@node Reporting mysqltest bugs,  , extending mysqltest, MySQL test suite

@subsection Extending the MySQL Test Suite

If your @strong{MySQL} version doesn't pass the test suite you should

do the following:

what when wrong!  When you do it, please use the @code{mysqlbug} script

so that we can get information about your system and @code{MySQL}

version. @xref{Bug reports}.

@item

Make sure to include the output of @code{mysql-test-run}, as well as

contents of all @code{.reject} files in @code{mysql-test/r} directory.

@item

If a test in the test suite fails, check if the test fails also when run

by its own:

@example

cd mysql-test

mysql-test-run --local test-name

@end example

If this fails, then you should configure @strong{MySQL} with

@code{--with-debug} and run @code{mysql-test-run} with the

@code{--debug} option. If this also fails send the trace file

@file{var/tmp/master.trace} to ftp://support.mysql.com/pub/mysql/secret

so that we can examine it. Please remember to also include a full

description of your system, the version of the mysqld binary and how you

compiled it.

@item

If you have compiled @strong{MySQL} yourself, check our manual for how

to compile @strong{MySQL} on your platform or, preferable, use one of

If you get an error, like @code{Result length mismatch} or @code{Result

content mismatch} it means that the output of the test didn't match

exactly the expected output. This could be a bug in @strong{MySQL} or

that your @code{mysqld} version produces slightly different results under some

circumstances. In this case, you should compare the @file{.test}

and @file{.reject} file in the @file{mysql-test/r} sub directory to

see if this is something to worry about.

that your mysqld version produces slight different results under some

circumstances.

Failed test results are put in a file with the same base name as the

result file with the @code{.reject} extension.  If your test case is

failing, you should do a diff on the two files.  If you cannot see how

they are different, examine both with @code{od -c} and also check their

lengths.

@item

If a test fails totally, you should check the logs file in the

@item

If you have compiled @strong{MySQL} with debugging you can try to debug this

with the @code{--gdb} and @code{--debug} options to @code{mysql-test-run}.

by running @code{mysql-test-run} with the @code{--gdb} and/or @code{--debug}

options.

@xref{Making trace files}.

If you have not compiled @strong{MySQL} for debugging you should probably

Windows GUI (binary only) to administrate a database, by David B. Mansel,

@email{david@@zhadum.org}.

@item @uref{http://members.xoom.com/_opex_/mysqlmanager/index.html, MySQL Manager}

a graphical MySQL server manager for MySQL server written in Java, for Windows

@item @uref{http://www.mysql.com/Downloads/Win32/netadmin.zip, netadmin.zip}

An administrator tool for @strong{MySQL} on Windows 95/98 and Windows NT

4.0. Only tested with @strong{MySQL} Versions 3.23.5 - 3.23.7. Written

@appendixsubsec Changes in release 3.23.39

@itemize @bullet

@item

Fixed that date-part extract functions works with dates where day

and/or month is 0.

@item

Extended argument length in option files from 256 to 512 chars.

@item

Fixed problem with shutdown when @code{INSERT DELAYED} was waiting for

extern ulint	srv_lock_wait_timeout;

extern char*    srv_unix_file_flush_method_str;

extern ulint    srv_unix_file_flush_method;

extern ibool    srv_set_thread_priorities;

extern int      srv_query_thread_priority;

/* The server system */

extern srv_sys_t*	srv_sys;

/* Alternatives for fiel flush option in Unix; see the InnoDB manual about

what these mean */

#define SRV_UNIX_FDATASYNC   1

#define SRV_UNIX_O_DSYNC     2

#define SRV_UNIX_LITTLESYNC  3

#define SRV_UNIX_NOSYNC      4

/*************************************************************************

Boots Innobase server. */

		/* It was a checkpoint write */

		group = (log_group_t*)((ulint)group - 1);

		if (srv_unix_file_flush_method == SRV_UNIX_LITTLESYNC) {

		        fil_flush(group->space_id);

		}

		log_io_complete_checkpoint(group);

		return;

	}

	if (srv_unix_file_flush_method == SRV_UNIX_LITTLESYNC) {

	        fil_flush(group->space_id);

	}

	mutex_enter(&(log_sys->mutex));

		recv_apply_hashed_log_recs(TRUE);

	}

	if (srv_unix_file_flush_method == SRV_UNIX_LITTLESYNC) {

	        fil_flush_file_spaces(FIL_TABLESPACE);

	}

	mutex_enter(&(log_sys->mutex));

#include "os0file.h"

#include "os0sync.h"

#include "ut0mem.h"

#include "srv0srv.h"

#ifdef POSIX_ASYNC_IO

	UT_NOT_USED(purpose);

	/* On Linux opening a file in the O_SYNC mode seems to be much

        more efficient for small writes than calling an explicit fsync or

	fdatasync after each write, but on Solaris O_SYNC and O_DSYNC is

	extremely slow in large block writes to a big file. Therefore we

	do not use these options, but use explicit fdatasync. */

#ifdef O_DSYNC

	if (srv_unix_file_flush_method == SRV_UNIX_O_DSYNC) {

	        create_flag = create_flag | O_DSYNC;

	}

#endif

	if (create_mode == OS_FILE_CREATE) {

	        file = open(name, create_flag, S_IRUSR | S_IWUSR | S_IRGRP

			                     | S_IWGRP | S_IROTH | S_IWOTH);

#else

	int	ret;

#ifdef O_DSYNC

	if (srv_unix_file_flush_method == SRV_UNIX_O_DSYNC) {

	        return(TRUE);

	}

#endif

#ifdef HAVE_FDATASYNC

	ret = fdatasync(file);

#else

#ifdef HAVE_PWRITE

	ret = pwrite(file, buf, n, offs);

	/* Always do fsync to reduce the probability that when the OS crashes,

	a database page is only partially physically written to disk. */

	if (srv_unix_file_flush_method != SRV_UNIX_LITTLESYNC

	    && srv_unix_file_flush_method != SRV_UNIX_NOSYNC) {

	        /* Always do fsync to reduce the probability that when

                the OS crashes, a database page is only partially

                physically written to disk. */

	        ut_a(TRUE == os_file_flush(file));

	}

        return(ret);

#else

	ret = write(file, buf, n);

	/* Always do fsync to reduce the probability that when the OS crashes,

	a database page is only partially physically written to disk. */

	if (srv_unix_file_flush_method != SRV_UNIX_LITTLESYNC

	    && srv_unix_file_flush_method != SRV_UNIX_NOSYNC) {

	        /* Always do fsync to reduce the probability that when

                the OS crashes, a database page is only partially

                physically written to disk. */

	        ut_a(TRUE == os_file_flush(file));

	}

	os_mutex_exit(os_file_seek_mutexes[i]);