Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.1Mb
PDF (A4) - 38.1Mb
PDF (RPM) - 33.0Mb
HTML Download (TGZ) - 8.1Mb
HTML Download (Zip) - 8.1Mb
HTML Download (RPM) - 6.9Mb
Man Pages (TGZ) - 132.7Kb
Man Pages (Zip) - 189.0Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Moving Tablespace Files While the Server is Offline

15.7.7 Moving Tablespace Files While the Server is Offline

The innodb_directories option, which defines directories to scan at startup for tablespace files, supports moving or restoring tablespace files to a new location while the server is offline. During startup, discovered tablespace files are used instead those referenced in the data dictionary, and the data dictionary is updated to reference the relocated files. If duplicate tablespace files are discovered by the scan, startup fails with an error indicating that multiple files were found for the same tablespace ID.

The directories defined by the innodb_data_home_dir, innodb_undo_directory, and datadir configuration options are automatically appended to the innodb_directories argument value. These directories are scanned at startup regardless of whether the innodb_directories option is specified explicitly. The implicit addition of these directories permits moving system tablespace files, the data directory, or undo tablespace files without configuring the innodb_directories setting. However, settings must be updated when directories change. For example, after relocating the data directory, you must update the --datadir setting before restarting the server.

The innodb_directories option may be specified in a startup command or MySQL option file. Quotes are used around the argument value because otherwise a semicolon (;) is interpreted as a special character by some command interpreters. (Unix shells treat it as a command terminator, for example.)

Startup command:

mysqld --innodb-directories="directory_path_1;directory_path_2"

MySQL option file:

[mysqld]
innodb_directories="directory_path_1;directory_path_2"

The following procedure is applicable to moving individual file-per-table and general tablespace files, system tablespace files, undo tablespace files, or the data directory. Before moving files or directories, review the usage notes that follow.

  1. Stop the server.

  2. Move the tablespace files or directories.

  3. Make the new directory known to InnoDB.

    • If moving individual file-per-table or general tablespace files, add unknown directories to the innodb_directories value.

      • The directories defined by the innodb_data_home_dir, innodb_undo_directory, and datadir configuration options are automatically appended to the innodb_directories argument value, so you need not specify these.

      • A file-per-table tablespace file can only be moved to a directory with same name as the schema. For example, if the actor table belongs to the sakila schema, then the actor.ibd data file can only be moved to a directory named sakila.

      • General tablespace files cannot be moved to the data directory or a subdirectory of the data directory.

    • If moving system tablespace files, undo tablespaces, or the data directory, update the innodb_data_home_dir, innodb_undo_directory, and datadir settings, as necessary.

  4. Restart the server.

Usage Notes

  • Wildcard expressions cannot be used in the innodb_directories argument value.

  • The innodb_directories scan also traverses subdirectories of specified directories. Duplicate directories and subdirectories are discarded from the list of directories to be scanned.

  • The innodb_directories option only supports moving InnoDB tablespace files. Moving files that belong to a storage engine other than InnoDB is not supported. This restriction also applies when moving the entire data directory.

  • The innodb_directories option supports renaming of tablespace files when moving files to a scanned directory. It also supports moving tablespaces files to other supported operating systems.

  • When moving tablespace files to a different operating system, ensure that tablespace file names do not include prohibited characters or characters with a special meaning on the destination system.

  • If moving tablespace files to a different operating system introduces cross-platform replication, it is the responsibility of the Database Administrator to ensure proper replication of DDL statements that contain platform-specific directories. Statements that permit specifying directories include CREATE TABLE ... DATA DIRECTORY and CREATE TABLESPACE ... ADD DATAFILE.

  • The directory of file-per-table and general tablespace files created with an absolute path or in a location outside of the data directory should be added to the innodb_directories argument value. Otherwise, InnoDB is not able to locate these files during recovery. CREATE TABLE ... DATA DIRECTORY and CREATE TABLESPACE ... ADD DATAFILE permit creation of tablespace files with absolute paths. CREATE TABLESPACE ... ADD DATAFILE also permits tablespace file directories that are relative to the data directory. To view tablespace file locations, query the INFORMATION_SCHEMA.FILES table:

    mysql> SELECT TABLESPACE_NAME, FILE_NAME FROM INFORMATION_SCHEMA.FILES \G
  • CREATE TABLESPACE ... ADD DATAFILE requires that the target directory exists and is known to InnoDB. Known directories include those implicitly and explicitly defined by the innodb_directories option.


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.