docs: revise docs

querybook/README.md

@@ -257,14 +257,37 @@ Admin users can:
 4. Configure settings:
 
    ```plain
-   Name: Trino Iceberg
+   Name: Trino
    Metastore Loader: SqlAlchemyMetastoreLoader
-   Connection String: trino://trino.example.com:443/iceberg?SSL=true
+   Connection String: trino://admin:<password>@trino.example.com:443/iceberg?SSL=true
-   Username: admin
-   Password: [from just trino::admin-password]
    ```
 
-5. Link the Metastore to your Query Engine (Admin → Query Engines → Edit → Metastore)
+   **Important**: The Connection String must include username and password embedded in the URL format: `trino://username:password@host:port/catalog?SSL=true`
+
+5. Configure Connect_args section:
+
+   ```plain
+   Key: http_scheme
+   Value: https
+   ```
+
+   This setting ensures proper HTTPS connection handling for the Metastore loader.
+
+6. Enable Impersonate option:
+
+   ```plain
+   Impersonate: ON
+   ```
+
+   This ensures metadata is fetched as the logged-in user, consistent with query execution behavior. Each user will see tables and schemas they have access to.
+
+7. Link the Metastore to your Query Engine (Admin → Query Engines → Edit → Metastore)
+
+Trino admin password can be retrieved with:
+
+```bash
+just trino::admin-password
+```
 
 **Features**:
 
@@ -425,7 +448,7 @@ kubectl get pods -n querybook
 
 - **Metastore not loading tables**:
     - Verify Metastore configuration: Admin → Metastores → Edit
-    - Check connection string includes catalog: `trino://host:443/iceberg?SSL=true`
+    - Check connection string includes catalog: `trino://admin:password@host:443/iceberg?SSL=true`
     - Test Trino connection with admin credentials
     - Check worker pod logs for errors: `just querybook::logs worker`
 

trino/README.md

@@ -197,70 +197,11 @@ See [MCP.md](./MCP.md) for detailed instructions on integrating Trino with Claud
 
 ### Metabase Integration
 
-Metabase connects to Trino using the JDBC driver (Starburst driver). You must use the external hostname with SSL/TLS for authenticated connections.
+For detailed Metabase integration instructions, see [Metabase README](../metabase/README.md).
-
-#### Connection Configuration
-
-1. In Metabase, go to Admin → Databases → Add database
-2. Select **Database type**: Starburst
-3. Configure connection:
-
-    ```plain
-    Host: your-trino-host (e.g., trino.example.com)
-    Port: 443
-    Username: admin
-    Password: [from just trino::admin-password]
-    Catalog: postgresql  (or iceberg for Iceberg tables)
-    SSL: Yes
-    ```
-
-#### Catalog Selection
-
-- Use `postgresql` to query PostgreSQL database tables
-- Use `iceberg` to query Iceberg tables via Lakekeeper
-- You can create multiple Metabase connections, one for each catalog
 
 ### Querybook Integration
 
-#### Connection Configuration
+For detailed Querybook integration instructions, see [Querybook README](../querybook/README.md).
-
-1. In Querybook, create a new Environment and Query Engine
-2. Configure the Trino connection:
-
-    ```plain
-    Connection String: trino://your-trino-host:443?SSL=true
-    Username: admin
-    Password: [from just trino::admin-password]
-    Catalog: postgresql  (or iceberg for Iceberg tables)
-    ```
-
-3. Optional: Configure `Proxy_user_id` to enable user impersonation
-
-#### User Impersonation
-
-Querybook can execute queries as logged-in users via Trino's impersonation feature. Trino is configured with file-based access control that allows the `admin` user to impersonate any user.
-
-**Benefits:**
-
-- Querybook connects as `admin` but executes queries as the actual logged-in user
-- Proper query attribution and audit logging
-- User-specific access control (when configured)
-
-The impersonation rules are defined in `trino-values.gomplate.yaml`:
-
-```json
-{
-  "catalogs": [{"allow": "all"}],
-  "impersonation": [
-    {
-      "original_user": "admin",
-      "new_user": ".*"
-    }
-  ]
-}
-```
-
-See the [Access Control](#access-control) section for detailed impersonation configuration.
 
 ### External Hostname Requirement
 
@@ -601,26 +542,6 @@ accessControl:
 4. Query executes with `actual_username` as the principal
 5. Audit logs show `actual_username`, not `admin`
 
-#### Example: Querybook Integration
-
-```python
-# Querybook connects to Trino
-connection = trino.dbapi.connect(
-    host="trino.example.com",
-    port=443,
-    user="admin",           # Authenticate as admin
-    http_scheme="https",
-    auth=trino.auth.BasicAuthentication("admin", "password")
-)
-
-# Execute query as logged-in user
-cursor = connection.cursor()
-cursor.execute("SELECT * FROM iceberg.sales",
-               http_headers={"X-Trino-User": "alice@example.com"})
-```
-
-Result: Query runs as `alice@example.com`, appears in Trino logs as executed by `alice@example.com`.
-
 **Use Cases:**
 
 - **Querybook/BI Tools**: Single admin connection, multi-user attribution