How much a pipeline will move, before you create it
Before a PostgreSQL pipeline exists, its connection test can tell you how much its tables weigh and how fast they change: the volume its first copy reads, and the volume its changes add each day after. Everything is read from the statistics your database already keeps, so nothing is scanned or counted on your tables to draw it, and every figure is an estimate, labelled with what it was read from.
There is no price in it. What a pipeline costs depends on the work it does, which this forecast does not measure; your usage page shows what each pipeline really used once it runs.
Asking for it
Section titled “Asking for it”Name the tables in catalogue_forecast on POST /v1/connections/test (at most 1,000, each once),
with the source as you would test it. A list whose names together are too long to hand the test in
one go is refused in words; ask about fewer tables at a time. The answer’s catalogue.forecast holds,
per table:
| Figure | What it is | Read from |
|---|---|---|
disk_bytes |
The table, its TOAST and its indexes, on disk at your source now | pg_total_relation_size |
disk_bytes_without_indexes |
The rows a first copy reads, on disk at your source | pg_table_size |
rows |
About how many rows it holds | the planner’s estimate, pg_class.reltuples |
changes_counted |
Rows inserted, updated and deleted since the counters began, attempted ones: rolled-back changes are counted too, so this is an upper figure | the counters behind pg_stat_all_tables (n_tup_ins + n_tup_upd + n_tup_del) |
changes_per_day |
That count averaged over the whole window the counters cover | the window in changes |
A partitioned table’s figures are its partitions’ summed. total sums the named tables, and is
given only when every one of them was read: a total that left a table out would be too small, and
would not say so. Each figure in it is given only when every table has it.
Reading the figures costs the same however many tables your database holds: only the tables you name are read, never a view over every table. One check of the whole catalogue remains, for a partial statistics reset (below), and it is made only when your database has recorded a reset; it stops at the first table that shows one.
log is the whole server’s write-ahead log, as pg_stat_wal counts it, averaged per day. It covers
every database on the server, indexes and maintenance included, so it is more than these tables’
changes; it is what a replication slot reads.
What “unknown” looks like
Section titled “What “unknown” looks like”A figure we cannot know is absent, never 0, and a field beside it says why:
rows_why: never_analyzed. The table, or one of its partitions, has never been analysed, so your database has no estimate. A table you have just bulk-loaded is in this state, and may be your largest; runningANALYZEon it gives it one.rows_why: estimate_is_stale. The estimate is 0 while the table has pages on disk. That is how PostgreSQL 13 and earlier spell “never analysed”, and what a table analysed while empty and loaded since keeps.ANALYZEgives it a real one.why: not_foundornot_readable. Nothing of that name, or the source’s role may notSELECTit (so a pipeline could not copy it either).why: not_a_table, withkind. The name holds aview, amaterialized_view, aforeign_table(its rows live on another server) or somethingother(a sequence, say). A query-based pipeline syncs a view or a materialized view picked with its key columns, reading it whole at every sync, so what it moves is what its query returns each time: your database keeps no statistic of that, so no figure is given. Name the tables the view reads to see theirs.bytes_why: foreign_partition. A partition is a foreign table, whose rows live on another server.changes.whysays why there is no per-day rate for any table:counting_start_not_recorded: your database did not record when its counters began. On PostgreSQL 15 and later that is the case until its statistics are first reset, and again after a crash. The counts are still given. We do not suggest resetting them: that also resets what your autovacuum reads to decide when to run.window_shorter_than_a_day: the counters began less than a day ago. A rate over a shorter window would be a sample of part of a day, not a day’s average.standby: you tested a standby, which counts none of the primary’s writes. Test the primary.counts_off:track_countsis off, so nothing is counted.promoted_since_counting_began: the server was a standby for part of the window and counted none of the changes then, so an average over it would read low. It is seen when the last change the server replayed is later than the window’s start, or when the window began at or before the server last started (a server that replayed anything since it started was in recovery from that start until its promotion).partial_reset: some table in your database still shows a vacuum or analyse time older than the window, so the last statistics reset was of one table (or one function), not the whole database. The window is then the start of no table but that one, so no rate is stated, and neither is the total’s. The counts are given, each since a start your database did not record. Rarely, the same reason is given after a whole-database reset: when a vacuum or analyse ended at the very moment of the reset, or the server’s clock was stepped back since; it clears once that table is vacuumed or analysed again.
changes_why: counters_older_than_windowon one table: its counters began before the window (it was vacuumed or analysed before the window’s start), so a rate over the window would read high for it. Its count stands, and it too began beforechanges.since: read it as counted since an earlier, unrecorded start, not over the window.log.whyaddsnot_offered: PostgreSQL 13 and earlier have nopg_stat_wal.catalogue.forecast.why:not_read(the statistics could not be read;sqlstatesays how,57014a statement that ran out of time,55P03a lock it waited for too long),timed_out(the test’s time ran out first) ornot_answered. The rest of the test’s answer stands.
What it cannot see
Section titled “What it cannot see”- A rate is an average over the window, not a forecast of your busiest hour. The window is said
in
changes.since,changes.untilandchanges.days. - The window’s start is the whole database’s, and resetting ONE table’s statistics moves it to that
moment. A table whose counters were not reset then has counted for longer than the window, and
reads high. We see such a partial reset when any table in your database still shows a vacuum or
analyse time older than the window, and then withhold every rate (
partial_reset). We cannot see it when no table in your database, PostgreSQL’s own catalogues included, still shows a vacuum or analyse time from before the reset: each has been vacuumed or analysed since, or never has been (for example after a crash, which clears every time). Then a rate can read high. (Corrected 2026-11-16 (IST): this page said only a table never vacuumed or analysed escapes. PostgreSQL keeps only the latest vacuum and analyse times, so a busy table autovacuumed since the reset escaped a check of its own times; the check is now database-wide. Corrected again the same day: the sentence after it said a partial reset is missed only when every table has been vacuumed or analysed since, leaving out the tables that never were.) - A table created after the counters began reads low: it is averaged over days it did not exist. Nothing in PostgreSQL records when a table was created, so this cannot be detected.
- A server promoted from a standby reads low over a window that began before the promotion. We withhold the rate when the promotion can be seen: when the last change the server replayed is later than the window’s start, or when the window began at or before the server last started. It cannot be seen once the server has restarted after its promotion, nor over a window that began after the server started while the last change it replayed is older than that window: for example the log’s counters of a server restored to an earlier point and promoted, which begin as it starts. (Corrected 2026-11-17 (IST): this said only that a restart after the promotion hides it. A standby restarted while its primary was quiet, then promoted, was missed too: the last change it replayed was older than the window. It is seen now, by the server’s start.)
- Bytes on disk are not bytes moved or stored. Indexes are not copied, values cross the network in another form, and your destination stores them in its own.
- The estimate of rows is only as fresh as the last
ANALYZEor autovacuum of the table.