docs(bigquery-jdbc): add user guide with connection property and custom endpoint reference

[Neenu1995]

No description provided.

[gemini-code-assist]

Code Review

This pull request adds a comprehensive User Guide (USER_GUIDE.md) for the Google BigQuery JDBC Driver, detailing configuration, architecture, and common code recipes. The review feedback correctly identifies several inconsistencies in the document, specifically regarding incorrect OAuthType values in the authentication examples (confusing OAuthType=0 for Service Accounts with OAuthType=3 for Application Default Credentials) and mismatches in the Table of Contents headings.

[Neenu1995]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive User Guide for the Google BigQuery JDBC Driver, detailing setup, configuration properties, architecture, and common code recipes. The review feedback highlights several critical corrections needed in the documentation's code examples: updating the transaction prerequisite exception from IllegalStateException to SQLException to match the JDBC contract, adding null and type safety checks to the complex types example to prevent runtime exceptions, replacing the stored procedure example with a multi-statement script since standard JDBC OUT parameters are unsupported, and wrapping the Spring Boot YAML connection URL in double quotes to avoid parsing issues.

[gemini-code-assist]

The JDBC API methods setAutoCommit, commit, and rollback are specified to throw java.sql.SQLException when an error or unsupported operation occurs. They do not throw IllegalStateException directly to the caller, as doing so would violate the standard JDBC interface contract and break connection pool wrappers like HikariCP. Please update the documentation to reference SQLException instead.

Suggested change

	1. **Pre-requisite Check**: Calling `setAutoCommit(false)`, `commit()`, or `rollback()` requires `;EnableSession=true` in the connection URL. If disabled, an `IllegalStateException` is thrown.
	1. **Pre-requisite Check**: Calling setAutoCommit(false), commit(), or rollback() requires ;EnableSession=true in the connection URL. If disabled, a SQLException is thrown.

[gemini-code-assist]

This code snippet has potential NullPointerException and ClassCastException risks:

1. Null Safety: If shipping_address, line_items, or tags are NULL in BigQuery, rs.getObject() or rs.getArray() will return null. Accessing methods on them directly will throw a NullPointerException.
2. Type Safety: Array.getArray() typically returns a generic Object[] array in most JDBC drivers. Casting Object[] directly to Struct[] or String[] will throw a ClassCastException at runtime. It is safer to cast to Object[] and process elements individually or use safe conversion utilities.

        // 1. Reading Struct
        Struct addressStruct = (Struct) rs.getObject("shipping_address");
        if (addressStruct != null) {
          Object[] addressAttrs = addressStruct.getAttributes();
          System.out.printf("Order %d Address: %s, %s%n", orderId, addressAttrs[0], addressAttrs[1]);
        }

        // 2. Reading Array of Structs
        Array itemsArray = rs.getArray("line_items");
        if (itemsArray != null) {
          Object[] items = (Object[]) itemsArray.getArray();
          for (Object itemObj : items) {
            Struct item = (Struct) itemObj;
            if (item != null) {
              Object[] itemAttrs = item.getAttributes();
              System.out.printf("  Item -> SKU: %s, Qty: %s%n", itemAttrs[0], itemAttrs[1]);
            }
          }
        }

        // 3. Reading Primitive Array
        Array tagsArray = rs.getArray("tags");
        if (tagsArray != null) {
          Object[] tags = (Object[]) tagsArray.getArray();
          System.out.println("  Tags: " + java.util.Arrays.toString(tags));
        }

[gemini-code-assist]

BigQuery stored procedures do not support standard JDBC OUT parameters via CallableStatement.registerOutParameter because the underlying BigQuery API does not return output parameters in the traditional JDBC response format. Calling prepareCall or registerOutParameter will likely throw a SQLFeatureNotSupportedException.

To retrieve OUT parameters from a BigQuery stored procedure, the standard and supported approach is to execute a multi-statement SQL script that declares a variable, calls the procedure, and then selects the variable to return it as a standard ResultSet.

import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

public class StoredProcedureCUJ {
  public static void main(String[] args) throws Exception {
    String url = "jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-project;OAuthType=0";

    // Declare a variable, call the procedure, and select the output variable
    String sql = "DECLARE tax DECIMAL; CALL my_dataset.calculate_tax(1000.00, tax); SELECT tax;";

    try (Connection conn = DriverManager.getConnection(url);
         Statement stmt = conn.createStatement()) {

      boolean hasResults = stmt.execute(sql);
      
      // Loop through results to find the selected output variable
      while (hasResults || stmt.getUpdateCount() != -1) {
        if (hasResults) {
          try (ResultSet rs = stmt.getResultSet()) {
            if (rs.next()) {
              BigDecimal taxAmount = rs.getBigDecimal(1);
              System.out.println("Calculated Tax Amount: $" + taxAmount);
            }
          }
        }
        hasResults = stmt.getMoreResults();
      }
    }
  }
}

[gemini-code-assist]

In YAML configuration files, connection URLs containing special characters (such as colons : and semicolons ;) should be wrapped in double quotes to prevent potential parsing errors by the YAML parser.

Suggested change

	url: jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-gcp-project;DefaultDataset=my_dataset;OAuthType=0;OAuthServiceAcctEmail=sa@my-project.iam.gserviceaccount.com;OAuthPvtKeyPath=/path/to/key.json
	url: "jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-gcp-project;DefaultDataset=my_dataset;OAuthType=0;OAuthServiceAcctEmail=sa@my-project.iam.gserviceaccount.com;OAuthPvtKeyPath=/path/to/key.json"