Why and how to mark_tables_colocated (#280)

admin_guide/upgrading_citus.rst

@@ -72,6 +72,11 @@ After installing the new package, run the extension upgrade script:
   psql -c '\dx'
   # you should see the newer Citus version in the list
 
+Step 3. (upgrade from 5.x only) Add Co-Location Metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When doing a major upgrade from Citus 5.x be sure to create metadata for your implicit table co-location. Read more about that in the :ref:`marking_colocation` section of the co-location page.
+
 .. _upgrading_postgres:
 
 Upgrading PostgreSQL version from 9.5 to 9.6

dist_tables/ddl.rst

@@ -129,6 +129,24 @@ To co-locate a number of tables, distribute one and then put the others into its
 
 Information about co-location groups is stored in the :ref:`pg_dist_colocation <colocation_group_table>` table, while :ref:`pg_dist_partition <partition_table>` reveals which tables are assigned to which groups.
 
+.. _marking_colocation:
+
+Upgrading from Citus 5.x
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting with Citus 6.0, we made co-location a first-class concept, and started tracking tables' assignment to co-location groups in pg_dist_colocation. Since Citus 5.x didn't have this concept, tables created with Citus 5 were not explicitly marked as co-located in metadata, even when the tables were physically co-located.
+
+Since Citus uses co-location metadata information for query optimization and pushdown, it becomes critical to inform Citus of this co-location for previously created tables. To fix the metadata, simply mark the tables as co-located:
+
+.. code-block:: postgresql
+
+  -- Assume that stores, products and line_items were created in a Citus 5.x database.
+
+  -- Put products and line_items into store's co-location group
+  SELECT mark_tables_colocated('stores', ARRAY['products', 'line_items']);
+
+This function requires the tables to be distributed with the same method, column type, number of shards, and replication method. It doesn't re-shard or physically move data, it merely updates Citus metadata.
+
 Dropping Tables
 ---------------