Index for Section 1

Alphabetical listing for I

Bottom of page

INITDB(1)
NAME
  initdb - create a new PostgreSQL database cluster

SYNOPSIS
  initdb [ option... ]	 [ --pgdata  ]	[ -D  ] directory

DESCRIPTION
  initdb creates a new PostgreSQL database cluster. A database cluster is a
  collection of databases that are managed by a single server instance.

  Creating a database cluster consists of creating the directories in which
  the database data will live, generating the shared catalog tables (tables
  that belong to the whole cluster rather than to any particular database),
  and creating the template1 and postgres databases. When you later create a
  new database, everything in the template1 database is copied. (Therefore,
  anything installed in template1 is automatically copied into each database
  created later.) The postgres database is a default database meant for use
  by users, utilities and third party applications.

  Although initdb will attempt to create the specified data directory, it
  might not have permission if the parent directory of the desired data
  directory is root-owned. To initialize in such a setup, create an empty
  data directory as root, then use chown to assign ownership of that
  directory to the database user account, then su to become the database user
  to run initdb.

  initdb must be run as the user that will own the server process, because
  the server needs to have access to the files and directories that initdb
  creates.  Since the server may not be run as root, you must not run initdb
  as root either. (It will in fact refuse to do so.)

  initdb initializes the database cluster's default locale and character set
  encoding. The collation order (LC_COLLATE) and character set classes
  (LC_CTYPE, e.g. upper, lower, digit) are fixed for all databases and can
  not be changed. Collation orders other than C or POSIX also have a
  performance penalty.	For these reasons it is important to choose the right
  locale when running initdb. The remaining locale categories can be changed
  later when the server is started. All server locale values (lc_*) can be
  displayed via SHOW ALL.  More details can be found in in the documentation.

  The character set encoding can be set separately for a database when it is
  created. initdb determines the encoding for the template1 database, which
  will serve as the default for all other databases. To alter the default
  encoding use the --encoding option. More details can be found in in the
  documentation.

OPTIONS
  -A authmethod

  --auth=authmethod
       This option specifies the authentication method for local users used
       in pg_hba.conf. Do not use trust unless you trust all local users on
       your system. Trust is the default for ease of installation.

  -D directory

  --pgdata=directory
       This option specifies the directory where the database cluster should
       be stored. This is the only information required by initdb, but you
       can avoid writing it by setting the PGDATA environment variable, which
       can be convenient since the database server (postgres) can find the
       database directory later by the same variable.

  -E encoding

  --encoding=encoding
       Selects the encoding of the template database. This will also be the
       default encoding of any database you create later, unless you override
       it there. The default is derived from the locale, or SQL_ASCII if that
       does not work. The character sets supported by the PostgreSQL server
       are described in in the documentation.

  --locale=locale
       Sets the default locale for the database cluster. If this option is
       not specified, the locale is inherited from the environment that
       initdb runs in. Locale support is described in in the documentation.

  --lc-collate=locale

  --lc-ctype=locale

  --lc-messages=locale

  --lc-monetary=locale

  --lc-numeric=locale

  --lc-time=locale
       Like --locale, but only sets the locale in the specified category.

  -U username

  --username=username
       Selects the user name of the database superuser. This defaults to the
       name of the effective user running initdb. It is really not important
       what the superuser's name is, but one might choose to keep the
       customary name postgres, even if the operating system user's name is
       different.

  -W

  --pwprompt
       Makes initdb prompt for a password to give the database superuser. If
       you don't plan on using password authentication, this is not
       important. Otherwise you won't be able to use password authentication
       until you have a password set up.

  --pwfile=filename
       Makes initdb read the database superuser's password from a file. The
       first line of the file is taken as the password.

  Other, less commonly used, parameters are also available:

  -d

  --debug
       Print debugging output from the bootstrap backend and a few other
       messages of lesser interest for the general public.  The bootstrap
       backend is the program initdb uses to create the catalog tables. This
       option generates a tremendous amount of extremely boring output.

  -L directory
       Specifies where initdb should find its input files to initialize the
       database cluster. This is normally not necessary. You will be told if
       you need to specify their location explicitly.

  -n

  --noclean
       By default, when initdb determines that an error prevented it from
       completely creating the database cluster, it removes any files it may
       have created before discovering that it can't finish the job. This
       option inhibits tidying-up and is thus useful for debugging.

ENVIRONMENT
  PGDATA
       Specifies the directory where the database cluster is to be stored;
       may be overridden using the -D option.

  This utility, like most other PostgreSQL utilities, also uses the
  environment variables supported by libpq (see in the documentation).

SEE ALSO
  postgres(1)

Index for Section 1

Alphabetical listing for I

Top of page