initdb Command in Linux
The initdb command in Linux creates a new PostgreSQL database cluster. PostgreSQL is an open-source, powerful, and feature-rich relational database management system (RDBMS).
A database cluster is a collection of databases that are managed by a single PostgreSQL server instance. It is important to note that initdb must be run by the PostgreSQL superuser or non-root user with appropriate permissions, as the server cannot access root-owned files.
Table of Contents
Here is a comprehensive guide to the options available with the initdb command −
- Prerequisites to Use initdb Command
- Syntax of initdb Command
- Options of initdb Command
- Examples of initdb Command in Linux
- Fixing initdb Command Not Found Error
Note − The initdb command not found error may appear while executing it because the initdb command is intentionally not included in the system's PATH to discourage direct usage by end users. If a single instance of PostgreSQL is required, the installation automatically includes a cluster named main, eliminating the need to run initdb for its creation. However, if you need multiple clusters, the PostgreSQL packages for Debian and Ubuntu offer a different command, pg_createcluster, which should be used instead of initdb.
Prerequisites to Use initdb Command
The PostgreSQL package must be installed and configured on Linux before using the initdb command. To install PostgreSQL on Ubuntu, Kali Linux, Raspberry Pi OS, Debian, and Debian-based distributions, use the command given below −
sudo apt install postgresql
To install it on CentOS, use the command given below −
sudo yum install -y postgresql15-server
To install it on Fedora, use the following command −
sudo dnf install postgresql-server postgresql-contrib
Now, verify the installation, using the following command −
psql --version
Syntax of initdb Command
The syntax of the Linux initdb command is as follows −
initdb [options] [directory]
The [options] field is used to specify the options. The [directory] field is used to specify the directory in which the cluster will be created.
Options of initdb Command
The options of the initdb command are listed below −
| Flags | Options | Description |
|---|---|---|
| -A authmethod | --auth= authmethod | To specify the authentication method for local user in pg_hba.conf (default is trust) |
| -D directory | --pgdata= directory | To specify the directory in which the cluster will be created |
| -E encoding | --encoding= encoding | To set the encoding for the template database (This will also be the default encoding of any database you create later unless you override it there.) |
| --locale= locale | To set the locale for the database cluster | |
| --no-locale | It sets the locale to C | |
| -X directory | --waldir= directory | To specify the directory for storing transaction log |
| -U username | --username= username | To set the username of the database superuser |
| -W | --pwprompt | To prompt for the password |
| --pwfile= file | To read passwords from the specified file | |
| -s | --show | To display the internal settings (useful to debug initdb installation) |
| -T config | --text-search-config= config | To set the default text search configuration |
| -d | --debug | To display the debug information |
| -L directory | To specify where initdb should find its input files to initialize the database cluster | |
| -n | --noclean | To prevent initdb from cleaning up files on errors, useful for debugging |
| -V | --version | To display the initdb version |
| -? | --help | To display initdb help |
Examples of initdb Command in Linux
This section demonstrates the usage of the initdb command in Linux −
Initializing a Database Cluster
First, use the following command to switch to the postgres system user with an interactive login shell.
sudo -i -u postgres
To manually initialize a database cluster, run the initdb command and use the -D option to specify the desired file system location for the cluster, for example −
initdb -D /usr/local/pgsql/data
The above command may give a permission denied error as shown in the following image.
To avoid this error, the directory /usr/local/pgsql/ must exist, and the user must have permission to access and modify it. To create and grant access to this directory to a user, use the following commands −
sudo mkdir -p /usr/local/pgsql/data sudo chown postgres:postgres /usr/local/pgsql/data
The above commands create a directory and give the user postgres (default user) ownership. The initdb will not run if the data directory already exists and contains files.
Initializing a Database Cluster by Specifying the Encoding
To initialize a database cluster with a specific encoding, use the -E or --encoding option −
initdb -D /usr/local/pgsql/data -E UTF8
Setting Up Transaction Log Directory
To set up a transaction log directory while initializing the database cluster, use the -X or --waldir option with the directory path:
initdb -D /usr/local/pgsql/data -X /var/lib/postgresql/psql_log
Reading Password from a File
To read the superuser password from a file, use the --pwfile option with the filename −
initdb -D /usr/local/pgsql/data --pwfile=password.txt
Displaying the Internal Settings
To display the internal settings, use the -s or --show option −
initdb -s /usr/local/pgsql/data
Displaying Help
To display help related to the initdb command, use the -? or --help option −
initdb -?
Fixing initdb Command Not Found Error
In the latest versions of PostgreSQL, the initdb is not installed as a user executable. It is only installed in /usr/lib/postgresql/XX.X/bin/. However, it can be made executable.
To fix the initdb command not found error and to make it executable, first find the PostgreSQL initdb binary path.
To find the initdb binary path run the following command −
sudo find / -name initdb
The initdb binary path is /usr/lib/postgresql/16/bin/initdb, as shown in the above output image.
Now, add this path to the ~/.bashrc or ~/.profile file. To add it to the ~/.bashrc file, first open it in the nano editor.
sudo nano ~/.bashrc
Add the following lines at the end of the file −
if [ -d "/usr/lib/postgresql/16/bin/" ] ; then PATH="/usr/lib/postgresql/16/bin/:$PATH" fi
Save and exit the editor, by pressing Ctrl+X and then the Enter key.
Lastly, update your shell by sourcing the file with the following command −
source ~/.bashrc
Now, the initdb command will be available. For verification, check the version of the initdb command −
initdb --version
Conclusion
The initdb command is essential for setting up a new PostgreSQL database cluster on Linux. It must be run by the database user to prevent permission issues. The users may encounter a command not found error since initdb is not included in the system's PATH.
For single PostgreSQL instances, a default cluster named main is created automatically, while pg_createcluster can be used for multiple clusters in Debian and Ubuntu.
In this tutorial, we explained the prerequisites, syntax, options, practical usage of the initdb command in Linux, and fixing the initdb command not found error.