<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h2 class="title">
      <a name="upgrading-what-is-upgraded">
      </a>
      3.4 What the MySQL Upgrade Process Upgrades
     </h2>
    </div>
   </div>
  </div>
  <p>
   Installing a new version of MySQL may require upgrading these
      parts of the existing installation:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The
      <code class="literal">
       mysql
      </code>
      system schema, which contains
          tables that store information required by the MySQL server as
          it runs (see
      <a class="xref" href="system-schema.html" title="7.3 The mysql System Schema">
       Section 7.3, “The mysql System Schema”
      </a>
      ).
      <code class="literal">
       mysql
      </code>
      schema tables fall into two broad
          categories:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         Data dictionary tables, which store database object
              metadata.
        </p>
       </li>
       <li class="listitem">
        <p>
         System tables (that is, the remaining non-data dictionary
              tables), which are used for other operational purposes.
        </p>
       </li>
      </ul>
     </div>
    </li>
    <li class="listitem">
     <p>
      Other schemas, some of which are built in and may be
          considered
      <span class="quote">
       “
       <span class="quote">
        owned
       </span>
       ”
      </span>
      by the server, and others
          which are not:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         The
         <a class="link" href="performance-schema.html" title="Chapter 29 MySQL Performance Schema">
          <code class="literal">
           performance_schema
          </code>
         </a>
         ,
         <a class="link" href="information-schema.html" title="Chapter 28 INFORMATION_SCHEMA Tables">
          <code class="literal">
           INFORMATION_SCHEMA
          </code>
         </a>
         ,
         <a class="link" href="mysql-cluster-ndbinfo.html" title="25.6.17 ndbinfo: The NDB Cluster Information Database">
          <code class="literal">
           ndbinfo
          </code>
         </a>
         , and
         <a class="link" href="sys-schema.html" title="Chapter 30 MySQL sys Schema">
          <code class="literal">
           sys
          </code>
         </a>
         schemas.
        </p>
       </li>
       <li class="listitem">
        <p>
         User schemas.
        </p>
       </li>
      </ul>
     </div>
    </li>
   </ul>
  </div>
  <p>
   Two distinct version numbers are associated with parts of the
      installation that may require upgrading:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      The data dictionary version. This applies to the data
          dictionary tables.
     </p>
    </li>
    <li class="listitem">
     <p>
      The server version, also known as the MySQL version. This
          applies to the system tables and objects in other schemas.
     </p>
    </li>
   </ul>
  </div>
  <p>
   In both cases, the actual version applicable to the existing MySQL
      installation is stored in the data dictionary, and the current
      expected version is compiled into the new version of MySQL. When
      an actual version is lower than the current expected version,
      those parts of the installation associated with that version must
      be upgraded to the current version. If both versions indicate an
      upgrade is needed, the data dictionary upgrade must occur first.
  </p>
  <p>
   As a reflection of the two distinct versions just mentioned, the
      upgrade occurs in two steps:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Step 1: Data dictionary upgrade.
     </p>
     <p>
      This step upgrades:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         The data dictionary tables in the
         <code class="literal">
          mysql
         </code>
         schema. If the actual data dictionary version is lower
              than the current expected version, the server creates data
              dictionary tables with updated definitions, copies
              persisted metadata to the new tables, atomically replaces
              the old tables with the new ones, and reinitializes the
              data dictionary.
        </p>
       </li>
       <li class="listitem">
        <p>
         The Performance Schema,
         <code class="literal">
          INFORMATION_SCHEMA
         </code>
         , and
         <code class="literal">
          ndbinfo
         </code>
         .
        </p>
       </li>
      </ul>
     </div>
    </li>
    <li class="listitem">
     <p>
      Step 2: Server upgrade.
     </p>
     <p>
      This step comprises all other upgrade tasks. If the server
          version of the existing MySQL installation is lower than that
          of the new installed MySQL version, everything else must be
          upgraded:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         The system tables in the
         <code class="literal">
          mysql
         </code>
         schema
              (the remaining non-data dictionary tables).
        </p>
       </li>
       <li class="listitem">
        <p>
         The
         <code class="literal">
          sys
         </code>
         schema.
        </p>
       </li>
       <li class="listitem">
        <p>
         User schemas.
        </p>
       </li>
      </ul>
     </div>
    </li>
   </ul>
  </div>
  <p>
   The data dictionary upgrade (step 1) is the responsibility of the
      server, which performs this task as necessary at startup unless
      invoked with an option that prevents it from doing so. The option
      is
   <a class="link" href="server-options.html#option_mysqld_upgrade">
    <code class="option">
     --upgrade=NONE
    </code>
   </a>
   .
  </p>
  <p>
   If the data dictionary is out of date but the server is prevented
      from upgrading it, the server does not run, and exits with an
      error instead. For example:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-none"><div class="docs-select-all right" id="sa38838395"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">[ERROR] [MY-013381] [Server] Server shutting down because upgrade is
required, yet prohibited by the command line option '--upgrade=NONE'.
[ERROR] [MY-010334] [Server] Failed to initialize DD Storage Engine
[ERROR] [MY-010020] [Server] Data Dictionary initialization failed.</code></pre>
  </div>
  <p>
   The
   <a class="link" href="server-options.html#option_mysqld_upgrade">
    <code class="option">
     --upgrade
    </code>
   </a>
   server option
      controls whether and how the server performs an automatic upgrade
      at startup:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      With no option or with
      <a class="link" href="server-options.html#option_mysqld_upgrade">
       <code class="option">
        --upgrade=AUTO
       </code>
      </a>
      , the server
          upgrades anything it determines to be out of date (steps 1 and
          2).
     </p>
    </li>
    <li class="listitem">
     <p>
      With
      <a class="link" href="server-options.html#option_mysqld_upgrade">
       <code class="option">
        --upgrade=NONE
       </code>
      </a>
      , the server
          upgrades nothing (skips steps 1 and 2), but also exits with an
          error if the data dictionary must be upgraded. It is not
          possible to run the server with an out-of-date data
          dictionary; the server insists on either upgrading it or
          exiting.
     </p>
    </li>
    <li class="listitem">
     <p>
      With
      <a class="link" href="server-options.html#option_mysqld_upgrade">
       <code class="option">
        --upgrade=MINIMAL
       </code>
      </a>
      , the
          server upgrades the data dictionary, the Performance Schema,
          and the
      <code class="literal">
       INFORMATION_SCHEMA
      </code>
      , if necessary
          (step 1). Note that following an upgrade with this option,
          Group Replication cannot be started, because system tables on
          which the replication internals depend are not updated, and
          reduced functionality might also be apparent in other areas.
     </p>
    </li>
    <li class="listitem">
     <p>
      With
      <a class="link" href="server-options.html#option_mysqld_upgrade">
       <code class="option">
        --upgrade=FORCE
       </code>
      </a>
      , the
          server upgrades the data dictionary, the Performance Schema,
          and the
      <code class="literal">
       INFORMATION_SCHEMA
      </code>
      , if necessary
          (step 1), and forces an upgrade of everything else (step 2).
          Expect server startup to take longer with this option because
          the server checks all objects in all schemas.
     </p>
    </li>
   </ul>
  </div>
  <p>
   <code class="literal">
    FORCE
   </code>
   is useful to force step 2 actions to be
      performed if the server thinks they are not necessary. One way
      that
   <code class="literal">
    FORCE
   </code>
   differs from
   <code class="literal">
    AUTO
   </code>
   is that with
   <code class="literal">
    FORCE
   </code>
   , the server re-creates
      system tables such as help tables or time zone tables if they are
      missing.
  </p>
  <p>
   Additional notes about what occurs during upgrade step 2:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Step 2 installs the
      <code class="literal">
       sys
      </code>
      schema if it is not
          installed, and upgrades it to the current version otherwise.
          An error occurs if a
      <code class="literal">
       sys
      </code>
      schema exists but
          has no
      <code class="literal">
       version
      </code>
      view, on the assumption that
          its absence indicates a user-created schema:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-none"><div class="docs-select-all right" id="sa86592220"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-none">A sys schema exists with no sys.version view. If
you have a user created sys schema, this must be renamed for the
upgrade to succeed.</code></pre>
     </div>
     <p>
      To upgrade in this case, remove or rename the existing
      <code class="literal">
       sys
      </code>
      schema first. Then perform the upgrade
          procedure again. (It may be necessary to force step 2.)
     </p>
     <p>
      To prevent the
      <code class="literal">
       sys
      </code>
      schema check, start the
          server with the
      <code class="option">
       --upgrade=NONE
      </code>
      or
      <code class="option">
       --upgrade=MINIMAL
      </code>
      option.
     </p>
    </li>
    <li class="listitem">
     <p>
      Step 2 upgrades the system tables to ensure that they have the
          current structure, and this includes the help tables but not
          the time zone tables. The procedure for loading time zone
          tables is platform dependent and requires decision making by
          the DBA, so it cannot be done automatically.
     </p>
    </li>
    <li class="listitem">
     <p>
      When Step 2 is upgrading the system tables in the
      <code class="literal">
       mysql
      </code>
      schema, the column order in the
          primary key of the
      <code class="literal">
       mysql.db
      </code>
      ,
      <code class="literal">
       mysql.tables_priv
      </code>
      ,
      <code class="literal">
       mysql.columns_priv
      </code>
      and
      <code class="literal">
       mysql.procs_priv
      </code>
      tables is changed to place
          the host name and user name columns together. Placing the host
          name and user name together means that index lookup can be
          used, which improves performance for
      <a class="link" href="create-user.html" title="15.7.1.3 CREATE USER Statement">
       <code class="literal">
        CREATE USER
       </code>
      </a>
      ,
      <a class="link" href="drop-user.html" title="15.7.1.5 DROP USER Statement">
       <code class="literal">
        DROP USER
       </code>
      </a>
      , and
      <a class="link" href="rename-user.html" title="15.7.1.7 RENAME USER Statement">
       <code class="literal">
        RENAME USER
       </code>
      </a>
      statements, and for
          ACL checks for multiple users with multiple privileges.
          Dropping and re-creating the index is necessary and might take
          some time if the system has a large number of users and
          privileges.
     </p>
    </li>
    <li class="listitem">
     <p>
      Step 2 processes all tables in all user schemas as necessary.
          Table checking might take a long time to complete. Each table
          is locked and therefore unavailable to other sessions while it
          is being processed. Check and repair operations can be
          time-consuming, particularly for large tables. Table checking
          uses the
      <code class="literal">
       FOR UPGRADE
      </code>
      option of the
      <a class="link" href="check-table.html" title="15.7.3.2 CHECK TABLE Statement">
       <code class="literal">
        CHECK TABLE
       </code>
      </a>
      statement. For
          details about what this option entails, see
      <a class="xref" href="check-table.html" title="15.7.3.2 CHECK TABLE Statement">
       Section 15.7.3.2, “CHECK TABLE Statement”
      </a>
      .
     </p>
     <p>
      To prevent table checking, start the server with the
      <code class="option">
       --upgrade=NONE
      </code>
      or
      <code class="option">
       --upgrade=MINIMAL
      </code>
      option.
     </p>
     <p>
      To force table checking, start the server with the
      <code class="option">
       --upgrade=FORCE
      </code>
      option.
     </p>
    </li>
    <li class="listitem">
     <p>
      Step 2 marks all checked and repaired tables with the current
          MySQL version number. This ensures that the next time upgrade
          checking occurs with the same version of the server, it can be
          determined whether there is any need to check or repair a
          given table again.
     </p>
    </li>
   </ul>
  </div>
 </div>
 <br/>
</div>
