Manage & Flush

Managing a table attaches KoldStore policy and WAL mirror capture. Flushing moves eligible latest-state rows from the hot heap into Parquet and prunes them from PostgreSQL.

Enable management

Prefer named arguments. hot_row_limit is required in the manage_table call — pass NULL for hot-only tables that should not flush.

SQL

1SELECT koldstore.manage_table(2  table_name        => 'chat.messages',3  storage           => 's3_archive',4  hot_row_limit     => 10000,5  min_flush_rows    => 1000,6  max_rows_per_file => 1000,7  auto_flush        => true,8  migration_order_by => 'created_at'9);

Parameter	Default	Meaning
`table_name`	required	Table to manage (`regclass`)
`storage`	required	Registered storage backend name
`hot_row_limit`	required (`NULL` allowed)	Max mirror rows to keep hot
`min_flush_rows`	`1000`	Minimum excess before a policy flush moves data
`max_rows_per_file`	`1000`	Max rows per Parquet segment (floor via `koldstore.min_max_rows_per_file`)
`table_type`	`'shared'`	`shared` or `user` (+ `scope_column`)
`compression`	`NULL`	Optional Parquet codec (`snappy`, `zstd`, `uncompressed`)
`target_file_size_mb`	`NULL`	Stored for future size-aware flush
`auto_flush`	`true`	Let the DB worker evaluate and run needed flushes

ALTER TABLE style

SQL

1ALTER TABLE chat.messages SET (2  koldstore_enabled = true,3  koldstore_storage = 's3_archive',4  koldstore_hot_row_limit = 10000,5  koldstore_min_flush_rows = 1000,6  koldstore_max_rows_per_file = 10007);

Age-based eviction (mutually exclusive with hot_row_limit):

SQL

1ALTER TABLE chat.messages SET (2  koldstore_enabled = true,3  koldstore_storage = 's3_archive',4  koldstore_move_after = '90 days',5  koldstore_min_flush_rows = 1000,6  koldstore_max_rows_per_file = 100007);

Age is measured from the latest captured mirror mutation encoded in seq.

Flush

Policy flush

SQL

1SELECT koldstore.flush_table(table_name => 'chat.messages'::regclass);

Keeps the newest rows hot by mirror seq and flushes oldest eligible excess first, honoring hot_row_limit / min_flush_rows / max_rows_per_file.

Force flush

SQL

1SELECT koldstore.flush_table(2  table_name => 'chat.messages'::regclass,3  force      => true4);

Flushes all pending mirror rows. Use carefully on large tables.

Enqueue without running

SQL

1SELECT koldstore.enqueue_flush_job(2  table_name => 'chat.messages'::regclass,3  force      => false4);

Returns 1 if a job was inserted, 0 if an active flush job already exists. auto_flush does not gate manual flush / enqueue.

Inspect progress

SQL

1SELECT jsonb_pretty(2  koldstore.describe_table(table_name => 'chat.messages'::regclass)3);4 5SELECT koldstore.list_jobs(6  statuses   => '["running","pending"]'::jsonb,7  job_types  => '["flush"]'::jsonb,8  table_name => 'chat.messages'::regclass9);

Useful describe_table fields: hot_rows, mirror_rows, cold_row_count, cold_segment_count, heap/index sizes, manifest_state, pending_jobs, last_error.

Cancel

SQL

1SELECT koldstore.cancel_job(job_id => '…'::uuid);2SELECT koldstore.cancel_table_jobs(table_name => 'chat.messages'::regclass);

Pending jobs cancel immediately when unlocked. Running jobs stop cooperatively at the next wave boundary. If cancel lands after cold publish already committed, the job may finish completed with payload.cancel_requested_after_publish = true (data is not unpublished).

Auto-flush toggle

SQL

1SELECT koldstore.set_table_auto_flush(2  table_name => 'chat.messages'::regclass,3  enabled    => false4);

Manual flush_table still works. See Operations for the built-in worker tick and pg_cron fallback.

Unmanage

SQL

1SELECT koldstore.unmanage_table(2  table_name => 'chat.messages'::regclass,3  rehydrate  => true,4  drop_cold  => false5);

Use this instead of koldstore_enabled = false. Optional rehydrate / drop_cold control whether cold rows return to the heap and whether cold objects are deleted.