<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Creating a Database Cluster</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 8.3.1 Documentation" HREF="index.html"><LINK REL="UP" TITLE="Operating System Environment" HREF="runtime.html"><LINK REL="PREVIOUS" TITLE="The PostgreSQL User Account" HREF="postgres-user.html"><LINK REL="NEXT" TITLE="Starting the Database Server" HREF="server-start.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2008-03-15T03:19:10"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" >PostgreSQL 8.3.1 Documentation</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="postgres-user.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="runtime.html" >Fast Backward</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Chapter 17. Operating System Environment</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="runtime.html" >Fast Forward</A ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="server-start.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="CREATING-CLUSTER" >17.2. Creating a Database Cluster</A ></H1 ><A NAME="AEN21547" ></A ><A NAME="AEN21549" ></A ><P > Before you can do anything, you must initialize a database storage area on disk. We call this a <I CLASS="FIRSTTERM" >database cluster</I >. (<ACRONYM CLASS="ACRONYM" >SQL</ACRONYM > uses the term catalog cluster.) A database cluster is a collection of databases that is managed by a single instance of a running database server. After initialization, a database cluster will contain a database named <TT CLASS="LITERAL" >postgres</TT >, which is meant as a default database for use by utilities, users and third party applications. The database server itself does not require the <TT CLASS="LITERAL" >postgres</TT > database to exist, but many external utility programs assume it exists. Another database created within each cluster during initialization is called <TT CLASS="LITERAL" >template1</TT >. As the name suggests, this will be used as a template for subsequently created databases; it should not be used for actual work. (See <A HREF="managing-databases.html" >Chapter 20</A > for information about creating new databases within a cluster.) </P ><P > In file system terms, a database cluster will be a single directory under which all data will be stored. We call this the <I CLASS="FIRSTTERM" >data directory</I > or <I CLASS="FIRSTTERM" >data area</I >. It is completely up to you where you choose to store your data. There is no default, although locations such as <TT CLASS="FILENAME" >/usr/local/pgsql/data</TT > or <TT CLASS="FILENAME" >/var/lib/pgsql/data</TT > are popular. To initialize a database cluster, use the command <A HREF="app-initdb.html" >initdb</A >,<A NAME="AEN21565" ></A > which is installed with <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN >. The desired file system location of your database cluster is indicated by the <TT CLASS="OPTION" >-D</TT > option, for example </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >initdb -D /usr/local/pgsql/data</KBD ></PRE ><P> Note that you must execute this command while logged into the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > user account, which is described in the previous section. </P ><DIV CLASS="TIP" ><BLOCKQUOTE CLASS="TIP" ><P ><B >Tip: </B > As an alternative to the <TT CLASS="OPTION" >-D</TT > option, you can set the environment variable <TT CLASS="ENVAR" >PGDATA</TT >. <A NAME="AEN21577" ></A > </P ></BLOCKQUOTE ></DIV ><P > <TT CLASS="COMMAND" >initdb</TT > will attempt to create the directory you specify if it does not already exist. It is likely that it will not have the permission to do so (if you followed our advice and created an unprivileged account). In that case you should create the directory yourself (as root) and change the owner to be the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > user. Here is how this might be done: </P><PRE CLASS="SCREEN" >root# <KBD CLASS="USERINPUT" >mkdir /usr/local/pgsql/data</KBD > root# <KBD CLASS="USERINPUT" >chown postgres /usr/local/pgsql/data</KBD > root# <KBD CLASS="USERINPUT" >su postgres</KBD > postgres$ <KBD CLASS="USERINPUT" >initdb -D /usr/local/pgsql/data</KBD ></PRE ><P> </P ><P > <TT CLASS="COMMAND" >initdb</TT > will refuse to run if the data directory looks like it has already been initialized.</P ><P > Because the data directory contains all the data stored in the database, it is essential that it be secured from unauthorized access. <TT CLASS="COMMAND" >initdb</TT > therefore revokes access permissions from everyone but the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > user. </P ><P > However, while the directory contents are secure, the default client authentication setup allows any local user to connect to the database and even become the database superuser. If you do not trust other local users, we recommend you use one of <TT CLASS="COMMAND" >initdb</TT >'s <TT CLASS="OPTION" >-W</TT >, <TT CLASS="OPTION" >--pwprompt</TT > or <TT CLASS="OPTION" >--pwfile</TT > options to assign a password to the database superuser.<A NAME="AEN21598" ></A > Also, specify <TT CLASS="OPTION" >-A md5</TT > or <TT CLASS="OPTION" >-A password</TT > so that the default <TT CLASS="LITERAL" >trust</TT > authentication mode is not used; or modify the generated <TT CLASS="FILENAME" >pg_hba.conf</TT > file after running <TT CLASS="COMMAND" >initdb</TT >, <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >before</I ></SPAN > you start the server for the first time. (Other reasonable approaches include using <TT CLASS="LITERAL" >ident</TT > authentication or file system permissions to restrict connections. See <A HREF="client-authentication.html" >Chapter 21</A > for more information.) </P ><P > <TT CLASS="COMMAND" >initdb</TT > also initializes the default locale<A NAME="AEN21611" ></A > 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 <A HREF="locale.html" >Section 22.1</A >. The sort order used within a particular database cluster is set by <TT CLASS="COMMAND" >initdb</TT > and cannot be changed later, short of dumping all data, rerunning <TT CLASS="COMMAND" >initdb</TT >, and reloading the data. There is also a performance impact for using locales other than <TT CLASS="LITERAL" >C</TT > or <TT CLASS="LITERAL" >POSIX</TT >. Therefore, it is important to make this choice correctly the first time. </P ><P > <TT CLASS="COMMAND" >initdb</TT > also sets the default character set encoding for the database cluster. Normally this should be chosen to match the locale setting. For details see <A HREF="multibyte.html" >Section 22.2</A >. </P ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="CREATING-CLUSTER-NFS" >17.2.1. Network File Systems</A ></H2 ><A NAME="AEN21623" ></A ><A NAME="AEN21625" ></A ><A NAME="AEN21629" ></A ><P > Many installations create database clusters on network file systems. Sometimes this is done directly via <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM >, or by using a Network Attached Storage (<ACRONYM CLASS="ACRONYM" >NAS</ACRONYM >) device that uses <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM > internally. <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > does nothing special for <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM > file systems, meaning it assumes <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM > behaves exactly like locally-connected drives (<ACRONYM CLASS="ACRONYM" >DAS</ACRONYM >, Direct Attached Storage). If client and server <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM > implementations have non-standard semantics, this can cause reliability problems (see <A HREF="http://www.time-travellers.org/shane/papers/NFS_considered_harmful.html" TARGET="_top" >http://www.time-travellers.org/shane/papers/NFS_considered_harmful.html</A >). Specifically, delayed (asynchronous) writes to the <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM > server can cause reliability problems; if possible, mount <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM > file systems synchronously (without caching) to avoid this. (Storage Area Networks (<ACRONYM CLASS="ACRONYM" >SAN</ACRONYM >) use a low-level communication protocol rather than <ACRONYM CLASS="ACRONYM" >NFS</ACRONYM >.) </P ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="postgres-user.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="server-start.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >The <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > User Account</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="runtime.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Starting the Database Server</TD ></TR ></TABLE ></DIV ></BODY ></HTML >