Distributed vacuum (#297)

admin_guide/table_management.rst

@@ -0,0 +1,34 @@
+Table Management
+$$$$$$$$$$$$$$$$$$
+
+Vacuuming Distributed Tables
+############################
+
+In PostgreSQL (and other MVCC databases), an UPDATE or DELETE of a row does not immediately remove the old version of the row. The accumulation of outdated rows is called bloat and must be cleaned to avoid decreased query performance and unbounded growth of disk space requirements. PostgreSQL runs a process called the auto-vacuum daemon that periodically vacuums (aka removes) outdated rows.
+
+It’s not just user queries which scale in a distributed database, vacuuming does too. In PostgreSQL big busy tables have great potential to bloat, both from lower sensitivity to PostgreSQL's vacuum scale factor parameter, and generally because of the extent of their row churn. Splitting a table into distributed shards means both that individual shards are smaller tables and that auto-vacuum workers can parallelize over different parts of the table on different machines. Ordinarily auto-vacuum can only run one worker per table.
+
+Due to the above, auto-vacuum operations on a Citus cluster are probably good enough for most cases. However for tables with particular workloads, or companies with certain "safe" hours to schedule a vacuum, it might make more sense to manually vacuum a table rather than leaving all the work to auto-vacuum.
+
+To vacuum a table, simply run this on the coordinator node:
+
+.. code-block:: postgresql
+
+  VACUUM my_distributed_table;
+
+Using vacuum against a distributed table will send a vacuum command to every one of that table's placements (one connection per placement). This is done in parallel. All `options <https://www.postgresql.org/docs/current/static/sql-vacuum.html>`_ are supported (including the :code:`column_list` parameter) except for :code:`VERBOSE`. The vacuum command also runs on the coordinator, and does so before any workers nodes are notified. Note that unqualified vacuum commands (i.e. those without a table specified) do not propagate to worker nodes.
+
+Analyzing Distributed Tables
+############################
+
+PostgreSQL's ANALYZE command collects statistics about the contents of tables in the database. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries.
+
+The auto-vacuum daemon, discussed in the previous section, will automatically issue ANALYZE commands whenever the content of a table has changed sufficiently. The daemon schedules ANALYZE strictly as a function of the number of rows inserted or updated; it has no knowledge of whether that will lead to meaningful statistical changes. Administrators might prefer to manually schedule ANALYZE operations instead, to coincide with statistically meaningful table changes.
+
+To analyze a table, run this on the coordinator node:
+
+.. code-block:: postgresql
+
+  ANALYZE my_distributed_table;
+
+Citus propagates the ANALYZE command to all worker node placements.

index.rst

@@ -74,6 +74,7 @@ topics.
    :caption: Administration
 
    admin_guide/cluster_management.rst
+   admin_guide/table_management.rst
    admin_guide/upgrading_citus.rst
 
 .. toctree::