Communication goals (e.g. detailed howto vs orientation)
Citus does not support adding foreign keys between local and distributed tables. It does support distributing the target table for an existing foreign key. It does not allow distributing the source table for an existing foreign key. Thus the easiest way to avoid getting tangled up in dependencies is to distribute all tables first, and add foreign keys later.
Question for SE: have we considered marking the FKs as "NOT VALID" prior to distribution, and running "VALIDATE CONSTRAINT" afterward? That's a pg feature made available in 8.1
Communication goals (e.g. detailed howto vs orientation)
Citus does not support adding foreign keys between local and distributed tables. It does support distributing the target table for an existing foreign key. It does not allow distributing the source table for an existing foreign key. Thus the easiest way to avoid getting tangled up in dependencies is to distribute all tables first, and add foreign keys later.
Good locations for content in docs structure