Skip to content

M
mariadb
Commit 754eb8f5 authored by unknown's avatar unknown
Browse files
Options

manual.texi: 

  Manual changes to reflect auto-extending data file and better foreign key support in 3.23.50


Docs/manual.texi:
  Manual changes to reflect auto-extending data file and better foreign key support in 3.23.50
parent 134a1bb8
Show whitespace changes
Inline Side-by-side
Showing with 198 additions and 88 deletions
Docs/manual.texi
View file @ 754eb8f5
......@@ -37530,23 +37530,60 @@ In the source distribution of MySQL, InnoDB appears as a subdirectory.
@node InnoDB start, InnoDB init, InnoDB overview, InnoDB
@subsection InnoDB Startup Options
To use InnoDB tables in MySQL-Max-3.23
you @strong{MUST} specify configuration parameters
in the MySQL configuration file in the @code{[mysqld]} section of
the configuration file @file{my.cnf}. @xref{Option files}.
The only required parameter to use InnoDB in MySQL-Max-3.23
is @code{innodb_data_file_path}.
To use InnoDB tables in MySQL-Max-3.23 you MUST specify configuration
parameters
in the @code{[mysqld]} section of
the configuration file @file{my.cnf}, or on Windows optionally in
@file{my.ini}.
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 is to create a 64 MB
data file @file{ibdata1} to the @code{datadir} of MySQL.
@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
auto-extending.)
But to get good performance you MUST explicitly set the InnoDB parameters
listed below in examples.
listed below in the examples.
Suppose you have a Windows NT machine with 128 MB RAM and a single 10 GB
hard disk. Below is an example of possible configuration parameters in
@file{my.cnf} for InnoDB:
Starting from versions 3.23.50 and 4.0.2 InnoDB allows the last
data file 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
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
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
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:
@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:
@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
@file{my.cnf} or @file{my.ini} for InnoDB:
@example
[mysqld]
......@@ -37581,33 +37618,36 @@ set-variable = innodb_lock_wait_timeout=50
Note that @strong{InnoDB does not create directories:
you have to create them yourself.}
Use the Unix or MS-DOS @code{mkdir} command to create
the data and log group home directories.
Check also that the MySQL server
has the @strong{rights to create files in the directories} you specify.
has @strong{the rights to create files} in the directories you specify.
Note that data files must be < 2G in
some file systems! The total size of data files has
to be >= 10 MB. The combined size of log files MUST be < 4G
in 32-bit computers.
some file systems! The combined size of data files
must be >= 10 MB.
The combined size of the log files must be < 4G.
The default value for @code{innodb_data_home_dir} is the @code{datadir}
of MySQL. If you do not specify @code{innodb_data_home_dir}, then
you cannot use absolute paths in @code{innodb_data_file_path}.
If you do not specify @code{innodb_data_home_dir}, then
the default is that InnoDB creates its data files to the
@code{datadir} of MySQL. Then you cannot use absolute
file paths in @code{innodb_data_file_path}.
When you the first time create an InnoDB database, it
is best that you start the MySQL server from the command
prompt. Then InnoDB will print the information about the
database creation to the screen, and you see what is
happening. See below in section 3 what the printout
should look like.
happening.
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.
@strong{Where to put my.cnf or my.ini in Windows?}
@strong{Where to put @file{my.cnf} or @file{my.ini} in Windows?}
The rules for Windows are the following:
@itemize @bullet
@itemize bullet
@item Only one of @file{my.cnf} or @file{my.ini} should be created.
@item The @file{my.cnf} file should be placed in the root
directory of the drive @file{C:}.
......@@ -37621,30 +37661,28 @@ is not the boot drive, then your only option is to use the @file{my.ini} file.
@strong{Where to specify options in Unix?}
On Unix @file{mysqld} reads options from the following files, if they exist,
in the following order:
@itemize @bullet
@itemize bullet
@item @file{/etc/my.cnf} Global options.
@item @file{COMPILATION_DATADIR/my.cnf} Server-specific options.
@item @file{defaults-extra-file} The file specified with
@code{--defaults-extra-file=...}.
@item @file{~/.my.cnf} User-specific options.
@end itemize
@code{COMPILATION_DATADIR} is the MySQL data directory which was
@file{COMPILATION_DATADIR} is the MySQL data directory which was
specified as a @code{./configure} option when @file{mysqld}
was compiled
(typically @file{/usr/local/mysql/data} for a
binary installation or @file{/usr/local/var}
for a source installation).
(typically @file{/usr/local/mysql/data} for a binary installation or @file{/usr/local/var} for a source installation).
If you are not sure from where @file{mysqld} reads its @file{my.cnf}
or @file{my.ini}, you can give the path as a command-line option:
@code{--defaults-file=your_path_to_my_cnf}.
or @file{my.ini}, you can give the path as the first command-line
option to the server:
@code{mysqld --defaults-file=your_path_to_my_cnf}.
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 in @file{my.cnf} for
three 20 GB hard disks (at directory paths @file{`/'},
@file{`/dr2'} and @file{`/dr3'}).
Below is an example of possible configuration parameters
in @file{my.cnf} for
InnoDB:
@example
......@@ -37658,7 +37696,7 @@ innodb_data_home_dir = /
innodb_data_file_path = ibdata/ibdata1:2000M;dr2/ibdata/ibdata2:2000M
# Set buffer pool size to 50 - 80 %
# of your computer's memory, but
# make sure on Linux x86 the total
# make sure on Linux x86 total
# memory usage is < 2 GB
set-variable = innodb_buffer_pool_size=350M
set-variable = innodb_additional_mem_pool_size=20M
......@@ -37693,20 +37731,46 @@ formed by the data files 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
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. Make sure
which will crash your server. It is a risk if the value of
@example
innodb_buffer_pool_size + key_buffer +
max_connections * (sort_buffer + record_buffer) + max_connections * 1 MB
max_connections * (sort_buffer + record_buffer) + max_connections * 2 MB
@end example
is significantly smaller than 2 GB. Each thread will use a stack
(often 1 MB) and in the worst case also
@code{sort_buffer + record_buff}
is close to 2 GB or exceeds 2 GB. Each thread will use a stack
(often 2 MB, but in MySQL AB binaries only 256 kB) and in the worst case also
@code{sort_buffer + record_buffer}
additional memory.
@strong{How to tune other @file{mysqld} server parameters?}
For detailed information on how to tune other MySQL server
parameters, see the MySQL <a href="http://www.mysql.com/doc/">manual</a>.
Typical values which suit most users are:
@example
set-variable = max_connections=200
set-variable = record_buffer=1M
set-variable = sort_buffer=1M
# Set key_buffer to 5 - 50 %
# of your RAM depending on how
# much you use MyISAM tables, but
# keep key_buffer + InnoDB
# buffer pool size < 80 % of
# your RAM
set-variable = key_buffer=...
@end example
Note that some parameters are given using the numeric @file{my.cnf}
parameter format: @code{set-variable = innodb... = 123}, others
(string and boolean parameters) with another format:
@code{innodb_... = ... }.
The meanings of the configuration parameters are the following:
@multitable @columnfractions .30 .70
......@@ -37966,33 +38030,68 @@ your job again, rather than wait for millions of disk i/os to complete.
@subsubsection Foreign Key Constraints
InnoDB version 3.23.44 features foreign key constraints. InnoDB is the
first MySQL table type which allows you to define foreign key
Starting from version 3.23.43b InnoDB features foreign key constraints.
InnoDB is the first MySQL table type which allows you to define foreign key
constraints to guard the integrity of your data.
The syntax of a foreign key constraint definition in InnoDB:
@example
FOREIGN KEY (index_col_name, ...)
REFERENCES table_name (index_col_name, ...)
FOREIGN KEY (index_col_name, ...) REFERENCES table_name (index_col_name, ...)
@end example
Starting from version 3.23.50 the InnoDB parser allows you to
use also backquotes around table and column names in the above
definition.
An example:
@example
CREATE TABLE parent(id INT NOT NULL, PRIMARY KEY (id)) TYPE=INNODB;
CREATE TABLE child(id INT, parent_id INT, INDEX par_ind (parent_id),
FOREIGN KEY (parent_id) REFERENCES parent(id)) TYPE=INNODB;
@end example
Both tables have to be InnoDB type and there must be an index
Both tables have to be InnoDB type and @strong{there must be an index
where the foreign key and the referenced key are listed as the first
columns. Any @code{ALTER TABLE} currently removes all foreign key
constrainst defined for the table, but not the constraints
that reference the table. Corresponding columns in the foreign key
and the referenced key have to have similar internal data types
columns}. InnoDB does not auto-create indexes on foreign keys or
referenced keys: you have to create them explicitly.
If MySQL gives the error number 1005 from a @code{CREATE TABLE}
statement, and the error message string refers to errno 150, then
the table creation failed because a foreign key constraint was not
correctly formed.
Similarly, if an @code{ALTER TABLE} fails and it refers to errno
150, that means a foreign key definition would be incorrectly
formed for the altered table.
Starting from version 3.23.50 InnoDB allows you to add a new
foreign key constraint to a table through
@example
ALTER TABLE yourtablename ADD CONSTRAINT FOREIGN KEY (...) REFERENCES anothertablename(...)
@end example
Remember to create the required indexes first, though.
Starting from version 3.23.50, InnoDB does not check foreign key
constraints on those foreign key or referenced key values
which contain a NULL column.
In InnoDB versions < 3.23.50 @code{ALTER TABLE}
or @code{CREATE INDEX}
should not be used in connection with tables which have foreign
key constraints or which are referenced in foreign key constraints:
Any @code{ALTER TABLE} removes all foreign key
constrainst defined for the table. You should not use
@code{ALTER TABLE} to the referenced table either, but
use @code{DROP TABLE} and @code{CREATE TABLE} to modify the
schema. When MySQL does an @code{ALTER TABLE} it may internally
use @code{RENAME TABLE}, and that will confuse the
foreign key costraints which refer to the table.
A @code{CREATE INDEX} statement is in MySQL
processed as an @code{ALTER TABLE}, and these
restrictions apply also to it.
Corresponding columns in the foreign key
and the referenced key must have similar internal data types
inside InnoDB so that they can be compared without a type
conversion. The length of string types need not be the same.
The size and the signedness of integer types has to be same.
The size and the signedness of integer types has to be the same.
When doing foreign key checks InnoDB sets shared row
level locks on child or parent records it has to look at.
......@@ -38004,20 +38103,31 @@ would break the foreign key constraints which reference
the table. When you drop a table the constraints which
were defined in its create statement are also dropped.
If you recreate a table which was dropped, it has to have
If you re-create a table which was dropped, it has to have
a definition which conforms to the foreign key constraints
referencing it. It must have the right column names and types,
and it must have indexes on the referenced keys, as stated above.
If these are not satisfied, MySQL returns error number 1005
and refers to errno 150 in the error message string.
Starting from version 3.23.50 InnoDB returns the foreign key
definitions of a table when you call
@example
SHOW CREATE TABLE yourtablename
@end example
Then also @file{mysqldump} produces correct definitions
of tables to the dump file, and does not forget about the
foreign keys.
You can list the foreign key constraints for a table
You can also list the foreign key constraints for a table
@code{T} with
@example
SHOW TABLE STATUS FROM yourdatabasename LIKE 'T';
SHOW TABLE STATUS FROM yourdatabasename LIKE 'T'
@end example
The foreign key constraints are listed in the table comment of
the output.
InnoDB does not yet support @code{CASCADE ON DELETE}
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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7