WL#9809: RESTART command
Affects: Server-8.0 — Status: Complete
To enable remote management of the MySQL server through a remote SQL connection, it must be possible to set certain non-dynamic configuration variables which may require a restart of the server. Because requiring a manual restart of the server through a shell session in the host where MySQL is running would not be completely useful, it must also be possible to restart the server itself through a SQL connection. Accordingly this WL shall implement SQL command RESTART which allows a server to restart itself via a SQL connection.
FR1: Platform support FR1.1: The RESTART command will be supported for *nix OSes which support systemd FR1.2: The RESTART command will be supported on Windows when mysqld is started either as a windows service or standalone. FR1.3: For *nux platforms not supporting systemd, the RESTART command will be supported through mysqld_safe. FR2: Installation FR2.1: *nix which support systemd: The installer will configure systemd service file to enable RESTART. FR2.2: For *nix platforms not supporting systemd, there are no special installation requirements. FR3: The RESTART command should be logged as a force print note to the error log. FR4: The RESTART command should have the same privilege requirements as SHUTDOWN. SHUTDOWN needs to be accorded to user who want to execute RESTART. FR5: The RESTART command will shut down the server with a special exit-code, to distinguish the shutdown from a normal shutdown.
If a restart fails after a RESTART command has been issued, the user is left to sort out the failure. If possible, the server should try to detect a situation where the server is restarted in a circular fashion, and then just fail with a message to the error log.
RESTART command ================ Introduction ------------- The worklog introduces a RESTART sql command. The semantics of this sql command is that it shuts the mysql server and allows it to restart. This command is similar to that of the SHUTDOWN sql and is an administrative command. The SHUTDOWN privilege needs to be accorded to the user for the execution of this command. RESTART shall be administrative DDL type of command and there would be no replication semantics associated with this command. Parser Component The parser component consists of required changes in the parser related code to implement the SQL interface RESTART. This component provides interaction with DBAs and end-users for RESTART implementation. It does syntax validation and invokes the core runtime executor to implement the functionality. Runtime execution component The runtime execution component implements the RESTART functionality. The implementation is different for Unix and Windows. Unix Implementation The restart on unix is performed by an external supervisor process. The supervisor processessystemd (on linux platforms) and mysqld_safe are supported by default for restart. Other supervisor processes can be configured for restart. The supervisor needs to set an environment variable MYSQLD_PARENT_PID. systemd and mysqld_safe are configured to set this variable accordingly. If mysqld is invoked without this environment, it shall fail with ER_RESTART_FAILED with appropriate indicating that it is not under the control of a supervisor process. The restart implementation sends a signal SIGUSR2 to the signal handler thread. The signal handler thread closes the listener sockets and then closes all client connections. Then signal thread then joins the main mysqld thread. Further shutdown sequence happens in this thread. For the restart case, once all cleanups, we exit mysqld with exit code of 16. Please note an exit code of zero signifies successful exit. The exit code of 16 will be used by server only for restart and most cases of unsuccessful exit from server via mysqld_exit has an exit code of 1. In some case the server uses a direct exit and return exit value of 3. We use the exit value 16.An assert has been added in mysqld_exit to enforce this.The supervisor process makes use of the special exit code to restart mysqld. It is up to the end user to ensure system is in a safe state before RESTART is invoked. Windows Implementation Windows service only restart on failure codes and an event is logged in event log indicating an failure. Hence we can't make use of the windows to configure for restart. We have in-built parent monitor process which shall spawn the child mysqld to allow for restart under windows. In windows, when mysqld is invoked, the initial process acts as monitor process and it add the environment MYSQLD_PARENT_PID and then spawns the child mysqld with this modified environment. The monitor the waits on the process handle of spawned mysqld monitoring for restart and shutdown. This works when mysqld is started as a standalone. For integration with windows service, in addition a named pipe shall be created between the monitor and mysqld. The mysqld will send service status to the monitor which then shall rely to the windows SCM. This is used indicate when the servic has started successfully and is running as well as for setting slow start timeout of the service in case the server does some recovery. The service initialization needs to be done by the initial monitor (parent) process.
Copyright (c) 2000, 2023, Oracle Corporation and/or its affiliates. All rights reserved.