Address feedback

format/FlightSql.proto

@@ -102,6 +102,20 @@ enum SqlInfo {
    */
   FLIGHT_SQL_TRANSACTION = 5;
 
+  /*
+   * Retrieves an int32 indicating the timeout for prepared statement handles.
+   *
+   * If 0, there is no timeout.
+   */
+  FLIGHT_SQL_STATEMENT_TIMEOUT = 6;
+
+  /*
+   * Retrieves an int32 indicating the timeout for transactions, since transactions are not tied to a connection.
+   *
+   * If 0, there is no timeout.
+   */
+  FLIGHT_SQL_TRANSACTION_TIMEOUT = 7;
+
   // SQL Syntax Information [500-1000): provides information about SQL syntax supported by the Flight SQL Server.
 
   /*
@@ -776,9 +790,11 @@ enum SqlInfo {
 enum FlightSqlTransactionSupport {
   // Unknown/not indicated
   FLIGHT_SQL_TRANSACTION_SUPPORT_UNKNOWN = 0;
-  // No supprot
+  // No support
   FLIGHT_SQL_TRANSACTION_SUPPORT_NONE = 1;
-  // Transactions, but not savepoints
+  // Transactions, but not savepoints.
+  // A savepoint is a mark within a transaction that can be individually
+  // rolled back to. Not all databases support savepoints.
   FLIGHT_SQL_TRANSACTION_SUPPORT_TRANSACTION = 2;
   // Transactions and savepoints
   FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT = 3;
@@ -1489,27 +1505,34 @@ message ActionClosePreparedStatementRequest {
  * Begins a transaction or creates a savepoint within a transaction.
  */
 message ActionBeginTransactionRequest {
-  // Create a savepoint within the identified transaction. Only supported if
-  // FLIGHT_SQL_TRANSACTION is FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
+  // The transaction to which a savepoint belongs, if applicable.
+  //
+  // To begin a transaction, leave this field empty.
+  //
+  // Only supported if FLIGHT_SQL_TRANSACTION is
+  // FLIGHT_SQL_TRANSACTION_SUPPORT_SAVEPOINT.
   bytes transaction_id = 1;
-  // Name for the savepoint (if applicable).
+  // Name for the savepoint, if applicable.
   string name = 2;
 }
 
 /*
  * The result of a "BeginTransaction" action.
  *
  * The transaction/savepoint can be manipulated with the "EndTransaction"
- * action, or automatically via server timeout.
+ * action, or automatically via server timeout. If the transaction times out,
+ * then it is automatically rolled back.
  */
 message ActionBeginTransactionResult {
-  // Opaque handle for the transaction on the server.
+  // Opaque handle for the transaction or savepoint on the server.
   bytes transaction_id = 1;
 }
 
 /*
  * Request message for the "EndTransaction" action.
- * Commit or rollback a transaction, or release/rollback a savepoint within a transaction.
+ *
+ * With a transaction: commit (COMMIT) or rollback (ROLLBACK) the transaction.
+ * With a savepoint: remove (COMMIT) or rollback to (ROLLBACK) the savepoint.
  */
 message ActionEndTransactionRequest {
   enum EndTransaction {
@@ -1519,7 +1542,7 @@ message ActionEndTransactionRequest {
     // Roll back the transaction or to a savepoint.
     END_TRANSACTION_ROLLBACK = 2;
   }
-  // Opaque handle for the transaction on the server.
+  // Opaque handle for the transaction or savepoint on the server.
   bytes transaction_id = 1;
   // Whether to commit/rollback/release the given transaction/savepoint.
   EndTransaction action = 2;
@@ -1662,7 +1685,9 @@ message DoPutUpdateResult {
  * Explicitly cancel a running query.
  *
  * For distributed queries (ones that use GetFlightInfo->DoGet), this lets a
- * single client explicitly cancel work across all clients, given server support.
+ * single client explicitly cancel work across all clients, given server
+ * support. The transaction/statement is not rolled back. This only indicates
+ * the client no longer wishes to read the remainder of the query results.
  */
 message ActionCancelQuery {
   // The result of the GetFlightInfo RPC that initated the query.