Introduction
PostgreSQL offers two command-line methods to drop a database - using the DROP DATABASE statement or a shell utility.
Removing unused databases is good practice and helps keep the workspace clean. However, keep in mind that deleting an existing PostgreSQL database removes all catalog entries and data for that database.
Continue reading to learn how to drop a database in PostgreSQL.
Prerequisites
- PostgreSQL 10 or higher installed and configured (follow our guide for Ubuntu or Windows; if already installed, check the PostgreSQL version on the system).
- Access to the terminal with sudo privileges.
DROP DATABASE Statement
Important: ONLY the database owner can delete a database.
The first method to remove a PostgreSQL database is to use the following SQL statement:
DROP DATABASE <database name>;The command removes the directory containing the database information and the catalog entries. Only the database owner can execute the DROP DATABASE command. If anyone is currently using the database, the command does not execute.
To see how DROP DATABASE works, do the following:
1. Open the terminal (CTRL+ALT+T).
sudo -i -u postgres psql
3. Create a database for the example:
CREATE DATABASE example;
The terminal prints the executed statement.
4. List all the databases with:
\l
The database from the previous step shows up on the list.
5. Drop the database with:
DROP DATABASE example;
The output shows the executed statement.
6. List all databases again:
\lThe example database no longer appears in the list.
IF Exists
The IF EXISTS option is open for all versions where DROP DATABASE is available. The full command syntax with the IF EXISTS option is as follows:
DROP DATABASE IF EXISTS <database name>;The option first checks if a database exists before deleting it. If a database exists, the command drops the database. However, if a database doesn't exist, the command prints an informative notice message.
To test how the command works, follow the steps below:
1. Create an example database:
CREATE DATABASE example;2. Drop the database using the IF EXISTS option:
DROP DATABASE IF EXISTS example;
The result is identical to using DROP DATABASE if the database does exist.
3. The database is no longer available. Rerun the command to see the output:
DROP DATABASE IF EXISTS example;
A notice message prints stating the database does not exist.
4. To see the difference between using IF EXISTS and omitting the option, run the following command:
DROP DATABASE example;
Using DROP DATABASE without the IF EXISTS option on a non-existent database throws an error message.
WITH (FORCE)
The WITH (FORCE) option is available in PostgreSQL version 13 and higher.
The DROP DATABASE method won't remove the database if it's in use. If the database is in use, the terminal prints an error that a database session is open.
Add the WITH (FORCE) option to forcefully close the session and delete the database:
DROP DATABASE <database name> WITH (FORCE);
If possible, Postgres closes the user's session and deletes the database forcefully.
The dropdb Utility
The dropdb shell utility is a wrapper for the DROP DATABASE command. Effectively, the two methods are identical. However, dropdb offers additional options including removing databases remotely.
The basic syntax is:
dropdb <connection parameters> <options> <database name>Options
The table below shows all the possible options when using the dropdb utility.
| Option | Type | Description |
|---|---|---|
-e--echo | Option | Prints the commands that dropdb sends to the server. |
-f--force | Option | Attempts to terminate all current connections before dropping the database. |
-i--interactive | Option | Prompts verification before executing database deletion. |
-V--version | Option | The console prints the utility version. |
--if-exists | Option | Prints a notice instead of an error if the database does not exist. |
-?--help | Option | Show the help menu. |
-h <host>--host=<host> | Connection parameter | Specifies the hostname of the machine where the server is running. |
-p <port>--port=<port> | Connection parameter | Specifies the TCP port where the server is listening. |
-U <username>--username <username> | Connection parameter | Connect as the specified user. |
-w--no-password | Connection parameter | Never issue the password prompt. Useful for batch and script jobs when no user is present. |
-W--password | Connection parameter | Force password prompt. Without the option, the server loses the connection attempt if a password is necessary. |
--maintenance-db=<database name> | Connection parameter | The option specifies the database name connection. |
For example, try the following command to see how dropdb works with the -i and -e options:
dropdb -i -e exampleThe program asks for confirmation before the deletion because of the -i tag.
Press y to confirm. The program prints the commands generated to the server. Because the database is non-existent, the program throws an error and exits.
Conclusion
After following the examples from this guide, you know how to drop a PostgreSQL database using two methods.
To learn how to drop a user in multiple ways, read our guide on how to delete Postgres user.
Next, consider learning about the different data types in PostgreSQL.
