Technical Analysis: vacuumdb --exclude-database Option

Core Problem

The vacuumdb --all command in PostgreSQL's client utilities vacuums every connectable database on a cluster without exception. This is an all-or-nothing approach that creates operational friction in production environments where administrators need selective control over which databases participate in maintenance windows.

Why This Matters Architecturally

The vacuumdb utility is part of PostgreSQL's suite of client-side maintenance tools (alongside reindexdb, clusterdb, etc.). These tools follow a common pattern established in src/bin/scripts/: they either operate on a single specified database (-d dbname) or iterate over all databases (--all). The lack of exclusion semantics forces operators into one of two suboptimal patterns:

1. Manual enumeration: Explicitly listing every database to vacuum, which is fragile as databases are added/removed
2. Wrapper scripts: Shell scripts that query pg_database, filter, and invoke vacuumdb per-database — duplicating logic that belongs in the tool itself

The problem is particularly acute for:

• Clusters with large archival/historical databases where VACUUM is expensive and unnecessary (no write activity)
• Test databases colocated on production clusters
• Databases undergoing migration where maintenance should be deferred

Proposed Solution

The patch adds a new command-line option --exclude-database (short form -D) that accepts database names to skip when --all is specified. The option can be repeated to exclude multiple databases.

Design Decisions

1. Requires --all: The option is only valid in combination with --all. Using --exclude-database without --all produces an error. This is a sensible constraint — exclusion semantics only make sense when iterating all databases.

2. Mutual exclusion with -d: Using both --exclude-database and -d (specific database) is an error. This prevents confusing option combinations.

3. Silent handling of non-existent databases: Excluding a database name that doesn't exist is silently ignored rather than producing an error. This is a pragmatic choice for scripting — it means exclusion lists don't break when databases are dropped.

4. Case-sensitive matching: Database name matching is exact/case-sensitive, which aligns with PostgreSQL's general identifier handling (unquoted identifiers are folded to lowercase, but the actual catalog stores the precise name).

Implementation Considerations

The implementation likely modifies the database iteration logic in src/bin/scripts/vacuumdb.c. The --all mode queries pg_database to get a list of connectable databases, then iterates over them. The patch would add a filtering step that checks each database name against the exclusion list before processing.

Key implementation questions that reviewers would likely raise:

• Where is the exclusion list stored? Likely a SimpleStringList (the standard linked-list-of-strings type used throughout PostgreSQL's client utilities for multi-value options).
• Pattern matching vs. exact names: The patch appears to use exact name matching only. A reviewer might ask whether glob/regex patterns would be useful (e.g., --exclude-database='test_*'), though this adds complexity.
• Consistency with other tools: If this pattern is useful for vacuumdb, it's equally useful for reindexdb --all and clusterdb --all. A reviewer might suggest implementing this at a shared level or at minimum establishing a precedent for the other tools.

Potential Review Concerns

1. Option letter conflict: The short option -D needs verification against existing options. In vacuumdb, -d is already used for --dbname. Using uppercase -D for exclusion is reasonable but reviewers may check for conflicts with other tools sharing option parsing infrastructure.

2. Error messaging: When all databases are excluded, what happens? The test suite covers this case (test scenario 3), suggesting the tool handles it gracefully (likely exits with success after doing nothing, or with a notice).

3. SQL injection in database names: Test scenario 9 explicitly covers SQL injection protection, suggesting the implementation properly quotes/escapes database names when constructing connection strings or queries.

4. Precedent for --exclude-table: This patch could open discussion about whether --exclude-table (to skip specific tables within a database) would also be valuable, though that's a separate feature with different implementation characteristics.

Testing Approach

The patch includes both integrated TAP tests (added to 101_vacuumdb_all.pl, the appropriate location since exclusion requires --all) and a standalone shell test script. The TAP test integration is the important part for CI; the shell script serves as supplementary documentation of behavior.

The 11 test scenarios provide good coverage of both positive cases (exclusion works) and negative cases (error on invalid option combinations, case sensitivity boundary).

Assessment

This is a straightforward usability improvement to a client-side tool. It doesn't touch server internals, WAL, catalogs, or the executor — it's purely a client utility enhancement. The risk is minimal, the implementation is likely small (probably under 100 lines of C changes plus tests), and the operational benefit is clear.

The main discussion points will likely center on:

• Whether this should be generalized to other --all-supporting tools simultaneously
• Whether pattern matching should be supported
• Whether the feature should support --include-database as well (positive filtering as an alternative to --all)