<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h2 class="title">
      <a name="charset-applications">
      </a>
      12.5 Configuring Application Character Set and Collation
     </h2>
    </div>
   </div>
  </div>
  <a class="indexterm" name="idm46045217278528">
  </a>
  <p>
   For applications that store data using the default MySQL character
      set and collation (
   <code class="literal">
    utf8mb4
   </code>
   ,
   <code class="literal">
    utf8mb4_0900_ai_ci
   </code>
   ), no special configuration
      should be needed. If applications require data storage using a
      different character set or collation, you can configure character
      set information several ways:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Specify character settings per database. For example,
          applications that use one database might use the default of
      <code class="literal">
       utf8mb4
      </code>
      , whereas applications that use
          another database might use
      <code class="literal">
       sjis
      </code>
      .
     </p>
    </li>
    <li class="listitem">
     <p>
      Specify character settings at server startup. This causes the
          server to use the given settings for all applications that do
          not make other arrangements.
     </p>
    </li>
    <li class="listitem">
     <p>
      Specify character settings at configuration time, if you build
          MySQL from source. This causes the server to use the given
          settings as the defaults for all applications, without having
          to specify them at server startup.
     </p>
    </li>
   </ul>
  </div>
  <p>
   When different applications require different character settings,
      the per-database technique provides a good deal of flexibility. If
      most or all applications use the same character set, specifying
      character settings at server startup or configuration time may be
      most convenient.
  </p>
  <p>
   For the per-database or server-startup techniques, the settings
      control the character set for data storage. Applications must also
      tell the server which character set to use for client/server
      communications, as described in the following instructions.
  </p>
  <p>
   The examples shown here assume use of the
   <code class="literal">
    latin1
   </code>
   character set and
   <code class="literal">
    latin1_swedish_ci
   </code>
   collation in particular
      contexts as an alternative to the defaults of
   <code class="literal">
    utf8mb4
   </code>
   and
   <code class="literal">
    utf8mb4_0900_ai_ci
   </code>
   .
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      <b>
       Specify character settings per database.
      </b>
      To create a database such that its tables use a given
            default character set and collation for data storage, use a
      <a class="link" href="create-database.html" title="15.1.12 CREATE DATABASE Statement">
       <code class="literal">
        CREATE DATABASE
       </code>
      </a>
      statement
            like this:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-sql"><div class="docs-select-all right" id="sa10168135"><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-sql"><span class="token keyword">CREATE</span> <span class="token keyword">DATABASE</span> mydb
  <span class="token keyword">CHARACTER</span> <span class="token keyword">SET</span> latin1
  <span class="token keyword">COLLATE</span> latin1_swedish_ci<span class="token punctuation">;</span></code></pre>
     </div>
     <p>
      Tables created in the database use
      <code class="literal">
       latin1
      </code>
      and
      <code class="literal">
       latin1_swedish_ci
      </code>
      by default for any
          character columns.
     </p>
     <p>
      Applications that use the database should also configure their
          connection to the server each time they connect. This can be
          done by executing a
      <code class="literal">
       SET NAMES 'latin1'
      </code>
      statement after connecting. The statement can be used
          regardless of connection method (the
      <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
       <span class="command">
        <strong>
         mysql
        </strong>
       </span>
      </a>
      client, PHP scripts, and so forth).
     </p>
     <p>
      In some cases, it may be possible to configure the connection
          to use the desired character set some other way. For example,
          to connect using
      <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
       <span class="command">
        <strong>
         mysql
        </strong>
       </span>
      </a>
      , you can specify the
      <a class="link" href="mysql-command-options.html#option_mysql_default-character-set">
       <code class="option">
        --default-character-set=latin1
       </code>
      </a>
      command-line option to achieve the same effect as
      <code class="literal">
       SET
          NAMES 'latin1'
      </code>
      .
     </p>
     <p>
      For more information about configuring client connections, see
      <a class="xref" href="charset-connection.html" title="12.4 Connection Character Sets and Collations">
       Section 12.4, “Connection Character Sets and Collations”
      </a>
      .
     </p>
     <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
      <div class="admon-title">
       Note
      </div>
      <p>
       If you use
       <a class="link" href="alter-database.html" title="15.1.2 ALTER DATABASE Statement">
        <code class="literal">
         ALTER DATABASE
        </code>
       </a>
       to
            change the database default character set or collation,
            existing stored routines in the database that use those
            defaults must be dropped and recreated so that they use the
            new defaults. (In a stored routine, variables with character
            data types use the database defaults if the character set or
            collation are not specified explicitly. See
       <a class="xref" href="create-procedure.html" title="15.1.17 CREATE PROCEDURE and CREATE FUNCTION Statements">
        Section 15.1.17, “CREATE PROCEDURE and CREATE FUNCTION Statements”
       </a>
       .)
      </p>
     </div>
    </li>
    <li class="listitem">
     <p>
      <b>
       Specify character settings at server startup.
      </b>
      To select a character set and collation at server startup,
            use the
      <a class="link" href="server-system-variables.html#sysvar_character_set_server">
       <code class="option">
        --character-set-server
       </code>
      </a>
      and
      <a class="link" href="server-system-variables.html#sysvar_collation_server">
       <code class="option">
        --collation-server
       </code>
      </a>
      options.
            For example, to specify the options in an option file,
            include these lines:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-ini"><div class="docs-select-all right" id="sa61965647"><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-ini"><span class="token selector">[mysqld]</span>
<span class="token constant">character-set-server</span><span class="token attr-value"><span class="token punctuation">=</span>latin1</span>
<span class="token constant">collation-server</span><span class="token attr-value"><span class="token punctuation">=</span>latin1_swedish_ci</span></code></pre>
     </div>
     <p>
      These settings apply server-wide and apply as the defaults for
          databases created by any application, and for tables created
          in those databases.
     </p>
     <p>
      It is still necessary for applications to configure their
          connection using
      <a class="link" href="set-names.html" title="15.7.6.3 SET NAMES Statement">
       <code class="literal">
        SET NAMES
       </code>
      </a>
      or
          equivalent after they connect, as described previously. You
          might be tempted to start the server with the
      <a class="link" href="server-system-variables.html#sysvar_init_connect">
       <code class="option">
        --init_connect="SET NAMES
          'latin1'"
       </code>
      </a>
      option to cause
      <a class="link" href="set-names.html" title="15.7.6.3 SET NAMES Statement">
       <code class="literal">
        SET
          NAMES
       </code>
      </a>
      to be executed automatically for each client
          that connects. However, this may yield inconsistent results
          because the
      <a class="link" href="server-system-variables.html#sysvar_init_connect">
       <code class="literal">
        init_connect
       </code>
      </a>
      value is not executed for users who have the
      <a class="link" href="privileges-provided.html#priv_connection-admin">
       <code class="literal">
        CONNECTION_ADMIN
       </code>
      </a>
      privilege (or
          the deprecated
      <a class="link" href="privileges-provided.html#priv_super">
       <code class="literal">
        SUPER
       </code>
      </a>
      privilege).
     </p>
    </li>
    <li class="listitem">
     <p>
      <b>
       Specify character settings at MySQL configuration time.
      </b>
      To select a character set and collation if you configure and
            build MySQL from source, use the
      <a class="link" href="source-configuration-options.html#option_cmake_default_charset">
       <code class="option">
        DEFAULT_CHARSET
       </code>
      </a>
      and
      <a class="link" href="source-configuration-options.html#option_cmake_default_collation">
       <code class="option">
        DEFAULT_COLLATION
       </code>
      </a>
      <span class="command">
       <strong>
        CMake
       </strong>
      </span>
      options:
     </p>
     <div class="copytoclipboard-wrapper">
      <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa27836952"><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-terminal">cmake <span class="token punctuation">.</span> <span class="token constant">-DDEFAULT_CHARSET</span><span class="token attr-value"><span class="token punctuation">=</span>latin1</span> \
  <span class="token constant">-DDEFAULT_COLLATION</span><span class="token attr-value"><span class="token punctuation">=</span>latin1_swedish_ci</span></code></pre>
     </div>
     <p>
      The resulting server uses
      <code class="literal">
       latin1
      </code>
      and
      <code class="literal">
       latin1_swedish_ci
      </code>
      as the default for
          databases and tables and for client connections. It is
          unnecessary to use
      <a class="link" href="server-system-variables.html#sysvar_character_set_server">
       <code class="option">
        --character-set-server
       </code>
      </a>
      and
      <a class="link" href="server-system-variables.html#sysvar_collation_server">
       <code class="option">
        --collation-server
       </code>
      </a>
      to specify
          those defaults at server startup. It is also unnecessary for
          applications to configure their connection using
      <a class="link" href="set-names.html" title="15.7.6.3 SET NAMES Statement">
       <code class="literal">
        SET NAMES
       </code>
      </a>
      or equivalent after
          they connect to the server.
     </p>
    </li>
   </ul>
  </div>
  <p>
   Regardless of how you configure the MySQL character set for
      application use, you must also consider the environment within
      which those applications execute. For example, if you intend to
      send statements using UTF-8 text taken from a file that you create
      in an editor, you should edit the file with the locale of your
      environment set to UTF-8 so that the file encoding is correct and
      so that the operating system handles it correctly. If you use the
   <a class="link" href="mysql.html" title="6.5.1 mysql — The MySQL Command-Line Client">
    <span class="command">
     <strong>
      mysql
     </strong>
    </span>
   </a>
   client from within a terminal window, the
      window must be configured to use UTF-8 or characters may not
      display properly. For a script that executes in a Web environment,
      the script must handle character encoding properly for its
      interaction with the MySQL server, and it must generate pages that
      correctly indicate the encoding so that browsers know how to
      display the content of the pages. For example, you can include
      this
   <code class="literal">
    &lt;meta&gt;
   </code>
   tag within your
   <code class="literal">
    &lt;head&gt;
   </code>
   element:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting one-line language-html"><div class="docs-select-all right" id="sa12094245"><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-html"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>meta</span> <span class="token attr-name">http-equiv</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Content-Type<span class="token punctuation">"</span></span> <span class="token attr-name">content</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>text/html; charset<span class="token punctuation">=</span>utf-8<span class="token punctuation">"</span></span> <span class="token punctuation">/&gt;</span></span></code></pre>
  </div>
 </div>
 <br/>
</div>
