CLUSTERDB(1)

💅 clusterdb(1) — the glow-up your tables deserved

okay so real talk, this page is from the PostgreSQL 16.15 Documentation and it's all about clusterdb, the little utility that goes back and re-clusters your tables. bestie, let me walk you through it 🫶

---

✨ NAME ✨

clusterdb — cluster a PostgreSQL database

🌸 SYNOPSIS 🌸

clusterdb [connection-option...] [--verbose | -v]
          [ --table | -t table ]...  [dbname]

clusterdb [connection-option...] [--verbose | -v] --all | -a

🦋 DESCRIPTION 🦋

so clusterdb is this utility for reclustering tables in a PostgreSQL database. what it does is: it goes hunting for tables that have previously been clustered, and then clusters them again on the same index that was used last time. tables that have never been clustered? not affected, not even a little. they get left exactly where they are 💅

and yes, clusterdb is literally just a wrapper around the SQL command CLUSTER(7). there is no effective difference between clustering databases via this utility and via any other method of accessing the server. same energy, fr fr.

🎀 OPTIONS 🎀

clusterdb accepts the following command-line arguments:

• -a, --all — cluster all the databases. all of them. every last one.
• [-d] dbname, [--dbname=]dbname — tells it the name of the database to be clustered, for when you're not using -a/--all. if you don't specify it, the database name gets read from the environment variable PGDATABASE. and if that isn't set either, it uses the user name you specified for the connection. also heads up: the dbname can be a connection string — if it is, connection string parameters will override any conflicting command line options. slay but be aware 💀
• -e, --echo — echoes the commands that clusterdb generates and sends to the server. so you can see exactly what it's out here doing.
• -q, --quiet — don't display progress messages. no chatter, just vibes.
• -t table, --table=table — cluster only this table. and hmm, you can cluster multiple tables by writing multiple -t switches. stack 'em, bestie 🍓
• -v, --verbose — print detailed information during processing. the full play-by-play.
• -V, --version — print the clusterdb version and exit.
• -?, --help — show help about clusterdb command line arguments, and exit.

clusterdb also accepts the following command-line arguments for connection parameters:

• -h host, --host=host — specifies the host name of the machine on which the server is running. and ooh, if the value begins with a slash, it gets used as the directory for the Unix domain socket.
• -p port, --port=port — specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections.
• -U username, --username=username — the user name to connect as. who are you today 👑
• -w, --no-password — never issue a password prompt. like, ever. if the server requires password authentication and a password isn't available by other means such as a .pgpass file, the connection attempt will fail. this option can be useful in batch jobs and scripts where no user is present to enter a password. lowkey iconic for automation.
• -W, --password — force clusterdb to prompt for a password before connecting to a database. this option is never essential, since clusterdb will automatically prompt for a password if the server demands password authentication. however, clusterdb will waste a connection attempt finding out that the server wants a password. in some cases it is worth typing -W to avoid the extra connection attempt. so like, optional but efficient ✨
• --maintenance-db=dbname — when -a/--all is used, connect to this database to gather the list of databases to cluster. if not specified, the postgres database will be used, or if that doesn't exist, template1 will be used. this can be a connection string — if so, connection string parameters will override any conflicting command line options. also, connection string parameters other than the database name itself will be re-used when connecting to other databases. iykyk 🌈

💖 ENVIRONMENT 💖

• PGDATABASE
• PGHOST
• PGPORT
• PGUSER

these are the default connection parameters 🫶

• PG_COLOR — specifies whether to use color in diagnostic messages. possible values are always, auto and never.

this utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section 34.15).

😭 DIAGNOSTICS 😭

in case of difficulty, see CLUSTER(7) and psql(1) for discussions of potential problems and error messages. also, the database server must be running at the targeted host. no server, no clustering, periodt. and any default connection settings and environment variables used by the libpq front-end library will apply.

⭐ EXAMPLES ⭐

to cluster the database test:

$ clusterdb test

to cluster a single table foo in a database named xyzzy:

$ clusterdb --table=foo xyzzy

🔥 SEE ALSO 🔥

CLUSTER(7)

---

and that's the whole page, bestie 💜 this adorable little manual page is PostgreSQL 16.15, dated 2026 — cluster responsibly, mwah 🧚