charset.sgml 41.9 KB
Newer Older
1
<!-- $PostgreSQL: pgsql/doc/src/sgml/charset.sgml,v 2.84 2007/09/28 22:25:49 tgl Exp $ -->
2

3 4 5
<chapter id="charset">
 <title>Localization</>

6 7 8 9
 <para>
  This chapter describes the available localization features from the
  point of view of the administrator.
  <productname>PostgreSQL</productname> supports localization with
10
  two approaches:
11 12 13 14

   <itemizedlist>
    <listitem>
     <para>
15
      Using the locale features of the operating system to provide
Peter Eisentraut's avatar
Peter Eisentraut committed
16 17
      locale-specific collation order, number formatting, translated
      messages, and other aspects.
18 19 20 21 22
     </para>
    </listitem>

    <listitem>
     <para>
23 24 25
      Providing a number of different character sets defined in the
      <productname>PostgreSQL</productname> server, including
      multiple-byte character sets, to support storing text in all
26
      kinds of languages, and providing character set translation between
27
      client and server.
28 29
     </para>
    </listitem>
30 31 32
   </itemizedlist>
  </para>

33 34 35 36

 <sect1 id="locale">
  <title>Locale Support</title>
  
37 38
  <indexterm zone="locale"><primary>locale</></>

39 40 41 42
  <para>
   <firstterm>Locale</> support refers to an application respecting
   cultural preferences regarding alphabets, sorting, number
   formatting, etc.  <productname>PostgreSQL</> uses the standard ISO
43
   C and <acronym>POSIX</acronym> locale facilities provided by the server operating
44
   system.  For additional information refer to the documentation of your
45 46 47 48 49 50
   system.
  </para>

  <sect2>
   <title>Overview</>

51 52 53 54
   <para>
    Locale support is automatically initialized when a database
    cluster is created using <command>initdb</command>.
    <command>initdb</command> will initialize the database cluster
55 56 57 58 59 60 61
    with the locale setting of its execution environment by default,
    so if your system is already set to use the locale that you want
    in your database cluster then there is nothing else you need to
    do.  If you want to use a different locale (or you are not sure
    which locale your system is set to), you can instruct
    <command>initdb</command> exactly which locale to use by
    specifying the <option>--locale</option> option. For example:
62
<screen>
63
initdb --locale=sv_SE
64 65 66
</screen>
   </para>

Peter Eisentraut's avatar
Peter Eisentraut committed
67
   <para>
68 69 70 71 72
    This example sets the locale to Swedish (<literal>sv</>) as spoken
    in Sweden (<literal>SE</>).  Other possibilities might be
    <literal>en_US</> (U.S. English) and <literal>fr_CA</> (French
    Canadian).  If more than one character set can be useful for a
    locale then the specifications look like this:
73 74
    <literal>cs_CZ.ISO8859-2</>. What locales are available under what
    names on your system depends on what was provided by the operating
75 76
    system vendor and what was installed.  (On most systems, the command
    <literal>locale -a</> will provide a list of available locales.)
77 78 79 80
   </para>

   <para>
    Occasionally it is useful to mix rules from several locales, e.g.,
81
    use English collation rules but Spanish messages.  To support that, a
82
    set of locale subcategories exist that control only a certain
83
    aspect of the localization rules:
84 85 86 87 88

    <informaltable>
     <tgroup cols="2">
      <tbody>
       <row>
89
        <entry><envar>LC_COLLATE</></>
90 91 92
        <entry>String sort order</>
       </row>
       <row>
93
        <entry><envar>LC_CTYPE</></>
94
        <entry>Character classification (What is a letter? Its upper-case equivalent?)</>
95 96
       </row>
       <row>
97
        <entry><envar>LC_MESSAGES</></>
98 99 100
        <entry>Language of messages</>
       </row>
       <row>
101
        <entry><envar>LC_MONETARY</></>
102 103 104
        <entry>Formatting of currency amounts</>
       </row>
       <row>
105
        <entry><envar>LC_NUMERIC</></>
106 107 108
        <entry>Formatting of numbers</>
       </row>
       <row>
109
        <entry><envar>LC_TIME</></>
110 111 112 113 114 115
        <entry>Formatting of dates and times</>
       </row>
      </tbody>
     </tgroup>
    </informaltable>

116 117 118 119 120
    The category names translate into names of
    <command>initdb</command> options to override the locale choice
    for a specific category.  For instance, to set the locale to
    French Canadian, but use U.S. rules for formatting currency, use
    <literal>initdb --locale=fr_CA --lc-monetary=en_US</literal>.
121 122 123 124
   </para>

   <para>
    If you want the system to behave as if it had no locale support,
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
    use the special locale <literal>C</> or <literal>POSIX</>.
   </para>

   <para>
    The nature of some locale categories is that their value has to be
    fixed for the lifetime of a database cluster.  That is, once
    <command>initdb</command> has run, you cannot change them anymore.
    <literal>LC_COLLATE</literal> and <literal>LC_CTYPE</literal> are
    those categories.  They affect the sort order of indexes, so they
    must be kept fixed, or indexes on text columns will become corrupt.
    <productname>PostgreSQL</productname> enforces this by recording
    the values of <envar>LC_COLLATE</> and <envar>LC_CTYPE</> that are
    seen by <command>initdb</>.  The server automatically adopts
    those two values when it is started.
   </para>

   <para>
    The other locale categories can be changed as desired whenever the
143
    server is running by setting the run-time configuration variables
144
    that have the same name as the locale categories (see <xref
145
    linkend="runtime-config-client-format"> for details).  The defaults that are
146 147
    chosen by <command>initdb</command> are actually only written into
    the configuration file <filename>postgresql.conf</filename> to
148
    serve as defaults when the server is started.  If you delete these
149
    assignments from <filename>postgresql.conf</filename> then the
150
    server will inherit the settings from its execution environment.
151 152 153
   </para>

   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
154 155
    Note that the locale behavior of the server is determined by the
    environment variables seen by the server, not by the environment
156
    of any client.  Therefore, be careful to configure the correct locale settings
Peter Eisentraut's avatar
Peter Eisentraut committed
157
    before starting the server.  A consequence of this is that if
158
    client and server are set up in different locales, messages might
Peter Eisentraut's avatar
Peter Eisentraut committed
159
    appear in different languages depending on where they originated.
160 161
   </para>

162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
   <note>
    <para>
     When we speak of inheriting the locale from the execution
     environment, this means the following on most operating systems:
     For a given locale category, say the collation, the following
     environment variables are consulted in this order until one is
     found to be set: <envar>LC_ALL</envar>, <envar>LC_COLLATE</envar>
     (the variable corresponding to the respective category),
     <envar>LANG</envar>.  If none of these environment variables are
     set then the locale defaults to <literal>C</literal>.
    </para>

    <para>
     Some message localization libraries also look at the environment
     variable <envar>LANGUAGE</envar> which overrides all other locale
     settings for the purpose of setting the language of messages.  If
     in doubt, please refer to the documentation of your operating
179 180
     system, in particular the documentation about
     <application>gettext</>, for more information.
181 182 183
    </para>
   </note>

184
   <para>
185
    To enable messages to be translated to the user's preferred language,
186 187
    <acronym>NLS</acronym> must have been enabled at build time.  This
    choice is independent of the other locale support.
188 189 190 191
   </para>
  </sect2>

  <sect2>
192
   <title>Behavior</>
193 194

   <para>
195
    The locale settings influence the following SQL features:
196 197 198 199

    <itemizedlist>
     <listitem>
      <para>
200
       Sort order in queries using <literal>ORDER BY</> on textual data
Peter Eisentraut's avatar
Peter Eisentraut committed
201
       <indexterm><primary>ORDER BY</><secondary>and locales</></indexterm>
202 203 204
      </para>
     </listitem>

205 206 207 208 209 210 211
     <listitem>
      <para>
       The ability to use indexes with <literal>LIKE</> clauses
       <indexterm><primary>LIKE</><secondary>and locales</></indexterm>
      </para>
     </listitem>

212 213 214 215 216 217 218 219 220
     <listitem>
      <para>
       The <function>upper</>,  <function>lower</>,  and <function>initcap</>
       functions
       <indexterm><primary>upper</><secondary>and locales</></indexterm>
       <indexterm><primary>lower</><secondary>and locales</></indexterm>
      </para>
     </listitem>

221 222 223
     <listitem>
      <para>
       The <function>to_char</> family of functions
224
       <indexterm><primary>to_char</><secondary>and locales</></indexterm>
225 226 227 228 229 230
      </para>
     </listitem>
    </itemizedlist>
   </para>

   <para>
231 232 233 234 235
    The drawback of using locales other than <literal>C</> or
    <literal>POSIX</> in <productname>PostgreSQL</> is its performance
    impact. It slows character handling and prevents ordinary indexes
    from being used by <literal>LIKE</>. For this reason use locales
    only if you actually need them.
236
   </para>
237 238 239 240 241 242 243 244 245

   <para>
    As a workaround to allow <productname>PostgreSQL</> to use indexes
    with <literal>LIKE</> clauses under a non-C locale, several custom
    operator classes exist. These allow the creation of an index that
    performs a strict character-by-character comparison, ignoring
    locale comparison rules. Refer to <xref linkend="indexes-opclass">
    for more information.
   </para>
246 247 248 249 250 251
  </sect2>

  <sect2>
   <title>Problems</>

   <para>
252
    If locale support doesn't work according to the explanation above,
253 254
    check that the locale support in your operating system is
    correctly configured.  To check what locales are installed on your
255
    system, you can use the command <literal>locale -a</literal> if
256
    your operating system provides it.
257 258 259
   </para>

   <para>
260 261 262 263 264 265
    Check that <productname>PostgreSQL</> is actually using the locale
    that you think it is.  <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
    settings are determined at <command>initdb</> time and cannot be
    changed without repeating <command>initdb</>.  Other locale
    settings including <envar>LC_MESSAGES</> and <envar>LC_MONETARY</>
    are initially determined by the environment the server is started
266 267
    in, but can be changed on-the-fly.  You can check the active locale
    settings using the <command>SHOW</> command.
268 269
   </para>

270
   <para>
271 272 273
    The directory <filename>src/test/locale</> in the source
    distribution contains a test suite for
    <productname>PostgreSQL</>'s locale support.
274
   </para>
Peter Eisentraut's avatar
Peter Eisentraut committed
275 276 277 278

   <para>
    Client applications that handle server-side errors by parsing the
    text of the error message will obviously have problems when the
Peter Eisentraut's avatar
Peter Eisentraut committed
279 280 281
    server's messages are in a different language.  Authors of such
    applications are advised to make use of the error code scheme
    instead.
Peter Eisentraut's avatar
Peter Eisentraut committed
282 283 284 285 286 287
   </para>

   <para>
    Maintaining catalogs of message translations requires the on-going
    efforts of many volunteers that want to see
    <productname>PostgreSQL</> speak their preferred language well.
288
    If messages in your language are currently not available or not fully
Peter Eisentraut's avatar
Peter Eisentraut committed
289
    translated, your assistance would be appreciated.  If you want to
290
    help, refer to <xref linkend="nls"> or write to the developers'
291
    mailing list.
Peter Eisentraut's avatar
Peter Eisentraut committed
292
   </para>
293 294 295 296
  </sect2>
 </sect1>


297 298
 <sect1 id="multibyte">
  <title>Character Set Support</title>
299

300
  <indexterm zone="multibyte"><primary>character set</></>
301

302 303
  <para>
   The character set support in <productname>PostgreSQL</productname>
304 305
   allows you to store text in a variety of character sets (also called
   encodings), including
306 307
   single-byte character sets such as the ISO 8859 series and
   multiple-byte character sets such as <acronym>EUC</> (Extended Unix
308 309 310 311
   Code), UTF-8, and Mule internal code.  All supported character sets
   can be used transparently by clients, but a few are not supported
   for use within the server (that is, as a server-side encoding).
   The default character set is selected while
312 313
   initializing your <productname>PostgreSQL</productname> database
   cluster using <command>initdb</>.  It can be overridden when you
314
   create a database, so you can have multiple
315 316
   databases each with a different character set.
  </para>
317

318 319 320 321 322 323 324 325 326 327 328 329 330 331
  <para>
   An important restriction, however, is that each database character set
   must be compatible with the server's <envar>LC_CTYPE</> setting.
   When <envar>LC_CTYPE</> is <literal>C</> or <literal>POSIX</>, any
   character set is allowed, but for other settings of <envar>LC_CTYPE</>
   there is only one character set that will work correctly.
   Since the <envar>LC_CTYPE</> setting is frozen by <command>initdb</>, the
   apparent flexibility to use different encodings in different databases
   of a cluster is more theoretical than real, except when you select
   <literal>C</> or <literal>POSIX</> locale (thus disabling any real locale
   awareness).  It is likely that these mechanisms will be revisited in future
   versions of <productname>PostgreSQL</productname>.
  </para>

332
   <sect2 id="multibyte-charset-supported">
333
    <title>Supported Character Sets</title>
334

335
    <para>
336
     <xref linkend="charset-table"> shows the character sets available
337
     for use in <productname>PostgreSQL</productname>.
338
    </para>
339

340
     <table id="charset-table">
Tom Lane's avatar
Tom Lane committed
341
      <title><productname>PostgreSQL</productname> Character Sets</title>
342
      <tgroup cols="6">
343
       <thead>
344 345 346
        <row>
         <entry>Name</entry>
         <entry>Description</entry>
347
         <entry>Language</entry>
348
         <entry>Server?</entry>
349 350 351 352
         <!--
          The Bytes/Char field is populated by looking at the values returned
          by pg_wchar_table.mblen function for each encoding.
         -->
353
         <entry>Bytes/Char</entry>
354
         <entry>Aliases</entry>
355
        </row>
356 357
       </thead>
       <tbody>
358 359
        <row>
         <entry><literal>BIG5</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
360 361
         <entry>Big Five</entry>
         <entry>Traditional Chinese</entry>
362
         <entry>No</entry>
363 364
         <entry>1-2</entry>
         <entry><literal>WIN950</>, <literal>Windows950</></entry>
365
        </row>
366 367
        <row>
         <entry><literal>EUC_CN</literal></entry>
368
         <entry>Extended UNIX Code-CN</entry>
Bruce Momjian's avatar
Bruce Momjian committed
369
         <entry>Simplified Chinese</entry>
370
         <entry>Yes</entry>
371
         <entry>1-3</entry>
Bruce Momjian's avatar
Bruce Momjian committed
372
         <entry></entry>
373 374
        </row>
        <row>
375
         <entry><literal>EUC_JP</literal></entry>
376 377
         <entry>Extended UNIX Code-JP</entry>
         <entry>Japanese</entry>
378
         <entry>Yes</entry>
379
         <entry>1-3</entry>
Bruce Momjian's avatar
Bruce Momjian committed
380
         <entry></entry>
381
        </row>
382 383 384 385 386 387 388 389
        <row>
         <entry><literal>EUC_JIS_2004</literal></entry>
         <entry>Extended UNIX Code-JP, JIS X 0213</entry>
         <entry>Japanese</entry>
         <entry>Yes</entry>
         <entry>1-3</entry>
         <entry></entry>
        </row>
390
        <row>
391
         <entry><literal>EUC_KR</literal></entry>
392 393
         <entry>Extended UNIX Code-KR</entry>
         <entry>Korean</entry>
394
         <entry>Yes</entry>
395
         <entry>1-3</entry>
Bruce Momjian's avatar
Bruce Momjian committed
396
         <entry></entry>
397 398 399
        </row>
        <row>
         <entry><literal>EUC_TW</literal></entry>
400
         <entry>Extended UNIX Code-TW</entry>
Bruce Momjian's avatar
Bruce Momjian committed
401
         <entry>Traditional Chinese, Taiwanese</entry>
402
         <entry>Yes</entry>
403
         <entry>1-3</entry>
Bruce Momjian's avatar
Bruce Momjian committed
404
         <entry></entry>
405
        </row>
406 407
        <row>
         <entry><literal>GB18030</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
408
         <entry>National Standard</entry>
409
         <entry>Chinese</entry>
410
         <entry>No</entry>
411
         <entry>1-2</entry>
Bruce Momjian's avatar
Bruce Momjian committed
412
         <entry></entry>
413
        </row>
414 415
        <row>
         <entry><literal>GBK</literal></entry>
416
         <entry>Extended National Standard</entry>
Bruce Momjian's avatar
Bruce Momjian committed
417
         <entry>Simplified Chinese</entry>
418
         <entry>No</entry>
419 420
         <entry>1-2</entry>
         <entry><literal>WIN936</>, <literal>Windows936</></entry>
421 422
        </row>
        <row>
423
         <entry><literal>ISO_8859_5</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
424
         <entry>ISO 8859-5, <acronym>ECMA</> 113</entry>
425
         <entry>Latin/Cyrillic</entry>
426
         <entry>Yes</entry>
427
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
428
         <entry></entry>
429
        </row>
430
        <row>
431
         <entry><literal>ISO_8859_6</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
432
         <entry>ISO 8859-6, <acronym>ECMA</> 114</entry>
433
         <entry>Latin/Arabic</entry>
434
         <entry>Yes</entry>
435
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
436
         <entry></entry>
437 438
        </row>
        <row>
439
         <entry><literal>ISO_8859_7</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
440
         <entry>ISO 8859-7, <acronym>ECMA</> 118</entry>
441
         <entry>Latin/Greek</entry>
442
         <entry>Yes</entry>
443
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
444
         <entry></entry>
445 446 447
        </row>
        <row>
         <entry><literal>ISO_8859_8</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
448
         <entry>ISO 8859-8, <acronym>ECMA</> 121</entry>
449
         <entry>Latin/Hebrew</entry>
450
         <entry>Yes</entry>
451
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
452
         <entry></entry>
453 454 455
        </row>
        <row>
         <entry><literal>JOHAB</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
456
         <entry><acronym>JOHAB</></entry>
Bruce Momjian's avatar
Bruce Momjian committed
457
         <entry>Korean (Hangul)</entry>
458
         <entry>No</entry>
459
         <entry>1-3</entry>
Bruce Momjian's avatar
Bruce Momjian committed
460
         <entry></entry>
461 462 463
        </row>
        <row>
         <entry><literal>KOI8</literal></entry>
464 465
         <entry><acronym>KOI</acronym>8-R(U)</entry>
         <entry>Cyrillic</entry>
466
         <entry>Yes</entry>
467 468
         <entry>1</entry>
         <entry><literal>KOI8R</></entry>
469 470 471
        </row>
        <row>
         <entry><literal>LATIN1</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
472
         <entry>ISO 8859-1, <acronym>ECMA</> 94</entry>
473
         <entry>Western European</entry>
474
         <entry>Yes</entry>
475 476
         <entry>1</entry>
         <entry><literal>ISO88591</></entry>
477 478 479
        </row>
        <row>
         <entry><literal>LATIN2</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
480
         <entry>ISO 8859-2, <acronym>ECMA</> 94</entry>
481
         <entry>Central European</entry>
482
         <entry>Yes</entry>
483 484
         <entry>1</entry>
         <entry><literal>ISO88592</></entry>
485 486 487
        </row>
        <row>
         <entry><literal>LATIN3</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
488
         <entry>ISO 8859-3, <acronym>ECMA</> 94</entry>
489
         <entry>South European</entry>
490
         <entry>Yes</entry>
491 492
         <entry>1</entry>
         <entry><literal>ISO88593</></entry>
493 494 495
        </row>
        <row>
         <entry><literal>LATIN4</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
496
         <entry>ISO 8859-4, <acronym>ECMA</> 94</entry>
497
         <entry>North European</entry>
498
         <entry>Yes</entry>
499 500
         <entry>1</entry>
         <entry><literal>ISO88594</></entry>
501 502 503
        </row>
        <row>
         <entry><literal>LATIN5</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
504
         <entry>ISO 8859-9, <acronym>ECMA</> 128</entry>
505
         <entry>Turkish</entry>
506
         <entry>Yes</entry>
507 508
         <entry>1</entry>
         <entry><literal>ISO88599</></entry>
509 510 511
        </row>
        <row>
         <entry><literal>LATIN6</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
512
         <entry>ISO 8859-10, <acronym>ECMA</> 144</entry>
513
         <entry>Nordic</entry>
514
         <entry>Yes</entry>
515 516
         <entry>1</entry>
         <entry><literal>ISO885910</></entry>
517 518 519
        </row>
        <row>
         <entry><literal>LATIN7</literal></entry>
520 521
         <entry>ISO 8859-13</entry>
         <entry>Baltic</entry>
522
         <entry>Yes</entry>
523 524
         <entry>1</entry>
         <entry><literal>ISO885913</></entry>
525 526 527
        </row>
        <row>
         <entry><literal>LATIN8</literal></entry>
528 529
         <entry>ISO 8859-14</entry>
         <entry>Celtic</entry>
530
         <entry>Yes</entry>
531 532
         <entry>1</entry>
         <entry><literal>ISO885914</></entry>
533 534 535
        </row>
        <row>
         <entry><literal>LATIN9</literal></entry>
536 537
         <entry>ISO 8859-15</entry>
         <entry>LATIN1 with Euro and accents</entry>
538
         <entry>Yes</entry>
539
         <entry>1</entry>
540
         <entry>ISO885915</entry>
541 542 543
        </row>
        <row>
         <entry><literal>LATIN10</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
544
         <entry>ISO 8859-16, <acronym>ASRO</> SR 14111</entry>
545
         <entry>Romanian</entry>
546
         <entry>Yes</entry>
547 548
         <entry>1</entry>
         <entry><literal>ISO885916</></entry>
549 550
        </row>
        <row>
551
         <entry><literal>MULE_INTERNAL</literal></entry>
552
         <entry>Mule internal code</entry>
553
         <entry>Multilingual Emacs</entry>
554
         <entry>Yes</entry>
555
         <entry>1-4</entry>
Bruce Momjian's avatar
Bruce Momjian committed
556
         <entry></entry>
557 558 559
        </row>
        <row>
         <entry><literal>SJIS</literal></entry>
560 561
         <entry>Shift JIS</entry>
         <entry>Japanese</entry>
562
         <entry>No</entry>
563 564
         <entry>1-2</entry>
         <entry><literal>Mskanji</>, <literal>ShiftJIS</>, <literal>WIN932</>, <literal>Windows932</></entry>
565
        </row>
566 567 568 569 570 571 572 573
        <row>
         <entry><literal>SHIFT_JIS_2004</literal></entry>
         <entry>Shift JIS, JIS X 0213</entry>
         <entry>Japanese</entry>
         <entry>No</entry>
         <entry>1-2</entry>
         <entry></entry>
        </row>
574 575
        <row>
         <entry><literal>SQL_ASCII</literal></entry>
576 577
         <entry>unspecified (see text)</entry>
         <entry><emphasis>any</></entry>
578
         <entry>Yes</entry>
579
         <entry>1</entry>
580
         <entry></entry>
581
        </row>
582 583
        <row>
         <entry><literal>UHC</literal></entry>
584 585
         <entry>Unified Hangul Code</entry>
         <entry>Korean</entry>
586
         <entry>No</entry>
587 588
         <entry>1-2</entry>
         <entry><literal>WIN949</>, <literal>Windows949</></entry>
589
        </row>
590 591
        <row>
         <entry><literal>UTF8</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
592 593
         <entry>Unicode, 8-bit</entry>
         <entry><emphasis>all</></entry>
594
         <entry>Yes</entry>
595
         <entry>1-4</entry>
596
         <entry><literal>Unicode</></entry>
597
        </row>
598
        <row>
599
         <entry><literal>WIN866</literal></entry>
600 601
         <entry>Windows CP866</entry>
         <entry>Cyrillic</entry>
602
         <entry>Yes</entry>
603 604
         <entry>1</entry>
         <entry><literal>ALT</></entry>
605 606 607
        </row>
        <row>
         <entry><literal>WIN874</literal></entry>
608 609
         <entry>Windows CP874</entry>
         <entry>Thai</entry>
610
         <entry>Yes</entry>
611
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
612
         <entry></entry>
613 614 615
        </row>
        <row>
         <entry><literal>WIN1250</literal></entry>
616 617
         <entry>Windows CP1250</entry>
         <entry>Central European</entry>
618
         <entry>Yes</entry>
619
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
620
         <entry></entry>
621 622
        </row>
        <row>
623
         <entry><literal>WIN1251</literal></entry>
624
         <entry>Windows CP1251</entry>
625
         <entry>Cyrillic</entry>
626
         <entry>Yes</entry>
627
         <entry>1</entry>
628
         <entry><literal>WIN</></entry>
629 630 631 632
        </row>
        <row>
         <entry><literal>WIN1252</literal></entry>
         <entry>Windows CP1252</entry>
633
         <entry>Western European</entry>
634
         <entry>Yes</entry>
635
         <entry>1</entry>
636
         <entry></entry>
637
        </row>
638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659
        <row>
         <entry><literal>WIN1253</literal></entry>
         <entry>Windows CP1253</entry>
         <entry>Greek</entry>
         <entry>Yes</entry>
         <entry>1</entry>
         <entry></entry>
        </row>
        <row>
         <entry><literal>WIN1254</literal></entry>
         <entry>Windows CP1254</entry>
         <entry>Turkish</entry>
         <entry>Yes</entry>
         <entry>1</entry>
         <entry></entry>
        </row>
        <row>
         <entry><literal>WIN1255</literal></entry>
         <entry>Windows CP1255</entry>
         <entry>Hebrew</entry>
         <entry>Yes</entry>
         <entry>1</entry>
660 661
         <entry></entry>
        </row>
662 663
        <row>
         <entry><literal>WIN1256</literal></entry>
664 665
         <entry>Windows CP1256</entry>
         <entry>Arabic</entry>
666 667 668 669 670 671 672 673 674
         <entry>Yes</entry>
         <entry>1</entry>
         <entry></entry>
        </row>
        <row>
         <entry><literal>WIN1257</literal></entry>
         <entry>Windows CP1257</entry>
         <entry>Baltic</entry>
         <entry>Yes</entry>
675
         <entry>1</entry>
Bruce Momjian's avatar
Bruce Momjian committed
676
         <entry></entry>
677 678
        </row>
        <row>
679
         <entry><literal>WIN1258</literal></entry>
Bruce Momjian's avatar
Bruce Momjian committed
680
         <entry>Windows CP1258</entry>
681
         <entry>Vietnamese</entry>
682
         <entry>Yes</entry>
683 684
         <entry>1</entry>
         <entry><literal>ABC</>, <literal>TCVN</>, <literal>TCVN5712</>, <literal>VSCII</></entry>
685
        </row>
686 687 688 689
       </tbody>
      </tgroup>
     </table>

Peter Eisentraut's avatar
Peter Eisentraut committed
690
     <para>
691
      Not all <acronym>API</>s support all the listed character sets. For example, the
Peter Eisentraut's avatar
Peter Eisentraut committed
692 693 694 695
      <productname>PostgreSQL</>
      JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>,
      <literal>LATIN8</>, and <literal>LATIN10</>.
     </para>
696 697 698 699 700 701 702 703 704 705 706 707 708 709 710

     <para>
      The <literal>SQL_ASCII</> setting behaves considerably differently
      from the other settings.  When the server character set is
      <literal>SQL_ASCII</>, the server interprets byte values 0-127
      according to the ASCII standard, while byte values 128-255 are taken
      as uninterpreted characters.  No encoding conversion will be done when
      the setting is <literal>SQL_ASCII</>.  Thus, this setting is not so
      much a declaration that a specific encoding is in use, as a declaration
      of ignorance about the encoding.  In most cases, if you are
      working with any non-ASCII data, it is unwise to use the
      <literal>SQL_ASCII</> setting, because
      <productname>PostgreSQL</productname> will be unable to help you by
      converting or validating non-ASCII characters.
     </para>
711
    </sect2>
712
    
713
   <sect2>
714
    <title>Setting the Character Set</title>
715 716

    <para>
717 718
     <command>initdb</> defines the default character set
     for a <productname>PostgreSQL</productname> cluster. For example,
719

Peter Eisentraut's avatar
Peter Eisentraut committed
720
<screen>
721
initdb -E EUC_JP
Peter Eisentraut's avatar
Peter Eisentraut committed
722
</screen>
723

724 725 726 727
     sets the default character set (encoding) to
     <literal>EUC_JP</literal> (Extended Unix Code for Japanese).  You
     can use <option>--encoding</option> instead of
     <option>-E</option> if you prefer to type longer option strings.
728
     If no <option>-E</> or <option>--encoding</option> option is
729 730
     given, <command>initdb</> attempts to determine the appropriate
     encoding to use based on the specified or default locale.
731 732 733
    </para>

    <para>
734 735
     If you have selected <literal>C</> or <literal>POSIX</> locale,
     you can create a database with a different character set:
736

Peter Eisentraut's avatar
Peter Eisentraut committed
737
<screen>
738
createdb -E EUC_KR korean
Peter Eisentraut's avatar
Peter Eisentraut committed
739
</screen>
740

741 742 743
     This will create a database named <literal>korean</literal> that
     uses the character set <literal>EUC_KR</literal>.  Another way to
     accomplish this is to use this SQL command:
744

Peter Eisentraut's avatar
Peter Eisentraut committed
745
<programlisting>
746
CREATE DATABASE korean WITH ENCODING 'EUC_KR';
Peter Eisentraut's avatar
Peter Eisentraut committed
747
</programlisting>
748

749
     The encoding for a database is stored in the system catalog
750
     <literal>pg_database</literal>.  You can see it by using the
751 752
     <option>-l</option> option or the <command>\l</command> command
     of <command>psql</command>.
753

Peter Eisentraut's avatar
Peter Eisentraut committed
754 755
<screen>
$ <userinput>psql -l</userinput>
756 757 758 759 760 761 762 763
            List of databases
   Database    |  Owner  |   Encoding    
---------------+---------+---------------
 euc_cn        | t-ishii | EUC_CN
 euc_jp        | t-ishii | EUC_JP
 euc_kr        | t-ishii | EUC_KR
 euc_tw        | t-ishii | EUC_TW
 mule_internal | t-ishii | MULE_INTERNAL
764
 postgres      | t-ishii | EUC_JP
765 766 767
 regression    | t-ishii | SQL_ASCII
 template1     | t-ishii | EUC_JP
 test          | t-ishii | EUC_JP
768
 utf8          | t-ishii | UTF8
769
(9 rows)
Peter Eisentraut's avatar
Peter Eisentraut committed
770
</screen>
771
    </para>
772 773 774

    <important>
     <para>
775 776 777 778 779 780 781
      On most modern operating systems, <productname>PostgreSQL</productname>
      can determine which character set is implied by an <envar>LC_CTYPE</>
      setting, and it will enforce that only the correct database encoding is
      used.  On older systems it is your responsibility to ensure that you use
      the encoding expected by the locale you have selected.  A mistake in
      this area is likely to lead to strange misbehavior of locale-dependent
      operations such as sorting.
782 783 784
     </para>

     <para>
785 786 787 788 789 790 791
      <productname>PostgreSQL</productname> will allow superusers to create
      databases with <literal>SQL_ASCII</> encoding even when
      <envar>LC_CTYPE</> is not <literal>C</> or <literal>POSIX</>.  As noted
      above, <literal>SQL_ASCII</> does not enforce that the data stored in
      the database has any particular encoding, and so this choice poses risks
      of locale-dependent misbehavior.  Using this combination of settings is
      deprecated and may someday be forbidden altogether.
792 793
     </para>
    </important>
794 795 796
   </sect2>

   <sect2>
797
    <title>Automatic Character Set Conversion Between Server and Client</title>
798 799

    <para>
800 801
     <productname>PostgreSQL</productname> supports automatic
     character set conversion between server and client for certain
802 803 804 805 806
     character set combinations. The conversion information is stored in the
     <literal>pg_conversion</> system catalog.  <productname>PostgreSQL</>
     comes with some predefined conversions, as shown in <xref
     linkend="multibyte-translation-table">. You can create a new
     conversion using the SQL command <command>CREATE CONVERSION</command>.
Peter Eisentraut's avatar
Peter Eisentraut committed
807
    </para>
808

809 810
     <table id="multibyte-translation-table">
      <title>Client/Server Character Set Conversions</title>
811 812
      <tgroup cols="2">
       <thead>
813 814 815 816
        <row>
         <entry>Server Character Set</entry>
         <entry>Available Client Character Sets</entry>
        </row>
817 818
       </thead>
       <tbody>
819
        <row>
820
         <entry><literal>BIG5</literal></entry>
821
         <entry><emphasis>not supported as a server encoding</emphasis>
822 823 824 825
         </entry>
        </row>
        <row>
         <entry><literal>EUC_CN</literal></entry>
826
         <entry><emphasis>EUC_CN</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
827 828
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>
829 830 831 832
         </entry>
        </row>
        <row>
         <entry><literal>EUC_JP</literal></entry>
833
         <entry><emphasis>EUC_JP</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
834 835 836
         <literal>MULE_INTERNAL</literal>,
         <literal>SJIS</literal>,
         <literal>UTF8</literal>
837 838 839
         </entry>
        </row>
        <row>
840
         <entry><literal>EUC_KR</literal></entry>
841
         <entry><emphasis>EUC_KR</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
842 843
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>
844 845 846
         </entry>
        </row>
        <row>
847
         <entry><literal>EUC_TW</literal></entry>
848
         <entry><emphasis>EUC_TW</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
849 850 851
         <literal>BIG5</literal>,
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>
852 853 854 855
         </entry>
        </row>
        <row>
         <entry><literal>GB18030</literal></entry>
856
         <entry><emphasis>not supported as a server encoding</emphasis>
857 858 859 860
         </entry>
        </row>
        <row>
         <entry><literal>GBK</literal></entry>
861
         <entry><emphasis>not supported as a server encoding</emphasis>
862 863 864 865
         </entry>
        </row>
        <row>
         <entry><literal>ISO_8859_5</literal></entry>
866
         <entry><emphasis>ISO_8859_5</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
867
         <literal>KOI8</literal>,
868
         <literal>MULE_INTERNAL</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
869
         <literal>UTF8</literal>,
870
         <literal>WIN866</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
871
         <literal>WIN1251</literal>
872 873 874 875
         </entry>
        </row>
        <row>
         <entry><literal>ISO_8859_6</literal></entry>
876
         <entry><emphasis>ISO_8859_6</emphasis>,
877 878 879 880 881
         <literal>UTF8</literal>
         </entry>
        </row>
        <row>
         <entry><literal>ISO_8859_7</literal></entry>
882
         <entry><emphasis>ISO_8859_7</emphasis>,
883 884 885 886 887
         <literal>UTF8</literal>
         </entry>
        </row>
        <row>
         <entry><literal>ISO_8859_8</literal></entry>
888
         <entry><emphasis>ISO_8859_8</emphasis>,
889
         <literal>UTF8</literal>
890 891 892 893
         </entry>
        </row>
        <row>
         <entry><literal>JOHAB</literal></entry>
894
         <entry><emphasis>JOHAB</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
895
         <literal>UTF8</literal>
896 897 898
         </entry>
        </row>
        <row>
899
         <entry><literal>KOI8</literal></entry>
900
         <entry><emphasis>KOI8</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
901 902 903 904 905
         <literal>ISO_8859_5</literal>,
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>,
         <literal>WIN866</literal>,
         <literal>WIN1251</literal>
906 907
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
908
        <row> 
909
         <entry><literal>LATIN1</literal></entry>
910
         <entry><emphasis>LATIN1</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
911 912
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>
913 914
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
915
        <row> 
916
         <entry><literal>LATIN2</literal></entry>
917
         <entry><emphasis>LATIN2</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
918
         <literal>MULE_INTERNAL</literal>,
919
         <literal>UTF8</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
920
         <literal>WIN1250</literal>
921 922
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
923
        <row> 
924
         <entry><literal>LATIN3</literal></entry>
925
         <entry><emphasis>LATIN3</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
926 927
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>
928 929
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
930
        <row> 
931
         <entry><literal>LATIN4</literal></entry>
932
         <entry><emphasis>LATIN4</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
933 934
         <literal>MULE_INTERNAL</literal>,
         <literal>UTF8</literal>
935 936
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
937
        <row> 
938
         <entry><literal>LATIN5</literal></entry>
939
         <entry><emphasis>LATIN5</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
940
         <literal>UTF8</literal>
941 942
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
943
        <row> 
944
         <entry><literal>LATIN6</literal></entry>
945
         <entry><emphasis>LATIN6</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
946
         <literal>UTF8</literal>
947 948
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
949
        <row> 
950
         <entry><literal>LATIN7</literal></entry>
951
         <entry><emphasis>LATIN7</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
952
         <literal>UTF8</literal>
953 954
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
955
        <row> 
956
         <entry><literal>LATIN8</literal></entry>
957
         <entry><emphasis>LATIN8</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
958
         <literal>UTF8</literal>
959 960
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
961
        <row> 
962
         <entry><literal>LATIN9</literal></entry>
963
         <entry><emphasis>LATIN9</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
964
         <literal>UTF8</literal>
965 966
         </entry>
        </row>
Bruce Momjian's avatar
Bruce Momjian committed
967
        <row> 
968
         <entry><literal>LATIN10</literal></entry>
969
         <entry><emphasis>LATIN10</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
970
         <literal>UTF8</literal>
971 972 973
         </entry>
        </row>
        <row>
974
         <entry><literal>MULE_INTERNAL</literal></entry>
975
         <entry><emphasis>MULE_INTERNAL</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
976 977 978 979 980 981
          <literal>BIG5</literal>,
          <literal>EUC_CN</literal>,
          <literal>EUC_JP</literal>,
          <literal>EUC_KR</literal>,
          <literal>EUC_TW</literal>,
          <literal>ISO_8859_5</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
982
          <literal>KOI8</literal>,
983
          <literal>LATIN1</literal> to <literal>LATIN4</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
984 985 986 987
          <literal>SJIS</literal>,
          <literal>WIN866</literal>,
          <literal>WIN1250</literal>,
          <literal>WIN1251</literal>
Bruce Momjian's avatar
Bruce Momjian committed
988
         </entry>
Bruce Momjian's avatar
Bruce Momjian committed
989 990
        </row>
        <row> 
991
         <entry><literal>SJIS</literal></entry>
992
         <entry><emphasis>not supported as a server encoding</emphasis>
993 994 995
         </entry>
        </row>
        <row>
996
         <entry><literal>SQL_ASCII</literal></entry>
997
         <entry><emphasis>any (no conversion will be performed)</emphasis>
998 999 1000
         </entry>
        </row>
        <row>
1001
         <entry><literal>UHC</literal></entry>
1002
         <entry><emphasis>not supported as a server encoding</emphasis>
1003 1004 1005
         </entry>
        </row>
        <row>
1006
         <entry><literal>UTF8</literal></entry>
1007
         <entry><emphasis>all supported encodings</emphasis>
1008 1009 1010
         </entry>
        </row>
        <row>
1011
         <entry><literal>WIN866</literal></entry>
1012
         <entry><emphasis>WIN866</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
1013
          <literal>ISO_8859_5</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
1014 1015 1016 1017
          <literal>KOI8</literal>,
          <literal>MULE_INTERNAL</literal>,
          <literal>UTF8</literal>,
          <literal>WIN1251</literal>
1018 1019 1020 1021
         </entry>
        </row>
        <row>
         <entry><literal>WIN874</literal></entry>
1022
         <entry><emphasis>WIN874</emphasis>,
1023
         <literal>UTF8</literal>
1024 1025 1026 1027
         </entry>
        </row>
        <row>
         <entry><literal>WIN1250</literal></entry>
1028
         <entry><emphasis>WIN1250</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
1029
          <literal>LATIN2</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
1030 1031
          <literal>MULE_INTERNAL</literal>,
          <literal>UTF8</literal>
1032 1033 1034
         </entry>
        </row>
        <row>
1035
         <entry><literal>WIN1251</literal></entry>
1036
         <entry><emphasis>WIN1251</emphasis>,
Bruce Momjian's avatar
Bruce Momjian committed
1037
          <literal>ISO_8859_5</literal>,
Bruce Momjian's avatar
Bruce Momjian committed
1038 1039 1040 1041
          <literal>KOI8</literal>,
          <literal>MULE_INTERNAL</literal>,
          <literal>UTF8</literal>,
          <literal>WIN866</literal>
1042 1043
         </entry>
        </row>
1044 1045 1046 1047 1048 1049
        <row>
         <entry><literal>WIN1252</literal></entry>
         <entry><emphasis>WIN1252</emphasis>,
          <literal>UTF8</literal>
         </entry>
        </row>
1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067
        <row>
         <entry><literal>WIN1253</literal></entry>
         <entry><emphasis>WIN1253</emphasis>,
          <literal>UTF8</literal>
         </entry>
        </row>
        <row>
         <entry><literal>WIN1254</literal></entry>
         <entry><emphasis>WIN1254</emphasis>,
          <literal>UTF8</literal>
         </entry>
        </row>
        <row>
         <entry><literal>WIN1255</literal></entry>
         <entry><emphasis>WIN1255</emphasis>,
          <literal>UTF8</literal>
         </entry>
        </row>
1068 1069
        <row>
         <entry><literal>WIN1256</literal></entry>
1070
         <entry><emphasis>WIN1256</emphasis>,
1071
         <literal>UTF8</literal>
1072 1073
         </entry>
        </row>
1074 1075 1076 1077 1078 1079
        <row>
         <entry><literal>WIN1257</literal></entry>
         <entry><emphasis>WIN1257</emphasis>,
          <literal>UTF8</literal>
         </entry>
        </row>
1080
        <row>
1081
         <entry><literal>WIN1258</literal></entry>
1082
         <entry><emphasis>WIN1258</emphasis>,
1083
         <literal>UTF8</literal>
1084 1085
         </entry>
        </row>
1086 1087 1088 1089 1090
       </tbody>
      </tgroup>
     </table>

    <para>
1091
     To enable automatic character set conversion, you have to
1092 1093 1094
     tell <productname>PostgreSQL</productname> the character set
     (encoding) you would like to use in the client. There are several
     ways to accomplish this:
1095 1096 1097 1098

     <itemizedlist>
      <listitem>
       <para>
1099 1100 1101 1102 1103
        Using the <command>\encoding</command> command in
        <application>psql</application>.
        <command>\encoding</command> allows you to change client
        encoding on the fly. For
        example, to change the encoding to <literal>SJIS</literal>, type:
1104

Peter Eisentraut's avatar
Peter Eisentraut committed
1105
<programlisting>
1106
\encoding SJIS
Peter Eisentraut's avatar
Peter Eisentraut committed
1107
</programlisting>
1108 1109 1110 1111 1112
       </para>
      </listitem>

      <listitem>
       <para>
1113 1114 1115
        Using <application>libpq</> functions.
        <command>\encoding</command> actually calls
        <function>PQsetClientEncoding()</function> for its purpose.
1116

Peter Eisentraut's avatar
Peter Eisentraut committed
1117
<synopsis>
1118
int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
Peter Eisentraut's avatar
Peter Eisentraut committed
1119
</synopsis>
1120

1121 1122 1123 1124 1125
        where <replaceable>conn</replaceable> is a connection to the server,
        and <replaceable>encoding</replaceable> is the encoding you
        want to use. If the function successfully sets the encoding, it returns 0,
        otherwise -1. The current encoding for this connection can be determined by
        using:
1126

Peter Eisentraut's avatar
Peter Eisentraut committed
1127
<synopsis>
1128
int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
Peter Eisentraut's avatar
Peter Eisentraut committed
1129
</synopsis>
1130

1131 1132 1133
        Note that it returns the encoding ID, not a symbolic string
        such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
        can use:
1134

Peter Eisentraut's avatar
Peter Eisentraut committed
1135
<synopsis>
1136
char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
Peter Eisentraut's avatar
Peter Eisentraut committed
1137
</synopsis>
1138 1139 1140 1141 1142
       </para>
      </listitem>

      <listitem>
       <para>
1143
        Using <command>SET client_encoding TO</command>.
1144

1145
        Setting the client encoding can be done with this SQL command:
1146

Peter Eisentraut's avatar
Peter Eisentraut committed
1147
<programlisting>
1148
SET CLIENT_ENCODING TO '<replaceable>value</>';
Peter Eisentraut's avatar
Peter Eisentraut committed
1149
</programlisting>
1150

1151 1152
        Also you can use the standard SQL syntax <literal>SET NAMES</literal>
        for this purpose:
1153

Peter Eisentraut's avatar
Peter Eisentraut committed
1154
<programlisting>
1155
SET NAMES '<replaceable>value</>';
Peter Eisentraut's avatar
Peter Eisentraut committed
1156
</programlisting>
1157

1158
        To query the current client encoding:
1159

Peter Eisentraut's avatar
Peter Eisentraut committed
1160
<programlisting>
1161
SHOW client_encoding;
Peter Eisentraut's avatar
Peter Eisentraut committed
1162
</programlisting>
1163

1164
        To return to the default encoding:
1165

Peter Eisentraut's avatar
Peter Eisentraut committed
1166
<programlisting>
1167
RESET client_encoding;
Peter Eisentraut's avatar
Peter Eisentraut committed
1168
</programlisting>
1169 1170
       </para>
      </listitem>
1171 1172 1173

      <listitem>
       <para>
1174
        Using <envar>PGCLIENTENCODING</envar>. If the environment variable
1175 1176 1177 1178 1179
        <envar>PGCLIENTENCODING</envar> is defined in the client's
        environment, that client encoding is automatically selected
        when a connection to the server is made.  (This can
        subsequently be overridden using any of the other methods
        mentioned above.)
1180 1181
       </para>
      </listitem>
1182 1183 1184

      <listitem>
      <para>
1185 1186 1187 1188 1189 1190
       Using the configuration variable <xref
       linkend="guc-client-encoding">. If the
       <varname>client_encoding</> variable is set, that client
       encoding is automatically selected when a connection to the
       server is made.  (This can subsequently be overridden using any
       of the other methods mentioned above.)
1191 1192 1193
       </para>
      </listitem>

1194 1195 1196 1197
     </itemizedlist>
    </para>

    <para>
1198 1199 1200
     If the conversion of a particular character is not possible
     &mdash; suppose you chose <literal>EUC_JP</literal> for the
     server and <literal>LATIN1</literal> for the client, then some
1201 1202
     Japanese characters do not have a representation in
     <literal>LATIN1</literal> &mdash; then an error is reported.
1203
    </para>
1204 1205 1206 1207 1208 1209 1210

    <para>
     If the client character set is defined as <literal>SQL_ASCII</>,
     encoding conversion is disabled, regardless of the server's character
     set.  Just as for the server, use of <literal>SQL_ASCII</> is unwise
     unless you are working with all-ASCII data.
    </para>
1211 1212 1213
   </sect2>

   <sect2>
1214
    <title>Further Reading</title>
1215 1216

    <para>
1217
     These are good sources to start learning about various kinds of encoding
1218 1219
     systems.

1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231
     <variablelist>
      <varlistentry>
       <term><ulink url="http://www.i18ngurus.com/docs/984813247.html"></ulink></term>

       <listitem>
        <para>
         An extensive collection of documents about character sets, encodings,
         and code pages.
        </para>
       </listitem>
      </varlistentry>

1232
      <varlistentry>
1233
       <term><ulink url="ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/cjk.inf"></ulink></term>
1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244

       <listitem>
        <para>
         Detailed explanations of <literal>EUC_JP</literal>,
         <literal>EUC_CN</literal>, <literal>EUC_KR</literal>,
         <literal>EUC_TW</literal> appear in section 3.2.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
1245
       <term><ulink url="http://www.unicode.org/"></ulink></term>
1246 1247 1248 1249 1250 1251 1252 1253 1254

       <listitem>
        <para>
         The web site of the Unicode Consortium
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
1255
       <term>RFC 3629</term>
1256 1257 1258

       <listitem>
        <para>
1259
         <acronym>UTF</acronym>-8 is defined here.
1260 1261 1262 1263
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
1264 1265 1266 1267
    </para>
   </sect2>

  </sect1>
1268 1269

</chapter>