Address comments

Author: jayantsing-db

README.md

@@ -69,34 +69,9 @@ or to a Databricks Runtime interactive cluster (e.g. /sql/protocolv1/o/123456789
 
 ## Transaction Support
 
-The connector supports multi-statement transactions with manual commit/rollback control:
+The connector supports multi-statement transactions with manual commit/rollback control. Set `connection.autocommit = False` to disable autocommit mode, then use `connection.commit()` and `connection.rollback()` to control transactions.
 
-```python
-import os
-from databricks import sql
-
-connection = sql.connect(
-    server_hostname=os.getenv("DATABRICKS_HOST"),
-    http_path=os.getenv("DATABRICKS_HTTP_PATH")
-)
-
-# Disable autocommit to use explicit transactions
-connection.autocommit = False
-
-cursor = connection.cursor()
-try:
-    cursor.execute("INSERT INTO table1 VALUES (1, 'a')")
-    cursor.execute("INSERT INTO table2 VALUES (2, 'b')")
-    connection.commit()  # Commit both inserts atomically
-except Exception as e:
-    connection.rollback()  # Rollback on error
-    raise
-
-cursor.close()
-connection.close()
-```
-
-For detailed information about transaction behavior, isolation levels, error handling, and best practices, see [TRANSACTIONS.md](TRANSACTIONS.md).
+For detailed documentation, examples, and best practices, see **[TRANSACTIONS.md](TRANSACTIONS.md)**.
 
 ## SQLAlchemy
 Starting from `databricks-sql-connector` version 4.0.0 SQLAlchemy support has been extracted to a new library `databricks-sqlalchemy`.

TRANSACTIONS.md

@@ -53,6 +53,8 @@ try:
 except Exception as e:
     connection.rollback()  # Neither insert is saved
     raise
+finally:
+    connection.autocommit = True  # Restore default state
 ```
 
 ### Rolling Back Changes
@@ -106,6 +108,8 @@ try:
 except Exception as e:
     connection.rollback()  # All three inserts are discarded
     raise
+finally:
+    connection.autocommit = True  # Restore default state
 ```
 
 This is particularly useful for maintaining data consistency across related tables.
@@ -175,14 +179,19 @@ You cannot change autocommit mode while a transaction is active:
 
 ```python
 connection.autocommit = False
-cursor.execute("INSERT INTO logs VALUES (1, 'data')")
+cursor = connection.cursor()
 
-# This will raise TransactionError
 try:
-    connection.autocommit = True
+    cursor.execute("INSERT INTO logs VALUES (1, 'data')")
+    
+    # This will raise TransactionError
+    connection.autocommit = True  # Error: transaction is active
+    
 except sql.TransactionError as e:
     print(f"Cannot change autocommit: {e}")
-    connection.rollback()  # Clean up
+    connection.rollback()  # Clean up the transaction
+finally:
+    connection.autocommit = True  # Now it's safe to restore
 ```
 
 ### Committing Without an Active Transaction
@@ -215,14 +224,19 @@ try:
 except Exception as e:
     connection.rollback()  # Discard the partial transaction
 
-    # Now you can start a fresh transaction
-    cursor.execute("INSERT INTO error_log VALUES (1, 'Query failed')")
-    connection.commit()
+    # Log the error (with autocommit still disabled)
+    try:
+        cursor.execute("INSERT INTO error_log VALUES (1, 'Query failed')")
+        connection.commit()
+    except Exception:
+        connection.rollback()
+finally:
+    connection.autocommit = True  # Restore default state
 ```
 
 ## Querying Server State
 
-By default, the `autocommit` property returns a cached value for performance. If you need to query the server each time (for example, if you're debugging or the state might change externally):
+By default, the `autocommit` property returns a cached value for performance. If you need to query the server each time (for instance, when strong consistency is required):
 
 ```python
 connection = sql.connect(
@@ -291,7 +305,7 @@ conn2.commit()  # Also OK
 
 1. **Keep transactions short**: Long-running transactions can cause conflicts with other connections. Commit as soon as your atomic unit of work is complete.
 
-2. **Always handle exceptions**: Wrap transaction code in try/except and call `rollback()` on errors.
+2. **Always handle exceptions**: Wrap transaction code in try/except/finally and call `rollback()` on errors.
 
 ```python
 connection.autocommit = False
@@ -305,6 +319,8 @@ except Exception as e:
     connection.rollback()
     logger.error(f"Transaction failed: {e}")
     raise
+finally:
+    connection.autocommit = True  # Restore default state
 ```
 
 3. **Use context managers**: If you're writing helper functions, consider using a context manager pattern:
@@ -331,15 +347,18 @@ with transaction(connection):
     # Auto-commits on success, auto-rolls back on exception
 ```
 
-4. **Reset autocommit when done**: After using explicit transactions, consider resetting autocommit to True for subsequent operations:
+4. **Reset autocommit when done**: Use a `finally` block to restore autocommit to `True`. This is especially important if the connection is reused or part of a connection pool:
 
 ```python
 connection.autocommit = False
 try:
     # ... transaction code ...
     connection.commit()
+except Exception:
+    connection.rollback()
+    raise
 finally:
-    connection.autocommit = True  # Reset to default
+    connection.autocommit = True  # Restore to default state
 ```
 
 5. **Be aware of isolation semantics**: Remember that repeatable read means you see a snapshot from the start of your transaction. If you need to see recent changes from other transactions, commit your current transaction and start a new one.