SQLite 3.54 Makes It Easier to See What Is Filling Your Database

A growing SQLite file poses a deceptively simple question: is the space holding useful data, expensive indexes, or pages left available after deletions? SQLite 3.54.0, released on October 9, 2026, brings a tool for answering that question into its command-line shell. The new .diskused command replaces the separate sqlite3_analyzer utility, which the project has deprecated.

For developers maintaining local applications or small services, the useful change is a shorter path from noticing growth to finding which database objects account for it. It is an inspection tool, not a cleanup command—and its availability in the shell does not mean it is automatically available inside an application.

Start with a snapshot, not a cleanup

Use a consistent database snapshot for an initial investigation. SQLite’s Online Backup API can copy a live database incrementally and produces a consistent snapshot when it completes. Prefer tooling built around that API over casually copying a database file while the application is writing to it.

Preserve the pre-cleanup state. VACUUM INTO creates a compacted copy, so it is useful for a different purpose: it changes the space layout you are trying to investigate. An ordinary backup gives you a better starting point for comparing storage before and after a proposed change.

With a snapshot saved as app-snapshot.db, run the following using the SQLite 3.54 command-line tool:

The extension documentation describes this command as the preferred way to obtain a complete space-utilization analysis. Internally, it calls SELECT diskused('main'); and displays the returned text.

Read the report as evidence, not a verdict

The CLI documentation explains that the output includes a human-readable report inside a SQL comment, plus SQL for a space_used table. You can read the report directly or load the generated SQL into a separate analysis database to query its figures. Keep that analysis database separate from the application snapshot.

Use the breakdown to choose the next question. If a table dominates, review what it stores and whether its retention rules match the product’s needs. If indexes dominate, investigate the queries they support before removing anything. A large index is not, by itself, evidence of a bad index.

Deletion also needs careful interpretation. With auto_vacuum disabled, SQLite keeps unused pages on a freelist and reuses them for later inserts; the database file does not shrink. PRAGMA freelist_count; reports the number of unused pages. Those pages are not necessarily a leak or an urgent reason to rewrite the file.

The shell and your application are different builds

The diskused() function is built into the CLI but is not included in sqlite3.c, SQLite’s amalgamation. According to the implementation notes, third-party applications need to compile the extension separately and load it through sqlite3_load_extension(). It also requires a SQLite build with SQLITE_ENABLE_DBSTAT_VTAB enabled.

That makes upgrading a diagnostic shell a different task from adding the function to an embedded runtime. Check the application’s actual build before promising an in-app storage dashboard. A successful command in a terminal does not establish that the same SQL function exists in a language binding or packaged application.

Do not confuse diagnosis with reclamation

VACUUM rebuilds the database and can reclaim unused space, but it has operational costs. SQLite documents a requirement for as much as twice the original database size in free disk space. It is a write operation, can fail when locks prevent writes, and may change row IDs in tables without an explicit INTEGER PRIMARY KEY. Plan and test it as maintenance, not as an automatic response to an alert.

Also inspect which file is actually growing. In WAL mode, committed changes can reside in a separate -wal file. Long-running readers can stop checkpoint progress. A table-and-index report is therefore not a complete explanation for a large application directory; WAL growth calls for an investigation of transactions and checkpointing.

The practical starting point is modest: capture a consistent snapshot, record the report, and form a specific hypothesis before changing retention, indexes, or maintenance policy. SQLite 3.54 makes the measurement easier to obtain. Deciding whether the measured space is waste still requires understanding the workload.