Clarify the onboarding steps / add docs in OLTP Streamlit

Author: antontruly

docs/docs/streamlit/tables/oltp_database_connect.mdx

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+---
+
+# Connect an OLTP database
+
+This app connects to a [Databricks Lakebase](https://docs.databricks.com/aws/en/oltp/) OLTP database instance. Provide the instance name, database, schema, and table.
+
+## Code snippet
+
+```python title="app.py"
+import uuid
+import streamlit as st
+import pandas as pd
+
+from databricks.sdk import WorkspaceClient
+
+import psycopg
+from psycopg_pool import ConnectionPool
+
+
+w = WorkspaceClient()
+
+
+def _generate_token(instance_name: str) -> str:
+    cred = w.database.generate_database_credential(
+        request_id=str(uuid.uuid4()), instance_names=[instance_name]
+    )
+    return cred.token
+
+    
+class RotatingTokenConnection(psycopg.Connection):
+    @classmethod
+    def connect(cls, conninfo: str = "", **kwargs):
+        instance_name = kwargs.pop("_instance_name")
+        kwargs["password"] = _generate_token(instance_name)
+        kwargs.setdefault("sslmode", "require")
+        return super().connect(conninfo, **kwargs)
+
+        
+@st.cache_resource
+def build_pool(instance_name: str, host: str, user: str, database: str) -> ConnectionPool:
+    return ConnectionPool(
+        conninfo=f"host={host} dbname={database} user={user}",
+        connection_class=RotatingTokenConnection,
+        kwargs={"_instance_name": instance_name},
+        min_size=1,
+        max_size=10,
+        open=True,
+    )
+
+    
+def query_df(pool: ConnectionPool, sql: str) -> pd.DataFrame:
+    with pool.connection() as conn:
+        with conn.cursor() as cur:
+            cur.execute(sql)
+            cols = [d.name for d in cur.description]
+            rows = cur.fetchall()
+
+    return pd.DataFrame(rows, columns=cols)
+
+    
+instance_name = "dbase_instance"
+database = "customer_database"
+table = "customer_core.customers_oltp"
+user = w.current_user.me().user_name
+host = w.database.get_database_instance(name=instance_name).read_write_dns
+
+pool = build_pool(instance_name, host, user, database)
+df = query_df(pool, f'SELECT * FROM {table} LIMIT 100')
+st.dataframe(df)
+```
+
+:::info
+
+This sample uses Streamlit's [st.cache_resource](https://docs.streamlit.io/develop/concepts/architecture/caching#stcache_resource) to cache the database connection across users, sessions, and reruns. Use Streamlit's caching decorators to implement a caching strategy that works for your use case.
+
+:::
+
+## Resources
+
+- [Lakebase](https://docs.databricks.com/aws/en/oltp/) database instance (PostgreSQL).
+- Target PostgreSQL database/schema/table.
+
+## Permissions
+
+First, the database instance should be specified in your [**App resources**](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/resources).
+
+Then, your [app service principal](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/#how-does-databricks-apps-manage-authorization) needs the following permissions:
+
+GRANT CONNECT ON DATABASE databricks_postgres TO "099f0306-9e29-4a87-84c0-3046e4bcea02";
+GRANT USAGE ON SCHEMA public TO "099f0306-9e29-4a87-84c0-3046e4bcea02";
+GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE quotes_history TO "099f0306-9e29-4a87-84c0-3046e4bcea02";
+
+See [this guide](https://docs.databricks.com/aws/en/oltp/pg-roles?language=PostgreSQL#create-postgres-roles-and-grant-privileges-for-databricks-identities) for more information.
+
+[This guide](https://learn.microsoft.com/en-us/azure/databricks/oltp/query/sql-editor#create-a-new-query) shows you how to query your Lakebase.
+
+## Dependencies
+
+- [Databricks SDK](https://pypi.org/project/databricks-sdk/) - `databricks-sdk`
+- [`psycopg[binary]`](https://pypi.org/project/psycopg/), [`psycopg-pool`](https://pypi.org/project/psycopg-pool/)
+- [Pandas](https://pypi.org/project/pandas/) - `pandas`
+- [Streamlit](https://pypi.org/project/streamlit/) - `streamlit`
+
+```python title="requirements.txt"
+databricks-sdk
+databricks-sql-connector
+pandas
+streamlit
+psycopg[binary]
+psycopg-pool
+```

docs/docs/streamlit/tables/tables_edit.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Edit a table

docs/docs/streamlit/tables/tables_read.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 # Read a table

streamlit/views/oltp_database_connect.py

@@ -157,16 +157,17 @@ def query_df(pool: ConnectionPool, sql: str) -> pd.DataFrame:
         st.markdown(
             """
             **Permissions (app service principal)**
+            * The database instance should be specified in your [**App resources**](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/resources).
             * A PostgreSQL role for the service principal is **required**.
             See [this guide](https://docs.databricks.com/aws/en/oltp/pg-roles?language=PostgreSQL#create-postgres-roles-and-grant-privileges-for-databricks-identities).
             * The PostgreSQL service principal role should have these example grants:
             """
         )
         st.code(
             '''
-GRANT CONNECT ON DATABASE customer_database TO "<YOUR-SERVICE-PRINCIPAL-ID>";
-GRANT USAGE ON SCHEMA customer_core TO "<YOUR-SERVICE-PRINCIPAL-ID>";
-GRANT SELECT ON TABLE customers_oltp TO "<YOUR-SERVICE-PRINCIPAL-ID>";
+GRANT CONNECT ON DATABASE databricks_postgres TO "099f0306-9e29-4a87-84c0-3046e4bcea02";
+GRANT USAGE ON SCHEMA public TO "099f0306-9e29-4a87-84c0-3046e4bcea02";
+GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE quotes_history TO "099f0306-9e29-4a87-84c0-3046e4bcea02";
             ''',
             language="sql",
         )