Stopping a database server is not just a routine command; it is an operation that directly affects data integrity, active users, and system stability. In PostgreSQL, shutdown behavior is carefully designed to give administrators flexibility depending on the situation.
This article provides a detailed explanation of the three shutdown modes available in PostgreSQL like smart, fast, and immediate, along with a real-world experiment that demonstrates how each mode behaves under active workload conditions.
Understanding the pg_ctl Utility
The pg_ctl utility is used to control the PostgreSQL server. It allows you to initialize, start, stop, restart, and manage the database instance.
You can verify this tools more detaily and version using the following commands:
pg_ctl --help
Example :
pg_ctl is a utility to initialize, start, stop, or control a PostgreSQL server.
Usage:
pg_ctl init[db] [-D DATADIR] [-s] [-o OPTIONS]
pg_ctl start [-D DATADIR] [-l FILENAME] [-W] [-t SECS] [-s]
[-o OPTIONS] [-p PATH] [-c]
pg_ctl stop [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]
pg_ctl restart [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]
[-o OPTIONS] [-c]
pg_ctl reload [-D DATADIR] [-s]
pg_ctl status [-D DATADIR]
pg_ctl promote [-D DATADIR] [-W] [-t SECS] [-s]
pg_ctl logrotate [-D DATADIR] [-s]
pg_ctl kill SIGNALNAME PID
Common options:
-D, --pgdata=DATADIR location of the database storage area
-s, --silent only print errors, no informational messages
-t, --timeout=SECS seconds to wait when using -w option
-V, --version output version information, then exit
-w, --wait wait until operation completes (default)
-W, --no-wait do not wait until operation completes
-?, --help show this help, then exit
If the -D option is omitted, the environment variable PGDATA is used.
Options for start or restart:
-c, --core-files allow postgres to produce core files
-l, --log=FILENAME write (or append) server log to FILENAME
-o, --options=OPTIONS command line options to pass to postgres
(PostgreSQL server executable) or initdb
-p PATH-TO-POSTGRES normally not necessary
Options for stop or restart:
-m, --mode=MODE MODE can be "smart", "fast", or "immediate"
Shutdown modes are:
smart quit after all clients have disconnected
fast quit directly, with proper shutdown (default)
immediate quit without complete shutdown; will lead to recovery on restart
Allowed signal names for kill:
ABRT HUP INT KILL QUIT TERM USR1 USR2
Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page: <https://www.postgresql.org/>
You can check the path of this installed pg_ctl command like this
which pg_ctl
Result :
/home/cybrosys/pg18/bin/pg_ctl
Check the version of pg_ctl utility like this
/home/cybrosys/pg18/bin/pg_ctl --version
Result :
pg_ctl (PostgreSQL) 18.1
This confirms that the PostgreSQL control utility from version 18.1 is being used.
Inspecting PostgreSQL Clusters
Before performing shutdown operations, check the running clusters:
pg_lsclusters
Example :
Ver Cluster Port Status Owner Data directory Log file
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17-main.log
18 main 5432 online postgres /var/lib/postgresql/18/main /var/log/postgresql/postgresql-18-main.log
18 main2 5434 online postgres /var/lib/postgresql/18/main2 /var/log/postgresql/postgresql-18-main2.log
Creating an Active Workload for Testing
To properly observe how each shutdown mode behaves, create an active database session.
sudo su postgres
psql
Then you executed the following query:
select count(*) from pg_stat_activity where state = 'active';
Now repeat this query in each second by using the watch command
\watch
This setup continuously runs the query every second. As a result, there is always at least one active session connected to the database. This is an effective way to simulate a real-world scenario where users or applications are actively interacting with the system.
Smart Shutdown Mode: Waiting for Sessions to Finish
Let’s try to shut down the postgres using the smart mode
postgres@cybrosys:/home/cybrosys$ /home/cybrosys/pg18/bin/pg_ctl stop -D /var/lib/postgresql/18/main -m smart
While this command was running, the server did not shut down immediately. It remained in a waiting state because the active session created by the \watch command was still running.
Now let’s exit from the psql terminal like this
postgres=# \q
postgres@cybrosys:/home/cybrosys$
Only after you manually exited the psql session did the shutdown complete:
waiting for server to shut down................................................ done
server stopped
Detailed Behavior of Smart Mode
Smart mode is the most conservative and graceful shutdown mechanism provided by PostgreSQL. It works based on the following principles:
- The server stops accepting new connections immediately after the command is issued.
- Existing connections are allowed to continue running without interruption.
- All active transactions are allowed to complete normally.
- The server shuts down only after all clients disconnect.
This behavior ensures that no user session is forcibly terminated and no work is lost. However, it also means that if any session remains open intentionally or accidentally the shutdown will be delayed indefinitely.
Practical Implications
Smart mode is best suited for controlled environments where:
- You can ensure that all users will disconnect soon.
- You want to avoid interrupting long-running queries.
- Data consistency and user experience are top priorities.
However, it is not ideal when immediate shutdown is required or when sessions are not under strict control.
Fast Shutdown Mode: Controlled and Immediate Termination
Now let’s shutdown the postgres using the fast mode
cybrosys@cybrosys:~$ sudo su postgres
postgres@cybrosys:/home/cybrosys$ /home/cybrosys/pg18/bin/pg_ctl stop -D /var/lib/postgresql/18/main -m fast
The output was:
waiting for server to shut down.... done
server stopped
Unlike smart mode, the server shut down immediately without waiting for you to exit the psql session.
Detailed Behavior of Fast Mode
Fast mode is designed to balance safety and efficiency. Its behavior includes:
- All active client connections are terminated immediately.
- Any running transactions are aborted and rolled back.
- The system performs a proper checkpoint before shutting down.
- No crash recovery is required on the next startup.
This demonstrates that fast mode does not wait for client cooperation.
Practical Implications
Fast mode is the default shutdown mode in PostgreSQL and is widely used in production systems because:
- It ensures a clean shutdown.
- It does not depend on user actions.
- It minimizes downtime during restarts.
- It maintains data consistency through proper transaction rollback.
Immediate Shutdown Mode: Forced Termination
Now let’s try the immediate shut down mode
cybrosys@cybrosys:~$ sudo su postgres
postgres@cybrosys:/home/cybrosys$ /home/cybrosys/pg87/bin/pg_ctl stop -D /var/lib/postgresql/18/main -m immediate
The output was:
waiting for server to shut down.... done
server stopped
At first glance, this may look similar to fast mode, but internally the behavior is significantly different.
Detailed Behavior of Immediate Mode
Immediate mode is equivalent to a forced crash of the database server. Its characteristics include:
- All processes are terminated instantly.
- No attempt is made to finish active transactions.
- No checkpoint is performed.
- Shared memory structures are not cleaned up properly.
Because of this abrupt termination, PostgreSQL treats the next startup as a crash recovery scenario. During restart, the system replays WAL (Write-Ahead Logging) to restore consistency.
Practical Implications
Immediate mode should be used only in exceptional situations such as:
- The server is unresponsive or hung.
- Normal shutdown methods are not working.
- Emergency intervention is required.
Although PostgreSQL is designed to recover safely, repeated use of immediate shutdown can increase recovery time and may temporarily affect system performance.
Best shut down mode for Production
In real-world production environments, the choice of shutdown mode depends on operational requirements. However, in most cases, fast mode is the best and most practical option.
Why Fast Mode is Recommended
Fast mode provides the right balance between safety and control:
- It guarantees a clean and consistent shutdown.
- It avoids indefinite waiting caused by active sessions.
- It ensures that incomplete transactions are rolled back properly.
- It allows the server to restart without requiring crash recovery.
When to Use Smart Mode
Smart mode is appropriate when:
- You are performing scheduled maintenance.
- You want to allow all users to complete their work.
- You have control over client disconnections.
When to Use Immediate Mode
Immediate mode should be considered only as a last resort when:
- The server is not responding to normal shutdown commands.
- There is an urgent need to stop the database immediately.
- System stability is at risk.
Shutting down a PostgreSQL server is not a one-size-fits-all operation. Each shutdown mode, like smart, fast, and immediate, serves a distinct purpose and behaves differently depending on the state of active connections and transactions.
From the practical tests, it becomes clear that smart mode prioritizes ongoing user activity by waiting for sessions to finish, which makes it suitable for controlled environments but less practical when time is limited. Fast mode, on the other hand, provides a reliable and efficient way to stop the server by terminating active sessions safely and ensuring that all transactions are handled correctly. Immediate mode bypasses all cleanup steps and should only be used in situations where the server cannot be stopped through normal means.
In most production scenarios, fast mode stands out as the preferred choice because it maintains data integrity while allowing the system to shut down without unnecessary delays. Smart mode is useful when you can afford to wait, and immediate mode should remain a fallback option for emergencies.