diff options
Diffstat (limited to 'Docs')
| -rw-r--r-- | Docs/INSTALL-BINARY | 194 | ||||
| -rw-r--r-- | Docs/README-wsrep | 485 | ||||
| -rw-r--r-- | Docs/myisam.txt | 901 | ||||
| -rw-r--r-- | Docs/mysql.info | 11 |
4 files changed, 1591 insertions, 0 deletions
diff --git a/Docs/INSTALL-BINARY b/Docs/INSTALL-BINARY new file mode 100644 index 00000000..081f4dc9 --- /dev/null +++ b/Docs/INSTALL-BINARY @@ -0,0 +1,194 @@ +MariaDB and MySQL have identical install methods. In this document we +describe how to install MariaDB. + +The full documentation for installing MariaDB can be found at +https://mariadb.com/kb/en/library/binary-packages/ +However most documentation at www.mysql.com also applies. + +2.2. Installing MariaDB from Generic Binaries on Unix/Linux + + This section covers the installation of MariaDB binary distributions + that are provided for various platforms in the form of compressed + tar files (files with a .tar.gz extension). + + MariaDB tar file binary distributions have names of the form + mariadb-VERSION-OS.tar.gz, where VERSION is a number (for example, + 5.1.39), and OS indicates the type of operating system for which + the distribution is intended (for example, pc-linux-i686). + + You need the following tools to install a MariaDB tar file binary + distribution: + + * GNU gunzip to uncompress the distribution. + + * A reasonable tar to unpack the distribution. GNU tar is known + to work. Some operating systems come with a preinstalled + version of tar that is known to have problems. For example, + the tar provided with early versions of Mac OS X, SunOS 4.x, + Solaris 8, Solaris 9, Solaris 10 and OpenSolaris, and HP-UX + are known to have problems with long file names. On Mac OS X, + you can use the preinstalled gnutar program. On Solaris 10 and + OpenSolaris you can use the preinstalled gtar. On other + systems with a deficient tar, you should install GNU tar + first. + + If you run into problems and need to file a bug report, + please report them to: https://mariadb.org/jira + + See the instructions at + https://mariadb.com/kb/en/mariadb-community-bug-reporting + + The basic commands that you must execute to install and use a + MariaDB binary distribution are: + +shell> groupadd mysql +shell> useradd -g mysql mysql +shell> cd /usr/local +shell> gunzip < /path/to/mariadb-VERSION-OS.tar.gz | tar xvf - +shell> ln -s full-path-to-mariadb-VERSION-OS mysql +shell> cd mysql +shell> chown -R mysql . +shell> chgrp -R mysql . +shell> scripts/mysql_install_db --user=mysql +shell> chown -R root . +shell> chown -R mysql data +shell> bin/mysqld_safe --user=mysql & + +Note + + This procedure does not set up any passwords for MariaDB accounts. + After following the procedure, proceed to Section 2.13, + "Post-Installation Setup and Testing." + + A more detailed version of the preceding description for + installing a binary distribution follows: + + 1. Add a login user and group for mysqld to run as: +shell> groupadd mysql +shell> useradd -g mysql mysql + These commands add the mysql group and the mysql user. The + syntax for useradd and groupadd may differ slightly on + different versions of Unix, or they may have different names + such as adduser and addgroup. + You might want to call the user and group something else + instead of mysql. If so, substitute the appropriate name in + the following steps. + + 2. Pick the directory under which you want to unpack the + distribution and change location into it. In the following + example, we unpack the distribution under /usr/local. (The + instructions, therefore, assume that you have permission to + create files and directories in /usr/local. If that directory + is protected, you must perform the installation as root.) +shell> cd /usr/local + + 3. Obtain a distribution file using the instructions at + https://mariadb.com/kb/en/library/where-to-download-mariadb/ + The description below describes how to install a MariaDB tar file. + + 4. Unpack the distribution, which creates the installation + directory. Then create a symbolic link to that directory: +shell> gunzip < /path/to/mariadb-VERSION-OS.tar.gz | tar xvf - +shell> ln -s full-path-to-mariadb-VERSION-OS mysql + The tar command creates a directory named mariadb-VERSION-OS. + The ln command makes a symbolic link to that directory. This + lets you refer more easily to the installation directory as + /usr/local/mysql. + With GNU tar, no separate invocation of gunzip is necessary. + You can replace the first line with the following alternative + command to uncompress and extract the distribution: +shell> tar zxvf /path/to/mariadb-VERSION-OS.tar.gz + + 5. Change location into the installation directory: +shell> cd mysql + You will find several files and subdirectories in the mysql + directory. The most important for installation purposes are + the bin and scripts subdirectories: + + + The bin directory contains client programs and the + server. You should add the full path name of this + directory to your PATH environment variable so that your + shell finds the MariaDB programs properly. See Section + 2.14, "Environment Variables." + + + The scripts directory contains the mysql_install_db + script used to initialize the mysql database containing + the grant tables that store the server access + permissions. + + 6. Ensure that the distribution contents are accessible to mysql. + If you unpacked the distribution as mysql, no further action + is required. If you unpacked the distribution as root, its + contents will be owned by root. Change its ownership to mysql + by executing the following commands as root in the + installation directory: +shell> chown -R mysql . +shell> chgrp -R mysql . + The first command changes the owner attribute of the files to + the mysql user. The second changes the group attribute to the + mysql group. + + 7. If you have not installed MariaDB before, you must create the + MariaDB data directory and initialize the grant tables: +shell> scripts/mysql_install_db --user=mysql + If you run the command as root, include the --user option as + shown. If you run the command while logged in as that user, + you can omit the --user option. + The command should create the data directory and its contents + with mysql as the owner. + After creating or updating the grant tables, you need to + restart the server manually. + + 8. Most of the MariaDB installation can be owned by root if you + like. The exception is that the data directory must be owned + by mysql. To accomplish this, run the following commands as + root in the installation directory: + +shell> chown -R root . +shell> chown -R mysql data + + 9. If you want MariaDB to start automatically when you boot your + machine, you can copy support-files/mysql.server to the + location where your system has its startup files. More + information can be found in the support-files/mysql.server + script itself and at + https://mariadb.com/kb/en/starting-and-stopping-mariadb-automatically. + 10. You can set up new accounts using the bin/mysql_setpermission + script if you install the DBI and DBD::MariaDB Perl modules. See + Section 4.6.14, "mysql_setpermission --- Interactively Set + Permissions in Grant Tables." For Perl module installation + instructions, see Section 2.15, "Perl Installation Notes." + 11. If you would like to use mysqlaccess and have the MariaDB + distribution in some nonstandard location, you must change the + location where mysqlaccess expects to find the mysql client. + Edit the bin/mysqlaccess script at approximately line 18. + Search for a line that looks like this: +$MYSQL = '/usr/local/bin/mysql'; # path to mysql executable + Change the path to reflect the location where mysql actually + is stored on your system. If you do not do this, a Broken pipe + error will occur when you run mysqlaccess. + + After everything has been unpacked and installed, you should test + your distribution. To start the MariaDB server, use the following + command: +shell> bin/mysqld_safe --user=mysql & + + If you run the command as root, you must use the --user option as + shown. The value of the option is the name of the login account + that you created in the first step to use for running the server. + If you run the command while logged in as mysql, you can omit the + --user option. + + If the command fails immediately and prints mysqld ended, you can + find some information in the host_name.err file in the data + directory. + + More information about mysqld_safe can be found at + https://mariadb.com/kb/en/mysqld_safe + +Note + + The accounts that are listed in the MariaDB grant tables initially + have no passwords. After starting the server, you should set up + passwords for them using the instructions in Section 2.13, + "Post-Installation Setup and Testing." diff --git a/Docs/README-wsrep b/Docs/README-wsrep new file mode 100644 index 00000000..2e3bf522 --- /dev/null +++ b/Docs/README-wsrep @@ -0,0 +1,485 @@ +Codership Oy +http://www.codership.com +<info@codership.com> + +DISCLAIMER + +THIS SOFTWARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER +EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +IN NO EVENT SHALL CODERSHIP OY BE HELD LIABLE TO ANY PARTY FOR ANY DAMAGES +RESULTING DIRECTLY OR INDIRECTLY FROM THE USE OF THIS SOFTWARE. + +Trademark Information. + +MySQL is a trademark or registered trademark of Oracle and/or its affiliates. +Other trademarks are the property of their respective owners. + +Licensing Information. + +Please see file COPYING that came with this distribution + +Source code can be found at +wsrep API: https://launchpad.net/wsrep +MySQL patch: https://launchpad.net/codership-mysql + + +ABOUT THIS DOCUMENT + +This document covers installation and configuration issues specific to this +wsrep-patched MySQL distribution by Codership. It does not cover the use or +administration of MySQL server per se. The reader is assumed to know how to +install, configure, administer and use standard MySQL server version 5.1.xx. + + + MYSQL-5.5.x/wsrep-23.x + +CONTENTS: +========= +1. WHAT IS WSREP PATCH FOR MYSQL +2. INSTALLATION +3. FIRST TIME SETUP + 3.1 CONFIGURATION FILES + 3.2 DATABASE PRIVILEGES + 3.3 CHECK AND CORRECT FIREWALL SETTINGS + 3.4 SELINUX + 3.5 APPARMOR + 3.6 CONNECT TO CLUSTER +4. UPGRADING FROM MySQL 5.1.x +5. CONFIGURATION OPTIONS + 5.1 MANDATORY MYSQL OPTIONS + 5.2 WSREP OPTIONS +6. ONLINE SCHEMA UPGRADE + 6.1 TOTAL ORDER ISOLATION (TOI) + 6.2 ROLLING SCHEMA UPGRADE (RSU) +7. LIMITATIONS + + +1. WHAT IS WSREP PATCH FOR MYSQL/INNODB + +Wsrep API developed by Codership Oy is a modern generic (database-agnostic) +replication API for transactional databases with a goal to make database +replication/logging subsystem completely modular and pluggable. It is developed +with flexibility and completeness in mind to satisfy a broad range of modern +replication scenarios. It is equally suitable for synchronous and asynchronous, +master-slave and multi-master replication. + +wsrep stands for Write Set REPlication. + +Wsrep patch for MySQL/InnoDB allows MySQL server to load and use various wsrep +API implementations ("wsrep providers") with different qualities of service. +Without wsrep provider MySQL-wsrep server will function like a regular +standalone server. + + +2. INSTALLATION + +In the examples below mysql authentication options are omitted for brevity. + +2.1 Download and install mysql-wsrep package. + +Download binary package for your Linux distribution from +https://launchpad.net/codership-mysql/ + +2.1.1 On Debian and Debian-derived distributions. + +Upgrade from mysql-server-5.0 to mysql-wsrep is not supported yet, please +upgrade to mysql-server-5.1 first. + +If you're installing over an existing mysql installation, mysql-server-wsrep +will conflict with the mysql-server-5.1 package, so remove it first: + +$ sudo apt-get remove mysql-server-5.1 mysql-server-core-5.1 + +mysql-server-wsrep requires psmisc and mysql-client-5.1.47 (or later). +MySQL 5.1 packages can be found from backports repositories. +For further information about configuring and using Debian or Ubuntu +backports, see: + +* http://backports.debian.org + +* https://help.ubuntu.com/community/UbuntuBackports + +For example, installation of required packages on Debian Lenny: + +$ sudo apt-get install psmisc +$ sudo apt-get -t lenny-backports install mysql-client-5.1 + +Now you should be able to install the mysql-wsrep package: + +$ sudo dpkg -i <mysql-server-wsrep DEB> + +2.1.2 On CentOS and similar RPM-based distributions. + +If you're migrating from existing MySQL installation, there are two variants: + + a) If you're already using official MySQL-server-community 5.1.x RPM from + Oracle: + + # rpm -e mysql-server + + b) If you're upgrading from the stock mysql-5.0.77 on CentOS: + + 1) Make sure that the following packages are not installed: + # rpm --nodeps --allmatches -e mysql-server mysql-test mysql-bench + + 2) Install *official* MySQL-shared-compat-5.1.x from + http://dev.mysql.com/downloads/mysql/5.1.html + +Actual installation: + + # rpm -Uvh <MySQL-server-wsrep RPM> + + If this fails due to unsatisfied dependencies, install missing packages + (e.g. yum install perl-DBI) and retry. + +Additional packages to consider (if not yet installed): + * galera (multi-master replication provider, https://launchpad.net/galera) + * MySQL-client-community (for connecting to server and mysqldump-based SST) + * rsync (for rsync-based SST) + * mariabackup and nc (for mariabackup-based SST) + +2.2 Upgrade system tables. + +If you're upgrading a previous MySQL installation, it might be advisable to +upgrade system tables. To do that start mysqld and run mysql_upgrade command. +Consult MySQL documentation in case of errors. Normally they are not critical +and can be ignored unless specific functionality is needed. + + +3. FIRST TIME SETUP + +Unless you're upgrading an already installed mysql-wsrep package, you will need +to set up a few things to prepare the server for operation. + +3.1 CONFIGURATION FILES + +* Make sure system-wide my.cnf does not bind mysqld to 127.0.0.1. That is, if + you have the following line in [mysqld] section, comment it out: + + #bind-address = 127.0.0.1 + +* Make sure system-wide my.cnf contains "!includedir /etc/mysql/conf.d/" line. + +* Edit /etc/mysql/conf.d/wsrep.cnf and set wsrep_provider option by specifying + a path to the provider library. If you don't have a provider, leave it as it is. + +* When a new node joins the cluster it'll have to receive a state snapshot from + one of the peers. This requires a privileged MySQL account with access from + the rest of the cluster. Edit /etc/mysql/conf.d/wsrep.cnf and set mysql + login/password pair for SST, for example: + + wsrep_sst_auth=wsrep_sst:wspass + +* See CONFIGURATION section below about other configuration parameters that you + might want to change at this point. + +3.2 DATABASE PRIVILEGES + +Restart MySQL server and connect to it as root to grant privileges to SST +account (empty users confuse MySQL authentication matching rules, we need to +delete them too): + +$ mysql -e "SET wsrep_on=OFF; DELETE FROM mysql.user WHERE user='';" +$ mysql -e "SET wsrep_on=OFF; GRANT ALL ON *.* TO wsrep_sst@'%' IDENTIFIED BY 'wspass'"; + +3.3 CHECK AND CORRECT FIREWALL SETTINGS. + +MySQL-wsrep server needs to be accessible from other cluster members through +its client listening socket and through wsrep provider socket. See your +distribution and wsrep provider documentation for details. For example on +CentOS you might need to do something along these lines: + +# iptables --insert RH-Firewall-1-INPUT 1 --proto tcp --source <my IP>/24 --destination <my IP>/32 --dport 3306 -j ACCEPT +# iptables --insert RH-Firewall-1-INPUT 1 --proto tcp --source <my IP>/24 --destination <my IP>/32 --dport 4567 -j ACCEPT + +If there is a NAT firewall between the nodes, it must be configured to allow +direct connections between the nodes (e.g. via port forwarding). + +3.4 SELINUX + +If you have SELinux enabled, it may block mysqld from doing required operations. +You'll need to either disable it or configure to allow mysqld to run external +programs and open listen sockets at unprivileged ports (i.e. things that +an unprivileged user can do). See SELinux documentation about it. + +To quickly disable SELinux: +1) run 'setenforce 0' as root. +2) set 'SELINUX=permissive' in /etc/selinux/config + +3.5 APPARMOR + +AppArmor automatically comes with Ubuntu and may also prevent mysqld to from +opening additional ports or run scripts. See AppArmor documentation about its +configuration. To disable AppArmor for mysqld: + +$ cd /etc/apparmor.d/disable/ +$ sudo ln -s /etc/apparmor.d/usr.sbin.mysqld +$ sudo service apparmor restart + + +3.6 CONNECT TO CLUSTER + +Now you're ready to connect to cluster by setting wsrep_cluster_address variable +and monitor status of wsrep provider: + +mysql> SET GLOBAL wsrep_cluster_address='<cluster address string>'; +mysql> SHOW STATUS LIKE 'wsrep%'; + + +4 UPGRADING FROM MySQL 5.1.x + +!!! THESE INSTRUCTIONS ARE PRELIMINARY AND INCOMPLETE !!! + +1) BEFORE UPGRADE (while running 5.1.x): + - comment out 'wsrep_provider' setting from configuration files + (my.cnf and/or wsrep.cnf) + - If performing a rolling upgrade on a running cluster, set + wsrep_sst_method=mysqldump. + You might also need to configure wsrep_sst_receive_address and + wsrep_sst_auth appropriately. mysqldump is the only way to transfer data + from 5.1.x to 5.5.x reliably. + - remove innodb_plugin settings from configuration files. + +2) Perform upgrade as usual: + http://dev.mysql.com/doc/refman/5.5/en/upgrading-from-previous-series.html + Don't forget to run 'mysql_upgrade' command. + +3) AFTER UPGRADING individual node: + - uncomment 'wsrep_provider' line in configuration file. + - restart the server and join the cluster. + +4) AFTER UPGRADING the whole cluster: + - revert to usual wsrep SST settings if not 'mysqldump'. + + +5. CONFIGURATION OPTIONS + +5.1 MANDATORY MYSQL OPTIONS + +binlog_format=ROW + This option is required to use row-level replication as opposed to + statement-level. For performance and consistency considerations don't change + that. As a side effect, binlog, if turned on, can be ROW only. In future this + option won't have special meaning. + +innodb_autoinc_lock_mode=2 + This is a required parameter. Without it INSERTs into tables with + AUTO_INCREMENT column may fail. + autoinc lock modes 0 and 1 can cause unresolved deadlock, and make + the system unresponsive. + +5.2 WSREP OPTIONS + +All options are optional except for wsrep_provider, wsrep_cluster_address, and +wsrep_sst_auth. + +wsrep_provider=none + A full path to the library that implements WSREP interface. If none is + specified, the server behaves like a regular mysqld. + +wsrep_provider_options= + Provider-specific option string. Check wsrep provider documentation or + http://www.codership.com/wiki + +wsrep_cluster_address= + Provider-specific cluster address string. This is used to connect a node to + the desired cluster. This option can be given either on mysqld startup or set + during runtime. See wsrep provider documentation for possible values. + +wsrep_cluster_name="my_wsrep_cluster" + Logical cluster name, must be the same for all nodes of the cluster. + +wsrep_node_address= + An option to explicitly specify the network address of the node in the form + <address>[:port] if autoguessing for some reason does not produce desirable + results (multiple network interfaces, NAT, etc.) + If not explicitly overridden by wsrep_sst_receive_address, the <address> part + will be used to listen for SST (see below). And the whole <address>[:port] + will be passed to the wsrep provider to be used as a base address in its + communications. + +wsrep_node_name= + Human readable node name (for easier log reading only). Defaults to hostname. + +wsrep_slave_threads=1 + The number of threads dedicated to the processing of writesets from other nodes. + For best performance should be few per CPU core. + +wsrep_dbug_option + Options for the built-in DBUG library (independent from what MySQL uses). + Empty by default. Not currently in use. + +wsrep_debug=0 + Enable debug-level logging. + +wsrep_convert_LOCK_to_trx=0 + Implicitly convert locking sessions into transactions inside mysqld. By + itself it does not mean support for locking sessions, but it prevents the + database from going into logically inconsistent state. Note however, that + loading large database dump with LOCK statements might result in abnormally + large transactions and cause an out-of-memory condition + +wsrep_retry_autocommit=1 + Retry autocommit queries and single statement transactions should they fail + certification test. This is analogous to rescheduling an autocommit query + should it go into a deadlock with other transactions in the database lock + manager. + +wsrep_auto_increment_control=1 + Automatically adjust auto_increment_increment and auto_increment_offset + variables based on the number of nodes in the cluster. Significantly reduces + certification conflict rate for INSERTS. + +wsrep_drupal_282555_workaround=1 + MySQL seems to have an obscure bug when INSERT into table with + AUTO_INCREMENT column with NULL value for that column can fail with a + duplicate key error. When this option is on, it retries such INSERTs. + Required for stable Drupal operation. Documented at: + http://bugs.mysql.com/bug.php?id=41984 + http://drupal.org/node/282555 + +wsrep_causal_reads=0 + Enforce strict READ COMMITTED semantics on reads and transactions. May + result in additional latencies. It is a session variable. + +wsrep_OSU_method=TOI + Online Schema Upgrade (OSU) can be performed with two alternative methods: + Total Order Isolation (TOI) runs DDL statement in all cluster nodes in + same total order sequence locking the affected table for the duration of the + operation. This may result in the whole cluster being blocked for the + duration of the operation. + Rolling Schema Upgrade (RSU) executes the DDL statement only locally, thus + blocking only one cluster node. During the DDL processing, the node + is not replicating and may be unable to process replication events (due to + table lock). Once DDL operation is complete, the node will catch up and sync + with the cluster to become fully operational again. The DDL statement or + its effects are not replicated, so it is the user's responsibility to manually + perform this operation on each of the nodes. + +wsrep_forced_binlog_format=none + Force every transaction to use given binlog format. When this variable is + set to something else than NONE, all transactions will use the given forced + format, regardless of what the client session has specified in binlog_format. + Valid choices for wsrep_forced_binlog_format are: ROW, STATEMENT, MIXED and + special value NONE, meaning that there is no forced binlog format in effect. + This variable was introduced to support STATEMENT format replication during + rolling schema upgrade processing. However, in most cases ROW replication + is valid for asymmetric schema replication. + +State snapshot transfer options. + +When a new node joins the cluster it has to synchronize its initial state with +the other cluster members by transferring state snapshot from one of them. +The options below govern how this happens and should be set up before attempting +to join or start a cluster. + +wsrep_sst_method=rsync + What method to use to copy database state to a newly joined node. Supported + methods: + - mysqldump: slow (except for small datasets) but allows for upgrade + between major MySQL versions or InnoDB features. + - rsync: much faster on large datasets (default). + - rsync_wan: same as rsync but with deltaxfer to minimize network traffic. + - mariabackup: very fast and practically non-blocking SST method based on + mariabackup tool (enhanced version of Percona's xtrabackup). + + (for mariabackup to work the following settings must be present in my.cnf + on all nodes: + [mysqld] + wsrep_sst_auth=root:<root password> + datadir=<path to data dir> + [client] + socket=<path to socket> + ) + +wsrep_sst_receive_address= + Address (hostname:port) at which this node wants to receive state snapshot. + Defaults to mysqld bind address, and if that is not specified (0.0.0.0) - + to the first IP of eth0 + mysqld bind port. + NOTE: check that your firewall allows connections to this address from other + cluster nodes. + +wsrep_sst_auth= + Authentication information needed for state transfer. Depends on the state + transfer method. For mysqldump-based SST it is + <mysql_root_user>:<mysql_root_password> + and should be the same on all nodes - it is used to authenticate with both + state snapshot receiver and state snapshot donor. + +wsrep_sst_donor= + A name of the node which should serve as state snapshot donor. This allows + controlling which node will serve the state snapshot request. By default the + most suitable node is chosen by the wsrep provider. This is the same as given in + wsrep_node_name. + + +6. ONLINE SCHEMA UPGRADE + + Schema upgrades mean any data definition statements (DDL statements) run + for the database. They change the database structure and are non- + transactional. + + Release 22.3 brings a new method for performing schema upgrades. A user can + now choose whether to use the traditional total order isolation or new + rolling schema upgrade method. The OSU method choice is done by global + parameter: 'wsrep_OSU_method'. + +6.1 Total Order Isolation (TOI) + + With earlier releases, DDL processing happened always by Total Order + Isolation (TOI) method. With TOI, the DDL was scheduled to be processed in + same transaction sequencing 'slot' in each cluster node. + The processing is secured by locking the affected table from any other use. + With TOI method, the whole cluster has part of the database locked for the + duration of the DDL processing. + +6.2 Rolling Schema Upgrade (RSU) + + Rolling schema upgrade is a new DDL processing method, where DDL will be + processed locally for the node. The node is disconnected of the replication + for the duration of the DDL processing, so that there is only DDL statement + processing in the node and it does not block the rest of the cluster. When + the DDL processing is complete, the node applies delayed replication events + and synchronizes back with the cluster. + The DDL can then be executed cluster-wide by running the same DDL statement + for each node in turn. When this rolling schema upgrade proceeds, part of + the cluster will have old schema structure and part of the cluster will have + new schema structure. + + +7. LIMITATIONS + +1) Currently replication works only with InnoDB storage engine. Any writes to + tables of other types, including system (mysql.*) tables are not replicated. + However, DDL statements are replicated in statement level, and changes + to mysql.* tables will get replicated that way. + So, you can safely issue: CREATE USER..., + but issuing: INSERT INTO mysql.user..., will not be replicated. + +2) DELETE operation is unsupported on tables without primary key. Also rows in + tables without primary key may appear in different order on different nodes. + As a result SELECT...LIMIT... may return slightly different sets. + +3) Unsupported queries: + * LOCK/UNLOCK TABLES cannot be supported in multi-master setups. + * lock functions (GET_LOCK(), RELEASE_LOCK()... ) + +4) Query log cannot be directed to a table. If you enable query logging, + you must forward the log to a file: + log_output = FILE + Use general_log and general_log_file to choose query logging and the + log file name + +5) Maximum allowed transaction size is defined by wsrep_max_ws_rows and + wsrep_max_ws_size. Anything bigger (e.g. huge LOAD DATA) will be rejected. + +6) Due to cluster level optimistic concurrency control, transaction issuing + COMMIT may still be aborted at that stage. There can be two transactions. + writing to same rows and committing in separate cluster nodes, and only one + of them can successfully commit. The failing one will be aborted. + For cluster level aborts, MySQL/galera cluster gives back deadlock error. + code (Error: 1213 SQLSTATE: 40001 (ER_LOCK_DEADLOCK)). + +7) XA transactions can not be supported due to possible rollback on commit. + diff --git a/Docs/myisam.txt b/Docs/myisam.txt new file mode 100644 index 00000000..f959d8eb --- /dev/null +++ b/Docs/myisam.txt @@ -0,0 +1,901 @@ +#.# mi_changed() + +int mi_is_changed(MI_INFO *mip) + +#.#.1 Description + +Reports whether any changes have occurred to the MyISAM table associated with mip. + +For information only, I notice that mi_changed() is a wrapper around this: (_mi_readinfo(info,F_RDLCK,1)). + +#.#.2 Return values + +Zero if the table has not changed. Non-zero (-1) if the table has changed. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +if( mi_changed( mip )) printf( "file has changed" ); +==================== +#.# mi_close() + +int mi_close( MI_INFO *mip ) + +#.#.1 Description + +Closes the MyISAM table associated with mip, a structure created by mi_open(). +Any locks on that file pointer are released. +The MI_INFO structure mip is released. +See also mi_panic() which can be used to close all open MyISAM files. +mip is a pointer to the MI_INFO returned by mi_open(). + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +result = mi_close(mip); +==================== +#.# mi_create() + +int mi_create( const char *name, uint keys, MI_KEYDEF *keydefs, + uint columns, MI_COLUMNDEF *recinfo, + uint uniques, MI_UNIQUEDEF *uniquedefs, + MI_CREATE_INFO *ci, uint flags ) + +#.#.1 Description + +Creates a new MyISAM table. +Documentation for this function is not complete because I am not using mi_create directly. +Because all our tables are used with MySQL, I create new tables using SQL "CREATE TABLE" via the C API. +See MySQL Appendix B "Choosing a table type". +MyISAM allows about 32 indexes. However the official MySQL limit is 16 until MySQL 4.0. + +The parameters are specified as follows: +name The file pathname, excluding the suffixes. +keys Number of indexes. +keydefs A MI_KEYDEF structure containing key definitions. +HA_KEYTYPE_END=0 +HA_KEYTYPE_TEXT=1, /* Key is sorted as letters */ +HA_KEYTYPE_BINARY=2, /* Key is sorted as unsigned chars +HA_KEYTYPE_SHORT_INT=3, +HA_KEYTYPE_LONG_INT=4, +HA_KEYTYPE_FLOAT=5, +HA_KEYTYPE_DOUBLE=6, +HA_KEYTYPE_NUM=7, /* Not packed num with pre-space * +HA_KEYTYPE_USHORT_INT=8, +HA_KEYTYPE_ULONG_INT=9, +HA_KEYTYPE_LONGLONG=10, +HA_KEYTYPE_ULONGLONG=11, +HA_KEYTYPE_INT24=12, +HA_KEYTYPE_UINT24=13, +HA_KEYTYPE_INT8=14, +HA_KEYTYPE_VARTEXT=15, /* Key is sorted as letters */ +HA_KEYTYPE_VARBINARY=16 /* Key is sorted as unsigned chars +columns The number of columns. +recinfo A MI_COLUMNDEF structure containing column definitions. +uniques The number of unique indexes. +uniquedefs A MI_UNIQUEDEF structure containing unique index definitions. +ci A MI_CREATE_INFO structure containing column definitions. +flags a pointer to the record buffer that will contain the row. + +#.#.2 Return values + +Zero if the create is successful. Non-zero if an error occurs. + +#.#.3 Errors + +HA_WRONG_CREATE_OPTION + means that some of the arguments was wrong. +apart from the above one can get any unix error that one can get from open(), write() or close(). + +#.#.4 Examples + +if (mi_create(fn_format(name,filename,"",MI_NAME_IEXT, 4+ (opt_follow_links ? 16 : 0)), + share.base.keys - share.state.header.uniques, keyinfo, share.base.fields, recdef, + share.state.header.uniques, uniquedef, &create_info, HA_DONT_TOUCH_DATA)) +==================== +#.# mi_delete() + +int mi_delete(MI_INFO *mip, const byte *buf) + +#.#.1 Description + +Removes a row from a MyISAM table. + +mip is an MI_INFO pointer to the open handle. +buf is the buffer containing the row that is to be deleted. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +EACCES +File was opened read-only. +HA_ERR_KEY_NOT_FOUND +No database read +HA_ERR_RECORD_CHANGED +The buffer contents were different to the actual row contents. +HA_ERR_CRASHED +The indexing has crashed. + +#.#.4 Examples + +if (mi_delete(file,read_record)) +==================== +#.# mi_delete_all() + +int mi_delete_all_rows(MI_INFO *mip) +#.#.1 Description + +Removes ALL rows from a MyISAM table. +This only clears the status information. The files are not truncated. + +mip is an MI_INFO pointer to the open handle. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +EACCES +File was opened read-only. + +#.#.4 Examples + +error = mi_delete_all( mip ); +==================== +#.# mi_extra() + +int mi_extra(MI_INFO *info, enum ha_extra_function function) + +#.#.1 Description + +Controls some special MyISAM modes. + +The function parameter can be: + HA_EXTRA_NORMAL=0 Optimize for space (def) +HA_EXTRA_QUICK=1 Optimize for speed +HA_EXTRA_RESET=2 Reset database to after open +HA_EXTRA_CACHE=3 Cash record in HA_rrnd() +HA_EXTRA_NO_CACHE=4 End caching of records (def) +HA_EXTRA_NO_READCHECK=5 No readcheck on update +HA_EXTRA_READCHECK=6 Use readcheck (def) +HA_EXTRA_KEYREAD=7 Read only key to database +HA_EXTRA_NO_KEYREAD=8 Normal read of records (def) +HA_EXTRA_NO_USER_CHANGE=9 No user is allowed to write +HA_EXTRA_KEY_CACHE=10 +HA_EXTRA_NO_KEY_CACHE=11 +HA_EXTRA_WAIT_LOCK=12 Wait until file is available (def) +HA_EXTRA_NO_WAIT_LOCK=13 If file is locked, return quickly +HA_EXTRA_WRITE_CACHE=14 Use write cache in ha_write() +HA_EXTRA_FLUSH_CACHE=15 flush write_record_cache +HA_EXTRA_NO_KEYS=16 Remove all update of keys +HA_EXTRA_KEYREAD_CHANGE_POS=17 Keyread, but change pos +xxxxchk -r must be used +HA_EXTRA_REMEMBER_POS=18 Remember pos for next/prev +HA_EXTRA_RESTORE_POS=19 +HA_EXTRA_REINIT_CACHE=20 init cache from current record +HA_EXTRA_FORCE_REOPEN=21 Datafile have changed on disk +HA_EXTRA_FLUSH Flush tables to disk +HA_EXTRA_NO_ROWS Don't write rows + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +==================== +#.# mi_make_application_key() + +void mi_make_application_key(register MI_INFO *mip, uint keynr, uchar *key, const byte *record) + +#.#.1 Description + +Construct a key string for the given index, from the provided record buffer. +Monty wrote this function to: "to create an external key for an application from your record. It should work for all keys except BLOB and true VARCHAR (not supported by MySQL yet), but I don't think you have either of these!" He just wrote it, so I expect it to included in releases from about 3.23.15. ?? + +The parameters are: +A MI_INFO pointer mip. +The index number keynr. +The buffer to contain the formatted key string key. +The record buffer record. + +#.#.2 Return values + +The byte length of the created key string. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +uint new_length=_mi_make_application_key(info,i,new_key,newrec); +==================== +#.# mi_open() + +MI_INFO *mi_open( const char *name, int mode, uint handle_locking ) + +#.#.1 Description + +Opens a MyISAM file for processing. +mi_open() returns a MI_INFO structure pointer that you must use in subsequent operations on the MyISAM file. MI_INFO structures are defined in "myisam/myisamdef.h", which is included in your program via your include myisam.h - used by both MyISAM and MySQL. +The name parameter must contain a null-terminated string without an extension, which is the filename of the MyISAM file to be processed. +There is no automatic positioning nor key selection. +Caution! It is extremely important to close MyISAM files after processing has finished, especially on operating systems without file-locking system calls. Failure to close MyISAM files using mi_close() or mi_panic() leaves the files locked on systems without these system calls. + +name Is the name of the file. +mode Is the access mode parameter. Use one of the following access mode parameters: +O_RDONLY to open for input only. +O_RDWR opens the file for output. +O_SHARE opens the file for both input and output. When used, O_SHARE should be added to O_RDONLY and O_RDWR. +handle_locking is the locking mode parameter. Select from the following: +HA_OPEN_ABORT_IF_LOCKED (0) exit with error if database is locked +HA_OPEN_WAIT_IF_LOCKED (1) wait if database is locked +HA_OPEN_IGNORE_IF_LOCKED (2) continue, but count-vars in st_i_info may be wrong. count-vars are automatically fixed after next isam request. + +#.#.2 Return values + +A pointer to MI_INFO for successfully open file. NULL if unsuccessful, when my_errno will contain the error code. + +#.#.3 Errors + +HA_ERR_OLD_FILE +wrong options +HA_ERR_CRASHED +wrong header +HA_ERR_UNSUPPORTED +too many keys or keys too long +HA_ERR_END_OF_FILE +empty file? +MY_FILE_ERROR +? +EACCES +cannot open in write mode +ENOMEM +not enough memory +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +pfm = mi_open("/D1/adir/perform",O_SHARE | O_RDONLY, HA_OPEN_ABORT_IF_LOCKED); +==================== +#.# mi_panic() + +int mi_panic( enum ha_panic_function flag ) + +#.#.1 Description + +mi_panic() is used to close any MyISAM files before exiting, or to safeguard file updates when using a shell. +The flag parameter specifies the function and can be: +HA_PANIC_CLOSE Close all databases (MyISAM files). +HA_PANIC_WRITE Unlock and write status, flushing all buffers to disk. +HA_PANIC_READ Lock and read key info per HA_PANIC_WRITE. + +The CLOSE function also writes buffers before it closes and turns logging off by closing the log file.. +See also my_end(), a debugging function. +One use is to do a WRITE, use a shell to run myisamchk, then do a READ. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +result = mi_panic(HA_PANIC_CLOSE); +==================== +#.# mi_position() + +my_off_t mi_position(MI_INFO *mip) + +#.#.1 Description + +Gets the byte position in the file of the last record read. + +mip is an MI_INFO pointer to the open handle. + +#.#.2 Return values + +Byte position if successful. Zero if an error occurred. ?? + +#.#.3 Errors + +HA_OFFSET_ERROR +if there wasn't any active row. + +#.#.4 Examples + +currentpos = mi_position( mip ); +==================== +#.# mi_rfirst() + +int mi_rfirst(MI_INFO *mip , byte *buf, int inx) + +#.#.1 Description + +Reads the first row in the MyISAM file according to the specified index. +If one wants to read rows in physical sequences, then one should instead use mi_scan() or mi_rrnd(). + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. +Inx is the index (key) number, which must be the same as currently selected. + +mi_rfirst() works by setting the current position mip->lastpos to HA_OFFSET_ERROR (undefined) then calling mi_rnext(). + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_END_OF_FILE +End of file +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +error = mi_rfirst( mip, buffer, keynum); +==================== +#.# mi_rkey() + +int mi_rkey(MI_INFO *mip, byte *buf, int inx, const byte *key, uint key_len, enum ha_rkey_function search_flag) + +#.#.1 Description + +Reads the next row after the last row read, using the current index. +If one wants to read rows in physical sequences, then one should instead use mi_scan() or mi_rrnd(). + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. +Inx is the index (key) number, which must be the same as currently selected. + +If (mip->lastpos) is HA_OFFSET_ERROR (undefined) then mi_rnext() gives the first row. +If you specify a different index number than the last read used, you will get an error. +If the last (current) row has been changed since we read it, mi_rnext() will reposition from the position where that row WAS, not where it is now. (This behaviour is similar to CISAM and better than used in Codebase.) + +mi_extra(HA_EXTRA_KEYREAD) can be called first, to cause mi_rkey to read the key but not the record. Then call mi_extra(HA_EXTRA_NO_KEYREAD) to resume normal behaviour. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_END_OF_FILE +End of file +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +error = mi_rnext( mip, buffer, keynum ); +==================== +#.# mi_rlast() + +int mi_rlast(MI_INFO *mip , byte *buf, int inx) + +#.#.1 Description + +Reads the last row in the MyISAM file according to the specified index. +If one wants to read rows in physical sequences, then one should instead use mi_scan() or mi_rrnd(). +mip is an MI_INFO pointer to the open handle. +buf is a pointer to the record buffer that will contain the row. +Inx is the index (key) number, which must be the same as currently selected. + +mi_rlast() works by setting the current position (mip->lastpos) to HA_OFFSET_ERROR (undefined) then calling mi_rprev(). + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_END_OF_FILE +End of file +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +error = mi_rlast( mip, buffer, keynum); +==================== +#.# mi_rnext() + +int mi_rnext(MI_INFO *mip , byte *buf, int inx ) + +#.#.1 Description + +Reads the next row after the last row read, using the current index. +If one wants to read rows in physical sequences, then one should instead use mi_scan() or mi_rrnd(). + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. +Inx is the index (key) number, which must be the same as currently selected. + +If (mip->lastpos) is HA_OFFSET_ERROR (undefined) then mi_rnext() gives the first row. +If you specify a different index number than the last read used, you will get an error. +If the last (current) row has been changed since we read it, mi_rnext() will reposition from the position where that row WAS, not where it is now. (This behaviour is similar to CISAM and better than used in Codebase.) + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_END_OF_FILE +End of file +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +error = mi_rnext( mip, buffer, keynum ); +==================== +#.# mi_rrnd() + +int mi_rrnd( MI_INFO *mip , byte *buf, my_off_t filepos ) + +#.#.1 Description + +Reads a row based on physical position. + +Position can be calculated from record number only when fixed record lengths are used: +position = mip->s.pack.header_length + recnum * mip->s->base.reclength. +If filepos= HA_OFFSET_ERROR then it reads the next row. +And if (mip->lastpos == HA_OFFSET_ERROR) it reads the first row. + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. +filepos is the byte position in the file of the required record. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_RECORD_DELETED +A deleted record was read. +HA_ERR_END_OF_FILE +End of file. + +#.#.4 Examples + +error = mi_rrnd( mip, buffer, mip->nextpos ); +==================== +#.# mi_rprev() + +int mi_rprev(MI_INFO *mip , byte *buf, int inx) + +#.#.1 Description + +Reads the row previous to the last row read, using the current index. +If one wants to read rows in physical sequences, then one should instead use mi_scan() or mi_rrnd(). + +If (mip->lastpos) is HA_OFFSET_ERROR (undefined) then mi_rnext() gives the last row in the index. +If you specify a different index number than the last read used, you will get an error. +If the last (current) row has been changed since we read it, mi_rprev() will reposition from the position where that row WAS, not where it is now. This behaviour is similar to CISAM and better than used in Codebase. + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. +Inx is the index (key) number, which must be the same as currently selected. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_END_OF_FILE +End of file +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +error = mi_rprev( mip, buffer, keynum ); +==================== +#.# mi_rsame() + +int mi_rsame(MI_INFO *mip, byte *buf, int inx) + +#.#.1 Description + +Reads the current row to get its latest contents. This is useful to refresh the record buffer in case someone else has changed it. +If inx is negative it reads by position. If inx is >= 0 it reads by key. +With mi_rsame() one can switch to use any other index for the current row. This is good if you have a user application that lets the user do 'read-next' on a row. In this case, if the user wants to start scanning on another index, one simply has to do a mi_rsame() on the new index to activate this. + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. +inx is the index (key) number, or a negative number to select read by position not index. Maybe the negative number has to be (-1) to achieve this behaviour. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_WRONG_INDEX +an incorrect index number was supplied +HA_ERR_KEY_NOT_FOUND +info->lastpos was not defined, or the record was already deleted. + +#.#.4 Examples + +error = mi_rsame( m5mip, rec_ptr, keynum ); +==================== +#.# mi_scan() + +int mi_scan(MI_INFO *mip, byte *buf) + +#.#.1 Description + +Reads the next row by physical position. + +Deleted rows are bypassed. +mi_scan() uses a function pointer "read_rnd" that uses either lower level static or dynamic read functions, positioning from mip->nextpos. Read_rnd is defined in mi_open() depending if the table is Static (read*static - see mi_statrec.c), Compressed (read*pack - see mi_packrec.c), or Space packed or Blobs (read*dynamic - see mi_dynrec.c). +See also mi_scan_init() which initialises ready to mi_scan() through the whole table. + +mip is an MI_INFO pointer to the open handle. +buf is the record buffer that will contain the row. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_END_OF_FILE +End of file +Otherwise one has probably got a fatal error like HA_ERR_CRASHED or some I-O related error from the Operating System. + +#.#.4 Examples + +error = mi_scan( mip, recbuff ); +==================== +#.# mi_scan_init() + +int mi_scan_init(MI_INFO *mip[SB1]) + +#.#.1 Description + +Initialises ready to mi_scan() through all rows. + +mip is an MI_INFO pointer to the open handle. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +==================== +#.# mi_status() + +int mi_status(MI_INFO *mip, MI_ISAMINFO *x, uint flag) + +#.#.1 Description + +Gets information about the table. +It is used to get/fill the MI_ISAMINFO struct with statistics data about the MySQL server. One can get information of the number of active rows, delete rows, file lengths... + +mip is an MI_INFO pointer to the open handle. +flag is one of the following: +HA_STATUS_POS Return position +HA_STATUS_NO_LOCK Don't use external lock +HA_STATUS_TIME Return update time +HA_STATUS_CONST Return constants value +HA_STATUS_VARIABLE +HA_STATUS_ERRKEY +HA_STATUS_AUTO + +#.#.2 Return values + +Zero. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +==================== +#.# mi_update() + +int mi_update( MI_INFO *mip, const byte *oldbuf, byte *newbuf) + +#.#.1 Description + +Updates the contents of the current record. +By default you must supply an oldbuf record buffer with the current record contents. This is compared with the file as a guard in case someone else has changed the record in the meantime. * + +mip is an MI_INFO pointer to the open handle. +oldbuf is the record buffer that contains the current record contents. +newbuf is the record buffer that contains the new record contents. + +*Sometimes you might want to force an update without checking whether another user has changed the record since you last read it. This is somewhat dangerous, so it should ideally not be used. That can be accomplished by wrapping the mi_update() call in two calls to mi_extra(), using these functions: +HA_EXTRA_NO_READCHECK=5 No readcheck on update +HA_EXTRA_READCHECK=6 Use readcheck (def) + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +EACCES +The file was opened for read-only access. +HA_ERR_RECORD_CHANGED + When mi_update() read the current record contents before updating, it differed from oldbuf. +HA_ERR_CRASHED +Key could not be found ?? +HA_ERR_FOUND_DUPP_KEY +HA_ERR_RECORD_FILE_FULL + +#.#.4 Examples + +error = mi_update( mip, oldbuf, newbuf ); +==================== +#.# mi_write() + +int mi_write( MI_INFO *mip, byte *record) + +#.#.1 Description + +Writes a row to a MyISAM table. + +mip is an MI_INFO pointer to the open handle. +The record contents are supplied in buf record buffer. + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +HA_ERR_FOUND_DUPP_KEY +A record already existed with a unique key same as this new record. +HA_ERR_RECORD_FILE_FULL +The error is given if you hit a system limit or if you try to create more rows in a table that you reserved room for with mi_create(). +ENOSPC +The disk is full. +EACCES +The file was opened for read-only access. + +#.#.4 Examples + +error = mi_write( m5mip, recbuf ); +==================== +#.# my_end() + +void my_end(int infoflag) + +#.#.1 Description + +Shows debugging information about open MyISAM handles. +my_end() exists primarily for MyISAM debugging. +It would not normally be used in a production environment. +It can give a nice summary of how you have used my_xxx() functions. +It can be used to check that you have closed all files that you have opened. + +infoflag is the list function and can be: +MY_CHECK_ERROR List which MyISAM handles are open. +MY_GIVE_INFO Show runtime information. + +#.#.2 Return values + +Void + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +my_end(MY_CHECK_ERROR | MY_GIVE_INFO); +==================== +#.# my_init() + +void my_init( void ) + +#.#.1 Description + +Performs MyISAM initialisation for program startup, particularly if using threads. + +If using threads, be sure to call my_init() at start of program. (CFS does this in XPOPEN.) It is also safe to call my_init() when not using threads. + +#.#.2 Return values + +void +Sometimes my_errno might be meaningful if a warning is generated during debugging. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +my_init(); +==================== +#.# init_key_cache() + +int init_key_cache( long int use_mem, (uint) reserve_mem; + +#.#.1 Description + +Starts and controls caching of keys. Call init_key_cache() to reserve memory for key caching and to start the caching. (CFS does this in XPOPEN if MYCACHE is defined (regular size), or MYCACHELARGE or MYCACHESMALL.) + +Provide use_mem the number of bytes of memory to use for key caching by this process. +reserve_mem should be 0. This is just for very old systems with very little memory. + +#.#.2 Return values + +The number of 1kb memory blocks now allocated to key caching. Zero if key caching cannot be started (check my_errno), or key caching was already active. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +Blocks = init_key_cache( 65536L, IO_SIZE*4*10 ); +==================== +#.# _mi_make_key() + +uint _mi_make_key( MI_INFO *mip, uint keynr, uchar *key, const char *record, my_off_t filepos) + +#.#.1 Description + +Construct a key string for the given index, from the provided record buffer. +??? When packed records are used ... +This is an internal function, not for use by applications. Monty says: "This can't be used to create an external key for an application from your record." +See mi_make_application_key() for a similar function that is usable by applications. + +The parameters are: +A MI_INFO pointer mip. +The index number keynr. +The buffer to contain the formatted key string key. +The record buffer record. +??? A file position filepos or zero. + +#.#.2 Return values + +The byte length of the created key string. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +uint new_length=_mi_make_key(info,i,new_key,newrec,pos); +==================== +#.# _mi_print_key() + +void _mi_print_key(FILE *stream, MI_KEYSEG *keyseg, const uchar *key, uint length) + +#.#.1 Description + +Prints a key in a user understandable format. +This is an internal function for debugging, not for use by applications. +??? Not yet fully documented. I just include it here so that I know it exists. + +#.#.2 Return values + +A readable print of the key contents goes to the specified output. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples + +_mi_print_key(stdout,share->keyinfo[info->errkey].seg,info->lastkey, USE_WHOLE_KEY); +==================== +APPENDIX B Choosing a table type +(excerpt from manual.txt in MySQL 3.23.8-alpha) + +With MySQL you can currently (version 3.23.5) choose between four usable table formats from a speed point of view. + +Static (Fixed-length) table characteristics +* This is the default format. It's used when the table contains no `VARCHAR', `BLOB' or `TEXT' columns. +* All `CHAR', `NUMERIC' and `DECIMAL' columns are space-padded to the column width. +* Very quick. +* Easy to cache. +* Easy to reconstruct after a crash, because records are located in fixed positions. +* Doesn't have to be reorganized (with `myisamchk') unless a huge number of records are deleted and you want to return free disk space to the operating system. +* Usually requires more disk space than dynamic tables. + +Dynamic table characteristics +* This format is used if the table contains any `VARCHAR', `BLOB' or `TEXT' columns. +* All string columns are dynamic (except those with a length less than 4). +* Each record is preceded by a bitmap indicating which columns are empty (`''') for string columns, or zero for numeric columns (this isn't the same as columns containing `NULL' values). If a string column has a length of zero after removal of trailing spaces, or a numeric column has a value of zero, it is marked in the bit map and not saved to disk. Non-empty strings are saved as a length byte plus the string contents. +* Usually takes much less disk space than fixed-length tables. +* Each record uses only as much space as is required. If a record becomes larger, it is split into as many pieces as required. This results in record fragmentation. +* If you update a row with information that extends the row length, the row will be fragmented. In this case, you may have to run `myisamchk -r' from time to time to get better performance. Use `myisamchk -ei tbl_name' for some statistics. +* Not as easy to reconstruct after a crash, because a record may be fragmented into many pieces and a link (fragment) may be missing. +* The expected row length for dynamic sized records is: +3 ++ (number of columns + 7) / 8 ++ (number of char columns) ++ packed size of numeric columns ++ length of strings ++ (number of NULL columns + 7) / 8 +There is a penalty of 6 bytes for each link. A dynamic record is linked whenever an update causes an enlargement of the record. +Each new link will be at least 20 bytes, so the next enlargement will probably go in the same link. If not, there will be another link. You may check how many links there are with `myisamchk -ed'. All links may be removed with `myisamchk -r'. + +Compressed table characteristics +* A read-only table made with the `myisampack' utility. All customers with extended *MySQL* email support are entitled to a copy of `myisampack' for their internal usage. +* The uncompress code exists in all *MySQL* distributions so that even customers who don't have `myisampack' can read tables that were compressed with `myisampack' +* Takes very little disk space. Minimises disk usage. +* Each record is compressed separately (very little access overhead). The header for a record is fixed (1-3 bytes) depending on the biggest record in the table. Each column is compressed differently. Some of the compression types are: +- There is usually a different Huffman table for each column. +- Suffix space compression. +- Prefix space compression. +- Numbers with value `0' are stored using 1 bit. +- If values in an integer column have a small range, the column is stored using the smallest possible type. For example, a `BIGINT' column (8 bytes) may be stored as a `TINYINT' column (1 byte) if all values are in the range `0' to `255'. +- If a column has only a small set of possible values, the column type is converted to `ENUM'. +- A column may use a combination of the above compressions. +* Can handle fixed or dynamic length records, but not `BLOB' or `TEXT' columns. +* Can be uncompressed with `myisamchk'. + +*MySQL* can support different index types, but the normal type is ISAM. +This is a B-tree index and you can roughly calculate the size for the index file as `(key_length+4)*0.67', summed over all keys. (This is for the worst case when all keys are inserted in sorted order.) + +String indexes are space compressed. If the first index part is a string, it will also be prefix compressed. +Space compression makes the index file smaller if the string column has a lot of trailing space or is a `VARCHAR' column that is not always used to the full length. +Prefix compression helps if there are many strings with an identical prefix. + +In memory table characteristics +HEAP tables only exists in memory so they are lost if `mysqld' is taken down or crashes. But since they are *very* fast they are useful as anyway. + +The *MySQL* internal HEAP tables uses 100% dynamic hashing without overflow areas and don't have problems with delete. + +You can only access things by equality using a index (usually by the `=' operator) with a heap table. +The downside with HEAPS are: + 1. You need enough extra memory for all HEAP tables that you want to use at the same time. + 2. You can't search on a part of a index. + 3. You can't search for the next entry in order (that is to use the index to do a `ORDER BY'). +1. *MySQL* also cannot find out how approximately many rows there are between two values. This is used by the optimizer to chose which index to use. But on the other hand no disk seeks are even needed. +==================== +#.# mi_() + +#.#.1 Description + +#.#.2 Return values + +Zero if successful. Non-zero if an error occurred. + +#.#.3 Errors + +Nothing specific yet identified. + +#.#.4 Examples +[SB1]int _mi_read_rnd_static_record(MI_INFO *info, byte *buf, my_off_t filepos, + my_bool skipp_deleted_blocks) +int _mi_read_dynamic_record(MI_INFO *info, my_off_t filepos, byte *buf) + +Printed on 17/03/00 + +C-7 diff --git a/Docs/mysql.info b/Docs/mysql.info new file mode 100644 index 00000000..02692f34 --- /dev/null +++ b/Docs/mysql.info @@ -0,0 +1,11 @@ +MariaDB is in most aspects identical to MySQL. + +Differences between MySQL and MariaDB can be found at: +https://mariadb.com/kb/en/mariadb-vs-mysql-features/ +https://mariadb.com/kb/en/mariadb-vs-mysql-compatibility/ + +The MariaDB manual can be found at: +https://mariadb.com/kb/ + +The MySQL Reference Manual is available in various formats on +http://dev.mysql.com/doc. |