CLUSTERDB(1)

💖 CLUSTERDB(1) 💖

okay so bestie, we're in the PostgreSQL 18.6 Documentation and today's main character is clusterdb — she clusters a PostgreSQL database and she does it flawlessly. let's get into it 🎀

---

✨ NAME ✨

clusterdb — cluster a PostgreSQL database 🦋

---

✨ SYNOPSIS ✨

clusterdb [connection-option...] [option...] [ --table | -t table ]...
          [dbname | -a | --all]

---

✨ DESCRIPTION ✨

so like, clusterdb is a utility for reclustering tables in a PostgreSQL database. what it does is it goes and finds the tables that have previously been clustered, and then clusters them again on the same index that was last used. tables that have never been clustered? not affected, not invited, they stay exactly as they are 💅

and here's the tea: clusterdb is literally just a wrapper around the SQL command CLUSTER(7). there is no effective difference between clustering databases through this utility and doing it any other way of accessing the server. same energy, fr fr ✨

---

✨ OPTIONS ✨

clusterdb accepts the following command-line arguments, bestie 👑

• -a, --all — cluster all the databases. all of them. every single one 🫶
• [-d] dbname, [--dbname=]dbname — tells it the name of the database you wanna cluster, for when -a/--all is not being used. if you don't specify it, the database name gets read from the environment variable PGDATABASE. and if that's not set either, then it just uses the user name that was specified for the connection. also! the dbname can be a connection string — and if it is, connection string parameters will override any conflicting command line options. so watch out for that 👀
• -e, --echo — echoes the commands that clusterdb generates and sends to the server. so you can literally see what she's saying 📣
• -q, --quiet — don't display progress messages. silent but deadly, love that for her 🤫
• -t table, --table=table — cluster table only. you can cluster multiple tables by writing multiple -t switches, one after another. iconic behavior 💅
• -v, --verbose — print detailed information during processing. she's giving full transparency ✨
• -V, --version — print the clusterdb version and exit. quick lil flex 🎀
• -?, --help — show help about clusterdb command line arguments, and exit. your bestie always tells you how to use her 🫶

---

🌸 connection parameters 🌸

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

• -h host, --host=host — specifies the host name of the machine the server is running on. and if the value starts with a slash, it's used as the directory for the Unix domain socket. slash = socket, noted 📝
• -p port, --port=port — specifies the TCP port, or the local Unix domain socket file extension, that the server is listening on for connections 🔌
• -U username, --username=username — the user name to connect as. who are you today? main character, obviously 💜
• -w, --no-password — never issue a password prompt. if the server requires password authentication and a password isn't available by other means like a .pgpass file, then the connection attempt will fail. this one is useful in batch jobs and scripts where there's literally no user around to type in a password 🥲
• -W, --password — forces clusterdb to prompt for a password before connecting to a database.

this option is never essential, because clusterdb will automatically prompt for a password if the server demands password authentication anyway. BUT — and this is the lowkey annoying part — clusterdb will waste a whole connection attempt just finding out that the server wants a password. so sometimes it's worth typing -W to skip that extra connection attempt. efficiency, periodt 💅

• --maintenance-db=dbname — when -a/--all is used, connect to this database to gather the list of databases to cluster. if you don't specify it, the postgres database will be used — or, if that one doesn't exist, template1 gets used instead. this can be a connection string, and if it is, 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. she remembers. she always remembers 🧚

---

✨ ENVIRONMENT ✨

• PGDATABASE
• PGHOST
• PGPORT
• PGUSER

those four are your default connection parameters 💖

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

and also, this utility — like most other PostgreSQL utilities — uses the environment variables supported by libpq (see Section 32.15). the whole squad, fr fr 🫶

---

✨ DIAGNOSTICS ✨

if you're having difficulty, go look at CLUSTER(7) and psql(1) for discussions of potential problems and error messages. also, the database server must be running at the targeted host, okay? that's non-negotiable 😭 and any default connection settings and environment variables used by the libpq front-end library will apply too.

---

✨ EXAMPLES ✨

to cluster the database test:

$ clusterdb test

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

$ clusterdb --table=foo xyzzy

look at her go 😌✨

---

✨ SEE ALSO ✨

CLUSTER(7) — that's the whole list, go read it bestie 👑

---

ngl if any of this is confusing just re-read the options section, it's literally all there 💖

---

okay and that's the whole page!! this was written for PostgreSQL 18.6, dated 2026, and it's the CLUSTERDB(1) page 💅 thanks for reading bestie, you ate this, periodt 🎀✨🦋