docs: update quickstart and code comments to explain how to teardown …

…properly (#511)

* docs: update quickstart to explain how to fully tear down

* docs: update function comments about --full command

docs/quickstart.md

@@ -181,9 +181,18 @@ $ belt sync testdatacenter1 database1
 
 ## Step 7: Enable write traffic to the destination host
 
-This is done outside of PgBelt, with your application. Note -- reverse replication will be ongoing until you feel a rollback is unnecessary. To stop reverse replication, simply run the following:
+Enabling write traffic to the destination host is done outside of PgBelt, with your application.
 
-    $ belt teardown-back-replication testdatacenter1 database1
+## Step 8: Teardown pgbelt replication and leftover objects!
+
+Up until this step, reverse replication will be ongoing. It is meant to do this until you feel a rollback is unnecessary. To stop reverse replication, and consider your pgbelt migration **complete**, simply run the following:
+
+    $ belt teardown testdatacenter1 database1
+    $ belt teardown testdatacenter1 database1 --full
+
+The first command will tear down all replication jobs if still running. At this point, you should only have your reverse replication running. It will also tear down all of the pgbelt replication job objects in the database, including the `pglogical` role used by the jobs.
+
+The second command will run through the first command, and finally drop the `pglogical` extension from the database. This is separated out because the extension drop tends to hang if the previous steps are done right beforehand. When run separately, the DROP command likely will run without hanging or run in significantly less time.
 
 # (Optional) Rolling Back
 

pgbelt/cmd/teardown.py

@@ -42,13 +42,13 @@ async def teardown_forward_replication(config_future: Awaitable[DbupgradeConfig]
 @run_with_configs
 async def teardown(
     config_future: Awaitable[DbupgradeConfig],
-    full: bool = Option(False, help="Remove pglogical user and extension"),
+    full: bool = Option(False, help="Remove pglogical extension"),
 ):
     """
     Removes all pglogical configuration from both databases. If any replication is
-    configured this will stop it.
+    configured this will stop it. It will also drop the pglogical user.
 
-    If run with --full the pglogical users and extension will be dropped.
+    If run with --full the pglogical extension will be dropped.
 
     WARNING: running with --full may cause the database to lock up. You should be
     prepared to reboot the database if you do this.