Troubleshooting Problems with MySQL Programs

This appendix from MySQL Administrator’s Guide (by MySQL AB, Sams, ISBN: 0672326345) lists some common problems and error messages that you may encounter when running MySQL programs. It describes how to determine the causes of the problems and what to do to solve them.

MySQLA.1 How to Determine What is Causing a Problem

When you run into a problem, the first thing you should do is to find out which program or piece of equipment is causing it. If you have one of the following symptoms, then it is probably a hardware problem (such as memory, motherboard, CPU, or hard disk) or kernel problem:

  • The keyboard doesn’t work. This can normally be checked by pressing the Caps Lock key. If the Caps Lock light doesn’t change, you have to replace your keyboard. (Before doing this, you should try to restart your computer and check all cables to the keyboard.)

  • The mouse pointer doesn’t move.

  • The machine doesn’t answer to a remote machine’s pings.

  • Other programs that are not related to MySQL don’t behave correctly.

  • Your system restarted unexpectedly. (A faulty user-level program should never be able to take down your system.)

    In this case, you should start by checking all your cables and run some diagnostic tool to check your hardware! You should also check whether there are any patches, updates, or service packs for your operating system that could likely solve your problem. Check also that all your libraries (such as glibc) are up to date.

    It’s always good to use a machine with ECC memory to discover memory problems early.

  • If your keyboard is locked up, you may be able to recover by logging in to your machine from another machine and executing kbd_mode -a.

  • Please examine your system log file (/var/log/messages or similar) for reasons for your problem. If you think the problem is in MySQL, you should also examine MySQL’s log files. See Section 4.8, “The MySQL Log Files.”

  • If you don’t think you have hardware problems, you should try to find out which program is causing problems. Try using top, ps, Task Manager, or some similar program, to check which program is taking all CPU or is locking the machine.

  • Use top, df, or a similar program to check whether you are out of memory, disk space, file descriptors, or some other critical resource.

  • If the problem is some runaway process, you can always try to kill it. If it doesn’t want to die, there is probably a bug in the operating system.

If after you have examined all other possibilities and you have concluded that the MySQL server or a MySQL client is causing the problem, it’s time to create a bug report for our mailing list or our support team. In the bug report, try to give a very detailed description of how the system is behaving and what you think is happening. You should also state why you think that MySQL is causing the problem. Take into consideration all the situations in this chapter. State any problems exactly how they appear when you examine your system. Use the “copy and paste” method for any output and error messages from programs and log files.

Try to describe in detail which program is not working and all symptoms you see. We have in the past received many bug reports that state only “the system doesn’t work.” This doesn’t provide us with any information about what could be the problem.

If a program fails, it’s always useful to know the following information:

  • Has the program in question made a segmentation fault (did it dump core)?

  • Is the program taking up all available CPU time? Check with top. Let the program run for a while, it may simply be evaluating something computationally intensive.

  • If the mysqld server is causing problems, can you get any response from it with mysqladmin -u root ping or mysqladmin -u root processlist?

  • What does a client program say when you try to connect to the MySQL server? (Try with mysql, for example.) Does the client jam? Do you get any output from the program?

When sending a bug report, you should follow the outline described in Section 1.7.1.2, “Asking Questions or Reporting Bugs.”   

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Common Errors When Using MySQL Programs}

A.2 Common Errors When Using MySQL Programs

This section lists some errors that users frequently encounter when running MySQL programs. Although the problems show up when you try to run client programs, the solutions to many of the problems involves changing the configuration of the MySQL server.

A.2.1 Access denied

An Access denied error can have many causes. Often the problem is related to the MySQL accounts that the server allows client programs to use when connecting. See Section 4.4.8, “Causes of Access denied Errors.” See Section 4.4.2, “How the Privilege System Works.”

A.2.2 Can’t connect to [local] MySQL server

A MySQL client on Unix can connect to the mysqld server in two different ways: By using a Unix socket file to connect through a file in the filesystem (default /tmp/mysql.sock), or by using TCP/IP, which connects through a port number. A Unix socket file connection is faster than TCP/IP, but can be used only when connecting to a server on the same computer. A Unix socket file is used if you don’t specify a hostname or if you specify the special hostname localhost.

If the MySQL server is running on Windows 9x or Me, you can connect only via TCP/IP. If the server is running on Windows NT, 2000, or XP and is started with the –enable-named-pipe option, you can also connect with named pipes if you run the client on the host where the server is running. The name of the named pipe is MySQL by default. If you don’t give a hostname when connecting to mysqld, a MySQL client first will try to connect to the named pipe. If that doesn’t work, it will connect to the TCP/IP port. You can force the use of named pipes on Windows by using . as the hostname.

The error (2002) Can’t connect to … normally means that there is no MySQL server running on the system or that you are using an incorrect Unix socket filename or TCP/IP port number when trying to connect to the server.

Start by checking whether there is a process named mysqld running on your server host. (Use ps on Unix or the Task Manager on Windows.) If there is no such process, you should start the server. See Section 2.4.4, “Starting and Troubleshooting the MySQL Server.”

If a mysqld process is running, you can check it by trying the following commands. The port number or Unix socket filename might be different in your setup. host_ip represents the IP number of the machine where the server is running.

shell> mysqladmin version
shell> mysqladmin variables
shell> mysqladmin -h ´hostname´ version variables
shell> mysqladmin -h ´hostname´ –port=3306 version
shell> mysqladmin -h host_ip version
shell> mysqladmin –protocol=socket –socket=/tmp/mysql.sock version

Note the use of backticks rather than forward quotes with the hostname command; these cause the output of hostname (that is, the current hostname) to be substituted into the mysqladmin command. If you have no hostname command or are running on Windows, you can manually type the hostname of your machine (without backticks) following the -h option. You can also try -h 127.0.0.1 to connect with TCP/IP to the local host.

Here are some reasons the Can’t connect to local MySQL server error might occur:

  • mysqld is not running.

  • You are running on a system that uses MIT-pthreads. If you are running on a system that doesn’t have native threads, mysqld uses the MIT-pthreads package. See Section 2.1.1, “Operating Systems Supported by MySQL.” However, not all MIT-pthreads versions support Unix socket files. On a system without socket file support, you must always specify the hostname explicitly when connecting to the server. Try using this command to check the connection to the server:
shell> mysqladmin -h ´hostname´ version
  • Someone has removed the Unix socket file that mysqld uses (/tmp/mysql.sock by default). For example, you might have a cron job that removes old files from the /tmp directory. You can always run mysqladmin version to check whether the Unix socket file that mysqladmin is trying to use really exists. The fix in this case is to change the cron job to not remove mysql.sock or to place the socket file somewhere else. See Section A.4.5, “How to Protect or Change the MySQL Socket File /tmp/mysql.sock.”

  • You have started the mysqld server with the –socket=/path/to/socket option, but forgotten to tell client programs the new name of the socket file. If you change the socket pathname for the server, you must also notify the MySQL clients. You can do this by providing the same –socket option when you run client programs. See Section A.4.5, “How to Protect or Change the MySQL Socket File /tmp/mysql.sock.”

  • You are using Linux and one server thread has died (dumped core). In this case, you must kill the other mysqld threads (for example, with kill or with the mysql_zap script) before you can restart the MySQL server. See Section A.4.2, “What to Do If MySQL Keeps Crashing.”

  • The server or client program might not have the proper access privileges for the directory that holds the Unix socket file or the socket file itself. In this case, you must either change the access privileges for the directory or socket file so that the server and clients can access them, or restart mysqld with a –socket option that specifies a socket filename in a directory where the server can create it and where client programs can access it.

If you get the error message Can’t connect to MySQL server on some_host, you can try the following things to find out what the problem is:

  • Check whether the server is running on that host by executing telnet some_host 3306 and pressing the Enter key a couple of times. (3306 is the default MySQL port number. Change the value if your server is listening to a different port.) If there is a MySQL server running and listening to the port, you should get a response that includes the server’s version number. If you get an error such as telnet: Unable to connect to remote host: Connection refused, then there is no server running on the given port.

  • If the server is running on the local host, try using mysqladmin -h localhost variables to connect using the Unix socket file. Verify the TCP/IP port number that the server is configured to listen to (it is the value of the port variable.)

  • Make sure that your mysqld server was not started with the –skip-networking option. If it was, you will not be able to connect to it using TCP/IP.

  

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Authentication Protocol}

A.2.3 Client does not support authentication protocol

MySQL 4.1 and up uses an authentication protocol based on a password hashing algorithm that is incompatible with that used by older clients. If you upgrade the server to 4.1, attempts to connect to it with an older client may fail with the following message:

shell> mysql
Client does not support authentication protocol requested
by server; consider upgrading MySQL client

To solve this problem, you should use one of the following approaches:

  • Upgrade all client programs to use a 4.1.1 or newer client library.

  • When connecting to the server with a pre-4.1 client program, use an account that still has a pre-4.1-style password.

  • Reset the password to pre-4.1 style for each user that needs to use a pre-4.1 client program. This can be done using the SET PASSWORD statement and the OLD_PASSWORD() function:

    mysql> SET PASSWORD FOR
      -> some_user‘@’some_host‘ = OLD_PASSWORD(‘newpwd‘);

    Alternatively, use UPDATE and FLUSH PRIVILEGES:

    mysql> UPDATE mysql.user SET Password = OLD_PASSWORD(‘newpwd‘)
      -> WHERE Host = ‘some_host‘ AND User = ‘some_user‘;
    mysql> FLUSH PRIVILEGES;

    Substitute the password you want to use for “newpwd” in the preceding examples. MySQL cannot tell you what the original password was, so you’ll need to pick a new one.

  • Tell the server to use the older password hashing algorithm:

    1. Start mysqld with the –old-passwords option.

    2. Assign an old-format password to each account that has had its password updated to the longer 4.1 format. You can identify these accounts with the following query:

      mysql> SELECT Host, User, Password FROM mysql.user
                   -> WHERE LENGTH(Password) > 16;
    3. For each account record displayed by the query, use the Host and User values and assign a password using the OLD_PASSWORD() function and either SET PASSWORD or UPDATE, as described earlier.

For additional background on password hashing and authentication, see Section 4.4.9, “Password Hashing in MySQL 4.1.”

A.2.4 Password Fails When Entered Interactively

MySQL client programs prompt for a password when invoked with a –password or -p option that has no following password value:

shell> mysql -u user_name -p
Enter password:

On some systems, you may find that your password works when specified in an option file or on the command line, but not when you enter it interactively at the Enter password: prompt. This occurs when the library provided by the system to read passwords limits password values to a small number of characters (typically eight). That is a problem with the system library, not with MySQL. To work around it, change your MySQL password to a value that is eight or fewer characters long, or put your password in an option file.

A.2.5 Host ‘host_name‘ is blocked

If you get the following error, it means that mysqld has received many connect requests from the host host_name that have been interrupted in the middle:

Host ‘host_name‘ is blocked because of many connection errors.
Unblock with ‘mysqladmin flush-hosts’

The number of interrupted connect requests allowed is determined by the value of the max_connect_errors system variable. After max_connect_errors failed requests, mysqld assumes that something is wrong (for example, that someone is trying to break in), and blocks the host from further connections until you execute a mysqladmin flush-hosts command or issue a FLUSH HOSTS statement. See Section 4.2.3, “Server System Variables.”

By default, mysqld blocks a host after 10 connection errors. You can adjust the value by starting the server like this:

shell> mysqld_safe –max_connect_errors=10000 &

If you get this error message for a given host, you should first verify that there isn’t anything wrong with TCP/IP connections from that host. If you are having network problems, it will do you no good to increase the value of the max_connect_errors variable.

A.2.6 Too many connections

If you get a Too many connections error when you try to connect to the mysqld server, this means that all available connections already are used by other clients.

The number of connections allowed is controlled by the max_connections system variable. Its default value is 100. If you need to support more connections, you should restart mysqld with a larger value for this variable.

mysqld actually allows max_connections+1 clients to connect. The extra connection is reserved for use by accounts that have the SUPER privilege. By granting the SUPER privilege to administrators and not to normal users (who should not need it), an administrator can connect to the server and use SHOW PROCESSLIST to diagnose problems even if the maximum number of unprivileged clients already are connected.

The maximum number of connections MySQL can support depends on the quality of the thread library on a given platform. Linux or Solaris should be able to support 500-1000 simultaneous connections, depending on how much RAM you have and what your clients are doing.  

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Memory and Lost Connection}

A.2.7 Out of memory

If you issue a query using the mysql client program and receive an error like the following one, it means that mysql does not have enough memory to store the entire query result:

mysql: Out of memory at line 42, ‘malloc.c’
mysql: needed 8136 byte (8k), memory in use: 12481367 bytes (12189k)
ERROR 2008: MySQL client ran out of memory

To remedy the problem, first check whether your query is correct. Is it reasonable that it should return so many rows? If not, correct the query and try again. Otherwise, you can invoke mysql with the –quick option. This causes it to use the mysql_use_result() C API function to retrieve the result set, which places less of a load on the client (but more on the server).

A.2.8 MySQL server has gone away

This section also covers the related Lost connection to server during query error.

The most common reason for the MySQL server has gone away error is that the server timed out and closed the connection. In this case, you normally get one of the following error codes (which one you get is operating system-dependent):

Error Code Description
CR_SERVER_GONE_ERROR The client couldn’t send a question to the server.
CR_SERVER_LOST The client didn’t get an error when writing to the server, but it didn’t get a full answer (or any answer) to the question.

By default, the server closes the connection after eight hours if nothing has happened. You can change the time limit by setting the wait_timeout variable when you start mysqld. See Section 4.2.3, “Server System Variables.”

If you have a script, you just have to issue the query again for the client to do an automatic reconnection.

You will also get an error if someone has killed the running thread with a KILL statement or a mysqladmin kill command.

Another common reason the MySQL server has gone away error occurs within an application program is that you tried to run a query after closing the connection to the server. This indicates a logic error in the application that should be corrected.

You can check whether the MySQL server died and restarted by executing mysqladmin version and examining the server’s uptime. If the client connection was broken because mysqld crashed and restarted, you should concentrate on finding the reason for the crash. Start by checking whether issuing the query again kills the server again. See Section A.4.2, “What to Do If MySQL Keeps Crashing.”

You can also get these errors if you send a query to the server that is incorrect or too large. If mysqld receives a packet that is too large or out of order, it assumes that something has gone wrong with the client and closes the connection. If you need big queries (for example, if you are working with big BLOB columns), you can increase the query limit by setting the server’s max_allowed_packet variable, which has a default value of 1MB. You may also need to increase the maximum packet size on the client end. More information on setting the packet size is given in Section A.2.9, “Packet too large.”

You will also get a lost connection if you are sending a packet 16MB or larger if your client is older than 4.0.8 and your server is 4.0.8 and above, or the other way around.

If you want to create a bug report regarding this problem, be sure that you include the following information:

  • Indicate whether or not the MySQL server died. You can find information about this in the server error log. See Section A.4.2, “What to Do If MySQL Keeps Crashing.”

  • If a specific query kills mysqld and the tables involved were checked with CHECK TABLE before you ran the query, can you provide a reproducible test case?

  • What is the value of the wait_timeout system variable in the MySQL server? (mysqladmin variables gives you the value of this variable.)

  • Have you tried to run mysqld with the –log option to determine whether the problem query appears in the log?

See Section 1.7.1.2, “Asking Questions or Reporting Bugs.”   

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Packet too Large}

A.2.9 Packet too large

A communication packet is a single SQL statement sent to the MySQL server or a single row that is sent to the client.

In MySQL 3.23, the largest possible packet is 16MB, due to limits in the client/server protocol. In MySQL 4.0.1 and up, the limit is 1GB.

When a MySQL client or the mysqld server receives a packet bigger than max_allowed_packet bytes, it issues a Packet too large error and closes the connection. With some clients, you may also get a Lost connection to MySQL server during query error if the communication packet is too large.

Both the client and the server have their own max_allowed_packet variable, so if you want to handle big packets, you must increase this variable both in the client and in the server.

If you are using the mysql client program, its default max_allowed_packet variable is 16MB. That is also the maximum value before MySQL 4.0. To set a larger value from 4.0 on, start mysql like this:

mysql> mysql –max_allowed_packet=32M

That sets the packet size to 32MB.

The server’s default max_allowed_packet value is 1MB. You can increase this if the server needs to handle big queries (for example, if you are working with big BLOB columns). For example, to set the variable to 16MB, start the server like this:

mysql> mysqld –max_allowed_packet=16M

Before MySQL 4.0, use this syntax instead:

mysql> mysqld –set-variable=max_allowed_packet=16M

You can also use an option file to set max_allowed_packet. For example, to set the size for the server to 16MB, add the following lines in an option file:

[mysqld]
max_allowed_packet=16M

Before MySQL 4.0, use this syntax instead:

[mysqld]
set-variable = max_allowed_packet=16M

It’s safe to increase the value of this variable because the extra memory is allocated only when needed. For example, mysqld allocates more memory only when you issue a long query or when mysqld must return a large result row. The small default value of the variable is a precaution to catch incorrect packets between the client and server and also to ensure that you don’t run out of memory by using large packets accidentally.

You can also get strange problems with large packets if you are using large BLOB values but have not given mysqld access to enough memory to handle the query. If you suspect this is the case, try adding ulimit -d 256000 to the beginning of the mysqld_safe script and restarting mysqld.

A.2.10 Communication Errors and Aborted Connections

The server error log can be a useful source of information about connection problems. See Section 4.8.1, “The Error Log.” Starting with MySQL 3.23.40, if you start the server with the –warnings option (or –log-warnings from MySQL 4.0.3 on), you might find messages like this in your error log:

010301 14:38:23 Aborted connection 854 to db: ‘users’ user: ‘josh’

If Aborted connections messages appear in the error log, the cause can be any of the following:

  • The client program did not call mysql_close() before exiting.

  • The client had been sleeping more than wait_timeout or interactive_timeout seconds without issuing any requests to the server. See Section 4.2.3, “Server System Variables.”

  • The client program ended abruptly in the middle of a data transfer.

When any of these things happen, the server increments the Aborted_clients status variable.

The server increments the Aborted_connects status variable when the following things happen:

  • A client doesn’t have privileges to connect to a database.

  • A client uses an incorrect password.

  • A connection packet doesn’t contain the right information.

  • It takes more than connect_timeout seconds to get a connect packet. See Section 4.2.3, “Server System Variables.”

If these kinds of things happen, it might indicate that someone is trying to break into your server!

Other reasons for problems with aborted clients or aborted connections:

  • Use of Ethernet protocol with Linux, both half and full duplex. Many Linux Ethernet drivers have this bug. You should test for this bug by transferring a huge file via FTP between the client and server machines. If a transfer goes in burst-pause-burst-pause mode, you are experiencing a Linux duplex syndrome. The only solution is switching the duplex mode for both your network card and hub/switch to either full duplex or to half duplex and testing the results to determine the best setting.

  • Some problem with the thread library that causes interrupts on reads.

  • Badly configured TCP/IP.

  • Faulty Ethernets, hubs, switches, cables, and so forth. This can be diagnosed properly only by replacing hardware.

  • The max_allowed_packet variable value is too small or queries require more memory than you have allocated for mysqld. See Section A.2.9, “Packet too large.”

   

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Table Full}

A.2.11 The table is full

There are several ways a full-table error can occur:

  • You are using a MySQL server older than 3.23 and an in-memory temporary table becomes larger than tmp_table_size bytes. To avoid this problem, you can use the -O tmp_table_size=# option to make mysqld increase the temporary table size or use the SQL option SQL_BIG_TABLES before you issue the problematic query.

  • You can also start mysqld with the –big-tables option. This is exactly the same as using SQL_BIG_TABLES for all queries.

  • As of MySQL 3.23, this problem should not occur. If an in-memory temporary table becomes larger than tmp_table_size, the server automatically converts it to a disk-based MyISAM table.

  • You are using InnoDB tables and run out of room in the InnoDB tablespace. In this case, the solution is to extend the InnoDB tablespace. See Section 9.8, “Adding and Removing InnoDB Data and Log Files.”

  • You are using ISAM or MyISAM tables on an operating system that supports files only up to 2GB in size and you have hit this limit for the data file or index file.

  • You are using a MyISAM table and the space required for the table exceeds what is allowed by the internal pointer size. (If you don’t specify the MAX_ROWS table option when you create a table, MySQL uses the myisam_data_pointer_size system variable. Its default value of 4 bytes is enough to allow only 4GB of data.) See Section 4.2.3, “Server System Variables.”

  • You can check the maximum data/index sizes by using this statement:
SHOW TABLE STATUS FROM database LIKE ‘tbl_name‘;
  • You also can use myisamchk -dv /path/to/table-index-file.

  • If the pointer size is too small, you can fix the problem by using ALTER TABLE:
ALTER TABLE tbl_name MAX_ROWS=1000000000 AVG_ROW_LENGTH=nnn;
  • You have to specify AVG_ROW_LENGTH only for tables with BLOB or TEXT columns; in this case, MySQL can’t optimize the space required based only on the number of rows.

A.2.12 Can’t create/write to file

If you get an error of the following type for some queries, it means that MySQL cannot create a temporary file for the result set in the temporary directory:

Can’t create/write to file ‘\sqla3fe_0.ism’.

The preceding error is a typical message for Windows; the Unix message is similar. The fix is to start mysqld with the –tmpdir option or to add the option to the [mysqld] section of your option file. For example, to specify a directory of C:temp, use these lines:

[mysqld]
tmpdir=C:/temp

The C:temp directory must already exist. See Section 3.3.2, “Using Option Files.”

Check also the error code that you get with perror. One reason the server cannot write to a table is that the filesystem is full:

shell> perror 28
Error code 28: No space left on device

A.2.13 Commands out of sync

If you get Commands out of sync; you can’t run this command now in your client code, you are calling client functions in the wrong order.

This can happen, for example, if you are using mysql_use_result() and try to execute a new query before you have called mysql_free_result(). It can also happen if you try to execute two queries that return data without calling mysql_use_result() or mysql_store_result() in between.

A.2.14 Ignoring user

If you get the following error, it means that when mysqld was started or when it reloaded the grant tables, it found an account in the user table that had an invalid password.

Found wrong password for user: ‘some_user‘@’some_host‘; ignoring user

As a result, the account is simply ignored by the permission system.

The following list indicates possible causes of and fixes for this problem:

  • You may be running a new version of mysqld with an old user table. You can check this by executing mysqlshow mysql user to see whether the Password column is shorter than 16 characters. If so, you can correct this condition by running the scripts/add_long_password script.

  • The account has an old password (eight characters long) and you didn’t start mysqld with the –old-protocol option. Update the account in the user table to have a new password or restart mysqld with the –old-protocol option.

  • You have specified a password in the user table without using the PASSWORD() function. Use mysql to update the account in the user table with a new password, making sure to use the PASSWORD() function:
mysql> UPDATE user SET Password=PASSWORD(‘newpwd‘)
  -> WHERE User=’some_user‘ AND Host=’some_host‘;

A.2.15 Table ‘tbl_name‘ doesn’t exist

If you get either of the following errors, it usually means that no table exists in the current database with the given name:

Table ‘tbl_name‘ doesn’t exist
Can’t find file: ‘tbl_name‘ (errno: 2)

In some cases, it may be that the table does exist but that you are referring to it incorrectly:

  • Because MySQL uses directories and files to store databases and tables, database and table names are case sensitive if they are located on a filesystem that has case-sensitive filenames.

  • Even for filesystems that are not case sensitive, such as on Windows, all references to a given table within a query must use the same lettercase.

You can check which tables are in the current database with SHOW TABLES.

A.2.16 Can’t initialize character set

You might see an error like this if you have character set problems:

MySQL Connection Failed: Can’t initialize character set charset_name

This error can have any of the following causes:

  • The character set is a multi-byte character set and you have no support for the character set in the client. In this case, you need to recompile the client by running configure with the –with-charset=charset_name or –with-extra-charsets=charset_name option. See Section 2.3.2, “Typical configure Options.”

  • All standard MySQL binaries are compiled with –with-extra-character-sets=complex, which enables support for all multi-byte character sets. See Section 4.7.1, “The Character Set Used for Data and Sorting.”

  • The character set is a simple character set that is not compiled into mysqld, and the character set definition files are not in the place where the client expects to find them.

  • In this case, you need to use one of the following methods to solve the problem:

    • Recompile the client with support for the character set. See Section 2.3.2, “Typical configure Options.”

    • Specify to the client the directory where the character set definition files are located. For many clients, you can do this with the –character-sets-dir option.

    • Copy the character definition files to the path where the client expects them to be.

  

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=File Not Found}

A.2.17 File Not Found

If you get ERROR ‘…’ not found (errno: 23), Can’t open file: … (errno: 24), or any other error with errno 23 or errno 24 from MySQL, it means that you haven’t allocated enough file descriptors for the MySQL server. You can use the perror utility to get a description of what the error number means:

shell> perror 23
File table overflow
shell> perror 24
Too many open files
shell> perror 11
Resource temporarily unavailable

The problem here is that mysqld is trying to keep open too many files simultaneously. You can either tell mysqld not to open so many files at once or increase the number of file descriptors available to mysqld.

To tell mysqld to keep open fewer files at a time, you can make the table cache smaller by reducing the value of the table_cache system variable (the default value is 64). Reducing the value of max_connections also will reduce the number of open files (the default value is 100).

To change the number of file descriptors available to mysqld, you can use the –open-files-limit option to mysqld_safe or (as of MySQL 3.23.30) set the open_files_limit system variable. See Section 4.2.3, “Server System Variables.” The easiest way to set these values is to add an option to your option file. See Section 3.3.2, “Using Option Files.” If you have an old version of mysqld that doesn’t support setting the open files limit, you can edit the mysqld_safe script. There is a commented-out line ulimit -n 256 in the script. You can remove the ‘#‘ character to uncomment this line, and change the number 256 to set the number of file descriptors to be made available to mysqld.

–open-files-limit and ulimit can increase the number of file descriptors, but only up to the limit imposed by the operating system. There is also a “hard” limit that can be overridden only if you start mysqld_safe or mysqld as root (just remember that you also need to start the server with the –user option in this case so that it does not continue to run as root after it starts up). If you need to increase the operating system limit on the number of file descriptors available to each process, consult the documentation for your system.

Note: If you run the tcsh shell, ulimit will not work! tcsh will also report incorrect values when you ask for the current limits. In this case, you should start mysqld_safe using sh.  

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Installation-Related Issues}

A.3.1 Problems Linking to the MySQL Client Library

When you are linking an application program to use the MySQL client library, you might get undefined reference errors for symbols that start with mysql_, such as those shown here:

/tmp/ccFKsdPa.o: In function ´main’:
/tmp/ccFKsdPa.o(.text+0xb): undefined reference to ´mysql_init’
/tmp/ccFKsdPa.o(.text+0×31): undefined reference to ´mysql_real_connect’
/tmp/ccFKsdPa.o(.text+0×57): undefined reference to ´mysql_real_connect’
/tmp/ccFKsdPa.o(.text+0×69): undefined reference to ´mysql_error’
/tmp/ccFKsdPa.o(.text+0x9a): undefined reference to ´mysql_close’

You should be able to solve this problem by adding -Ldir_path -lmysqlclient at the end of your link command, where dir_path represents the pathname of the directory where the client library is located. To determine the correct directory, try this command:

shell> mysql_config –libs

The output from mysql_config might indicate other libraries that should be specified on the link command as well.

If you get undefined reference errors for the uncompress or compress function, add -lz to the end of your link command and try again.

If you get undefined reference errors for a function that should exist on your system, such as connect, check the manual page for the function in question to determine which libraries you should add to the link command.

You might get undefined reference errors such as the following for functions that don’t exist on your system:

mf_format.o(.text+0×201): undefined reference to ´__lxstat’

This usually means that your MySQL client library was compiled on a system that is not 100% compatible with yours. In this case, you should download the latest MySQL source distribution and compile MySQL yourself. See Section 2.3, “MySQL Installation Using a Source Distribution.”

You might get undefined reference errors at runtime when you try to execute a MySQL program. If these errors specify symbols that start with mysql_ or indicate that the mysqlclient library can’t be found, it means that your system can’t find the shared libmysqlclient.so library. The fix for this is to tell your system to search for shared libraries where the library is located. Use whichever of the following methods is appropriate for your system:

  • Add the path to the directory where libmysqlclient.so is located to the LD_LIBRARY_PATH environment variable.

  • Add the path to the directory where libmysqlclient.so is located to the LD_LIBRARY environment variable.

  • Copy libmysqlclient.so to some directory that is searched by your system, such as /lib, and update the shared library information by executing ldconfig.

Another way to solve this problem is by linking your program statically with the -static option, or by removing the dynamic MySQL libraries before linking your code. Before trying the second method, you should be sure that no other programs are using the dynamic libraries.

A.3.2 How to Run MySQL as a Normal User

On Windows, you can run the server as a Windows service using normal user accounts beginning with MySQL 4.0.17 and 4.1.2. (Older MySQL versions required you to have administrator rights. This was a bug introduced in MySQL 3.23.54.)

On Unix, the MySQL server mysqld can be started and run by any user. However, you should avoid running the server as the Unix root user for security reasons. In order to change mysqld to run as a normal unprivileged Unix user user_name, you must do the following:

  1. Stop the server if it’s running (use mysqladmin shutdown).

  2. Change the database directories and files so that user_name has privileges to read and write files in them (you might need to do this as the Unix root user):
    shell> chown -R user_name /path/to/mysql/datadir
  3. If you do not do this, the server will not be able to access databases or tables when it runs as user_name.

  4. If directories or files within the MySQL data directory are symbolic links, you’ll also need to follow those links and change the directories and files they point to. chown -R might not follow symbolic links for you.

  5. Start the server as user user_name. If you are using MySQL 3.22 or later, another alternative is to start mysqld as the Unix root user and use the –user=user_name option. mysqld will start up, then switch to run as the Unix user user_name before accepting any connections.

  6. To start the server as the given user automatically at system startup time, specify the username by adding a user option to the [mysqld] group of the /etc/my.cnf option file or the my.cnf option file in the server’s data directory. For example:
    [mysqld]
    user=user_name

If your Unix machine itself isn’t secured, you should assign passwords to the MySQL root accounts in the grant tables. Otherwise, any user with a login account on that machine can run the mysql client with a –user=root option and perform any operation. (It is a good idea to assign passwords to MySQL accounts in any case, but especially so when other login accounts exist on the server host.) See Section 2.4, “Post-Installation Setup and Testing.”  

A.3.3 Problems with File Permissions

If you have problems with file permissions, the UMASK environment variable might be set incorrectly when mysqld starts. For example, MySQL might issue the following error message when you create a table:

ERROR: Can’t find file: ‘path/with/filename.frm’ (Errcode: 13)

The default UMASK value is 0660. You can change this behavior by starting mysqld_safe as follows:

shell> UMASK=384 # = 600 in octal
shell> export UMASK
shell> mysqld_safe &

By default, MySQL creates database and RAID directories with an access permission value of 0700. You can modify this behavior by setting the UMASK_DIR variable. If you set its value, new directories are created with the combined UMASK and UMASK_DIR values. For example, if you want to give group access to all new directories, you can do this:

shell> UMASK_DIR=504 # = 770 in octal
shell> export UMASK_DIR
shell> mysqld_safe &

In MySQL 3.23.25 and above, MySQL assumes that the value for UMASK and UMASK_DIR is in octal if it starts with a zero.

See Appendix B, “Environment Variables.”   

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=Administration-Related Issues}

A.4.1 How to Reset the Root Password

If you have never set a root password for MySQL, the server will not require a password at all for connecting as root. However, it is recommended to set a password for each account. See Section 4.3.1, “General Security Guidelines.”

If you set a root password previously, but have forgotten what it was, you can set a new password. The following procedure is for Windows systems. The procedure for Unix systems is given later in this section.

The procedure under Windows:

  1. Log on to your system as Administrator.

  2. Stop the MySQL server if it is running. For a server that is running as a Windows service, go to the Services manager:
    Start Menu -> Control Panel -> Administrative Tools -> Services
  3. Then find the MySQL service in the list, and stop it.

  4. If your server is not running as a service, you may need to use the Task Manager to force it to stop.

  5. Open a console window to get to the DOS command prompt:
    Start Menu -> Run -> cmd
  6. We are assuming that you installed MySQL to C:mysql. If you installed MySQL to another location, adjust the following commands accordingly.

  7. At the DOS command prompt, execute this command:
    C:> C:mysqlbinmysqld-nt –skip-grant-tables
  8. This starts the server in a special mode that does not check the grant tables to control access.

  9. Keeping the first console window open, open a second console window and execute the following commands (type each on a single line):
    C:> C:mysqlbinmysqladmin -u root
         flush-privileges password “newpwd
    C:> C:mysqlbinmysqladmin -u root -p shutdown
  10. Replace “newpwd” with the actual root password that you want to use. The second command will prompt you to enter the new password for access. Enter the password that you assigned in the first command.

  11. Stop the MySQL server, then restart it in normal mode again. If you run the server as a service, start it from the Windows Services window. If you start the server manually, use whatever command you normally use.

  12. You should now be able to connect using the new password.

In a Unix environment, the procedure for resetting the root password is as follows:

  1. Log on to your system as either the Unix root user or as the same user that the mysqld server runs as.

  2. Locate the .pid file that contains the server’s process ID. The exact location and name of this file depend on your distribution, hostname, and configuration. Common locations are /var/lib/mysql/, /var/run/mysqld/, and /usr/local/mysql/data/. Generally, the filename has the extension of .pid and begins with either mysqld or your system’s hostname.

  3. Now you can stop the MySQL server by sending a normal kill (not kill -9) to the mysqld process, using the pathname of the .pid file in the following command:
    shell> kill ´cat /mysql-data-directory/host_name.pid´
  4. Note the use of backticks rather than forward quotes with the cat command; these cause the output of cat to be substituted into the kill command.

  5. Restart the MySQL server with the special –skip-grant-tables option:
    shell> mysqld_safe –skip-grant-tables &
  6. Set a new password for the root@localhost MySQL account:
    shell> mysqladmin -u root flush-privileges password “newpwd
  7. Replace “newpwd” with the actual root password that you want to use.

  8. Stop the MySQL server, then restart it in normal mode again.

  9. You should now be able to connect using the new password.

Alternatively, on any platform, you can set the new password using the mysql client:

  1. Stop mysqld and restart it with the –skip-grant-tables option as described earlier.

  2. Connect to the mysqld server with this command:
    shell> mysql -u root
  3. Issue the following statements in the mysql client:
    mysql> UPDATE mysql.user SET Password=PASSWORD(‘newpwd‘)
      ->          WHERE User=’root’;
    mysql> FLUSH PRIVILEGES;
  4. Replace “newpwd” with the actual root password that you want to use.

  5. Stop the MySQL server, then restart it in normal mode again.

  6. You should now be able to connect using the new password.

   

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=How to Deal with MySQL if it Crashes}

A.4.2 What to Do If MySQL Keeps Crashing

Each MySQL version is tested on many platforms before it is released. This doesn’t mean that there are no bugs in MySQL, but if there are bugs, they should be very few and can be hard to find. If you have a problem, it will always help if you try to find out exactly what crashes your system, because you will have a much better chance of getting the problem fixed quickly.

First, you should try to find out whether the problem is that the mysqld server dies or whether your problem has to do with your client. You can check how long your mysqld server has been up by executing mysqladmin version. If mysqld has died and restarted, you may find the reason by looking in the server’s error log. See Section 4.8.1, “The Error Log.”

On some systems, you can find in the error log a stack trace of where mysqld died that you can resolve with the resolve_stack_dump program. Note that the variable values written in the error log may not always be 100% correct.

Many server crashes are caused by corrupted data files or index files. MySQL will update the files on disk with the write() system call after every SQL statement and before the client is notified about the result. (This is not true if you are running with –delay-key-write, in which case data files are written but not index files.) This means that data file contents are safe even if mysqld crashes, because the operating system will ensure that the unflushed data is written to disk. You can force MySQL to flush everything to disk after every SQL statement by starting mysqld with the –flush option.

The preceding means that normally you should not get corrupted tables unless one of the following happens:

  • The MySQL server or the server host was killed in the middle of an update.

  • You have found a bug in mysqld that caused it to die in the middle of an update.

  • Some external program is manipulating data files or index files at the same time as mysqld without locking the table properly.

  • You are running many mysqld servers using the same data directory on a system that doesn’t support good filesystem locks (normally handled by the lockd lock manager), or you are running multiple servers with the –skip-external-locking option.

  • You have a crashed data file or index file that contains very corrupt data that confused mysqld.

  • You have found a bug in the data storage code. This isn’t likely, but it’s at least possible. In this case, you can try to change the table type to another storage engine by using ALTER TABLE on a repaired copy of the table.

Because it is very difficult to know why something is crashing, first try to check whether things that work for others crash for you. Please try the following things:

  • Stop the mysqld server with mysqladmin shutdown, run myisamchk –silent –force */*.MYI from the data directory to check all MyISAM tables, and restart mysqld. This will ensure that you are running from a clean state. See Chapter 4, “Database Administration.”

  • Start mysqld with the –log option and try to determine from the information written to the log whether some specific query kills the server. About 95% of all bugs are related to a particular query. Normally, this will be one of the last queries in the log file just before the server restarts. See Section 4.8.2, “The General Query Log.” If you can repeatedly kill MySQL with a specific query, even when you have checked all tables just before issuing it, then you have been able to locate the bug and should submit a bug report for it. See Section 1.7.1.3, “How to Report Bugs or Problems.”

  • Try to make a test case that we can use to repeat the problem.

  • Try running the tests in the mysql-test directory and the MySQL benchmarks. They should test MySQL rather well. You can also add code to the benchmarks that simulates your application. The benchmarks can be found in the sql-bench directory in a source distribution or, for a binary distribution, in the sql-bench directory under your MySQL installation directory.

  • Try the fork_big.pl script. (It is located in the tests directory of source distributions.)

  • If you configure MySQL for debugging, it will be much easier to gather information about possible errors if something goes wrong. Configuring MySQL for debugging causes a safe memory allocator to be included that can find some errors. It also provides a lot of output about what is happening. Reconfigure MySQL with the –with-debug or –with-debug=full option to configure and then recompile.

  • Make sure that you have applied the latest patches for your operating system.

  • Use the –skip-external-locking option to mysqld. On some systems, the lockd lock manager does not work properly; the –skip-external-locking option tells mysqld not to use external locking. (This means that you cannot run two mysqld servers on the same data directory and that you must be careful if you use myisamchk. Nevertheless, it may be instructive to try the option as a test.)

  • Have you tried mysqladmin -u root processlist when mysqld appears to be running but not responding? Sometimes mysqld is not comatose even though you might think so. The problem may be that all connections are in use, or there may be some internal lock problem. mysqladmin -u root processlist usually will be able to make a connection even in these cases, and can provide useful information about the current number of connections and their status.

  • Run the command mysqladmin -i 5 status or mysqladmin -i 5 -r status in a separate window to produce statistics while you run your other queries.

  • Try the following:

    1. Start mysqld from gdb (or another debugger).

    2. Run your test scripts.

    3. Print the backtrace and the local variables at the three lowest levels. In gdb, you can do this with the following commands when mysqld has crashed inside gdb:

    4. backtrace
      info local
      up
      info local
      up
      info local
    5. With gdb, you can also examine which threads exist with info threads and switch to a specific thread with thread #, where # is the thread ID.

  • Try to simulate your application with a Perl script to force MySQL to crash or misbehave.

  • Send a normal bug report. See Section 1.7.1.3, “How to Report Bugs or Problems.” Be even more detailed than usual. Because MySQL works for many people, it may be that the crash results from something that exists only on your computer (for example, an error that is related to your particular system libraries).

  • If you have a problem with tables containing dynamic-length rows and you are using only VARCHAR columns (not BLOB or TEXT columns), you can try to change all VARCHAR to CHAR with ALTER TABLE. This will force MySQL to use fixed-size rows. Fixed-size rows take a little extra space, but are much more tolerant to corruption.

  • The current dynamic row code has been in use at MySQL AB for several years with very few problems, but dynamic-length rows are by nature more prone to errors, so it may be a good idea to try this strategy to see whether it helps.

 

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

{mospagebreak title=How MySQL Handles a Full Disk, Temp Files, Socket Files and Time Zones}

A.4.3 How MySQL Handles a Full Disk

When a disk-full condition occurs, MySQL does the following:

  • It checks once every minute to see whether there is enough space to write the current row. If there is enough space, it continues as if nothing had happened.

  • Every six minutes it writes an entry to the log file, warning about the disk-full condition.

To alleviate the problem, you can take the following actions:

  • To continue, you only have to free enough disk space to insert all records.

  • To abort the thread, you must use mysqladmin kill. The thread will be aborted the next time it checks the disk (in one minute).

  • Other threads might be waiting for the table that caused the disk-full condition. If you have several “locked” threads, killing the one thread that is waiting on the disk-full condition will allow the other threads to continue.

Exceptions to the preceding behavior are when you use REPAIR TABLE or OPTIMIZE TABLE or when the indexes are created in a batch after LOAD DATA INFILE or after an ALTER TABLE statement. All of these statements may create large temporary files that, if left to themselves, would cause big problems for the rest of the system. If the disk becomes full while MySQL is doing any of these operations, it will remove the big temporary files and mark the table as crashed. The exception is that for ALTER TABLE, the old table will be left unchanged.

A.4.4 Where MySQL Stores Temporary Files

MySQL uses the value of the TMPDIR environment variable as the pathname of the directory in which to store temporary files. If you don’t have TMPDIR set, MySQL uses the system default, which is normally /tmp, /var/tmp, or /usr/tmp. If the filesystem containing your temporary file directory is too small, you can use the –tmpdir option to mysqld to specify a directory in a filesystem where you have enough space.

Starting from MySQL 4.1, the –tmpdir option can be set to a list of several paths that are used in round-robin fashion. Paths should be separated by colon characters (‘:‘) on Unix and semicolon characters (‘;‘) on Windows, NetWare, and OS/2. Note: To spread the load effectively, these paths should be located on different physical disks, not different partitions of the same disk.

If the MySQL server is acting as a replication slave, you should not set –tmpdir to point to a directory on a memory-based filesystem or to a directory that is cleared when the server host restarts. A replication slave needs some of its temporary files to survive a machine restart so that it can replicate temporary tables or LOAD DATA INFILE operations. If files in the temporary file directory are lost when the server restarts, replication will fail.

MySQL creates all temporary files as hidden files. This ensures that the temporary files will be removed if mysqld is terminated. The disadvantage of using hidden files is that you will not see a big temporary file that fills up the filesystem in which the temporary file directory is located.

When sorting (ORDER BY or GROUP BY), MySQL normally uses one or two temporary files. The maximum disk space required is determined by the following expression:

(length of what is sorted + sizeof(row pointer))
* number of matched rows
* 2

The row pointer size is usually four bytes, but may grow in the future for really big tables.

For some SELECT queries, MySQL also creates temporary SQL tables. These are not hidden and have names of the form SQL_*.

ALTER TABLE creates a temporary table in the same directory as the original table.

A.4.5 How to Protect or Change the MySQL Socket File /tmp/mysql.sock

The default location for the Unix socket file that the server uses for communication with local clients is /tmp/mysql.sock. This might cause problems, because on some versions of Unix, anyone can delete files in the /tmp directory.

On most versions of Unix, you can protect your /tmp directory so that files can be deleted only by their owners or the superuser (root). To do this, set the sticky bit on the /tmp directory by logging in as root and using the following command:

shell> chmod +t /tmp

You can check whether the sticky bit is set by executing ls -ld /tmp. If the last permission character is t, the bit is set.

Another approach is to change the place where the server creates the Unix socket file. If you do this, you should also let client programs know the new location of the file. You can specify the file location in several ways:

  • Specify the path in a global or local option file. For example, put the following lines in /etc/my.cnf:
    [mysqld]
    socket=/path/to/socket
    
    [client]
    socket=/path/to/socket
  • See Section 3.3.2, “Using Option Files.”

  • Specify a –socket option on the command line to mysqld_safe and when you run client programs.

  • Set the MYSQL_UNIX_PORT environment variable to the path of the Unix socket file.

  • Recompile MySQL from source to use a different default Unix socket file location. Define the path to the file with the –with-unix-socket-path option when you run configure. See Section 2.3.2, “Typical configure Options.”

You can test whether the new socket location works by attempting to connect to the server with this command:

shell> mysqladmin –socket=/path/to/socket version

A.4.6 Time Zone Problems

If you have a problem with SELECT NOW() returning values in GMT and not your local time, you have to tell the server your current time zone. The same applies if UNIX_TIMESTAMP() returns the wrong value. This should be done for the environment in which the server runs; for example, in mysqld_safe or mysql.server. See Appendix B, “Environment Variables.”

You can set the time zone for the server with the –timezone=timezone_name option to mysqld_safe. You can also set it by setting the TZ environment variable before you start mysqld.

The allowable values for –timezone or TZ are system-dependent. Consult your operating system documentation to see what values are acceptable.   

SamsThis chapter is from MySQL Administrator’s Guide, by MySQL AB. (Sams, 2004, ISBN: 0672326345). Check it out at your favorite bookstore today. Buy this book now.

Google+ Comments

Google+ Comments