Update MotherDuck docs for non-superuser functionality (#362)

docs/functions.md

@@ -190,4 +190,29 @@ TODO
 
 #### <a name="force_motherduck_sync"></a>`duckdb.force_motherduck_sync(drop_with_cascade BOOLEAN DEFAULT false)`
 
-This is a procedure, so usage is `CALL`. This is mostly meant for debugging the automatic synchronization of MotherDuck tables, not for general use. If for some reason the synchronization is not working, you can use this to force a full resync of all MotherDuck databases and schemas to Postgres.
+WARNING: There are known issues with this function currently. For now you
+should use the following command to retrigger a sync:
+
+```
+select * from pg_terminate_backend((select pid from pg_stat_activity where backend_type = 'pg_duckdb sync worker'));
+```
+
+`pg_duckdb` will normally automatically synchronize your MotherDuck tables with Postgres using a Postgres background worker. Sometimes this synchronization fails. This can happen for various reasons, but often this is due to permission issues or users having created dependencies on MotherDuck tables that need to be updated. In those cases this function can be helpful for a few reasons:
+
+1. To show the ERRORs that happen during syncing
+2. To retrigger a sync after fixing the issue
+3. To drop the MotherDuck tables with `CASCADE` to drop all objects that depend on it.
+
+For the first two usages you can simply call this procedure like follows:
+
+```sql
+CALL duckdb.force_motherduck_sync();
+```
+
+But for the third usage you need to run pass it the `drop_with_cascade` parameter:
+
+```sql
+CALL duckdb.force_motherduck_sync(drop_with_cascade := true);
+```
+
+NOTE: Dropping with cascade will drop all objects that depend on the MotherDuck tables. This includes all views, functions, and tables that depend on the MotherDuck tables. This can be a destructive operation, so use with caution.

docs/motherduck.md

@@ -20,6 +20,28 @@ If you installed `pg_duckdb` in a different Postgres database than the default o
 duckdb.motherduck_postgres_database = 'your_database_name'
 ```
 
+### Non-supersuer configuration
+
+If you want to use MotherDuck as a different user than a superuser you also have to configure:
+
+```ini
+duckdb.postgres_role = 'your_role_name'  # e.g. duckdb or duckdb_group
+```
+
+You also likely want to make sure that this role has `CREATE` permissions on the `public` schema in Postgres, because this is where the tables in the `main` schema are created in. You can grant these permissions as follows:
+
+```sql
+GRANT CREATE ON SCHEMA public TO {your_role_name};
+-- So if you've configured the duckdb role above
+GRANT CREATE ON SCHEMA public TO duckdb;
+```
+
+If you do this after starting postgres the initial sync of MotherDuck tables will probably have failed for the public schema. You can force a full resync of the tables by running:
+
+```sql
+select * from pg_terminate_backend((select pid from pg_stat_activity where backend_type = 'pg_duckdb sync worker'));
+```
+
 ## Using `pg_duckdb` with MotherDuck
 
 After doing the configuration (and possibly restarting Postgres). You can then you create tables in the MotherDuck database by using the `duckdb` [Table Access Method][tam] like this: