database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

Locale support is on by default. The choice of locale is done in initdb

Browse Source 
and/or with GUC variables.
This commit is contained in:
Peter Eisentraut
2002-04-03 05:39:33 +00:00
parent 3d7755c8e9
commit 867901db9e
19 changed files with 554 additions and 479 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
doc/src/sgml/charset.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.23 2002/03/22 19:20:05 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.24 2002/04/03 05:39:27 petere Exp $ -->
<chapter id="charset">
<title>Localization</>
@ -63,35 +63,24 @@
<sect2>
<title>Overview</>
<para>
Locale support is not built into <productname>PostgreSQL</> by
default; to enable it, supply the <option>--enable-locale</> option
to the <filename>configure</> script:
<informalexample>
<para>
Locale support is automatically initialized when a database
cluster is created using <command>initdb</command>.
<command>initdb</command> will initialize the database cluster
with the locale setting of its execution environment; 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 tell
<command>initdb</command> exactly which locale you want with the
option <option>--locale</option>. For example:
<screen>
<prompt>$ </><userinput>./configure --enable-locale</>
<prompt>$ </><userinput>initdb --locale=sv_SE</>
</screen>
</informalexample>
Locale support only affects the server; all clients are compatible
with servers with or without locale support.
</para>
<para>
To enable messages translated to the user's preferred language,
the <option>--enable-nls</option> option must be used. This
option is independent of the other locale support.
</para>
<para>
The information about which particular cultural rules to use is
determined by standard environment variables. If you are getting
localized behavior from other programs you probably have them set
up already. The simplest way to set the localization information
is the <envar>LANG</> variable, for example:
<programlisting>
export LANG=sv_SE
</programlisting>
This sets the locale to Swedish (<literal>sv</>) as spoken in
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</> (Canada,
French). If more than one character set can be useful for a locale
@ -103,9 +92,9 @@ export LANG=sv_SE
<para>
Occasionally it is useful to mix rules from several locales, e.g.,
use U.S. collation rules but Spanish messages. To do that a set of
environment variables exist that override the default of
<envar>LANG</> for a particular category:
use U.S. collation rules but Spanish messages. To support that, a
set of locale subcategories exist that control only a certain
aspect of the localization rules.
<informaltable>
<tgroup cols="2">
@ -138,12 +127,64 @@ export LANG=sv_SE
</tgroup>
</informaltable>
Additionally, all of these specific variables and the
<envar>LANG</> variable can be overridden with the
<envar>LC_ALL</> environment variable.
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>.
</para>
<para>
If you want the system to behave as if it had no locale support,
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
server is started by setting the run-time configuration variables
that have the same name as the locale categories (see <xref
linkend="runtime-config"> for details). The defaults that are
chosen by <command>initdb</command> are actually only written into
the configuration file <filename>postgresql.conf</filename> to
serve as defaults when the server is started. If you delete the
assignments from <filename>postgresql.conf</filename> then the
server will inherit the settings from the execution environment.
</para>
<para>
Note that the locale behavior of the server is determined by the
environment variables seen by the server, not by the environment
of any client. Therefore, be careful to configure the correct locale settings
before starting the server. A consequence of this is that if
client and server are set up to different locales, messages may
appear in different languages depending on where they originated.
</para>
<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
@ -156,31 +197,9 @@ export LANG=sv_SE
</note>
<para>
If you want the system to behave as if it had no locale support,
use the special locale <literal>C</> or <literal>POSIX</>, or
simply unset all locale-related variables.
</para>
<para>
Note that the locale behavior of the server is determined by the
environment variables seen by the server, not by the environment
of any client. Therefore, be careful to set these variables
before starting the server. A consequence of this is that if
client and server are set up to different locales, messages may
appear in different languages depending on where they originated.
</para>
<para>
The <envar>LC_COLLATE</> and <envar>LC_CTYPE</> variables affect the
sort order of indexes. Therefore, these values must be kept fixed
for any particular database cluster, 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 <application>initdb</>. The server automatically adopts
those two values when it is started; only the other <envar>LC_</>
categories can be set from the environment at server start-up.
In short, only one collation order can be used in a database cluster,
and it is chosen at <application>initdb</> time.
To enable messages translated to the user's preferred language,
the <option>--enable-nls</option> option must be used. This
option is independent of the other locale support.
</para>
</sect2>

10
doc/src/sgml/datatype.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.86 2002/03/22 19:20:07 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.87 2002/04/03 05:39:27 petere Exp $
-->
<chapter id="datatype">
@ -724,11 +724,9 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceabl
</note>
<para>
The <type>money</type> type stores U.S.-style currency with fixed
decimal point representation. If
<productname>PostgreSQL</productname> is compiled with locale
support then the <type>money</type> type uses locale-specific
output formatting.
The <type>money</type> type stores a currency amount with fixed
decimal point representation. The output format is
locale-specific.
</para>
<para>

13
doc/src/sgml/installation.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.74 2002/01/20 05:45:18 tgl Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.75 2002/04/03 05:39:28 petere Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@ -531,17 +531,6 @@ su - postgres
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-locale</option></term>
<listitem>
<para>
Enables locale support. There is a performance penalty
associated with locale support, but if you are not in an
English-speaking environment you will most likely need this.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--enable-recode</option></term>
<listitem>

54
doc/src/sgml/ref/initdb.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.19 2001/12/08 03:24:37 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.20 2002/04/03 05:39:29 petere Exp $
PostgreSQL documentation
-->
@ -38,6 +38,13 @@ PostgreSQL documentation
<arg>-E </arg>
<replaceable>encoding</replaceable>
</group>
<arg>--locale <replaceable>locale</replaceable></arg>
<arg>--lc-collate <replaceable>locale</replaceable></arg>
<arg>--lc-ctype <replaceable>locale</replaceable></arg>
<arg>--lc-messages <replaceable>locale</replaceable></arg>
<arg>--lc-monetary <replaceable>locale</replaceable></arg>
<arg>--lc-numeric <replaceable>locale</replaceable></arg>
<arg>--lc-time <replaceable>locale</replaceable></arg>
<arg>-L <replaceable>directory</replaceable></arg>
<group><arg>--noclean</arg><arg>-n</arg></group>
<group><arg>--debug</arg><arg>-d</arg></group>
@ -66,6 +73,25 @@ PostgreSQL documentation
built-in types.
</para>
<para>
<command>initdb</command> initializes the database cluster's
default locale and character set encoding. Some locale categories
are fixed for the lifetime of the cluster, so it is important to
make the right choice when running <command>initdb</command>.
Other locale categories can be changed later when the server is
started. <command>initdb</command> will write those locale
settings into the <filename>postgresql.conf</filename>
configuration file so they are the default, but they can be changed
by editing that file. To set the locale that
<command>initdb</command> uses, see the description of the
<option>--locale</option> option. The character set encoding can
be set separately for each database as it is created.
<command>initdb</command> determines the encoding for the
<literal>template1</literal> database, which will serve as the
default for all other databases. To alter the default encoding use
the <option>--encoding</option> option.
</para>
<para>
<command>initdb</command> must be run as the user that will own the
server process, because the server needs to have access to the
@ -150,6 +176,32 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term>--locale=<replaceable>locale</replaceable></term>
<listitem>
<para>
Sets the default locale for the database cluster. If this
option is not specified, the locale is inherited from the
environment that <command>initdb</command> runs in.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--lc-collate=<replaceable>locale</replaceable></term>
<term>--lc-ctype=<replaceable>locale</replaceable></term>
<term>--lc-messages=<replaceable>locale</replaceable></term>
<term>--lc-monetary=<replaceable>locale</replaceable></term>
<term>--lc-numeric=<replaceable>locale</replaceable></term>
<term>--lc-time=<replaceable>locale</replaceable></term>
<listitem>
<para>
Like <option>--locale</option>, but only sets the locale in
the specified category.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

3
doc/src/sgml/release.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.129 2002/04/01 04:35:37 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.130 2002/04/03 05:39:28 petere Exp $
-->
<appendix id="release">
@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without
worries about funny characters.
-->
<literallayout><![CDATA[
Locale support is now built by default; choice of locale is set by initdb and/or at run-time
ALTER TABLE ALTER COLUMN SET/DROP NOT NULL
EXPLAIN output comes out as a query result, not a NOTICE message
DOMAINs (types that are constrained versions of base types)

98
doc/src/sgml/runtime.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.111 2002/04/01 03:34:24 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.112 2002/04/03 05:39:29 petere Exp $
-->
<Chapter Id="runtime">
@ -135,8 +135,14 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
</para>
<para>
<indexterm><primary>locale</></>
<indexterm><primary>LC_COLLATE</></>
One surprise you might encounter while running
<command>initdb</command> also initializes the default locale for
the database cluster. Normally, it will just take the locale
settings in the environment and apply them to the initialized
database. It is possible to specify a different locale for the
database; more information about that can be found in <xref
linkend="locale">. One surprise you might encounter while running
<command>initdb</command> is a notice similar to this:
<screen>
WARNING: Initializing database with en_US collation order.
@ -145,18 +151,17 @@ WARNING: Initializing database with en_US collation order.
such queries, you may wish to set LC_COLLATE to "C" and
re-initdb. For more information see the Administrator's Guide.
</screen>
This is intended to warn you that the currently selected locale will
cause indexes to be sorted in an order that prevents them from being
used for LIKE and regular-expression searches. If you need good
performance in such searches, you should set your current locale to
<literal>C</> and re-run <command>initdb</command>. On most systems,
setting the current locale is done by changing the value of the
environment variable <literal>LC_ALL</literal> or
<literal>LANG</literal>. The sort order used within a particular
database cluster is set by <command>initdb</command> and cannot be
changed later, short of dumping all data, rerunning
<command>initdb</command>, and reloading the data. So it's important
to make this choice correctly the first time.
This is intended to warn you that the currently selected locale
will cause indexes to be sorted in an order that prevents them from
being used for LIKE and regular-expression searches. If you need
good performance in such searches, you should set your current
locale to <literal>C</> and re-run <command>initdb</command>, e.g.,
by running <literal>initdb --lc-collate=C</literal>. The sort
order used within a particular database cluster is set by
<command>initdb</command> and cannot be changed later, short of
dumping all data, rerunning <command>initdb</command>, and
reloading the data. So it's important to make this choice correctly
the first time.
</para>
</sect1>
@ -1316,6 +1321,71 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LC_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
Sets the language in which messages are displayed. Acceptable
values are system-dependent; see <xref linkend="locale"> for
more information. If this variable is set to the empty string
(which is the default) then the value is inherited from the
execution environment of the server in a system-dependent way.
</para>
<para>
On some systems, this locale category does not exist. Setting
this variable will still work, but there will be no effect.
Also, there is a chance that no translated messages for the
desired language exist. In that case you will continue to see
the English messages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LC_MONETARY</varname> (<type>string</type>)</term>
<listitem>
<para>
Sets the locale to use for formatting monetary amounts.
Acceptable values are system-dependent; see <xref
linkend="locale"> for more information. If this variable is
set to the empty string (which is the default) then the value
is inherited from the execution environment of the server in a
system-dependent way.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LC_NUMERIC</varname> (<type>string</type>)</term>
<listitem>
<para>
Sets the locale to use for formatting numbers, for example
with the <function>to_char()</function> family of
functions. Acceptable values are system-dependent; see <xref
linkend="locale"> for more information. If this variable is
set to the empty string (which is the default) then the value
is inherited from the execution environment of the server in a
system-dependent way.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LC_TIME</varname> (<type>string</type>)</term>
<listitem>
<para>
Sets the locale to use for formatting date and time values,
for example with the <function>to_char()</function> family of
functions. Acceptable values are system-dependent; see <xref
linkend="locale"> for more information. If this variable is
set to the empty string (which is the default) then the value
is inherited from the execution environment of the server in a
system-dependent way.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>MAX_CONNECTIONS</varname> (<type>integer</type>)</term>
<listitem>