improve publication-related docs for Postgres

Author: jgao54

docs/integrations/data-ingestion/clickpipes/postgres/faq.md

@@ -180,7 +180,7 @@ These adjustments should significantly enhance the performance of the initial lo
 
 ### How should I scope my publications when setting up replication? {#how-should-i-scope-my-publications-when-setting-up-replication}
 
-You can let ClickPipes manage your publications (requires additional permissions) or create them yourself. With ClickPipes-managed publications, we automatically handle table additions and removals as you edit the pipe. If self-managing, carefully scope your publications to only include tables you need to replicate - including unnecessary tables will slow down Postgres WAL decoding.
+We don't recommend creating a publication `FOR ALL TABLES`, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe). This will slow down Postgres WAL decoding and reduce overall efficiency.
 
 If you include any table in your publication, make sure it has either a primary key or `REPLICA IDENTITY FULL`. If you have tables without a primary key, creating a publication for all tables will cause DELETE and UPDATE operations to fail on those tables.
 
@@ -213,9 +213,7 @@ You have two options when dealing with tables without primary keys:
    ```
 
 :::tip
-If you're creating a publication manually instead of letting ClickPipes manage it, we don't recommend creating a publication `FOR ALL TABLES`, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
-
-For manually created publications, please add any tables you want to the publication before adding them to the pipe.
+Alternatively, ClickPipes can manage publications on your behalf, automatically handling table additions and removals as you modify the pipe. Note that this requires the database user to have both the `CREATE` permission on the database and ownership of the replicated tables, meaning the user cannot be configured with read-only access.
 :::
 
 :::warning

docs/integrations/data-ingestion/clickpipes/postgres/source/aurora.md

@@ -91,9 +91,17 @@ Connect to your Aurora PostgreSQL writer instance as an admin user and execute t
 4. Create a publication for replication:
 
     ```sql
-    CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+    CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
     ```
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 ## Configure network access {#configure-network-access}
 
 ### IP-based access control {#ip-based-access-control}

docs/integrations/data-ingestion/clickpipes/postgres/source/azure-flexible-server-postgres.md

@@ -60,9 +60,17 @@ Connect to your Azure Flexible Server Postgres through the admin user and run th
 4. Create publication that you'll be using for creating the MIRROR (replication) in future.
 
    ```sql
-   CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+   CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
    ```
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 5. Set `wal_sender_timeout` to 0 for `clickpipes_user`
 
    ```sql

docs/integrations/data-ingestion/clickpipes/postgres/source/crunchy-postgres.md

@@ -52,9 +52,17 @@ Connect to your Crunchy Bridge Postgres through the `postgres` user and run the
 4. Create publication that you'll be using for creating the MIRROR (replication) in future.
 
     ```sql
-    CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+    CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
     ```
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 ## Safe list ClickPipes IPs {#safe-list-clickpipes-ips}
 
 Safelist [ClickPipes IPs](../../index.md#list-of-static-ips) by adding the Firewall Rules in Crunchy Bridge.

docs/integrations/data-ingestion/clickpipes/postgres/source/generic.md

@@ -68,14 +68,22 @@ For this, you can connect to your Postgres instance and run the following SQL co
   ALTER USER clickpipes_user REPLICATION;
 
 -- Create a publication. We will use this when creating the pipe
-  CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+  CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
 ```
 :::note
 
 Make sure to replace `clickpipes_user` and `clickpipes_password` with your desired username and password.
 
 :::
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 ## Enabling connections in pg_hba.conf to the ClickPipes User {#enabling-connections-in-pg_hbaconf-to-the-clickpipes-user}
 
 If you are self serving, you need to allow connections to the ClickPipes user from the ClickPipes IP addresses by following the below steps. If you are using a managed service, you can do the same by following the provider's documentation.

docs/integrations/data-ingestion/clickpipes/postgres/source/google-cloudsql.md

@@ -70,9 +70,17 @@ Connect to your Cloud SQL Postgres through the admin user and run the below comm
 4. Create publication that you'll be using for creating the MIRROR (replication) in future.
 
    ```sql
-   CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+   CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
    ```
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 [//]: # (TODO Add SSH Tunneling)
 
 ## Add ClickPipes IPs to Firewall {#add-clickpipes-ips-to-firewall}

docs/integrations/data-ingestion/clickpipes/postgres/source/neon-postgres.md

@@ -37,8 +37,15 @@ Here, we can run the following SQL commands:
   ALTER USER clickpipes_user REPLICATION;
 
 -- Create a publication. We will use this when creating the mirror
-  CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+  CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
 ```
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
 
 <Image size="lg" img={neon_commands} alt="User and publication commands" border/>
 

docs/integrations/data-ingestion/clickpipes/postgres/source/planetscale.md

@@ -69,6 +69,14 @@ For this, you can connect to your PlanetScale Postgres instance using the defaul
 Make sure to replace `clickpipes_user` and `clickpipes_password` with your desired username and password.
 :::
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 ## Caveats {#caveats}
 1. To connect to PlanetScale Postgres, the current branch needs to be appended to the username created above. For example, if the created user was named `clickpipes_user`, the actual user provided during the ClickPipe creation needs to be `clickpipes_user`.`branch` where `branch` refers to the "id" of the current PlanetScale Postgres [branch](https://planetscale.com/docs/postgres/branching). To quickly determine this, you can refer to the username of the `postgres` user you used to create the user earlier, the part after the period would be the branch id.
 2. Do not use the `PSBouncer` port (currently `6432`) for CDC pipes connecting to PlanetScale Postgres, the normal port `5432` must be used. Either port may be used for initial-load only pipes.

docs/integrations/data-ingestion/clickpipes/postgres/source/rds.md

@@ -91,9 +91,17 @@ Connect to your RDS Postgres instance as an admin user and execute the following
 4. Create a publication for replication:
 
     ```sql
-    CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+    CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
     ```
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 ## Configure network access {#configure-network-access}
 
 ### IP-based access control {#ip-based-access-control}

docs/integrations/data-ingestion/clickpipes/postgres/source/supabase.md

@@ -38,9 +38,17 @@ Here, we can run the following SQL commands:
   ALTER USER clickpipes_user REPLICATION;
 
 -- Create a publication. We will use this when creating the mirror
-  CREATE PUBLICATION clickpipes_publication FOR ALL TABLES;
+  CREATE PUBLICATION clickpipes_publication FOR TABLE <...>, <...>;
 ```
 
+:::tip
+We don't recommend creating a publication `FOR ALL TABLES` unless you are replicating all tables, this leads to more traffic from Postgres to ClickPipes (to sending changes for other tables not in the pipe) and reduces overall efficiency.
+:::
+
+:::note
+ClickPipes can automatically create and manage the publication on your behalf. However, this requires granting the ClickPipes user both table ownership and the `CREATE` permission on the database. If you prefer read-only access for the ClickPipes user, we recommend creating and managing the publication manually.
+:::
+
 <Image img={supabase_commands} alt="User and publication commands" size="large" border/>
 
 Click on **Run** to have a publication and a user ready.