Add examples

Author: jayantsing-db

examples/README.md

@@ -31,6 +31,7 @@ To run all of these examples you can clone the entire repository to your disk. O
 
 - **`query_execute.py`** connects to the `samples` database of your default catalog, runs a small query, and prints the result to screen.
 - **`insert_data.py`** adds a tables called `squares` to your default catalog and inserts one hundred rows of example data. Then it fetches this data and prints it to the screen.
+- **`transactions.py`** demonstrates multi-statement transaction support with explicit commit/rollback control. Shows how to group multiple SQL statements into an atomic unit that either succeeds completely or fails completely.
 - **`query_cancel.py`** shows how to cancel a query assuming that you can access the `Cursor` executing that query from a different thread. This is necessary because `databricks-sql-connector` does not yet implement an asynchronous API; calling `.execute()` blocks the current thread until execution completes. Therefore, the connector can't cancel queries from the same thread where they began.
 - **`interactive_oauth.py`** shows the simplest example of authenticating by OAuth (no need for a PAT generated in the DBSQL UI) while Bring Your Own IDP is in public preview. When you run the script it will open a browser window so you can authenticate. Afterward, the script fetches some sample data from Databricks and prints it to the screen. For this script, the OAuth token is not persisted which means you need to authenticate every time you run the script.
 - **`m2m_oauth.py`** shows the simplest example of authenticating by using OAuth M2M (machine-to-machine) for service principal.

examples/transactions.py

@@ -0,0 +1,47 @@
+from databricks import sql
+import os
+
+with sql.connect(
+    server_hostname=os.getenv("DATABRICKS_SERVER_HOSTNAME"),
+    http_path=os.getenv("DATABRICKS_HTTP_PATH"),
+    access_token=os.getenv("DATABRICKS_TOKEN"),
+) as connection:
+
+    # Disable autocommit to use explicit transactions
+    connection.autocommit = False
+
+    with connection.cursor() as cursor:
+        try:
+            # Create tables for demonstration
+            cursor.execute("CREATE TABLE IF NOT EXISTS accounts (id int, balance int)")
+            cursor.execute(
+                "CREATE TABLE IF NOT EXISTS transfers (from_id int, to_id int, amount int)"
+            )
+            connection.commit()
+
+            # Start a new transaction - transfer money between accounts
+            cursor.execute("INSERT INTO accounts VALUES (1, 1000), (2, 500)")
+            cursor.execute("UPDATE accounts SET balance = balance - 100 WHERE id = 1")
+            cursor.execute("UPDATE accounts SET balance = balance + 100 WHERE id = 2")
+            cursor.execute("INSERT INTO transfers VALUES (1, 2, 100)")
+
+            # Commit the transaction - all changes succeed together
+            connection.commit()
+            print("Transaction committed successfully")
+
+            # Verify the results
+            cursor.execute("SELECT * FROM accounts ORDER BY id")
+            print("Accounts:", cursor.fetchall())
+
+            cursor.execute("SELECT * FROM transfers")
+            print("Transfers:", cursor.fetchall())
+
+        except Exception as e:
+            # Roll back on error - all changes are discarded
+            connection.rollback()
+            print(f"Transaction rolled back due to error: {e}")
+            raise
+
+        finally:
+            # Restore autocommit to default state
+            connection.autocommit = True