pg_ctl is an very useful but underrated utility that can make the lives
of development teams easier. Read on to learn more about
pg_ctl and how
it can improve your development and test workflows.
What is pg_ctl?
pg_ctl is a command-line tool included in the standard Postgres distribution. It is available everywhere that Postgres itself is, similar to the other included tools like psql and pg_dump.
The executable will be in the same directory as the other Postgres binaries. The exact location varies with the Linux distro and Postgres version:
You may want to add this directory to your PATH, or alias pg_ctl to the full path.
Create a Database Cluster
Unlike other RDBMSes, a single Postgres database server process (historically called the postmaster), manages a database cluster. The usage of the term cluster is not modern, and does not refer to a group of networked nodes. A database cluster hosts a set of databases, with some features (roles, physical replication, WAL files, etc.) common to all of them. The Postgres systemd service that is installed by your Linux distro serves a single database cluster.
You can use
pg_ctl to create a database cluster. At creation, the cluster
lives entirely within a single directory. It contains all necessary configuration
files (postgres.conf, pg_hba.conf, etc.) and data files. It is self-contained,
and can be moved to another reasonably similar machine if file permissions are
handled correctly. You can even place log files inside the directory, so that
you have all the related files (configuration, data, logs) in one place.
To create a database cluster, use:
This creates a directory called myclus under the current directory, and populates it with all the files necessary to start a server from it.
Here is a sample session:
Start a Database Server
A “Postgres server” is basically a postmaster process that is started with the location of a database cluster directory. This postmaster process in turn spawns multiple process that do various background activities as well as handle incoming connections. You can see this process model in action by viewing the system process tree using a tool like htop, for example.
To start a postmaster process for your new database cluster, use:
-l option specifies the location of the Postgres log file, which in this
case is within the cluster directory itself. It’s not uncommon to place the log
file within the cluster directory.
You should see an output like this:
Reloading, restarting and stopping happen as you’d expect:
You should now be able to connect to this new cluster using clients like psql and pgAdmin.
Setting Port And Other Options
Practically though, if you already have Postgres installed on your machine,
you’ll probably need to edit
myclus/postgres.conf and change the values
for port, unix_socket_directories and also maybe listen_address before
the cluster starts up cleanly. This is because the system-installed Postgres
service is already running on port 5432 and the directories in
unix_socket_directories cannot be written to by a regular user. The default
listen_address is localhost, meaning that you won’t be able to connect to
the cluster from outside localhost.
If you’re using pg_ctl to create and teardown clusters in your automated
test scripts, it is easier if you can specify these options directly from
the command-line rathen than programmatically editing
You can specify the options like this:
This starts the server on port 6000, with the unix socket created in the directory /tmp and listening on all interfaces.
You need to specify these options only for “start”, you can omit them for other commands, including even “restart”.
Other Useful Start Options
There are a couple of other options that you can use inside “-o” that might be useful:
-Fdisables fsync, useful to faster completion of test scripts
-B shared_bufffersset value of shared_buffers, example
-c conf_var=valueset any configuration value, example
Here’s an example with some of these set:
These options are acually the command line options of the postgres process, the full list of which are documented here.
Run Database of a Different Postgres Version
EnterpriseDB hosts pre-built binaries for various Postgres versions for various platforms. These are tarballs without any installer.
Grab the tarball you want, unpack it, locate the
pg_ctl binary with it,
and use that to create a cluster.
pg_ctl will automatically find the
associated initdb/postgres/other binaries that it needs to create/start
You can use this regardless, and independent of, any existing PostgreSQL installation on the machine.
Create Services on Windows
pg_ctl is available on all platforms, including MacOS and Windows. In particular,
you can use it to easily create a service that can be started and stopped via
the Service Control Manager (SCM). To create a service, use:
This creates an auto-start service called “myclus_service”.
This feature is available only in Postgres v10 and above.
pgDash is a modern, in-depth monitoring solution designed specifically for PostgreSQL deployments. pgDash shows you information and metrics about every aspect of your PostgreSQL database server, collected using the open-source tool pgmetrics.
pgDash provides core reporting and visualization functionality, including collecting and displaying PostgreSQL information and providing time-series graphs, detailed reports, diagnostics, alerting, teams and more. Checkout the features here or signup today for a free trial.