What's the difference between initdb /usr/local/var/[db] and createdb [db]

Question

I am starting to use PostgreSQL and I am confused about the two ways to create a database. When I installed it the first time, the instructions said I have to create a default database with initdb /usr/local/var/postgres When I lookup my databases, I can see that I have a database called postgres. Now I am able to create a database with two other commands whereas the former is the command line script and the latter the SQL command. In the case of a "postgres" called database it would be:

• createdb postgres
• CREATE DATABASE postgres

Both are setting up a database in my list of databases. When I try to create another database with initdb /usr/local/var/[someDbName] though, it doesn't appear in my list of databases. So what's the difference between initdb and createdb then?

Answer 1

initdb is not used to create a "new database".

As documented in the manual you need it to create a "cluster" or "data directory" which then stores databases created with create database.

Quote from the manual:

Before you can do anything, you must initialize a database storage area on disk. We call this a database cluster. (The SQL standard 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

[...]

In file system terms, a database cluster is a single directory under which all data will be stored. We call this the data directory or data area

In short: initdb creates the necessary directory layout on the harddisk to be able to create and manage databases.

It's a necessary part of the installation process of a Postgres server.