Multibyte Support

Enabling Multibyte Support

Run configure with the multibyte option:

% ./configure --enable-multibyte[=encoding_system]

where encoding_system can be one of the values in the following table:

Here is an example of configuring PostgreSQL to use a Japanese encoding by default:

% ./configure --enable-multibyte=EUC_JP

If the encoding system is omitted ( ./configure --enable-multibyte), SQL_ASCII is assumed.

Setting the Encoding

initdb defines the default encoding for a PostgreSQL installation. For example:

% initdb -E EUC_JP

sets the default encoding to EUC_JP (Extended UNIX Code for Japanese). Note that you can use "--encoding" instead of "-E" if you prefer to type longer option strings. If no -E or --encoding option is given, the encoding specified at configure time is used.

You can create a database with a different encoding:

% createdb -E EUC_KR korean

will create a database named "korean" with EUC_KR encoding. Another way to accomplish this is to use a SQL command:

CREATE DATABASE korean WITH ENCODING = 'EUC_KR';

The encoding for a database is represented as an encoding column in the pg_database system catalog. You can see that by using -l or \l of psql command.

$ psql -l 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 regression | t-ishii | SQL_ASCII template1 | t-ishii | EUC_JP test | t-ishii | EUC_JP unicode | t-ishii | UNICODE (9 rows)

Automatic Encoding Translation Between Backend and Frontend

PostgreSQL supports an automatic encoding translation between backend and frontend for some encodings.

To enable the automatic encoding translation, you have to tell PostgreSQL the encoding you would like to use in frontend. There are several ways to accomplish this.

• Using the \encoding command in psql. \encoding allows you to change frontend encoding on the fly. For example, to change the encoding to SJIS, type:

  \encoding SJIS

• Using libpq functions. \encoding actually calls PQsetClientEncoding() for its purpose.

  int PQsetClientEncoding(PGconn *conn, const char *encoding)

  where conn is a connection to the backend, and encoding is an encoding you want to use. If it successfully sets the encoding, it returns 0, otherwise -1. The current encoding for this connection can be shown by using:

  int PQclientEncoding(const PGconn *conn)

  Note that it returns the "encoding id," not the encoding symbol string such as "EUC_JP." To convert an encoding id to an encoding symbol, you can use:

  char *pg_encoding_to_char(int encoding_id)

• Using SET CLIENT_ENCODING TO. You can set frontend encoding with this SQL command:

  SET CLIENT_ENCODING TO 'encoding';

  Also you can use SQL92 syntax "SET NAMES" for this purpose:

  SET NAMES 'encoding';

  To query the current frontend encoding:

  SHOW CLIENT_ENCODING;

  To return to the default encoding:

  RESET CLIENT_ENCODING;

• Using PGCLIENTENCODING. If environment variable PGCLIENTENCODING is defined in the client's environment, that client encoding is automatically selected when a backend connection is made. This can subsequently be overridden using any of the other methods mentioned above.

About Unicode

An automatic encoding translation between Unicode and other encodings is supported. However, as this requires large conversion tables, it is not enabled by default. To enable this feature, run configure with the --enable-unicode-conversion option. Note that this requires the --enable-multibyte option also.

When Translation Is Not Possible

Suppose you choose EUC_JP for the backend, LATIN1 for the frontend, then some Japanese characters could not be translated into LATIN1. In this case, a letter that cannot be represented in the LATIN1 character set would be transformed as:

(HEXA DECIMAL)