Merge pull request #7566 from segmentio/retl-instructions

improve RETL setup instructions

Author: forstisabella

src/connections/reverse-etl/reverse-etl-source-setup-guides/databricks-setup.md

@@ -12,24 +12,26 @@ At a high level, when you set up Databricks for Reverse ETL, the configured serv
 ## Required permissions
 * Make sure the service principal you use to connect to Segment has permissions to use that warehouse. In the Databricks console go to **SQL warehouses** and select the warehouse you're using. Navigate to **Overview > Permissions** and make sure the service principal you use to connect to Segment has *can use* permissions.
 
+Note the Service Principal UUID from the [User Management Page](https://accounts.cloud.databricks.com/user-management/serviceprincipals/){:target="_blank”} (under Service Principals) for the following SQL operations.
+
 * To grant access to read data from the tables used in the model query, run: 
 
     ```
-    GRANT USAGE ON SCHEMA <schema_name> TO `<service principal you are using to connect to Segment>`; 
-    GRANT SELECT, READ_METADATA ON SCHEMA <schema_name> TO `<service principal you are using to connect to Segment>`; 
+    GRANT USAGE ON SCHEMA <schema_name> TO `<service principal ID you are using to connect to Segment>`; 
+    GRANT SELECT, READ_METADATA ON SCHEMA <schema_name> TO `<service principal ID you are using to connect to Segment>`; 
     ```
 
 * To grant Segment access to create a schema to keep track of the running syncs, run: 
 
     ```
-    GRANT CREATE on catalog <name of the catalog, usually hive_metastore or main if using unity-catalog> TO `<service principal you are using to connect to Segment>`;
+    GRANT CREATE on catalog <name of the catalog, usually hive_metastore or main if using unity-catalog> TO `<service principal ID you are using to connect to Segment>`;
     ```
 
 * If you want to create the schema yourself instead and then give Segment access to it, run:
 
     ```
     CREATE SCHEMA IF NOT EXISTS __segment_reverse_etl; 
-    GRANT ALL PRIVILEGES ON SCHEMA __segment_reverse_etl TO `<service principal you are using to connect to Segment>`;
+    GRANT ALL PRIVILEGES ON SCHEMA __segment_reverse_etl TO `<service principal ID you are using to connect to Segment>`;
     ```
 
 ## Set up guide

src/connections/reverse-etl/reverse-etl-source-setup-guides/postgres-setup.md

@@ -31,6 +31,15 @@ To set up Postgres with Reverse ETL:
 
     -- allows the "segment" user to create new schemas on the specified database. (this is the name you chose when provisioning your cluster) 
     GRANT CREATE ON DATABASE "<enter database name here>" TO "segment";
+   
+    -- create Segment schema
+    CREATE SCHEMA __segment_reverse_etl;
+   
+    -- Allow user to use the Segment schema
+    GRANT USAGE ON SCHEMA __segment_reverse_etl TO segment;
+
+    -- Grant all privileges on all existing tables in the Segment schema
+    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA __segment_reverse_etl TO segment;
     ```
 4. Make sure the user has correct access permissions to the database.
 5. Follow the steps listed in the [Add a source](/docs/connections/reverse-etl/setup/#step-1-add-a-source) section to finish adding Postgres as a source. 

src/connections/reverse-etl/reverse-etl-source-setup-guides/redshift-setup.md

@@ -15,12 +15,21 @@ To set up Redshift with Reverse ETL:
 2. Follow the [networking instructions](/docs/connections/storage/catalog/redshift/#networking) to configure the correct network and security settings. 
 3. Run the SQL commands below to create a user named `segment`. 
 
-    ```ts
+    ```sql
     -- create a user named "segment" that Segment will use when connecting to your Redshift cluster.
     CREATE USER segment PASSWORD '<enter password here>';
 
     -- allows the "segment" user to create new schemas on the specified database. (this is the name you chose when provisioning your cluster)
     GRANT CREATE ON DATABASE "<enter database name here>" TO "segment";
+    
+    -- create Segment schema
+    CREATE SCHEMA __segment_reverse_etl;
+   
+    -- Allow user to use the Segment schema
+    GRANT USAGE ON SCHEMA __segment_reverse_etl TO segment;
+
+    -- Grant all privileges on all current tables in the Segment schema
+    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA __segment_reverse_etl TO segment;
     ```
 4. Follow the steps listed in the [Add a source](/docs/connections/reverse-etl/setup/#step-1-add-a-source) section to finish adding Redshift as your source.
 

src/connections/reverse-etl/reverse-etl-source-setup-guides/snowflake-setup.md

@@ -55,6 +55,7 @@ Follow the instructions below to set up the Segment Snowflake connector. Segment
    -- database access
    GRANT USAGE ON DATABASE segment_reverse_etl TO ROLE segment_reverse_etl;
    GRANT CREATE SCHEMA ON DATABASE segment_reverse_etl TO ROLE segment_reverse_etl;
+   GRANT CREATE TABLE ON SCHEMA __segment_reverse_etl TO ROLE segment_reverse_etl;
    ```
 6. Enter and run one of the following code snippets below to create the user Segment uses to run queries. For added security, Segment recommends creating a user that authenticates using a key pair.