Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.0Mb
PDF (A4) - 38.0Mb
PDF (RPM) - 37.3Mb
HTML Download (TGZ) - 10.3Mb
HTML Download (Zip) - 10.3Mb
HTML Download (RPM) - 8.9Mb
Man Pages (TGZ) - 216.7Kb
Man Pages (Zip) - 329.5Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  Password Expiration and Sandbox Mode

6.3.8 Password Expiration and Sandbox Mode

MySQL provides password-expiration capability to enable database administrators to expire account passwords and require users to reset their password. This section describes how password expiration works.

To expire an account password, use the ALTER USER statement. For example:

ALTER USER 'myuser'@'localhost' PASSWORD EXPIRE;

This statement modifies the row of the mysql.user table associated with the named account, setting the password_expired column to 'Y'. This does not affect any current connections the account has open. For each subsequent connection that uses the account, the server either disconnects the client or handles the client in sandbox mode, in which the server permits to the client only those operations necessary to reset the expired password. The action taken by the server depends on both client and server settings.

If the server disconnects the client, it returns an ER_MUST_CHANGE_PASSWORD_LOGIN error:

shell> mysql -u myuser -p
Password: ******
ERROR 1862 (HY000): Your password has expired. To log in you must
change it using a client that supports expired passwords.

If the server puts the client in sandbox mode, these operations are permitted within the client session:

  • The client can reset the account password with ALTER USER or SET PASSWORD. This modifies the row of the mysql.user table associated with the current account, setting the password_expired column to 'N'. After the password has been reset, the server restores normal access for the session, as well as for subsequent connections that use the account.

    It is possible to reset a password by setting it to its current value. As a matter of good policy, it is preferable to choose a different password.

  • The client can use SET statements, which is useful before MySQL 5.7.6 if SET PASSWORD must be used instead of ALTER USER and the account password has a hashing format that requires old_passwords to be set to a value different from its default.

For any operation not permitted within the session, the server returns an ER_MUST_CHANGE_PASSWORD error:

mysql> USE performance_schema;
ERROR 1820 (HY000): You must reset your password using ALTER USER
statement before executing this statement.

mysql> SELECT 1;
ERROR 1820 (HY000): You must reset your password using ALTER USER
statement before executing this statement.

For noninteractive invocations of the mysql client (for example, in batch mode), the server normally disconnects the client if the password is expired. To permit noninteractive mysql invocations to stay connected so that the password can be changed (using the statements just described), add the --connect-expired-password option to the mysql command.

As mentioned previously, whether the server disconnects an expired-password client or puts it in sandbox mode depends on a combination of client and server settings. The following discussion describes the relevant settings and how they interact.

On the client side, a given client indicates whether it can handle sandbox mode for expired passwords. For clients that use the C client library, there are two ways to do this:

  • Pass the MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS flag to mysql_options() prior to connecting:

    arg = 1;
    result = mysql_options(mysql,
                           MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS, &arg);

    The mysql client enables MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS if invoked interactively or the --connect-expired-password option is given.

  • Pass the CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS flag to mysql_real_connect() at connection time:

    mysql = mysql_real_connect(mysql,
                               host, user, password, "test",
                               port, unix_socket,

Other MySQL Connectors have their own conventions for indicating readiness to handle sandbox mode. See the relevant Connector documentation.

On the server side, if a client indicates that it can handle expired passwords, the server puts it in sandbox mode.

If a client does not indicate that it can handle expired passwords (or uses an older version of the client library that cannot so indicate), the server action depends on the value of the disconnect_on_expired_password system variable:

The preceding client and server settings apply only for accounts with expired passwords. If a client connects using a nonexpired password, the server handles the client normally.

User Comments
Sign Up Login You must be logged in to post a comment.