table of contents
INITDB(1) | PostgreSQL 13.18 Documentation | 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 cannot be run as root, you must not run initdb as root either. (It will in fact refuse to do so.)
For security reasons the new cluster created by initdb will only be accessible by the cluster owner by default. The --allow-group-access option allows any user in the same group as the cluster owner to read files in the cluster. This is useful for performing backups as a non-privileged user.
initdb initializes the database cluster's default locale and character set encoding. The character set encoding, collation order (LC_COLLATE) and character set classes (LC_CTYPE, e.g., upper, lower, digit) can be set separately for a database when it is created. initdb determines those settings for the template1 database, which will serve as the default for all other databases.
To alter the default collation order or character set classes, use the --lc-collate and --lc-ctype options. 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. You can also use --locale to set the default for all locale categories, including collation order and character set classes. All server locale values (lc_*) can be displayed via SHOW ALL. More details can be found in Section 23.1.
To alter the default encoding, use the --encoding. More details can be found in Section 23.3.
OPTIONS¶
-A authmethod
--auth=authmethod
Do not use trust unless you trust all local users on your system. trust is the default for ease of installation.
--auth-host=authmethod
--auth-local=authmethod
-D directory
--pgdata=directory
-E encoding
--encoding=encoding
-g
--allow-group-access
-k
--data-checksums
--locale=locale
--lc-collate=locale
--lc-ctype=locale
--lc-messages=locale
--lc-monetary=locale
--lc-numeric=locale
--lc-time=locale
--no-locale
-N
--no-sync
--pwfile=filename
-S
--sync-only
-T config
--text-search-config=config
-U username
--username=username
-W
--pwprompt
-X directory
--waldir=directory
--wal-segsize=size
It may be useful to adjust this size to control the granularity of WAL log shipping or archiving. Also, in databases with a high volume of WAL, the sheer number of WAL files per directory can become a performance and management problem. Increasing the WAL file size will reduce the number of WAL files.
Other, less commonly used, options are also available:
-d
--debug
-L directory
-n
--no-clean
Other options:
-V
--version
-?
--help
ENVIRONMENT¶
PGDATA
PG_COLOR
TZ
NOTES¶
initdb can also be invoked via pg_ctl initdb.
SEE ALSO¶
2024 | PostgreSQL 13.18 |