docs: reformat all FDW documentation (#384)

* docs: reformat documentation for all FDW services - Add consistent Operations, Usage, and Notes sections - Preserve all technical content and functionality - Improve documentation structure and readability - Follow stripe.md template format Fixes #383 Co-Authored-By: [email protected] <[email protected]> * docs: reformat stripe.md documentation to match accounts template Co-Authored-By: [email protected] <[email protected]> * docs instructions * docs: standardize preparation sections across all FDW documentation Co-Authored-By: [email protected] <[email protected]> * docs: restore Query Pushdown Support sections Co-Authored-By: [email protected] <[email protected]> * small re-ordering * docs: add missing sections * update CONTRIBUTING.md --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: [email protected] <[email protected]> Co-authored-by: Copple <[email protected]> Co-authored-by: Bo Lu <[email protected]> Co-authored-by: Bo Lu <[email protected]>
supabase · Dec 16, 2024 · 032e303 · 032e303
1 parent a8db572
commit 032e303
Show file tree

Hide file tree

Showing 18 changed files with 1,903 additions and 892 deletions.
diff --git a/.gitignore b/.gitignore
@@ -16,3 +16,4 @@ cmake*/
 results/
 wrappers/results/
 wrappers/regression.*
+.venv/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,4 @@
+# Contributing
+
+Any contributions to wrappers are welcome, please visit https://fdw.dev/contributing/core/ for more details.
+
diff --git a/docs/catalog/airtable.md b/docs/catalog/airtable.md
@@ -19,23 +19,29 @@ The Airtable Wrapper allows you to read data from your Airtable bases/tables wit
 
 ## Preparation
 
-Before you get started, make sure the `wrappers` extension is installed on your database:
+Before you can query Airtable, you need to enable the Wrappers extension and store your credentials in Postgres.
+
+### Enable Wrappers
+
+Make sure the `wrappers` extension is installed on your database:
 
 ```sql
 create extension if not exists wrappers with schema extensions;
 ```
 
-and then create the foreign data wrapper:
+### Enable the Airtable Wrapper
+
+Enable the `airtable_wrapper` FDW:
 
 ```sql
 create foreign data wrapper airtable_wrapper
   handler airtable_fdw_handler
   validator airtable_fdw_validator;
 ```
 
-### Secure your credentials (optional)
+### Store your credentials (optional)
 
-By default, Postgres stores FDW credentials inide `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
+By default, Postgres stores FDW credentials inside `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
 
 ```sql
 -- Save your Airtable API key in Vault and retrieve the `key_id`
@@ -72,7 +78,15 @@ We need to provide Postgres with the credentials to connect to Airtable, and any
       );
     ```
 
-## Creating Foreign Tables
+### Create a schema
+
+We recommend creating a schema to hold all the foreign tables:
+
+```sql
+create schema if not exists airtable;
+```
+
+## Entities
 
 The Airtable Wrapper supports data reads from the Airtable API.
 
@@ -82,14 +96,14 @@ The Airtable Wrapper supports data reads from Airtable's [Records](https://airta
 
 #### Operations
 
-| Airtable | Select | Insert | Update | Delete | Truncate |
-| -------- | :----: | :----: | :----: | :----: | :------: |
-| Records  |   ✅   |   ❌   |   ❌   |   ❌   |    ❌    |
+| Object  | Select | Insert | Update | Delete | Truncate |
+| ------- | :----: | :----: | :----: | :----: | :------: |
+| Records |   ✅    |   ❌    |   ❌    |   ❌    |    ❌     |
 
 #### Usage
 
 ```sql
-create foreign table my_foreign_table (
+create foreign table airtable.my_foreign_table (
   name text
   -- other fields
 )
@@ -100,28 +114,23 @@ options (
 );
 ```
 
-#### Options
+#### Notes
 
-The full list of foreign table options are below:
-
-- `base_id` - Airtable Base ID the table belongs to, required.
-- `table_id` - Airtable table ID, required.
-- `view_id` - Airtable view ID, optional.
+- The table requires both `base_id` and `table_id` options
+- Optional `view_id` can be specified to query a specific view
 
 ## Query Pushdown Support
 
 This FDW doesn't support query pushdown.
 
 ## Examples
 
-Some examples on how to use Airtable foreign tables.
-
 ### Query an Airtable table
 
 This will create a "foreign table" inside your Postgres database called `airtable_table`:
 
 ```sql
-create foreign table airtable_table (
+create foreign table airtable.airtable_table (
   name text,
   notes text,
   content text,
@@ -138,15 +147,15 @@ options (
 You can now fetch your Airtable data from within your Postgres database:
 
 ```sql
-select * from airtable_table;
+select * from airtable.airtable_table;
 ```
 
 ### Query an Airtable view
 
 We can also create a foreign table from an Airtable View called `airtable_view`:
 
 ```sql
-create foreign table airtable_view (
+create foreign table airtable.airtable_view (
   name text,
   notes text,
   content text,
@@ -164,5 +173,5 @@ options (
 You can now fetch your Airtable data from within your Postgres database:
 
 ```sql
-select * from airtable_view;
+select * from airtable.airtable_view;
 ```
diff --git a/docs/catalog/auth0.md b/docs/catalog/auth0.md
@@ -19,23 +19,29 @@ The Auth0 Wrapper allows you to read data from your Auth0 tenant for use within
 
 ## Preparation
 
-Before you get started, make sure the `wrappers` extension is installed on your database:
+Before you can query Auth0, you need to enable the Wrappers extension and store your credentials in Postgres.
+
+### Enable Wrappers
+
+Make sure the `wrappers` extension is installed on your database:
 
 ```sql
 create extension if not exists wrappers with schema extensions;
 ```
 
-and then create the foreign data wrapper:
+### Enable the Auth0 Wrapper
+
+Enable the `auth0_wrapper` FDW:
 
 ```sql
 create foreign data wrapper auth0_wrapper
   handler auth0_fdw_handler
   validator auth0_fdw_validator;
 ```
 
-### Secure your credentials (optional)
+### Store your credentials (optional)
 
-By default, Postgres stores FDW credentials inide `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
+By default, Postgres stores FDW credentials inside `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
 
 ```sql
 -- Save your Auth0 API key in Vault and retrieve the `key_id`
@@ -73,47 +79,57 @@ We need to provide Postgres with the credentials to connect to Airtable, and any
     );
     ```
 
-## Creating Foreign Tables
+### Create a schema
+
+We recommend creating a schema to hold all the foreign tables:
+
+```sql
+create schema if not exists auth0;
+```
+
+## Entities
+
+The Auth0 Wrapper supports data reads from Auth0 API.
+
+### Users
 
 The Auth0 Wrapper supports data reads from Auth0's [Management API List users endpoint](https://auth0.com/docs/api/management/v2/users/get-users) endpoint (_read only_).
 
-| Auth0   | Select | Insert | Update | Delete | Truncate |
-| ------- | :----: | :----: | :----: | :----: | :------: |
-| Records |   ✅   |   ❌   |   ❌   |   ❌   |    ❌    |
+#### Operations
+
+| Object | Select | Insert | Update | Delete | Truncate |
+| ------ | :----: | :----: | :----: | :----: | :------: |
+| Users  |   ✅    |   ❌    |   ❌    |   ❌    |    ❌     |
 
-For example:
+#### Usage
 
 ```sql
-create foreign table my_foreign_table (
+create foreign table auth0.my_foreign_table (
   name text
   -- other fields
 )
 server auth0_server
 options (
-  object 'users',
+  object 'users'
 );
 ```
 
-### Foreign table options
+#### Notes
 
-The full list of foreign table options are below:
-
-- `objects` - Auth0 object to select from. Currently only supports `users`
+- Currently only supports the `users` object
 
 ## Query Pushdown Support
 
 This FDW doesn't support query pushdown.
 
 ## Examples
 
-Some examples on how to use Auth0 foreign tables.
-
-### Basic example
+### Basic Auth0 Users Query
 
-This will create a "foreign table" inside your Postgres database called `auth0_table`:
+This example demonstrates querying Auth0 users data.
 
 ```sql
-create foreign table auth0_table (
+create foreign table auth0.auth0_table (
   created_at text,
   email text,
   email_verified bool,
@@ -123,11 +139,10 @@ create foreign table auth0_table (
   options (
     object 'users'
   );
-
 ```
 
 You can now fetch your Auth0 data from within your Postgres database:
 
 ```sql
-select * from auth0;
+select * from auth0.auth0_table;
 ```
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		# Contributing

		Any contributions to wrappers are welcome, please visit https://fdw.dev/contributing/core/ for more details.