Package: groovy.sql

## [Java] Class Sql

- groovy.sql.Sql

- All Implemented Interfaces and Traits:
    AutoCloseable

      public class Sql
      extends Object
      implements AutoCloseable

  A facade over Java's normal JDBC APIs providing greatly simplified resource management and result set handling. Under the covers the facade hides away details associated with getting connections, constructing and configuring statements, interacting with the connection, closing resources and logging errors. Special features of the facade include using closures to iterate through result sets, a special GString syntax for representing prepared statements and treating result sets like collections of maps with the normal Groovy collection methods available.

  #### Typical usage

  First you need to set up your sql instance. There are several constructors and a few `newInstance` factory methods available to do this. In simple cases, you can just provide the necessary details to set up a connection (e.g. for hsqldb):

      def db = [url:'jdbc:hsqldb:mem:testDB', user:'sa', password:'', driver:'org.hsqldb.jdbc.JDBCDriver']
      def sql = Sql.newInstance(db.url, db.user, db.password, db.driver)

  or if you have an existing connection (perhaps from a connection pool) or a datasource use one of the constructors:

      def sql = new Sql(datasource)

  Now you can invoke sql, e.g. to create a table. Here is the DDL we want to execute:

      create table PROJECT (
          id integer not null,
          name varchar(50),
          url varchar(100),
      )

  And the Groovy that runs it via the facade:

      sql.execute '''
          create table PROJECT (
              id integer not null,
              name varchar(50),
              url varchar(100),
          )
      '''

  Or insert a row using JDBC PreparedStatement inspired syntax:

      def params = [10, 'Groovy', 'https://groovy-lang.org']
      sql.execute 'insert into PROJECT (id, name, url) values (?, ?, ?)', params

  Or insert a row using GString syntax:

      def map = [id:20, name:'Grails', url:'https://grails.org']
      sql.execute "insert into PROJECT (id, name, url) values ($map.id, $map.name, $map.url)"

  Or a row update:

      def newUrl = 'https://grails.org'
      def project = 'Grails'
      sql.executeUpdate "update PROJECT set url=$newUrl where name=$project"

  Now try a query using `eachRow`:

      println 'Some GR8 projects:'
      sql.eachRow('select * from PROJECT') { row ->
          println "${row.name.padRight(10)} ($row.url)"
      }

  Which will produce something like this:

      Some GR8 projects:
      Groovy     (https://groovy-lang.org)
      Grails     (https://grails.org)
      Griffon    (https://griffon-framework.org)
      Gradle     (https://gradle.org)

  Now try a query using `rows`:

      def rows = sql.rows("select * from PROJECT where name like 'Gra%'")
      assert rows.size() == 2
      println rows.join('\n')

  with output like this:

      [ID:20, NAME:Grails, URL:https://grails.org]
      [ID:40, NAME:Gradle, URL:https://gradle.org]

  Also, `eachRow` and `rows` support paging. Here's an example:

      sql.eachRow('select * from PROJECT', 2, 2) { row ->
          println "${row.name.padRight(10)} ($row.url)"
      }

  Which will start at the second row and return a maximum of 2 rows. Here's an example result:

      Grails     (https://grails.org)
      Griffon    (https://griffon-framework.org)

  Finally, we should clean up:

      sql.close()

  If we are using a DataSource and we haven't enabled statement caching, then strictly speaking the final `close()` method isn't required - as all connection handling is performed transparently on our behalf; however, it doesn't hurt to have it there as it will return silently in that case.

  If instead of `newInstance` you use `withInstance`, then `close()` will be called automatically for you. A complete end-to-end example combining setup, creation, insertion, querying, and cleanup:

      import groovy.sql.Sql

      def db = [url: 'jdbc:hsqldb:mem:testDB',
                user: 'sa', password: '',
                driver: 'org.hsqldb.jdbc.JDBCDriver']

      Sql.withInstance(db.url, db.user, db.password, db.driver) { sql ->
          sql.execute '''
              create table PROJECT (
                  id integer not null,
                  name varchar(50) not null,
                  url varchar(100)
              )
          '''

          [[10, 'Groovy', 'https://groovy-lang.org'],
           [20, 'Grails', 'https://grails.org'],
           [40, 'Gradle', 'https://gradle.org']].each { row ->
              sql.execute 'insert into PROJECT (id, name, url) values (?, ?, ?)', row
          }

          sql.eachRow('select * from PROJECT order by id') { row ->
              println "${row.name.padRight(10)} ($row.url)"
          }
      }

  #### Avoiding SQL injection

  If you find yourself creating queries based on any kind of input from the user or a 3rd party application you might wish to avoid the pure string method variants in this class. While this is safe: `sql.firstRow('select * from PersonTable')` This example is potentially at risk of SQL injection: `sql.firstRow('select * from PersonTable where SurnameColumn = ' + userInput)` This in turn will be fine if '`userInput`' is something like 'Smith' but maybe not so fine if '`userInput`' is something like 'Smith; DROP table PersonTable'. Instead, use one of the variants with parameters and placeholders: `sql.firstRow("select * from PersonTable where SurnameColumn = ?", [userInput])` or the GString variants which will be converted to the placeholder variants under the covers: `sql.firstRow("select * from PersonTable where SurnameColumn = $userInput")` or the named parameter variants discussed next.

  When using the GString variants, do not surround an interpolated expression with SQL quotes, e.g. `sql.firstRow("select * from PersonTable where SurnameColumn = '$userInput'")`. Such quoting prevents Groovy from using a JDBC PreparedStatement placeholder for the value and would otherwise reopen the SQL injection hole. By default Groovy rejects such queries by throwing a SQLException. The (insecure) legacy behaviour of inlining the value via string concatenation can be restored by setting the {@value #INJECTION_LENIENT} system property to `true`, but this is strongly discouraged.

  #### Named and named ordinal parameters

  Several of the methods in this class (ones which have a String-based sql query and params in a List<Object> or Object[] or Map) support named or named ordinal parameters. These methods are useful for queries with large numbers of parameters - though the GString variations are often preferred in such cases too. Reminder: when you see a variant with Object[] as the type of the last parameter, Groovy allows vararg style parameters so you don't explicitly need to create an Object[] and if the first parameter is of type Map, Groovy supports named arguments - examples of both are contained in the examples below.

  Named parameter queries use placeholder values in the query String. Two forms are supported ':propname1' and '?.propname2'. For these variations, a single model object is supplied in the parameter list/array/map. The propname refers to a property of that model object. The model object could be a map, Expando or domain class instance. Here are some examples:

      // using rows() with a named parameter with the parameter supplied in a map
      println sql.rows('select * from PROJECT where name=:foo', [foo:'Gradle'])
      // as above for eachRow()
      sql.eachRow('select * from PROJECT where name=:foo', [foo:'Gradle']) {
          // process row
      }

      // an example using both the ':' and '?.' variants of the notation
      println sql.rows('select * from PROJECT where name=:foo and id=?.bar', [foo:'Gradle', bar:40])
      // as above but using Groovy's named arguments instead of an explicit map
      println sql.rows('select * from PROJECT where name=:foo and id=?.bar', foo:'Gradle', bar:40)

      // an example showing rows() with a domain object instead of a map
      class MyDomainClass { def baz = 'Griffon' }
      println sql.rows('select * from PROJECT where name=?.baz', new MyDomainClass())
      // as above for eachRow() with the domain object supplied in a list
      sql.eachRow('select * from PROJECT where name=?.baz', [new MyDomainClass()]) {
          // process row
      }

  Named ordinal parameter queries have multiple model objects with the index number (starting at 1) also supplied in the placeholder. Only the question mark variation of placeholder is supported. Here are some examples:

      // an example showing the model objects as vararg style parameters (since rows() has an Object[] variant)
      println sql.rows("select * from PROJECT where name=?1.baz and id=?2.num", new MyDomainClass(), [num:30])

      // an example showing the model objects (one domain class and one map) provided in a list
      sql.eachRow("select * from PROJECT where name=?1.baz and id=?2.num", [new MyDomainClass(), [num:30]]) {
          // do something with row
      }

  #### More details

  See the method and constructor JavaDoc for more details.

  For advanced usage, the class provides numerous extension points for overriding the facade behavior associated with the various aspects of managing the interaction with the underlying database.

  This class is not thread-safe.

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `protected class` | `Sql.AbstractQueryCommand` | Base command object for query operations that manage statement and connection lifecycle.

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static int` | `ALL_RESULT_SETS` | Indicates that stored-procedure helpers should collect every returned result set.
    `static OutParameter` | `ARRAY` | Stored procedure OUT parameter marker for JDBC type ARRAY.
    `static OutParameter` | `BIGINT` | Stored procedure OUT parameter marker for JDBC type BIGINT.
    `static OutParameter` | `BINARY` | Stored procedure OUT parameter marker for JDBC type BINARY.
    `static OutParameter` | `BIT` | Stored procedure OUT parameter marker for JDBC type BIT.
    `static OutParameter` | `BLOB` | Stored procedure OUT parameter marker for JDBC type BLOB.
    `static OutParameter` | `BOOLEAN` | Stored procedure OUT parameter marker for JDBC type BOOLEAN.
    `static OutParameter` | `CHAR` | Stored procedure OUT parameter marker for JDBC type CHAR.
    `static OutParameter` | `CLOB` | Stored procedure OUT parameter marker for JDBC type CLOB.
    `static OutParameter` | `DATALINK` | Stored procedure OUT parameter marker for JDBC type DATALINK.
    `static OutParameter` | `DATE` | Stored procedure OUT parameter marker for JDBC type DATE.
    `static OutParameter` | `DECIMAL` | Stored procedure OUT parameter marker for JDBC type DECIMAL.
    `static OutParameter` | `DISTINCT` | Stored procedure OUT parameter marker for JDBC type DISTINCT.
    `static OutParameter` | `DOUBLE` | Stored procedure OUT parameter marker for JDBC type DOUBLE.
    `static int` | `FIRST_RESULT_SET` | Indicates that stored-procedure helpers should collect only the first returned result set.
    `static OutParameter` | `FLOAT` | Stored procedure OUT parameter marker for JDBC type FLOAT.
    `static String` | `INJECTION_LENIENT` | Boolean system property which controls how a quoted dynamic expression (an interpolated GString expression surrounded by SQL quotes, e.g.
    `static OutParameter` | `INTEGER` | Stored procedure OUT parameter marker for JDBC type INTEGER.
    `static OutParameter` | `JAVA_OBJECT` | Stored procedure OUT parameter marker for JDBC type JAVA_OBJECT.
    `protected static Logger` | `LOG` | Hook to allow derived classes to access the log
    `static OutParameter` | `LONGVARBINARY` | Stored procedure OUT parameter marker for JDBC type LONGVARBINARY.
    `static OutParameter` | `LONGVARCHAR` | Stored procedure OUT parameter marker for JDBC type LONGVARCHAR.
    `static int` | `NO_RESULT_SETS` | Indicates that stored-procedure helpers should ignore any returned result sets.
    `static OutParameter` | `NULL` | Stored procedure OUT parameter marker for JDBC type NULL.
    `static OutParameter` | `NUMERIC` | Stored procedure OUT parameter marker for JDBC type NUMERIC.
    `static OutParameter` | `OTHER` | Stored procedure OUT parameter marker for JDBC type OTHER.
    `static OutParameter` | `REAL` | Stored procedure OUT parameter marker for JDBC type REAL.
    `static OutParameter` | `REF` | Stored procedure OUT parameter marker for JDBC type REF.
    `static OutParameter` | `SMALLINT` | Stored procedure OUT parameter marker for JDBC type SMALLINT.
    `static OutParameter` | `STRUCT` | Stored procedure OUT parameter marker for JDBC type STRUCT.
    `static OutParameter` | `TIME` | Stored procedure OUT parameter marker for JDBC type TIME.
    `static OutParameter` | `TIMESTAMP` | Stored procedure OUT parameter marker for JDBC type TIMESTAMP.
    `static OutParameter` | `TINYINT` | Stored procedure OUT parameter marker for JDBC type TINYINT.
    `static OutParameter` | `VARBINARY` | Stored procedure OUT parameter marker for JDBC type VARBINARY.
    `static OutParameter` | `VARCHAR` | Stored procedure OUT parameter marker for JDBC type VARCHAR.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `Sql(DataSource dataSource)` Constructs an SQL instance using the given DataSource.
    `Sql(Connection connection)` Constructs an SQL instance using the given Connection.
    `Sql(Sql parent)` Constructs an `Sql` instance backed by the same DataSource or Connection as the supplied parent.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public static InParameter` | `ARRAY(Object value)` Creates a typed input parameter for JDBC type ARRAY.
    `` | `public static InParameter` | `BIGINT(Object value)` Creates a typed input parameter for JDBC type BIGINT.
    `` | `public static InParameter` | `BINARY(Object value)` Creates a typed input parameter for JDBC type BINARY.
    `` | `public static InParameter` | `BIT(Object value)` Creates a typed input parameter for JDBC type BIT.
    `` | `public static InParameter` | `BLOB(Object value)` Creates a typed input parameter for JDBC type BLOB.
    `` | `public static InParameter` | `BOOLEAN(Object value)` Creates a typed input parameter for JDBC type BOOLEAN.
    `` | `public static InParameter` | `CHAR(Object value)` Creates a typed input parameter for JDBC type CHAR.
    `` | `public static InParameter` | `CLOB(Object value)` Creates a typed input parameter for JDBC type CLOB.
    `` | `public static InParameter` | `DATALINK(Object value)` Creates a typed input parameter for JDBC type DATALINK.
    `` | `public static InParameter` | `DATE(Object value)` Creates a typed input parameter for JDBC type DATE.
    `` | `public static InParameter` | `DECIMAL(Object value)` Creates a typed input parameter for JDBC type DECIMAL.
    `` | `public static InParameter` | `DISTINCT(Object value)` Creates a typed input parameter for JDBC type DISTINCT.
    `` | `public static InParameter` | `DOUBLE(Object value)` Creates a typed input parameter for JDBC type DOUBLE.
    `` | `public static InParameter` | `FLOAT(Object value)` Creates a typed input parameter for JDBC type FLOAT.
    `` | `public static InParameter` | `INTEGER(Object value)` Creates a typed input parameter for JDBC type INTEGER.
    `` | `public static InParameter` | `JAVA_OBJECT(Object value)` Creates a typed input parameter for JDBC type JAVA_OBJECT.
    `` | `public static InParameter` | `LONGVARBINARY(Object value)` Creates a typed input parameter for JDBC type LONGVARBINARY.
    `` | `public static InParameter` | `LONGVARCHAR(Object value)` Creates a typed input parameter for JDBC type LONGVARCHAR.
    `` | `public static InParameter` | `NULL(Object value)` Creates a typed input parameter for JDBC type NULL.
    `` | `public static InParameter` | `NUMERIC(Object value)` Creates a typed input parameter for JDBC type NUMERIC.
    `` | `public static InParameter` | `OTHER(Object value)` Creates a typed input parameter for JDBC type OTHER.
    `` | `public static InParameter` | `REAL(Object value)` Creates a typed input parameter for JDBC type REAL.
    `` | `public static InParameter` | `REF(Object value)` Creates a typed input parameter for JDBC type REF.
    `` | `public static InParameter` | `SMALLINT(Object value)` Creates a typed input parameter for JDBC type SMALLINT.
    `` | `public static InParameter` | `STRUCT(Object value)` Creates a typed input parameter for JDBC type STRUCT.
    `` | `public static InParameter` | `TIME(Object value)` Creates a typed input parameter for JDBC type TIME.
    `` | `public static InParameter` | `TIMESTAMP(Object value)` Creates a typed input parameter for JDBC type TIMESTAMP.
    `` | `public static InParameter` | `TINYINT(Object value)` Creates a typed input parameter for JDBC type TINYINT.
    `` | `public static InParameter` | `VARBINARY(Object value)` Creates a typed input parameter for JDBC type VARBINARY.
    `` | `public static InParameter` | `VARCHAR(Object value)` Creates a typed input parameter for JDBC type VARCHAR.
    `` | `protected List<GroovyRowResult>` | `asList(String sql, ResultSet rs)` Hook to allow derived classes to override list of result collection behavior.
    `` | `protected List<GroovyRowResult>` | `asList(String sql, ResultSet rs, Closure metaClosure)` Hook to allow derived classes to override list of result collection behavior.
    `` | `protected List<GroovyRowResult>` | `asList(String sql, ResultSet rs, int offset, int maxRows, Closure metaClosure)` Hook to allow derived classes to override paged result collection behavior.
    `` | `protected String` | `asSql(GString gstring, List<?> values)` Hook to allow derived classes to override sql generation from GStrings.
    `` | `protected SqlWithParams` | `buildSqlWithIndexedProps(String sql)` Hook to allow derived classes to override behavior associated with the parsing and indexing of parameters from a given sql statement.
    `` | `public void` | `cacheConnection(Closure closure)` Caches the connection used while the closure is active.
    `` | `public void` | `cacheStatements(Closure closure)` Caches every created preparedStatement in Closure closure Every cached preparedStatement is closed after closure has been called.
    `` | `public int` | `call(String sql)` Performs a stored procedure call.
    `` | `public int` | `call(GString gstring)` Performs a stored procedure call with the given embedded parameters.
    `` | `public int` | `call(String sql, List<?> params)` Performs a stored procedure call with the given parameters.
    `` | `public int` | `call(String sql, Object[] params)` Performs a stored procedure call with the given parameters.
    `` | `public int` | `call(String sql, Map params)` A variant of call(String, List) useful when providing the named parameters as a map.
    `` | `public int` | `call(Map params, String sql)` A variant of call(String, List) useful when providing the named parameters as named arguments (Groovy named-argument syntax).
    `` | `public void` | `call(String sql, List<?> params, Closure closure)` Performs a stored procedure call with the given parameters.
    `` | `public void` | `call(GString gstring, Closure closure)` Performs a stored procedure call with the given parameters, calling the closure once with all result objects.
    `` | `public void` | `call(String sql, Map params, Closure closure)` A variant of call(String, List, Closure) useful when providing the named parameters as a map.
    `` | `public void` | `call(Map params, String sql, Closure closure)` A variant of call(String, List, Closure) useful when providing the named parameters as named arguments (Groovy named-argument syntax).
    `` | `public List<List<GroovyRowResult>>` | `callWithAllRows(GString gstring, Closure closure)` Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning a list of lists with the rows of the ResultSet(s).
    `` | `public List<List<GroovyRowResult>>` | `callWithAllRows(String sql, List<?> params, Closure closure)` Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning a list of lists with the rows of the ResultSet(s).
    `` | `public List<List<GroovyRowResult>>` | `callWithAllRows(String sql, Map params, Closure closure)` A variant of callWithAllRows(String, List, Closure) useful when providing the named parameters as a map.
    `` | `public List<List<GroovyRowResult>>` | `callWithAllRows(Map params, String sql, Closure closure)` A variant of callWithAllRows(String, List, Closure) useful when providing the named parameters as named arguments (Groovy named-argument syntax).
    `` | `public List<GroovyRowResult>` | `callWithRows(GString gstring, Closure closure)` Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning the rows of the ResultSet.
    `` | `public List<GroovyRowResult>` | `callWithRows(String sql, List<?> params, Closure closure)` Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning the rows of the ResultSet.
    `` | `public List<GroovyRowResult>` | `callWithRows(String sql, Map params, Closure closure)` A variant of callWithRows(String, List, Closure) useful when providing the named parameters as a map.
    `` | `public List<GroovyRowResult>` | `callWithRows(Map params, String sql, Closure closure)` A variant of callWithRows(String, List, Closure) useful when providing the named parameters as named arguments (Groovy named-argument syntax).
    `` | `protected List<List<GroovyRowResult>>` | `callWithRows(String sql, List<?> params, int processResultsSets, Closure closure)` Base internal method for call(), callWithRows(), and callWithAllRows() style of methods.
    `` | `public SqlWithParams` | `checkForNamedParams(String sql, List<?> params)` Rewrites named or named-ordinal parameter SQL into JDBC positional form and aligns the supplied parameters with the rewritten placeholders.
    `` | `protected void` | `cleanup(Statement statement)` Provides a hook for derived classes to be able to examine JDBC statements before cleanup/closing.
    `` | `public void` | `close()` If this SQL object was created with a Connection then this method closes the connection.
    `` | `protected void` | `closeResources(Connection connection, Statement statement, ResultSet results)` An extension point allowing derived classes to change the behavior of resource closing.
    `` | `protected void` | `closeResources(Connection connection, Statement statement)` An extension point allowing the behavior of resource closing to be overridden in derived classes.
    `` | `protected void` | `closeResources(Connection connection)` An extension point allowing the behavior of resource closing to be overridden in derived classes.
    `` | `public void` | `commit()` If this SQL object was created with a Connection then this method commits the connection.
    `` | `protected void` | `configure(Statement statement)` Provides a hook for derived classes to be able to configure JDBC statements.
    `` | `protected Connection` | `createConnection()` An extension point allowing derived classes to change the behavior of connection creation.
    `` | `protected Sql.AbstractQueryCommand` | `createPreparedQueryCommand(String sql, List<?> queryParams)` Factory for the PreparedQueryCommand command pattern object allows subclass to supply implementations of the command class.
    `` | `protected Sql.AbstractQueryCommand` | `createQueryCommand(String sql)` Factory for the QueryCommand command pattern object allows subclasses to supply implementations of the command class.
    `` | `public DataSet` | `dataSet(String table)` Creates a DataSet facade for the named table.
    `` | `public DataSet` | `dataSet(Class<?> type)` Creates a DataSet facade using the table mapping implied by the supplied type.
    `` | `public void` | `eachRow(String sql, Closure closure)` Performs the given SQL query calling the given Closure with each row of the result set.
    `` | `public void` | `eachRow(String sql, int offset, int maxRows, Closure closure)` Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows.
    `` | `public void` | `eachRow(String sql, Closure metaClosure, Closure rowClosure)` Performs the given SQL query calling the given `rowClosure` with each row of the result set.
    `` | `public void` | `eachRow(String sql, Closure metaClosure, int offset, int maxRows, Closure rowClosure)` Performs the given SQL query calling the given `rowClosure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows.
    `` | `public void` | `eachRow(String sql, List<?> params, Closure metaClosure, int offset, int maxRows, Closure rowClosure)` Performs the given SQL query calling the given `rowClosure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows.
    `` | `public void` | `eachRow(String sql, Map map, Closure metaClosure, int offset, int maxRows, Closure rowClosure)` A variant of eachRow(String, java.util.List, groovy.lang.Closure, int, int, groovy.lang.Closure) allowing the named parameters to be supplied in a map.
    `` | `public void` | `eachRow(Map map, String sql, Closure metaClosure, int offset, int maxRows, Closure rowClosure)` A variant of eachRow(String, java.util.List, groovy.lang.Closure, int, int, groovy.lang.Closure) allowing the named parameters to be supplied as named arguments.
    `` | `public void` | `eachRow(String sql, List<?> params, Closure metaClosure, Closure rowClosure)` Performs the given SQL query calling the given Closure with each row of the result set.
    `` | `public void` | `eachRow(String sql, Map params, Closure metaClosure, Closure rowClosure)` A variant of eachRow(String, java.util.List, groovy.lang.Closure, groovy.lang.Closure) useful when providing the named parameters as a map.
    `` | `public void` | `eachRow(Map params, String sql, Closure metaClosure, Closure rowClosure)` A variant of eachRow(String, java.util.List, groovy.lang.Closure, groovy.lang.Closure) useful when providing the named parameters as named arguments.
    `` | `public void` | `eachRow(String sql, List<?> params, Closure closure)` Performs the given SQL query calling the given Closure with each row of the result set.
    `` | `public void` | `eachRow(String sql, Map params, Closure closure)` A variant of eachRow(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as a map.
    `` | `public void` | `eachRow(Map params, String sql, Closure closure)` A variant of eachRow(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as named arguments.
    `` | `public void` | `eachRow(String sql, List<?> params, int offset, int maxRows, Closure closure)` Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows.
    `` | `public void` | `eachRow(String sql, Map params, int offset, int maxRows, Closure closure)` A variant of eachRow(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as a map.
    `` | `public void` | `eachRow(Map params, String sql, int offset, int maxRows, Closure closure)` A variant of eachRow(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as named arguments.
    `` | `public void` | `eachRow(GString gstring, Closure metaClosure, Closure rowClosure)` Performs the given SQL query calling the given Closure with each row of the result set.
    `` | `public void` | `eachRow(GString gstring, Closure metaClosure, int offset, int maxRows, Closure rowClosure)` Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows.
    `` | `public void` | `eachRow(GString gstring, int offset, int maxRows, Closure closure)` Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows.
    `` | `public void` | `eachRow(GString gstring, Closure closure)` Performs the given SQL query calling the given Closure with each row of the result set.
    `` | `public boolean` | `execute(String sql)` Executes the given piece of SQL.
    `` | `public void` | `execute(String sql, Closure resultClosure)` Executes the given piece of SQL.
    `` | `public void` | `execute(String sql, Closure metaClosure, Closure resultClosure)` Executes the given piece of SQL.
    `` | `public boolean` | `execute(String sql, List<?> params)` Executes the given piece of SQL with parameters.
    `` | `public void` | `execute(String sql, List<?> params, Closure resultClosure)` Executes the given piece of SQL with parameters.
    `` | `public void` | `execute(String sql, List<?> params, Closure metaClosure, Closure resultClosure)` Executes the given piece of SQL with parameters.
    `` | `public boolean` | `execute(Map params, String sql)` A variant of execute(String, java.util.List) useful when providing the named parameters as named arguments.
    `` | `public void` | `execute(Map params, String sql, Closure resultClosure)` A variant of execute(String, java.util.List, Closure) useful when providing the named parameters as named arguments.
    `` | `public void` | `execute(Map params, String sql, Closure metaClosure, Closure resultClosure)` A variant of execute(String, java.util.List, Closure, Closure) useful when providing the named parameters as named arguments.
    `` | `public boolean` | `execute(String sql, Object[] params)` Executes the given piece of SQL with parameters.
    `` | `public void` | `execute(String sql, Object[] params, Closure resultClosure)` Executes the given piece of SQL with parameters.
    `` | `public void` | `execute(String sql, Object[] params, Closure metaClosure, Closure resultClosure)` Executes the given piece of SQL with parameters.
    `` | `public boolean` | `execute(GString gstring)` Executes the given SQL with embedded expressions inside.
    `` | `public void` | `execute(GString gstring, Closure resultClosure)` Executes the given SQL with embedded expressions inside.
    `` | `public void` | `execute(GString gstring, Closure metaClosure, Closure resultClosure)` Executes the given SQL with embedded expressions inside.
    `` | `public List<List<Object>>` | `executeInsert(String sql)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<List<Object>>` | `executeInsert(String sql, List<?> params)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<GroovyRowResult>` | `executeInsert(String sql, List<?> params, List<String> keyColumnNames)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<List<Object>>` | `executeInsert(Map params, String sql)` A variant of executeInsert(String, java.util.List) useful when providing the named parameters as named arguments.
    `` | `public List<GroovyRowResult>` | `executeInsert(Map params, String sql, List<String> keyColumnNames)` A variant of executeInsert(String, List, List) useful when providing the named parameters as named arguments.
    `` | `public List<List<Object>>` | `executeInsert(String sql, Object[] params)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<GroovyRowResult>` | `executeInsert(String sql, String[] keyColumnNames)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<GroovyRowResult>` | `executeInsert(String sql, String[] keyColumnNames, Object[] params)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<List<Object>>` | `executeInsert(GString gstring)` Executes the given SQL statement (typically an INSERT statement).
    `` | `public List<GroovyRowResult>` | `executeInsert(GString gstring, List<String> keyColumnNames)` Executes the given SQL statement (typically an INSERT statement).
    `` | `protected final ResultSet` | `executePreparedQuery(String sql, List<?> params)` Useful helper method which handles resource management when executing a prepared query which returns a result set.
    `` | `protected final ResultSet` | `executeQuery(String sql)` Useful helper method which handles resource management when executing a query which returns a result set.
    `` | `public int` | `executeUpdate(String sql)` Executes the given SQL update.
    `` | `public int` | `executeUpdate(String sql, List<?> params)` Executes the given SQL update with parameters.
    `` | `public int` | `executeUpdate(Map params, String sql)` A variant of executeUpdate(String, java.util.List) useful when providing the named parameters as named arguments.
    `` | `public int` | `executeUpdate(String sql, Object[] params)` Executes the given SQL update with parameters.
    `` | `public int` | `executeUpdate(GString gstring)` Executes the given SQL update with embedded expressions inside.
    `` | `public static ExpandedVariable` | `expand(Object object)` When using GString SQL queries, allows a variable to be expanded in the Sql string rather than representing an sql parameter.
    `` | `protected int` | `findWhereKeyword(String sql)` Hook to allow derived classes to override where clause sniffing.
    `` | `public GroovyRowResult` | `firstRow(String sql)` Performs the given SQL query and return the first row of the result set.
    `` | `public GroovyRowResult` | `firstRow(GString gstring)` Performs the given SQL query and return the first row of the result set.
    `` | `public GroovyRowResult` | `firstRow(String sql, List<?> params)` Performs the given SQL query and return the first row of the result set.
    `` | `public GroovyRowResult` | `firstRow(Map params, String sql)` A variant of firstRow(String, java.util.List) useful when providing the named parameters as named arguments.
    `` | `public GroovyRowResult` | `firstRow(String sql, Object[] params)` Performs the given SQL query and return the first row of the result set.
    `` | `public Connection` | `getConnection()` If this instance was created with a single Connection then the connection is returned.
    `` | `public DataSource` | `getDataSource()` Returns the DataSource backing this instance.
    `` | `protected List<Object>` | `getParameters(GString gstring)` Hook to allow derived classes to override behavior associated with extracting params from a GString.
    `` | `public int` | `getResultSetConcurrency()` Gets the resultSetConcurrency for statements created using the connection.
    `` | `public int` | `getResultSetHoldability()` Gets the resultSetHoldability for statements created using the connection.
    `` | `public int` | `getResultSetType()` Gets the resultSetType for statements created using the connection.
    `` | `public int` | `getUpdateCount()` Returns: Returns the updateCount.
    `` | `public List<Object>` | `getUpdatedParams(List<?> params, List<Tuple> indexPropList)` Resolves the positional parameter list required by a named-parameter query.
    `` | `public static InParameter` | `in(int type, Object value)` Create a new InParameter
    `` | `public static InListParameter` | `inList(Collection<?> values)` Wraps a collection so that it expands to a comma-separated list of positional placeholders when bound to a SQL `IN` clause.
    `` | `public static InOutParameter` | `inout(InParameter in)` Create an inout parameter using this in parameter.
    `` | `public boolean` | `isCacheNamedQueries()` Returns: boolean true if caching is enabled (the default is true)
    `` | `public boolean` | `isCacheStatements()` Returns: boolean true if cache is enabled (default is false)
    `` | `public boolean` | `isEnableNamedQueries()` Returns: boolean true if named query processing is enabled (the default is true)
    `` | `public boolean` | `isWithinBatch()` Returns true if the current Sql object is currently executing a withBatch method call.
    `` | `public static void` | `loadDriver(String driverClassName)` Attempts to load the JDBC driver on the thread, current or system class loaders
    `` | `public static Sql` | `newInstance(String url)` Creates a new Sql instance given a JDBC connection URL.
    `` | `public static Sql` | `newInstance(String url, Properties properties)` Creates a new Sql instance given a JDBC connection URL and some properties.
    `` | `public static Sql` | `newInstance(String url, Properties properties, String driverClassName)` Creates a new Sql instance given a JDBC connection URL, some properties and a driver class name.
    `` | `public static Sql` | `newInstance(String url, String user, String password)` Creates a new Sql instance given a JDBC connection URL, a username and a password.
    `` | `public static Sql` | `newInstance(String url, String user, String password, String driverClassName)` Creates a new Sql instance given a JDBC connection URL, a username, a password and a driver class name.
    `` | `public static Sql` | `newInstance(String url, String driverClassName)` Creates a new Sql instance given a JDBC connection URL and a driver class name.
    `` | `public static Sql` | `newInstance(Map<String, Object> args)` Creates a new Sql instance given parameters in a Map.
    `` | `protected String` | `nullify(String sql)` Hook to allow derived classes to override null handling.
    `` | `public static OutParameter` | `out(int type)` Create a new OutParameter
    `` | `public SqlWithParams` | `preCheckForNamedParams(String sql)` deprecated: Use buildSqlWithIndexedProps(String) instead
    `` | `public void` | `query(String sql, Closure closure)` Performs the given SQL query, which should return a single `ResultSet` object.
    `` | `public void` | `query(String sql, List<?> params, Closure closure)` Performs the given SQL query, which should return a single `ResultSet` object.
    `` | `public void` | `query(String sql, Map map, Closure closure)` A variant of query(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as a map.
    `` | `public void` | `query(Map map, String sql, Closure closure)` A variant of query(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as named arguments.
    `` | `public void` | `query(GString gstring, Closure closure)` Performs the given SQL query, which should return a single `ResultSet` object.
    `` | `public static ResultSetOutParameter` | `resultSet(int type)` Create a new ResultSetOutParameter
    `` | `public void` | `rollback()` If this SQL object was created with a Connection then this method rolls back the connection.
    `` | `public List<GroovyRowResult>` | `rows(String sql)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, int offset, int maxRows)` Performs the given SQL query and return a "page" of rows from the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, Closure metaClosure)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, int offset, int maxRows, Closure metaClosure)` Performs the given SQL query and return a "page" of rows from the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, List<?> params)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(Map params, String sql)` A variant of rows(String, java.util.List) useful when providing the named parameters as named arguments.
    `` | `public List<GroovyRowResult>` | `rows(String sql, List<?> params, int offset, int maxRows)` Performs the given SQL query and return a "page" of rows from the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, Map params, int offset, int maxRows)` A variant of rows(String, java.util.List, int, int) useful when providing the named parameters as a map.
    `` | `public List<GroovyRowResult>` | `rows(Map params, String sql, int offset, int maxRows)` A variant of rows(String, java.util.List, int, int) useful when providing the named parameters as named arguments.
    `` | `public List<GroovyRowResult>` | `rows(String sql, Object[] params)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, Object[] params, int offset, int maxRows)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, List<?> params, Closure metaClosure)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, Map params, Closure metaClosure)` A variant of rows(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as a map.
    `` | `public List<GroovyRowResult>` | `rows(Map params, String sql, Closure metaClosure)` A variant of rows(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as named arguments.
    `` | `public List<GroovyRowResult>` | `rows(String sql, List<?> params, int offset, int maxRows, Closure metaClosure)` Performs the given SQL query and return a "page" of rows from the result set.
    `` | `public List<GroovyRowResult>` | `rows(String sql, Map params, int offset, int maxRows, Closure metaClosure)` A variant of rows(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as a map.
    `` | `public List<GroovyRowResult>` | `rows(Map params, String sql, int offset, int maxRows, Closure metaClosure)` A variant of rows(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as named arguments.
    `` | `public List<GroovyRowResult>` | `rows(GString sql, int offset, int maxRows)` Performs the given SQL query and return a "page" of rows from the result set.
    `` | `public List<GroovyRowResult>` | `rows(GString gstring)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(GString gstring, Closure metaClosure)` Performs the given SQL query and return the rows of the result set.
    `` | `public List<GroovyRowResult>` | `rows(GString gstring, int offset, int maxRows, Closure metaClosure)` Performs the given SQL query and return a "page" of rows from the result set.
    `` | `public void` | `setCacheNamedQueries(boolean cacheNamedQueries)` Enables named query caching.
    `` | `public void` | `setCacheStatements(boolean cacheStatements)` Enables statement caching.
    `` | `public void` | `setEnableNamedQueries(boolean enableNamedQueries)` Enables named query support: if enableNamedQueries is true, queries with ':propname' and '?
    `` | `protected void` | `setInternalConnection(Connection conn)` Stub needed for testing.
    `` | `protected void` | `setObject(PreparedStatement statement, int i, Object value)` Strategy method allowing derived classes to handle types differently such as for CLOBs etc.
    `` | `protected void` | `setParameters(List<?> params, PreparedStatement statement)` Hook to allow derived classes to override behavior associated with setting params for a prepared statement.
    `` | `public void` | `setResultSetConcurrency(int resultSetConcurrency)` Sets the resultSetConcurrency for statements created using the connection.
    `` | `public void` | `setResultSetHoldability(int resultSetHoldability)` Sets the resultSetHoldability for statements created using the connection.
    `` | `public void` | `setResultSetType(int resultSetType)` Sets the resultSetType for statements created using the connection.
    `` | `public int[]` | `withBatch(Closure closure)` Performs the closure (containing batch operations) within a batch.
    `` | `public int[]` | `withBatch(int batchSize, Closure closure)` Performs the closure (containing batch operations) within a batch using a given batch size.
    `` | `public int[]` | `withBatch(String sql, Closure closure)` Performs the closure (containing batch operations specific to an associated prepared statement) within a batch.
    `` | `public int[]` | `withBatch(int batchSize, String sql, Closure closure)` Performs the closure (containing batch operations specific to an associated prepared statement) within a batch using a given batch size.
    `` | `public void` | `withCleanupStatement(Closure cleanupStatement)` Allows a closure to be passed in which acts as a hook for JDBC statements before they are closed.
    `` | `public static void` | `withInstance(String url, Closure c)` Invokes a closure passing it a new Sql instance created from the given JDBC connection URL.
    `` | `public static void` | `withInstance(String url, Properties properties, Closure c)` Invokes a closure passing it a new Sql instance created from the given JDBC connection URL and properties.
    `` | `public static void` | `withInstance(String url, Properties properties, String driverClassName, Closure c)` Invokes a closure passing it a new Sql instance created from the given JDBC connection URL, properties and driver classname.
    `` | `public static void` | `withInstance(String url, String user, String password, Closure c)` Invokes a closure passing it a new Sql instance created from the given JDBC connection URL, user and password.
    `` | `public static void` | `withInstance(String url, String user, String password, String driverClassName, Closure c)` Invokes a closure passing it a new Sql instance created from the given JDBC connection URL.
    `` | `public static void` | `withInstance(String url, String driverClassName, Closure c)` Invokes a closure passing it a new Sql instance created from the given JDBC connection URL.
    `` | `public static void` | `withInstance(Map<String, Object> args, Closure c)` Invokes a closure passing it a new Sql instance created from the given map of arguments.
    `` | `public void` | `withStatement(Closure configureStatement)` Allows a closure to be passed in to configure the JDBC statements before they are executed.
    `` | `public void` | `withTransaction(Closure closure)` Performs the closure within a transaction using a cached connection.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### public static final int ALL_RESULT_SETS

      Indicates that stored-procedure helpers should collect every returned result set.

    - #### public static final OutParameter ARRAY

      Stored procedure OUT parameter marker for JDBC type ARRAY.

    - #### public static final OutParameter BIGINT

      Stored procedure OUT parameter marker for JDBC type BIGINT.

    - #### public static final OutParameter BINARY

      Stored procedure OUT parameter marker for JDBC type BINARY.

    - #### public static final OutParameter BIT

      Stored procedure OUT parameter marker for JDBC type BIT.

    - #### public static final OutParameter BLOB

      Stored procedure OUT parameter marker for JDBC type BLOB.

    - #### public static final OutParameter BOOLEAN

      Stored procedure OUT parameter marker for JDBC type BOOLEAN.

    - #### public static final OutParameter CHAR

      Stored procedure OUT parameter marker for JDBC type CHAR.

    - #### public static final OutParameter CLOB

      Stored procedure OUT parameter marker for JDBC type CLOB.

    - #### public static final OutParameter DATALINK

      Stored procedure OUT parameter marker for JDBC type DATALINK.

    - #### public static final OutParameter DATE

      Stored procedure OUT parameter marker for JDBC type DATE.

    - #### public static final OutParameter DECIMAL

      Stored procedure OUT parameter marker for JDBC type DECIMAL.

    - #### public static final OutParameter DISTINCT

      Stored procedure OUT parameter marker for JDBC type DISTINCT.

    - #### public static final OutParameter DOUBLE

      Stored procedure OUT parameter marker for JDBC type DOUBLE.

    - #### public static final int FIRST_RESULT_SET

      Indicates that stored-procedure helpers should collect only the first returned result set.

    - #### public static final OutParameter FLOAT

      Stored procedure OUT parameter marker for JDBC type FLOAT.

    - #### public static final String INJECTION_LENIENT

      Boolean system property which controls how a quoted dynamic expression (an interpolated GString expression surrounded by SQL quotes, e.g. `"... where name = '${value}'"`) is handled by asSql(GString, List).

      Such a construct can't be expressed as a JDBC PreparedStatement placeholder, so the value would have to be inlined into the SQL string via string concatenation, exposing a SQL injection vulnerability (CWE-89).

      By default (property unset or any value other than `true`) such a query is rejected with a SQLException, giving secure-by-default behaviour. Setting the property to `true` restores the legacy (insecure) behaviour of logging a warning and inlining the value; this is strongly discouraged and provided only for backwards compatibility.

      Since:
        6.0.0

    - #### public static final OutParameter INTEGER

      Stored procedure OUT parameter marker for JDBC type INTEGER.

    - #### public static final OutParameter JAVA_OBJECT

      Stored procedure OUT parameter marker for JDBC type JAVA_OBJECT.

    - #### protected static final Logger LOG

      Hook to allow derived classes to access the log

    - #### public static final OutParameter LONGVARBINARY

      Stored procedure OUT parameter marker for JDBC type LONGVARBINARY.

    - #### public static final OutParameter LONGVARCHAR

      Stored procedure OUT parameter marker for JDBC type LONGVARCHAR.

    - #### public static final int NO_RESULT_SETS

      Indicates that stored-procedure helpers should ignore any returned result sets.

    - #### public static final OutParameter NULL

      Stored procedure OUT parameter marker for JDBC type NULL.

    - #### public static final OutParameter NUMERIC

      Stored procedure OUT parameter marker for JDBC type NUMERIC.

    - #### public static final OutParameter OTHER

      Stored procedure OUT parameter marker for JDBC type OTHER.

    - #### public static final OutParameter REAL

      Stored procedure OUT parameter marker for JDBC type REAL.

    - #### public static final OutParameter REF

      Stored procedure OUT parameter marker for JDBC type REF.

    - #### public static final OutParameter SMALLINT

      Stored procedure OUT parameter marker for JDBC type SMALLINT.

    - #### public static final OutParameter STRUCT

      Stored procedure OUT parameter marker for JDBC type STRUCT.

    - #### public static final OutParameter TIME

      Stored procedure OUT parameter marker for JDBC type TIME.

    - #### public static final OutParameter TIMESTAMP

      Stored procedure OUT parameter marker for JDBC type TIMESTAMP.

    - #### public static final OutParameter TINYINT

      Stored procedure OUT parameter marker for JDBC type TINYINT.

    - #### public static final OutParameter VARBINARY

      Stored procedure OUT parameter marker for JDBC type VARBINARY.

    - #### public static final OutParameter VARCHAR

      Stored procedure OUT parameter marker for JDBC type VARCHAR.

  - ### Constructor Detail

    - #### public Sql(DataSource dataSource)

      Constructs an SQL instance using the given DataSource. Each operation will use a Connection from the DataSource pool and close it when the operation is completed putting it back into the pool.

      Parameters:
        `dataSource` - the DataSource to use

    - #### public Sql(Connection connection)

      Constructs an SQL instance using the given Connection. It is the caller's responsibility to close the Connection after the Sql instance has been used. Depending on which features you are using, you may be able to do this on the connection object directly but the preferred approach is to call the close() method which will close the connection but also free any cached resources.

      Parameters:
        `connection` - the Connection to use

    - #### public Sql(Sql parent)

      Constructs an `Sql` instance backed by the same DataSource or Connection as the supplied parent.

      Parameters:
        `parent` - the Sql instance to copy the connection source from

  - ### Method Detail

    - #### public static InParameter ARRAY(Object value)

      Creates a typed input parameter for JDBC type ARRAY.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter BIGINT(Object value)

      Creates a typed input parameter for JDBC type BIGINT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter BINARY(Object value)

      Creates a typed input parameter for JDBC type BINARY.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter BIT(Object value)

      Creates a typed input parameter for JDBC type BIT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter BLOB(Object value)

      Creates a typed input parameter for JDBC type BLOB.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter BOOLEAN(Object value)

      Creates a typed input parameter for JDBC type BOOLEAN.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter CHAR(Object value)

      Creates a typed input parameter for JDBC type CHAR.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter CLOB(Object value)

      Creates a typed input parameter for JDBC type CLOB.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter DATALINK(Object value)

      Creates a typed input parameter for JDBC type DATALINK.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter DATE(Object value)

      Creates a typed input parameter for JDBC type DATE.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter DECIMAL(Object value)

      Creates a typed input parameter for JDBC type DECIMAL.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter DISTINCT(Object value)

      Creates a typed input parameter for JDBC type DISTINCT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter DOUBLE(Object value)

      Creates a typed input parameter for JDBC type DOUBLE.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter FLOAT(Object value)

      Creates a typed input parameter for JDBC type FLOAT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter INTEGER(Object value)

      Creates a typed input parameter for JDBC type INTEGER.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter JAVA_OBJECT(Object value)

      Creates a typed input parameter for JDBC type JAVA_OBJECT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter LONGVARBINARY(Object value)

      Creates a typed input parameter for JDBC type LONGVARBINARY.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter LONGVARCHAR(Object value)

      Creates a typed input parameter for JDBC type LONGVARCHAR.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter NULL(Object value)

      Creates a typed input parameter for JDBC type NULL.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter NUMERIC(Object value)

      Creates a typed input parameter for JDBC type NUMERIC.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter OTHER(Object value)

      Creates a typed input parameter for JDBC type OTHER.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter REAL(Object value)

      Creates a typed input parameter for JDBC type REAL.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter REF(Object value)

      Creates a typed input parameter for JDBC type REF.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter SMALLINT(Object value)

      Creates a typed input parameter for JDBC type SMALLINT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter STRUCT(Object value)

      Creates a typed input parameter for JDBC type STRUCT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter TIME(Object value)

      Creates a typed input parameter for JDBC type TIME.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter TIMESTAMP(Object value)

      Creates a typed input parameter for JDBC type TIMESTAMP.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter TINYINT(Object value)

      Creates a typed input parameter for JDBC type TINYINT.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter VARBINARY(Object value)

      Creates a typed input parameter for JDBC type VARBINARY.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### public static InParameter VARCHAR(Object value)

      Creates a typed input parameter for JDBC type VARCHAR.

      Parameters:
        `value` - the parameter value
      Returns:
        an input parameter for the supplied value

    - #### protected List<GroovyRowResult> asList(String sql, ResultSet rs)

      Hook to allow derived classes to override list of result collection behavior. The default behavior is to return a list of GroovyRowResult objects corresponding to each row in the ResultSet.

      throws:
        SQLException if a database error occurs
      Parameters:
        `sql` - query to execute
        `rs` - the ResultSet to process
      Returns:
        the resulting list of rows

    - #### protected List<GroovyRowResult> asList(String sql, ResultSet rs, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Hook to allow derived classes to override list of result collection behavior. The default behavior is to return a list of GroovyRowResult objects corresponding to each row in the ResultSet.

      throws:
        SQLException if a database error occurs
      Parameters:
        `sql` - query to execute
        `rs` - the ResultSet to process
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        the resulting list of rows

    - #### protected List<GroovyRowResult> asList(String sql, ResultSet rs, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Hook to allow derived classes to override paged result collection behavior. The default behavior applies the optional metadata callback, moves to the requested offset, and converts up to `maxRows` rows into GroovyRowResult instances.

      throws:
        SQLException if a database error occurs
      Parameters:
        `sql` - query to execute
        `rs` - the ResultSet to process
        `offset` - the 1-based row offset, or `0` to start at the beginning
        `maxRows` - the maximum number of rows to collect, or `0` for no limit
        `metaClosure` - called once with metadata before any rows are read; may be `null`
      Returns:
        the resulting list of rows, or `null` if the offset is beyond the available rows

    - #### protected String asSql(GString gstring, List<?> values)

      Hook to allow derived classes to override sql generation from GStrings.

      throws:
        SQLException if a quoted dynamic expression is detected (a SQL injection risk), unless the {@value #INJECTION_LENIENT} system property is set to `true`
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `values` - the values to embed
      Returns:
        the SQL version of the given query using ? instead of any parameter
      See Also:
        expand(Object)

    - #### protected SqlWithParams buildSqlWithIndexedProps(String sql)

      Hook to allow derived classes to override behavior associated with the parsing and indexing of parameters from a given sql statement.

      Parameters:
        `sql` - the sql statement to process
      Returns:
        a SqlWithParams instance containing the parsed sql and parameters containing the indexed location and property name of parameters or `null` if no parsing of the sql was performed.

    - #### public void cacheConnection(@ClosureParams(value=SimpleType.class, options="java.sql.Connection")
      Closure closure)

      Caches the connection used while the closure is active. If the closure takes a single argument, it will be called with the connection, otherwise it will be called with no arguments.

      throws:
        SQLException if a database error occurs
      Parameters:
        `closure` - the given closure

    - #### public void cacheStatements(@ClosureParams(value=SimpleType.class, options="java.sql.Connection")
      Closure closure)

      Caches every created preparedStatement in Closure closure Every cached preparedStatement is closed after closure has been called. If the closure takes a single argument, it will be called with the connection, otherwise it will be called with no arguments.

      throws:
        SQLException if a database error occurs
      Parameters:
        `closure` - the given closure
      See Also:
        setCacheStatements(boolean)

    - #### public int call(String sql)

      Performs a stored procedure call.

      Example usage (tested with MySQL) - suppose we have the following stored procedure:

           sql.execute """
               CREATE PROCEDURE HouseSwap(_first1 VARCHAR(50), _first2 VARCHAR(50))
               BEGIN
                   DECLARE _loc1 INT;
                   DECLARE _loc2 INT;
                   SELECT location_id into _loc1 FROM PERSON where firstname = _first1;
                   SELECT location_id into _loc2 FROM PERSON where firstname = _first2;
                   UPDATE PERSON
                   set location_id = case firstname
                       when _first1 then _loc2
                       when _first2 then _loc1
                   end
                   where (firstname = _first1 OR firstname = _first2);
               END
           """

      then you can invoke the procedure as follows:

           def rowsChanged = sql.call("{call HouseSwap('Guillaume', 'Paul')}")
           assert rowsChanged == 2

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing

    - #### public int call(GString gstring)

      Performs a stored procedure call with the given embedded parameters.

      Example usage - see call(String) for more details about creating a `HouseSwap(IN name1, IN name2)` stored procedure. Once created, it can be called like this:

           def p1 = 'Paul'
           def p2 = 'Guillaume'
           def rowsChanged = sql.call("{call HouseSwap($p1, $p2)}")
           assert rowsChanged == 2

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      See Also:
        expand(Object)
        call(String)

    - #### public int call(String sql, List<?> params)

      Performs a stored procedure call with the given parameters.

      Example usage - see call(String) for more details about creating a `HouseSwap(IN name1, IN name2)` stored procedure. Once created, it can be called like this:

           def rowsChanged = sql.call("{call HouseSwap(?, ?)}", ['Guillaume', 'Paul'])
           assert rowsChanged == 2

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      See Also:
        call(String)

    - #### public int call(String sql, Object[] params)

      Performs a stored procedure call with the given parameters.

      An Object array variant of call(String, List).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      See Also:
        call(String)

    - #### public int call(String sql, Map params)

      A variant of call(String, List) useful when providing the named parameters as a map. The SQL may contain `:name` style placeholders looked up against the map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      Since:
        6.0.0

    - #### public int call(Map params, String sql)

      A variant of call(String, List) useful when providing the named parameters as named arguments (Groovy named-argument syntax).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      Since:
        6.0.0

    - #### public void call(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Performs a stored procedure call with the given parameters. The closure is called once with all the out parameters.

      Example usage - suppose we create a stored procedure (ignore its simplistic implementation):

           // Tested with MySql 5.0.75
           sql.execute """
               CREATE PROCEDURE Hemisphere(
                   IN p_firstname VARCHAR(50),
                   IN p_lastname VARCHAR(50),
                   OUT ans VARCHAR(50))
               BEGIN
               DECLARE loc INT;
               SELECT location_id into loc FROM PERSON where firstname = p_firstname and lastname = p_lastname;
               CASE loc
                   WHEN 40 THEN
                       SET ans = 'Southern Hemisphere';
                   ELSE
                       SET ans = 'Northern Hemisphere';
               END CASE;
               END;
           """

      we can now call the stored procedure as follows:

           sql.call '{call Hemisphere(?, ?, ?)}', ['Guillaume', 'Laforge', Sql.VARCHAR], { dwells ->
               println dwells
           }

      which will output '`Northern Hemisphere`'.

      We can also access stored functions with scalar return values where the return value will be treated as an OUT parameter. Here are examples for various databases for creating such a procedure:

           // Tested with MySql 5.0.75
           sql.execute """
               create function FullName(p_firstname VARCHAR(40)) returns VARCHAR(80)
               begin
                   declare ans VARCHAR(80);
                   SELECT CONCAT(firstname, ' ', lastname) INTO ans FROM PERSON WHERE firstname = p_firstname;
                   return ans;
               end
           """

           // Tested with MS SQLServer Express 2008
           sql.execute """
               create function FullName(@firstname VARCHAR(40)) returns VARCHAR(80)
               begin
                   declare @ans VARCHAR(80)
                   SET @ans = (SELECT firstname + ' ' + lastname FROM PERSON WHERE firstname = @firstname)
                   return @ans
               end
           """

           // Tested with Oracle XE 10g
           sql.execute """
               create function FullName(p_firstname VARCHAR) return VARCHAR is
               ans VARCHAR(80);
               begin
                   SELECT CONCAT(CONCAT(firstname, ' '), lastname) INTO ans FROM PERSON WHERE firstname = p_firstname;
                   return ans;
               end;
           """

      and here is how you access the stored function for all databases:

           sql.call("{? = call FullName(?)}", [Sql.VARCHAR, 'Sam']) { name ->
               assert name == 'Sam Pullara'
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `closure` - called for each row with a GroovyResultSet

    - #### public void call(GString gstring, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Performs a stored procedure call with the given parameters, calling the closure once with all result objects.

      See call(String, List, Closure) for more details about creating a `Hemisphere(IN first, IN last, OUT dwells)` stored procedure. Once created, it can be called like this:

           def first = 'Scott'
           def last = 'Davis'
           sql.call "{call Hemisphere($first, $last, ${Sql.VARCHAR})}", { dwells ->
               println dwells
           }

      As another example, see call(String, List, Closure) for more details about creating a `FullName(IN first)` stored function. Once created, it can be called like this:

           def first = 'Sam'
           sql.call("{$Sql.VARCHAR = call FullName($first)}") { name ->
               assert name == 'Sam Pullara'
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `closure` - called for each row with a GroovyResultSet
      See Also:
        call(String, List, Closure)
        expand(Object)

    - #### public void call(String sql, Map params, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      A variant of call(String, List, Closure) useful when providing the named parameters as a map. The SQL may contain `:name` style placeholders looked up against the map. Out parameter markers (e.g. VARCHAR) can appear as map values at their named positions.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
        `closure` - called once with all out parameter results
      Since:
        6.0.0

    - #### public void call(Map params, String sql, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      A variant of call(String, List, Closure) useful when providing the named parameters as named arguments (Groovy named-argument syntax).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
        `closure` - called once with all out parameter results
      Since:
        6.0.0

    - #### public List<List<GroovyRowResult>> callWithAllRows(GString gstring, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning a list of lists with the rows of the ResultSet(s).

      Use this when calling a stored procedure that utilizes both output parameters and returns multiple ResultSets.

      Once created, the stored procedure can be called like this:

           def first = 'Jeff'
           def last = 'Sheets'
           def rowsList = sql.callWithAllRows "{call Hemisphere2($first, $last, ${Sql.VARCHAR})}", { dwells ->
               println dwells
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `closure` - called once with all out parameter results
      Returns:
        a list containing lists of GroovyRowResult objects
      See Also:
        callWithAllRows(String, List, Closure)

    - #### public List<List<GroovyRowResult>> callWithAllRows(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning a list of lists with the rows of the ResultSet(s).

      Use this when calling a stored procedure that utilizes both output parameters and returns multiple ResultSets.

      Once created, the stored procedure can be called like this:

           def rowsList = sql.callWithAllRows '{call Hemisphere2(?, ?, ?)}', ['Guillaume', 'Laforge', Sql.VARCHAR], { dwells ->
               println dwells
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `closure` - called once with all out parameter results
      Returns:
        a list containing lists of GroovyRowResult objects
      See Also:
        callWithRows(GString, Closure)

    - #### public List<List<GroovyRowResult>> callWithAllRows(String sql, Map params, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      A variant of callWithAllRows(String, List, Closure) useful when providing the named parameters as a map. The SQL may contain `:name` style placeholders looked up against the map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
        `closure` - called once with all out parameter results
      Returns:
        a list containing lists of GroovyRowResult objects
      Since:
        6.0.0

    - #### public List<List<GroovyRowResult>> callWithAllRows(Map params, String sql, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      A variant of callWithAllRows(String, List, Closure) useful when providing the named parameters as named arguments (Groovy named-argument syntax).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
        `closure` - called once with all out parameter results
      Returns:
        a list containing lists of GroovyRowResult objects
      Since:
        6.0.0

    - #### public List<GroovyRowResult> callWithRows(GString gstring, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning the rows of the ResultSet.

      Use this when calling a stored procedure that utilizes both output parameters and returns a single ResultSet.

      Once created, the stored procedure can be called like this:

           def first = 'Jeff'
           def last = 'Sheets'
           def rows = sql.callWithRows "{call Hemisphere2($first, $last, ${Sql.VARCHAR})}", { dwells ->
               println dwells
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `closure` - called once with all out parameter results
      Returns:
        a list of GroovyRowResult objects
      See Also:
        callWithRows(String, List, Closure)

    - #### public List<GroovyRowResult> callWithRows(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning the rows of the ResultSet.

      Use this when calling a stored procedure that utilizes both output parameters and returns a single ResultSet.

      Once created, the stored procedure can be called like this:

           def rows = sql.callWithRows '{call Hemisphere2(?, ?, ?)}', ['Guillaume', 'Laforge', Sql.VARCHAR], { dwells ->
               println dwells
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `closure` - called once with all out parameter results
      Returns:
        a list of GroovyRowResult objects
      See Also:
        callWithRows(GString, Closure)

    - #### public List<GroovyRowResult> callWithRows(String sql, Map params, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      A variant of callWithRows(String, List, Closure) useful when providing the named parameters as a map. The SQL may contain `:name` style placeholders looked up against the map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
        `closure` - called once with all out parameter results
      Returns:
        a list of GroovyRowResult objects
      Since:
        6.0.0

    - #### public List<GroovyRowResult> callWithRows(Map params, String sql, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      A variant of callWithRows(String, List, Closure) useful when providing the named parameters as named arguments (Groovy named-argument syntax).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
        `closure` - called once with all out parameter results
      Returns:
        a list of GroovyRowResult objects
      Since:
        6.0.0

    - #### protected List<List<GroovyRowResult>> callWithRows(String sql, List<?> params, int processResultsSets, @ClosureParams(value=SimpleType.class, options="java.lang.Object[]")
      Closure closure)

      Base internal method for call(), callWithRows(), and callWithAllRows() style of methods.

      Performs a stored procedure call with the given parameters, calling the closure once with all result objects, and also returning the rows of the ResultSet(s) (if processResultSets is set to Sql.FIRST_RESULT_SET, Sql.ALL_RESULT_SETS)

      Main purpose of processResultSets param is to retain original call() method performance when this is set to Sql.NO_RESULT_SETS

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `processResultsSets` - the result sets to process, either Sql.NO_RESULT_SETS, Sql.FIRST_RESULT_SET, or Sql.ALL_RESULT_SETS
        `closure` - called once with all out parameter results
      Returns:
        a list of GroovyRowResult objects
      See Also:
        callWithRows(String, List, Closure)

    - #### public SqlWithParams checkForNamedParams(String sql, List<?> params)

      Rewrites named or named-ordinal parameter SQL into JDBC positional form and aligns the supplied parameters with the rewritten placeholders.

      Parameters:
        `sql` - the SQL statement to inspect
        `params` - the original parameter values or parameter carrier objects
      Returns:
        the rewritten SQL and ordered parameters, or the original SQL and params when no named-parameter processing is required

    - #### protected void cleanup(Statement statement)

      Provides a hook for derived classes to be able to examine JDBC statements before cleanup/closing. Default behavior is to call a previously saved closure, if any, using the statement as a parameter.

      Parameters:
        `statement` - the statement to clean up
      Since:
        4.0.1

    - #### public void close()

      If this SQL object was created with a Connection then this method closes the connection. If this SQL object was created from a DataSource then this method only frees any cached objects (statements in particular).

    - #### protected void closeResources(Connection connection, Statement statement, ResultSet results)

      An extension point allowing derived classes to change the behavior of resource closing.

      Parameters:
        `connection` - the connection to close
        `statement` - the statement to close
        `results` - the results to close

    - #### protected void closeResources(Connection connection, Statement statement)

      An extension point allowing the behavior of resource closing to be overridden in derived classes.

      Parameters:
        `connection` - the connection to close
        `statement` - the statement to close

    - #### protected void closeResources(Connection connection)

      An extension point allowing the behavior of resource closing to be overridden in derived classes.

      Parameters:
        `connection` - the connection to close

    - #### public void commit()

      If this SQL object was created with a Connection then this method commits the connection. If this SQL object was created from a DataSource then this method does nothing.

      throws:
        SQLException if a database access error occurs

    - #### protected void configure(Statement statement)

      Provides a hook for derived classes to be able to configure JDBC statements. Default behavior is to call a previously saved closure, if any, using the statement as a parameter.

      Parameters:
        `statement` - the statement to configure

    - #### protected Connection createConnection()

      An extension point allowing derived classes to change the behavior of connection creation. The default behavior is to either use the supplied connection or obtain it from the supplied datasource.

      throws:
        java.sql.SQLException if a SQL error occurs
      Returns:
        the connection associated with this Sql

    - #### protected Sql.AbstractQueryCommand createPreparedQueryCommand(String sql, List<?> queryParams)

      Factory for the PreparedQueryCommand command pattern object allows subclass to supply implementations of the command class.

      Parameters:
        `sql` - statement to be executed, including optional parameter placeholders (?)
        `queryParams` - List of parameter values corresponding to parameter placeholders
      Returns:
        a command - invoke its execute() and closeResource() methods
      See Also:
        createQueryCommand(String)

    - #### protected Sql.AbstractQueryCommand createQueryCommand(String sql)

      Factory for the QueryCommand command pattern object allows subclasses to supply implementations of the command class. The factory will be used in a pattern similar to:

           AbstractQueryCommand q = createQueryCommand("update TABLE set count = 0) where count is null");
           try {
               ResultSet rs = q.execute();
               return asList(rs);
           } finally {
               q.closeResources();
           }

      Parameters:
        `sql` - statement to be executed
      Returns:
        a command - invoke its execute() and closeResource() methods

    - #### public DataSet dataSet(String table)

      Creates a DataSet facade for the named table.

      Parameters:
        `table` - the table name to expose as a `DataSet`
      Returns:
        a `DataSet` backed by the supplied table

    - #### public DataSet dataSet(Class<?> type)

      Creates a DataSet facade using the table mapping implied by the supplied type.

      Parameters:
        `type` - the type describing the table to expose
      Returns:
        a `DataSet` backed by the supplied type

    - #### public void eachRow(String sql, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      Performs the given SQL query calling the given Closure with each row of the result set. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values.

      Example usages:

           sql.eachRow("select * from PERSON where firstname like 'S%'") { row ->
              println "$row.firstname ${row[2]}}"
           }

           sql.eachRow "call my_stored_proc_returning_resultset()", {
               println it.firstname
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `closure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `closure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      Performs the given SQL query calling the given `rowClosure` with each row of the result set. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument.

      Example usage:

           def printColNames = { meta ->
               (1..meta.columnCount).each {
                   print meta.getColumnLabel(it).padRight(20)
               }
               println()
           }
           def printRow = { row ->
               row.toRowResult().values().each{ print it.toString().padRight(20) }
               println()
           }
           sql.eachRow("select * from PERSON", printColNames, printRow)

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      Performs the given SQL query calling the given `rowClosure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values.

      In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      Performs the given SQL query calling the given `rowClosure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values.

      In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain placeholder question marks which match the given list of parameters.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, Map map, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      A variant of eachRow(String, java.util.List, groovy.lang.Closure, int, int, groovy.lang.Closure) allowing the named parameters to be supplied in a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `map` - a map containing the named parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(Map map, String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      A variant of eachRow(String, java.util.List, groovy.lang.Closure, int, int, groovy.lang.Closure) allowing the named parameters to be supplied as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `map` - a map containing the named parameters
        `sql` - the sql statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      Performs the given SQL query calling the given Closure with each row of the result set. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain placeholder question marks which match the given list of parameters.

      Example usage:

           def printColNames = { meta ->
               (1..meta.columnCount).each {
                   print meta.getColumnLabel(it).padRight(20)
               }
               println()
           }
           def printRow = { row ->
               row.toRowResult().values().each{ print it.toString().padRight(20) }
               println()
           }
           sql.eachRow("select * from PERSON where lastname like ?", ['%a%'], printColNames, printRow)

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, Map params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      A variant of eachRow(String, java.util.List, groovy.lang.Closure, groovy.lang.Closure) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a map of named parameters
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(Map params, String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      A variant of eachRow(String, java.util.List, groovy.lang.Closure, groovy.lang.Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the sql statement
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      Performs the given SQL query calling the given Closure with each row of the result set. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. The query may contain placeholder question marks which match the given list of parameters.

      Example usage:

           sql.eachRow("select * from PERSON where lastname like ?", ['%a%']) { row ->
               println "${row[1]} $row.lastname"
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `closure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, Map params, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      A variant of eachRow(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a map of named parameters
        `closure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(Map params, String sql, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      A variant of eachRow(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the sql statement
        `closure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(String sql, List<?> params, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. The query may contain placeholder question marks which match the given list of parameters.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `closure` - called for each row with a GroovyResultSet

    - #### public void eachRow(String sql, Map params, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      A variant of eachRow(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a map of named parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `closure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(Map params, String sql, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      A variant of eachRow(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the sql statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `closure` - called for each row with a GroovyResultSet
      Since:
        1.8.7

    - #### public void eachRow(GString gstring, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      Performs the given SQL query calling the given Closure with each row of the result set. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values.

      In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain GString expressions.

      Example usage:

           def location = 25
           def printColNames = { meta ->
               (1..meta.columnCount).each {
                   print meta.getColumnLabel(it).padRight(20)
               }
               println()
           }
           def printRow = { row ->
               row.toRowResult().values().each{ print it.toString().padRight(20) }
               println()
           }
           sql.eachRow("select * from PERSON where location_id < $location", printColNames, printRow)

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `metaClosure` - called for metadata (only once after sql execution)
        `rowClosure` - called for each row with a GroovyResultSet
      See Also:
        expand(Object)

    - #### public void eachRow(GString gstring, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure rowClosure)

      Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain GString expressions.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `metaClosure` - called for metadata (only once after sql execution)
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `rowClosure` - called for each row with a GroovyResultSet

    - #### public void eachRow(GString gstring, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      Performs the given SQL query calling the given `closure` with each row of the result set starting at the provided `offset`, and including up to `maxRows` number of rows. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. The query may contain GString expressions.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `closure` - called for each row with a GroovyResultSet

    - #### public void eachRow(GString gstring, @ClosureParams(value=SimpleType.class, options="groovy.sql.GroovyResultSet")
      Closure closure)

      Performs the given SQL query calling the given Closure with each row of the result set. The row will be a `GroovyResultSet` which is a `ResultSet` that supports accessing the fields using property style notation and ordinal index values. The query may contain GString expressions.

      Example usage:

           def location = 25
           sql.eachRow("select * from PERSON where location_id < $location") { row ->
               println row.firstname
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `closure` - called for each row with a GroovyResultSet
      See Also:
        expand(Object)

    - #### public boolean execute(String sql)

      Executes the given piece of SQL. Also saves the updateCount, if any, for subsequent examination.

      Example usages:

           sql.execute "DROP TABLE IF EXISTS person"

           sql.execute """
               CREATE TABLE person (
                   id INTEGER NOT NULL,
                   firstname VARCHAR(100),
                   lastname VARCHAR(100),
                   location_id INTEGER
               )
           """

           sql.execute """
               INSERT INTO person (id, firstname, lastname, location_id) VALUES (4, 'Paul', 'King', 40)
           """
           assert sql.updateCount == 1

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL to execute
      Returns:
        `true` if the first result is a `ResultSet` object; `false` if it is an update count or there are no results

    - #### public void execute(String sql, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given piece of SQL. Also calls the provided `resultClosure` to process any ResultSet or UpdateCount results that executing the SQL might produce.

      Example usages:

           boolean first = true
           sql.execute "{call FindAllByFirst('J')}", { isResultSet, result ->
             if (first) {
               first = false
               assert !isResultSet && result == 0
             } else {
               assert isResultSet && result == [[ID:1, FIRSTNAME:'James', LASTNAME:'Strachan'], [ID:4, FIRSTNAME:'Jean', LASTNAME:'Gabin']]
             }
           }

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL to execute
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      Since:
        2.3.2

    - #### public void execute(String sql, @ClosureParams(value = SimpleType.class, options = "java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value = FromString.class, options = {"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given piece of SQL. Also calls the provided `resultClosure` to process any ResultSet or UpdateCount results that executing the SQL might produce. In addition, the `metaClosure` will be called for each result producing a ResultSet, if any, passing in the `ResultSetMetaData` as argument.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL to execute
        `metaClosure` - called for metadata (only called for results which produce a ResultSet, if any)
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      Since:
        4.0.21

    - #### public boolean execute(String sql, List<?> params)

      Executes the given piece of SQL with parameters. Also saves the updateCount, if any, for subsequent examination.

      Example usage:

           sql.execute """
               insert into PERSON (id, firstname, lastname, location_id) values (?, ?, ?, ?)
           """, [1, "Guillaume", "Laforge", 10]
           assert sql.updateCount == 1

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
      Returns:
        `true` if the first result is a `ResultSet` object; `false` if it is an update count or there are no results

    - #### public void execute(String sql, List<?> params, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given piece of SQL with parameters. Also calls the provided `resultClosure` to process any ResultSet or UpdateCount results that executing the SQL might produce.

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      See Also:
        execute(String, Closure)
      Since:
        2.3.2

    - #### public void execute(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given piece of SQL with parameters. Also calls the provided `resultClosure` to process any ResultSet or UpdateCount results that executing the SQL might produce. In addition, the `metaClosure` will be called for each result producing a ResultSet, if any, passing in the `ResultSetMetaData` as argument.

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
        `metaClosure` - called for metadata (only called for results which produce a ResultSet, if any)
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      See Also:
        execute(String, Closure)
      Since:
        4.0.21

    - #### public boolean execute(Map params, String sql)

      A variant of execute(String, java.util.List) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - the SQL statement
      Returns:
        `true` if the first result is a `ResultSet` object; `false` if it is an update count or there are no results
      Since:
        1.8.7

    - #### public void execute(Map params, String sql, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      A variant of execute(String, java.util.List, Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - the SQL statement
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      Since:
        2.3.2

    - #### public void execute(Map params, String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      A variant of execute(String, java.util.List, Closure, Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - the SQL statement
        `metaClosure` - called for metadata (only called for results which produce a ResultSet, if any)
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      Since:
        4.0.21

    - #### public boolean execute(String sql, Object[] params)

      Executes the given piece of SQL with parameters.

      An Object array variant of execute(String, List).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
      Returns:
        `true` if the first result is a `ResultSet` object; `false` if it is an update count or there are no results

    - #### public void execute(String sql, Object[] params, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given piece of SQL with parameters.

      An Object array variant of execute(String, List, Closure).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      See Also:
        execute(String, List, Closure)
      Since:
        2.3.2

    - #### public void execute(String sql, Object[] params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given piece of SQL with parameters.

      An Object array variant of execute(String, List, Closure, Closure).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
        `metaClosure` - called for metadata (only called for results which produce a ResultSet, if any)
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      See Also:
        execute(String, List, Closure, Closure)
      Since:
        4.0.21

    - #### public boolean execute(GString gstring)

      Executes the given SQL with embedded expressions inside. Also saves the updateCount, if any, for subsequent examination.

      Example usage:

           def scott = [firstname: "Scott", lastname: "Davis", id: 5, location_id: 50]
           sql.execute """
               insert into PERSON (id, firstname, lastname, location_id) values ($scott.id, $scott.firstname, $scott.lastname, $scott.location_id)
           """
           assert sql.updateCount == 1

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        `true` if the first result is a `ResultSet` object; `false` if it is an update count or there are no results
      See Also:
        expand(Object)

    - #### public void execute(GString gstring, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given SQL with embedded expressions inside. Also calls the provided `resultClosure` to process any ResultSet or UpdateCount results that executing the SQL might produce. Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      See Also:
        expand(Object)
        execute(String, List, Closure)
      Since:
        2.3.2

    - #### public void execute(GString gstring, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure, @ClosureParams(value=FromString.class, options={"boolean,java.util.List", "boolean,int"})
      Closure resultClosure)

      Executes the given SQL with embedded expressions inside. Also calls the provided `resultClosure` to process any ResultSet or UpdateCount results that executing the SQL might produce. In addition, the `metaClosure` will be called for each result producing a ResultSet, if any, passing in the `ResultSetMetaData` as argument. Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `resultClosure` - a Closure which will be passed two parameters: either `true` plus a list of GroovyRowResult values derived from `statement.getResultSet()` or `false` plus the update count from `statement.getUpdateCount()`. The closure will be called for each result produced from executing the SQL.
      See Also:
        expand(Object)
        execute(String, List, Closure, Closure)
      Since:
        4.0.21

    - #### public List<List<Object>> executeInsert(String sql)

      Executes the given SQL statement (typically an INSERT statement). Use this variant when you want to receive the values of any auto-generated columns, such as an autoincrement ID field. See executeInsert(GString) for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - The SQL statement to execute
      Returns:
        A list of the auto-generated column values for each inserted row (typically auto-generated keys)

    - #### public List<List<Object>> executeInsert(String sql, List<?> params)

      Executes the given SQL statement (typically an INSERT statement). Use this variant when you want to receive the values of any auto-generated columns, such as an autoincrement ID field. The query may contain placeholder question marks which match the given list of parameters. See executeInsert(GString) for more details.

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - The SQL statement to execute
        `params` - The parameter values that will be substituted into the SQL statement's parameter slots
      Returns:
        A list of the auto-generated column values for each inserted row (typically auto-generated keys)

    - #### public List<GroovyRowResult> executeInsert(String sql, List<?> params, List<String> keyColumnNames)

      Executes the given SQL statement (typically an INSERT statement). Use this variant when you want to receive the values of any auto-generated columns, such as an autoincrement ID field (or fields) and you know the column name(s) of the ID field(s). The query may contain placeholder question marks which match the given list of parameters. See executeInsert(GString) for more details.

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - The SQL statement to execute
        `params` - The parameter values that will be substituted into the SQL statement's parameter slots
        `keyColumnNames` - a list of column names indicating the columns that should be returned from the inserted row or rows (some drivers may be case-sensitive, e.g. may require uppercase names)
      Returns:
        A list of the auto-generated row results for each inserted row (typically auto-generated keys)
      See Also:
        Connection.prepareStatement
      Since:
        2.3.2

    - #### public List<List<Object>> executeInsert(Map params, String sql)

      A variant of executeInsert(String, java.util.List) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - The SQL statement to execute
      Returns:
        A list of the auto-generated column values for each inserted row (typically auto-generated keys)
      Since:
        1.8.7

    - #### public List<GroovyRowResult> executeInsert(Map params, String sql, List<String> keyColumnNames)

      A variant of executeInsert(String, List, List) useful when providing the named parameters as named arguments. This variant allows you to receive the values of any auto-generated columns, such as an autoincrement ID field (or fields) when you know the column name(s) of the ID field(s).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - The SQL statement to execute
        `keyColumnNames` - a list of column names indicating the columns that should be returned from the inserted row or rows (some drivers may be case-sensitive, e.g. may require uppercase names)
      Returns:
        A list of the auto-generated row results for each inserted row (typically auto-generated keys)
      See Also:
        Connection.prepareStatement
      Since:
        2.3.2

    - #### public List<List<Object>> executeInsert(String sql, Object[] params)

      Executes the given SQL statement (typically an INSERT statement).

      An Object array variant of executeInsert(String, List).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - The SQL statement to execute
        `params` - The parameter values that will be substituted into the SQL statement's parameter slots
      Returns:
        A list of the auto-generated column values for each inserted row (typically auto-generated keys)

    - #### public List<GroovyRowResult> executeInsert(String sql, String[] keyColumnNames)

      Executes the given SQL statement (typically an INSERT statement). This variant allows you to receive the values of any auto-generated columns, such as an autoincrement ID field (or fields) when you know the column name(s) of the ID field(s).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - The SQL statement to execute
        `keyColumnNames` - an array of column names indicating the columns that should be returned from the inserted row or rows (some drivers may be case-sensitive, e.g. may require uppercase names)
      Returns:
        A list of the auto-generated row results for each inserted row (typically auto-generated keys)
      Since:
        2.3.2

    - #### public List<GroovyRowResult> executeInsert(String sql, String[] keyColumnNames, Object[] params)

      Executes the given SQL statement (typically an INSERT statement). This variant allows you to receive the values of any auto-generated columns, such as an autoincrement ID field (or fields) when you know the column name(s) of the ID field(s).

      An array variant of executeInsert(String, List, List).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - The SQL statement to execute
        `keyColumnNames` - an array of column names indicating the columns that should be returned from the inserted row or rows (some drivers may be case-sensitive, e.g. may require uppercase names)
        `params` - The parameter values that will be substituted into the SQL statement's parameter slots
      Returns:
        A list of the auto-generated row results for each inserted row (typically auto-generated keys)
      Since:
        2.3.2

    - #### public List<List<Object>> executeInsert(GString gstring)

      Executes the given SQL statement (typically an INSERT statement). Use this variant when you want to receive the values of any auto-generated columns, such as an autoincrement ID field. The query may contain GString expressions.

      Generated key values can be accessed using array notation. For example, to return the second auto-generated column value of the third row, use `keys[3][1]`. The method is designed to be used with SQL INSERT statements, but is not limited to them.

      The standard use for this method is when a table has an autoincrement ID column and you want to know what the ID is for a newly inserted row. In this example, we insert a single row into a table in which the first column contains the autoincrement ID:

           def sql = Sql.newInstance("jdbc:mysql://localhost:3306/groovy",
                                     "user",
                                     "password",
                                     "com.mysql.jdbc.Driver")

           def keys = sql.executeInsert("insert into test_table (INT_DATA, STRING_DATA) "
                                 + "VALUES (1, 'Key Largo')")

           def id = keys[0][0]

           // 'id' now contains the value of the new row's ID column.
           // It can be used to update an object representation's
           // id attribute for example.
           ...

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        A list of the auto-generated column values for each inserted row (typically auto-generated keys)
      See Also:
        expand(Object)

    - #### public List<GroovyRowResult> executeInsert(GString gstring, List<String> keyColumnNames)

      Executes the given SQL statement (typically an INSERT statement). Use this variant when you want to receive the values of any auto-generated columns, such as an autoincrement ID field (or fields) and you know the column name(s) of the ID field(s).

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `keyColumnNames` - a list of column names indicating the columns that should be returned from the inserted row or rows (some drivers may be case-sensitive, e.g. may require uppercase names)
      Returns:
        A list of the auto-generated row results for each inserted row (typically auto-generated keys)
      See Also:
        Connection.prepareStatement
        expand(Object)
      Since:
        2.3.2

    - #### protected final ResultSet executePreparedQuery(String sql, List<?> params)

      Useful helper method which handles resource management when executing a prepared query which returns a result set. Derived classes of Sql can override "createPreparedQueryCommand" and then call this method to access the ResultSet returned from the provided query.

      throws:
        SQLException if a database error occurs
      Parameters:
        `sql` - query to execute
        `params` - parameters matching question mark placeholders in the query
      Returns:
        the resulting ResultSet

    - #### protected final ResultSet executeQuery(String sql)

      Useful helper method which handles resource management when executing a query which returns a result set. Derived classes of Sql can override "createQueryCommand" and then call this method to access the ResultSet returned from the provided query or alternatively can use the higher-level method of Sql which return result sets which are funnelled through this method, e.g. eachRow, query.

      throws:
        SQLException if a database error occurs
      Parameters:
        `sql` - query to execute
      Returns:
        the resulting ResultSet

    - #### public int executeUpdate(String sql)

      Executes the given SQL update.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL to execute
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing

    - #### public int executeUpdate(String sql, List<?> params)

      Executes the given SQL update with parameters.

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing

    - #### public int executeUpdate(Map params, String sql)

      A variant of executeUpdate(String, java.util.List) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - the SQL statement
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      Since:
        1.8.7

    - #### public int executeUpdate(String sql, Object[] params)

      Executes the given SQL update with parameters.

      An Object array variant of executeUpdate(String, List).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing

    - #### public int executeUpdate(GString gstring)

      Executes the given SQL update with embedded expressions inside.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        the number of rows updated or 0 for SQL statements that return nothing
      See Also:
        expand(Object)

    - #### public static ExpandedVariable expand(Object object)

      When using GString SQL queries, allows a variable to be expanded in the Sql string rather than representing an sql parameter.

      Example usage:

           def fieldName = 'firstname'
           def fieldOp = Sql.expand('like')
           def fieldVal = '%a%'
           sql.query "select * from PERSON where ${Sql.expand(fieldName)} $fieldOp ${fieldVal}", { ResultSet rs ->
               while (rs.next()) println rs.getString('firstname')
           }
           // query will be 'select * from PERSON where firstname like ?'
           // params will be [fieldVal]

      For the common case of expanding a collection into an `IN (...)` clause, prefer inList(Collection) — it produces proper placeholder-bound parameters rather than inlining values as literals and so is safe against SQL injection.

      Parameters:
        `object` - the object of interest
      Returns:
        the expanded variable
      See Also:
        inList(Collection)

    - #### protected int findWhereKeyword(String sql)

      Hook to allow derived classes to override where clause sniffing. Default behavior is to find the first 'where' keyword in the sql doing simple avoidance of the word 'where' within quotes.

      Parameters:
        `sql` - the SQL statement
      Returns:
        the index of the found keyword or -1 if not found

    - #### public GroovyRowResult firstRow(String sql)

      Performs the given SQL query and return the first row of the result set.

      Example usage:

           def ans = sql.firstRow("select * from PERSON where firstname like 'S%'")
           println ans.firstname

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
      Returns:
        a GroovyRowResult object or `null` if no row is found

    - #### public GroovyRowResult firstRow(GString gstring)

      Performs the given SQL query and return the first row of the result set. The query may contain GString expressions.

      Example usage:

           def location = 25
           def ans = sql.firstRow("select * from PERSON where location_id < $location")
           println ans.firstname

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        a GroovyRowResult object or `null` if no row is found
      See Also:
        expand(Object)

    - #### public GroovyRowResult firstRow(String sql, List<?> params)

      Performs the given SQL query and return the first row of the result set. The query may contain placeholder question marks which match the given list of parameters.

      Example usages:

           def ans = sql.firstRow("select * from PERSON where lastname like ?", ['%a%'])
           println ans.firstname

      If your database returns scalar functions as ResultSets, you can also use firstRow to gain access to stored procedure results, e.g. using hsqldb 1.9 RC4:

           sql.execute """
               create function FullName(p_firstname VARCHAR(40)) returns VARCHAR(80)
               BEGIN atomic
               DECLARE ans VARCHAR(80);
               SET ans = (SELECT firstname || ' ' || lastname FROM PERSON WHERE firstname = p_firstname);
               RETURN ans;
               END
           """

           assert sql.firstRow("{call FullName(?)}", ['Sam'])[0] == 'Sam Pullara'

      This method supports named and named ordinal parameters by supplying such parameters in the `params` list. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
      Returns:
        a GroovyRowResult object or `null` if no row is found

    - #### public GroovyRowResult firstRow(Map params, String sql)

      A variant of firstRow(String, java.util.List) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - the SQL statement
      Returns:
        a GroovyRowResult object or `null` if no row is found
      Since:
        1.8.7

    - #### public GroovyRowResult firstRow(String sql, Object[] params)

      Performs the given SQL query and return the first row of the result set.

      An Object array variant of firstRow(String, List).

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
      Returns:
        a GroovyRowResult object or `null` if no row is found

    - #### public Connection getConnection()

      If this instance was created with a single Connection then the connection is returned. Otherwise if this instance was created with a DataSource then this method returns null

      Returns:
        the connection wired into this object, or null if this object uses a DataSource

    - #### public DataSource getDataSource()

      Returns the DataSource backing this instance.

      Returns:
        the configured data source, or `null` when this instance was created directly from a Connection

    - #### protected List<Object> getParameters(GString gstring)

      Hook to allow derived classes to override behavior associated with extracting params from a GString.

      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        extracts the parameters from the expression as a List
      See Also:
        expand(Object)

    - #### public int getResultSetConcurrency()

      Gets the resultSetConcurrency for statements created using the connection.

      Returns:
        the current resultSetConcurrency value
      Since:
        1.5.2

    - #### public int getResultSetHoldability()

      Gets the resultSetHoldability for statements created using the connection.

      Returns:
        the current resultSetHoldability value or -1 if not set
      Since:
        1.5.2

    - #### public int getResultSetType()

      Gets the resultSetType for statements created using the connection.

      Returns:
        the current resultSetType value
      Since:
        1.5.2

    - #### public int getUpdateCount()

      Returns:
        Returns the updateCount.

    - #### public List<Object> getUpdatedParams(List<?> params, List<Tuple> indexPropList)

      Resolves the positional parameter list required by a named-parameter query.

      throws:
        IllegalArgumentException if a referenced parameter index or property is invalid
      Parameters:
        `params` - the original parameter carrier objects
        `indexPropList` - indexed property descriptors produced by buildSqlWithIndexedProps(String)
      Returns:
        the flattened parameter values in JDBC binding order

    - #### public static InParameter in(int type, Object value)

      Create a new InParameter

      Parameters:
        `type` - the JDBC data type
        `value` - the object value
      Returns:
        an InParameter

    - #### public static InListParameter inList(Collection<?> values)

      Wraps a collection so that it expands to a comma-separated list of positional placeholders when bound to a SQL `IN` clause.

      Example usage:

           def ids = [1, 2, 3]
           sql.rows("SELECT name FROM t WHERE id IN (?)", [Sql.inList(ids)])
           // executed as: SELECT name FROM t WHERE id IN (?, ?, ?)
           // params:      [1, 2, 3]

           // GString form:
           sql.rows "SELECT name FROM t WHERE id IN (${Sql.inList(ids)})"

           // Named-parameter form:
           sql.rows("SELECT name FROM t WHERE id IN (:ids)", [ids: Sql.inList(ids)])

      The collection is snapshotted at construction. Null or empty collections are rejected with an IllegalArgumentException — callers must guard empty input explicitly (e.g. return early or omit the clause).

      Supported in the standard execution methods that route through `getPreparedStatement` or `getCallableStatement` — including `rows`, `eachRow`, `firstRow`, `query`, `execute`, `executeInsert`, `executeUpdate`, and the `call` / `callWithRows` / `callWithAllRows` families. Not supported inside `withBatch` blocks: batch operations prepare the statement once and bind a fixed parameter shape, which is incompatible with per-call placeholder expansion.

      throws:
        IllegalArgumentException if `values` is null or empty
      Parameters:
        `values` - the collection to expand; must be non-null and non-empty
      Returns:
        a marker usable as a parameter value in the methods listed above
      Since:
        6.0.0

    - #### public static InOutParameter inout(InParameter in)

      Create an inout parameter using this in parameter.

      Parameters:
        `in` - the InParameter of interest
      Returns:
        the resulting InOutParameter

    - #### public boolean isCacheNamedQueries()

      Returns:
        boolean true if caching is enabled (the default is true)

    - #### public boolean isCacheStatements()

      Returns:
        boolean true if cache is enabled (default is false)

    - #### public boolean isEnableNamedQueries()

      Returns:
        boolean true if named query processing is enabled (the default is true)

    - #### public boolean isWithinBatch()

      Returns true if the current Sql object is currently executing a withBatch method call.

      Returns:
        true if a withBatch call is currently being executed.

    - #### public static void loadDriver(String driverClassName)

      Attempts to load the JDBC driver on the thread, current or system class loaders

      throws:
        ClassNotFoundException if the class cannot be found or loaded
      Parameters:
        `driverClassName` - the fully qualified class name of the driver class

    - #### public static Sql newInstance(String url)

      Creates a new Sql instance given a JDBC connection URL.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
      Returns:
        a new Sql instance with a connection

    - #### public static Sql newInstance(String url, Properties properties)

      Creates a new Sql instance given a JDBC connection URL and some properties.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `properties` - a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
      Returns:
        a new Sql instance with a connection

    - #### public static Sql newInstance(String url, Properties properties, String driverClassName)

      Creates a new Sql instance given a JDBC connection URL, some properties and a driver class name.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `properties` - a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
        `driverClassName` - the fully qualified class name of the driver class
      Returns:
        a new Sql instance with a connection

    - #### public static Sql newInstance(String url, String user, String password)

      Creates a new Sql instance given a JDBC connection URL, a username and a password.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `user` - the database user on whose behalf the connection is being made
        `password` - the user's password
      Returns:
        a new Sql instance with a connection

    - #### public static Sql newInstance(String url, String user, String password, String driverClassName)

      Creates a new Sql instance given a JDBC connection URL, a username, a password and a driver class name.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `user` - the database user on whose behalf the connection is being made
        `password` - the user's password
        `driverClassName` - the fully qualified class name of the driver class
      Returns:
        a new Sql instance with a connection

    - #### public static Sql newInstance(String url, String driverClassName)

      Creates a new Sql instance given a JDBC connection URL and a driver class name.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `driverClassName` - the fully qualified class name of the driver class
      Returns:
        a new Sql instance with a connection

    - #### public static Sql newInstance(@NamedParam(value = "url", type = String.class, required = true)
      @NamedParam(value = "properties", type = Properties.class)
      @NamedParam(value = "driverClassName", type = String.class)
      @NamedParam(value = "driver", type = String.class)
      @NamedParam(value = "user", type = String.class)
      @NamedParam(value = "password", type = String.class)
      @NamedParam(value = "cacheNamedQueries", type = Boolean.class)
      @NamedParam(value = "cacheStatements", type = Boolean.class)
      @NamedParam(value = "enableNamedQueries", type = Boolean.class)
      @NamedParam(value = "resultSetConcurrency", type = Integer.class)
      @NamedParam(value = "resultSetHoldability", type = Integer.class)
      @NamedParam(value = "resultSetType", type = Integer.class)
      Map<String, Object> args)

      Creates a new Sql instance given parameters in a Map. Recognized keys for the Map include:

           driverClassName the fully qualified class name of the driver class
           driver          a synonym for driverClassName
           url             a database url of the form: jdbc:subprotocol:subname
           user            the database user on whose behalf the connection is being made
           password        the user's password
           properties      a list of arbitrary string tag/value pairs as connection arguments;
                           normally at least a "user" and "password" property should be included
           other           any of the public setter methods of this class may be used with property notation
                           e.g. cacheStatements: true, resultSetConcurrency: ResultSet.CONCUR_READ_ONLY

      Of these, '`url`' is required. Others may be needed depending on your database.
      If '`properties`' is supplied, neither '`user`' nor '`password`' should be supplied.
      If one of '`user`' or '`password`' is supplied, both should be supplied.

      Example usage:

           import groovy.sql.Sql
           import static java.sql.ResultSet.*

           def sql = Sql.newInstance(
               url:'jdbc:hsqldb:mem:testDB',
               user:'sa',
               password:'',
               driver:'org.hsqldb.jdbc.JDBCDriver',
               cacheStatements: true,
               resultSetConcurrency: CONCUR_READ_ONLY
           )

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `args` - a Map contain further arguments
      Returns:
        a new Sql instance with a connection

    - #### protected String nullify(String sql)

      Hook to allow derived classes to override null handling. Default behavior is to replace ?'"? references with NULLish

      Parameters:
        `sql` - the SQL statement
      Returns:
        the modified SQL String

    - #### public static OutParameter out(int type)

      Create a new OutParameter

      Parameters:
        `type` - the JDBC data type.
      Returns:
        an OutParameter

    - #### @Deprecated
      public SqlWithParams preCheckForNamedParams(String sql)

      deprecated:
        Use buildSqlWithIndexedProps(String) instead

    - #### public void query(String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSet")
      Closure closure)

      Performs the given SQL query, which should return a single `ResultSet` object. The given closure is called with the `ResultSet` as its argument.

      Example usages:

           sql.query("select * from PERSON where firstname like 'S%'") { ResultSet rs ->
               while (rs.next()) println rs.getString('firstname') + ' ' + rs.getString(3)
           }

           sql.query("call get_people_places()") { ResultSet rs ->
               while (rs.next()) println rs.toRowResult().firstname
           }

      All resources including the ResultSet are closed automatically after the closure is called.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `closure` - called for each row with a `ResultSet`

    - #### public void query(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSet")
      Closure closure)

      Performs the given SQL query, which should return a single `ResultSet` object. The given closure is called with the `ResultSet` as its argument. The query may contain placeholder question marks which match the given list of parameters.

      Example usage:

           sql.query('select * from PERSON where lastname like ?', ['%a%']) { ResultSet rs ->
               while (rs.next()) println rs.getString('lastname')
           }

      This method supports named and named ordinal parameters. See the class Javadoc for more details.

      All resources including the ResultSet are closed automatically after the closure is called.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `params` - a list of parameters
        `closure` - called for each row with a `ResultSet`

    - #### public void query(String sql, Map map, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSet")
      Closure closure)

      A variant of query(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the sql statement
        `map` - a map containing the named parameters
        `closure` - called for each row with a `ResultSet`
      Since:
        1.8.7

    - #### public void query(Map map, String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSet")
      Closure closure)

      A variant of query(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `map` - a map containing the named parameters
        `sql` - the sql statement
        `closure` - called for each row with a `ResultSet`
      Since:
        1.8.7

    - #### public void query(GString gstring, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSet")
      Closure closure)

      Performs the given SQL query, which should return a single `ResultSet` object. The given closure is called with the `ResultSet` as its argument. The query may contain GString expressions.

      Example usage:

           def location = 25
           sql.query "select * from PERSON where location_id < $location", { ResultSet rs ->
               while (rs.next()) println rs.getString('firstname')
           }

      All resources including the ResultSet are closed automatically after the closure is called.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `closure` - called for each row with a `ResultSet`
      See Also:
        expand(Object)

    - #### public static ResultSetOutParameter resultSet(int type)

      Create a new ResultSetOutParameter

      Parameters:
        `type` - the JDBC data type.
      Returns:
        a ResultSetOutParameter

    - #### public void rollback()

      If this SQL object was created with a Connection then this method rolls back the connection. If this SQL object was created from a DataSource then this method does nothing.

      throws:
        SQLException if a database access error occurs

    - #### public List<GroovyRowResult> rows(String sql)

      Performs the given SQL query and return the rows of the result set.

      Example usage:

           def ans = sql.rows("select * from PERSON where firstname like 'S%'")
           println "Found ${ans.size()} rows"

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, int offset, int maxRows)

      Performs the given SQL query and return a "page" of rows from the result set. A page is defined as starting at a 1-based offset, and containing a maximum number of rows.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Performs the given SQL query and return the rows of the result set. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument.

      Example usage:

           def printNumCols = { meta -> println "Found $meta.columnCount columns" }
           def ans = sql.rows("select * from PERSON", printNumCols)
           println "Found ${ans.size()} rows"

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `metaClosure` - called with metadata of the ResultSet
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Performs the given SQL query and return a "page" of rows from the result set. A page is defined as starting at a 1-based offset, and containing a maximum number of rows. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, List<?> params)

      Performs the given SQL query and return the rows of the result set. The query may contain placeholder question marks which match the given list of parameters.

      Example usage:

           def ans = sql.rows("select * from PERSON where lastname like ?", ['%a%'])
           println "Found ${ans.size()} rows"

      This method supports named and named ordinal parameters by supplying such parameters in the `params` list. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(Map params, String sql)

      A variant of rows(String, java.util.List) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map containing the named parameters
        `sql` - the SQL statement
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(String sql, List<?> params, int offset, int maxRows)

      Performs the given SQL query and return a "page" of rows from the result set. A page is defined as starting at a 1-based offset, and containing a maximum number of rows. The query may contain placeholder question marks which match the given list of parameters.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      This method supports named and named ordinal parameters by supplying such parameters in the `params` list. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, Map params, int offset, int maxRows)

      A variant of rows(String, java.util.List, int, int) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(Map params, String sql, int offset, int maxRows)

      A variant of rows(String, java.util.List, int, int) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(String sql, Object[] params)

      Performs the given SQL query and return the rows of the result set.

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      An Object array variant of rows(String, List).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, Object[] params, int offset, int maxRows)

      Performs the given SQL query and return the rows of the result set.

      This method supports named and named ordinal parameters by supplying such parameters in the `params` array. See the class Javadoc for more details.

      An Object array variant of rows(String, List, int, int).

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - an array of parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, List<?> params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Performs the given SQL query and return the rows of the result set. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain placeholder question marks which match the given list of parameters.

      Example usage:

           def printNumCols = { meta -> println "Found $meta.columnCount columns" }
           def ans = sql.rows("select * from PERSON where lastname like ?", ['%a%'], printNumCols)
           println "Found ${ans.size()} rows"

      This method supports named and named ordinal parameters by supplying such parameters in the `params` list. Here is an example:

           def printNumCols = { meta -> println "Found $meta.columnCount columns" }

           def mapParam = [foo: 'Smith']
           def domainParam = new MyDomainClass(bar: 'John')
           def qry = 'select * from PERSON where lastname=?1.foo and firstname=?2.bar'
           def ans = sql.rows(qry, [mapParam, domainParam], printNumCols)
           println "Found ${ans.size()} rows"

           def qry2 = 'select * from PERSON where firstname=:first and lastname=:last'
           def ans2 = sql.rows(qry2, [[last:'Smith', first:'John']], printNumCols)
           println "Found ${ans2.size()} rows"

      See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, Map params, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      A variant of rows(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(Map params, String sql, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      A variant of rows(String, java.util.List, groovy.lang.Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(String sql, List<?> params, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Performs the given SQL query and return a "page" of rows from the result set. A page is defined as starting at a 1-based offset, and containing a maximum number of rows. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain placeholder question marks which match the given list of parameters.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      This method supports named and named ordinal parameters by supplying such parameters in the `params` list. See the class Javadoc for more details.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a list of parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(String sql, Map params, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      A variant of rows(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as a map.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `params` - a map of named parameters
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(Map params, String sql, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      A variant of rows(String, java.util.List, int, int, groovy.lang.Closure) useful when providing the named parameters as named arguments.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - a map of named parameters
        `sql` - the SQL statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects
      Since:
        1.8.7

    - #### public List<GroovyRowResult> rows(GString sql, int offset, int maxRows)

      Performs the given SQL query and return a "page" of rows from the result set. A page is defined as starting at a 1-based offset, and containing a maximum number of rows. The query may contain GString expressions.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `sql` - the SQL statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
      Returns:
        a list of GroovyRowResult objects

    - #### public List<GroovyRowResult> rows(GString gstring)

      Performs the given SQL query and return the rows of the result set. The query may contain GString expressions.

      Example usage:

           def location = 25
           def ans = sql.rows("select * from PERSON where location_id < $location")
           println "Found ${ans.size()} rows"

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
      Returns:
        a list of GroovyRowResult objects
      See Also:
        expand(Object)

    - #### public List<GroovyRowResult> rows(GString gstring, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Performs the given SQL query and return the rows of the result set. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain GString expressions.

      Example usage:

           def location = 25
           def printNumCols = { meta -> println "Found $meta.columnCount columns" }
           def ans = sql.rows("select * from PERSON where location_id < $location", printNumCols)
           println "Found ${ans.size()} rows"

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - a GString containing the SQL query with embedded params
        `metaClosure` - called with metadata of the ResultSet
      Returns:
        a list of GroovyRowResult objects
      See Also:
        expand(Object)

    - #### public List<GroovyRowResult> rows(GString gstring, int offset, int maxRows, @ClosureParams(value=SimpleType.class, options="java.sql.ResultSetMetaData")
      Closure metaClosure)

      Performs the given SQL query and return a "page" of rows from the result set. A page is defined as starting at a 1-based offset, and containing a maximum number of rows. In addition, the `metaClosure` will be called once passing in the `ResultSetMetaData` as argument. The query may contain GString expressions.

      Note that the underlying implementation is based on either invoking `ResultSet.absolute()`, or if the ResultSet type is `ResultSet.TYPE_FORWARD_ONLY`, the `ResultSet.next()` method is invoked equivalently. The first row of a ResultSet is 1, so passing in an offset of 1 or less has no effect on the initial positioning within the result set.

      Note that different database and JDBC driver implementations may work differently with respect to this method. Specifically, one should expect that `ResultSet.TYPE_FORWARD_ONLY` may be less efficient than a "scrollable" type.

      Resource handling is performed automatically where appropriate.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `gstring` - the SQL statement
        `offset` - the 1-based offset for the first row to be processed
        `maxRows` - the maximum number of rows to be processed
        `metaClosure` - called for metadata (only once after sql execution)
      Returns:
        a list of GroovyRowResult objects

    - #### public void setCacheNamedQueries(boolean cacheNamedQueries)

      Enables named query caching.
      if cacheNamedQueries is true, cache is created and processed named queries will be cached. if cacheNamedQueries is false, no caching will occur saving memory at the cost of additional processing time.

      Parameters:
        `cacheNamedQueries` - the new value

    - #### public void setCacheStatements(boolean cacheStatements)

      Enables statement caching.
      if cacheStatements is true, cache is created and all created prepared statements will be cached. if cacheStatements is false, all cached statements will be properly closed.

      Parameters:
        `cacheStatements` - the new value

    - #### public void setEnableNamedQueries(boolean enableNamedQueries)

      Enables named query support:

      - if enableNamedQueries is true, queries with ':propname' and '?1.propname' style placeholders will be processed.
      - if enableNamedQueries is false, this feature will be turned off.
      Parameters:
        `enableNamedQueries` - the new value

    - #### protected void setInternalConnection(Connection conn)

      Stub needed for testing. Called when a connection is opened by one of the command-pattern classes so that a test case can monitor the state of the connection through its subclass.

      Parameters:
        `conn` - the connection that is about to be used by a command

    - #### protected void setObject(PreparedStatement statement, int i, Object value)

      Strategy method allowing derived classes to handle types differently such as for CLOBs etc.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `statement` - the statement of interest
        `i` - the index of the object of interest
        `value` - the new object value

    - #### protected void setParameters(List<?> params, PreparedStatement statement)

      Hook to allow derived classes to override behavior associated with setting params for a prepared statement. Default behavior is to append the parameters to the given statement using `setObject`.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `params` - the parameters to append
        `statement` - the statement

    - #### public void setResultSetConcurrency(int resultSetConcurrency)

      Sets the resultSetConcurrency for statements created using the connection. May cause SQLFeatureNotSupportedException exceptions to occur if the underlying database doesn't support the requested concurrency value.

      Parameters:
        `resultSetConcurrency` - one of the following `ResultSet` constants: `ResultSet.CONCUR_READ_ONLY` or `ResultSet.CONCUR_UPDATABLE`
      Since:
        1.5.2

    - #### public void setResultSetHoldability(int resultSetHoldability)

      Sets the resultSetHoldability for statements created using the connection. May cause SQLFeatureNotSupportedException exceptions to occur if the underlying database doesn't support the requested holdability value.

      Parameters:
        `resultSetHoldability` - one of the following `ResultSet` constants: `ResultSet.HOLD_CURSORS_OVER_COMMIT` or `ResultSet.CLOSE_CURSORS_AT_COMMIT`
      Since:
        1.5.2

    - #### public void setResultSetType(int resultSetType)

      Sets the resultSetType for statements created using the connection. May cause SQLFeatureNotSupportedException exceptions to occur if the underlying database doesn't support the requested type value.

      Parameters:
        `resultSetType` - one of the following `ResultSet` constants: `ResultSet.TYPE_FORWARD_ONLY`, `ResultSet.TYPE_SCROLL_INSENSITIVE`, or `ResultSet.TYPE_SCROLL_SENSITIVE`
      Since:
        1.5.2

    - #### public int[] withBatch(@ClosureParams(value=SimpleType.class, options="groovy.sql.BatchingStatementWrapper")
      Closure closure)

      Performs the closure (containing batch operations) within a batch. Uses a batch size of zero, i.e. no automatic partitioning of batches.

      This means that `executeBatch()` will be called automatically after the `withBatch` closure has finished but may be called explicitly if desired as well for more fine-grained partitioning of the batch.

      The closure will be called with a single argument; the database statement (actually a `BatchingStatementWrapper` helper object) associated with this batch.

      Use it like this:

           def updateCounts = sql.withBatch { stmt ->
               stmt.addBatch("insert into TABLENAME ...")
               stmt.addBatch("insert into TABLENAME ...")
               stmt.addBatch("insert into TABLENAME ...")
               ...
           }

      For integrity and performance reasons, you may wish to consider executing your batch command(s) within a transaction:

           sql.withTransaction {
               def result1 = sql.withBatch { ... }
               ...
           }

      throws:
        SQLException if a database access error occurs, or this method is called on a closed `Statement`, or the driver does not support batch statements. Throws BatchUpdateException (a subclass of `SQLException`) if one of the commands sent to the database fails to execute properly or attempts to return a result set.
      Parameters:
        `closure` - the closure containing batch and optionally other statements
      Returns:
        an array of update counts containing one element for each command in the batch. The elements of the array are ordered according to the order in which commands were added to the batch.
      See Also:
        withBatch(int, Closure)

    - #### public int[] withBatch(int batchSize, @ClosureParams(value=SimpleType.class, options="groovy.sql.BatchingStatementWrapper")
      Closure closure)

      Performs the closure (containing batch operations) within a batch using a given batch size.

      After every `batchSize` `addBatch(sqlBatchOperation)` operations, automatically calls an `executeBatch()` operation to "chunk" up the database operations into partitions. Though not normally needed, you can also explicitly call `executeBatch()` which after executing the current batch, resets the batch count back to zero.

      The closure will be called with a single argument; the database statement (actually a `BatchingStatementWrapper` helper object) associated with this batch.

      Use it like this for batchSize of 20:

           def updateCounts = sql.withBatch(20) { stmt ->
               stmt.addBatch("insert into TABLENAME ...")
               stmt.addBatch("insert into TABLENAME ...")
               stmt.addBatch("insert into TABLENAME ...")
               ...
           }

      For integrity and performance reasons, you may wish to consider executing your batch command(s) within a transaction:

           sql.withTransaction {
               def result1 = sql.withBatch { ... }
               ...
           }

      throws:
        SQLException if a database access error occurs, or this method is called on a closed `Statement`, or the driver does not support batch statements. Throws BatchUpdateException (a subclass of `SQLException`) if one of the commands sent to the database fails to execute properly or attempts to return a result set.
      Parameters:
        `batchSize` - partition the batch into batchSize pieces, i.e. after batchSize `addBatch()` invocations, call `executeBatch()` automatically; 0 means manual calls to executeBatch are required
        `closure` - the closure containing batch and optionally other statements
      Returns:
        an array of update counts containing one element for each command in the batch. The elements of the array are ordered according to the order in which commands were added to the batch.
      See Also:
        withBatch(Closure)
        BatchingStatementWrapper
        Statement

    - #### public int[] withBatch(String sql, @ClosureParams(value=SimpleType.class, options="groovy.sql.BatchingPreparedStatementWrapper")
      Closure closure)

      Performs the closure (containing batch operations specific to an associated prepared statement) within a batch. Uses a batch size of zero, i.e. no automatic partitioning of batches.

      This means that `executeBatch()` will be called automatically after the `withBatch` closure has finished but may be called explicitly if desired as well for more fine-grained partitioning of the batch.

      The closure will be called with a single argument; the prepared statement (actually a `BatchingPreparedStatementWrapper` helper object) associated with this batch.

      An example:

           def updateCounts = sql.withBatch('insert into TABLENAME(a, b, c) values (?, ?, ?)') { ps ->
               ps.addBatch([10, 12, 5])
               ps.addBatch([7, 3, 98])
               ps.addBatch(22, 67, 11)
               def partialUpdateCounts = ps.executeBatch() // optional interim batching
               ps.addBatch(30, 40, 50)
               ...
           }

      For integrity and performance reasons, you may wish to consider executing your batch command(s) within a transaction:

           sql.withTransaction {
               def result1 = sql.withBatch { ... }
               ...
           }

      throws:
        SQLException if a database access error occurs, or this method is called on a closed `Statement`, or the driver does not support batch statements. Throws BatchUpdateException (a subclass of `SQLException`) if one of the commands sent to the database fails to execute properly or attempts to return a result set.
      Parameters:
        `sql` - batch update statement
        `closure` - the closure containing batch statements (to bind parameters) and optionally other statements
      Returns:
        an array of update counts containing one element for each binding in the batch. The elements of the array are ordered according to the order in which commands were executed.
      See Also:
        withBatch(int, String, Closure)
        BatchingPreparedStatementWrapper
        PreparedStatement

    - #### public int[] withBatch(int batchSize, String sql, @ClosureParams(value=SimpleType.class, options="groovy.sql.BatchingPreparedStatementWrapper")
      Closure closure)

      Performs the closure (containing batch operations specific to an associated prepared statement) within a batch using a given batch size.

      After every `batchSize` `addBatch(params)` operations, automatically calls an `executeBatch()` operation to "chunk" up the database operations into partitions. Though not normally needed, you can also explicitly call `executeBatch()` which after executing the current batch, resets the batch count back to zero.

      The closure will be called with a single argument; the prepared statement (actually a `BatchingPreparedStatementWrapper` helper object) associated with this batch.

      Below is an example using a batchSize of 20:

           def updateCounts = sql.withBatch(20, 'insert into TABLENAME(a, b, c) values (?, ?, ?)') { ps ->
               ps.addBatch(10, 12, 5)      // varargs style
               ps.addBatch([7, 3, 98])     // list
               ps.addBatch([22, 67, 11])
               ...
           }

      Named parameters (into maps or domain objects) are also supported:

           def updateCounts = sql.withBatch(20, 'insert into TABLENAME(a, b, c) values (:foo, :bar, :baz)') { ps ->
               ps.addBatch([foo:10, bar:12, baz:5])  // map
               ps.addBatch(foo:7, bar:3, baz:98)     // Groovy named args allow outer brackets to be dropped
               ...
           }

      Named ordinal parameters (into maps or domain objects) are also supported:

           def updateCounts = sql.withBatch(20, 'insert into TABLENAME(a, b, c) values (?1.foo, ?2.bar, ?2.baz)') { ps ->
               ps.addBatch([[foo:22], [bar:67, baz:11]])  // list of maps or domain objects
               ps.addBatch([foo:10], [bar:12, baz:5])     // varargs allows outer brackets to be dropped
               ps.addBatch([foo:7], [bar:3, baz:98])
               ...
           }
           // swap to batch size of 5 and illustrate simple and domain object cases ...
           class Person { String first, last }
           def updateCounts2 = sql.withBatch(5, 'insert into PERSON(id, first, last) values (?1, ?2.first, ?2.last)') { ps ->
               ps.addBatch(1, new Person(first:'Peter', last:'Pan'))
               ps.addBatch(2, new Person(first:'Snow', last:'White'))
               ...
           }

      For integrity and performance reasons, you may wish to consider executing your batch command(s) within a transaction:

           sql.withTransaction {
               def result1 = sql.withBatch { ... }
               ...
           }

      throws:
        SQLException if a database access error occurs, or this method is called on a closed `Statement`, or the driver does not support batch statements. Throws BatchUpdateException (a subclass of `SQLException`) if one of the commands sent to the database fails to execute properly or attempts to return a result set.
      Parameters:
        `batchSize` - partition the batch into batchSize pieces, i.e. after batchSize `addBatch()` invocations, call `executeBatch()` automatically; 0 means manual calls to executeBatch are required if additional partitioning of the batch is required
        `sql` - batch update statement
        `closure` - the closure containing batch statements (to bind parameters) and optionally other statements
      Returns:
        an array of update counts containing one element for each binding in the batch. The elements of the array are ordered according to the order in which commands were executed.
      See Also:
        BatchingPreparedStatementWrapper
        PreparedStatement

    - #### public void withCleanupStatement(@ClosureParams(value=SimpleType.class, options="java.sql.Statement")
      Closure cleanupStatement)

      Allows a closure to be passed in which acts as a hook for JDBC statements before they are closed. It can be used to do things like check SQL warnings, e.g.:

           sql.withCleanupStatement{ stmt -> assert !stmt.warnings }
           def rows = sql.rows("select * from table")

      Parameters:
        `cleanupStatement` - the closure
      Since:
        4.0.1

    - #### public static void withInstance(String url, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given JDBC connection URL. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `c` - the Closure to call
      See Also:
        newInstance(String)

    - #### public static void withInstance(String url, Properties properties, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given JDBC connection URL and properties. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `properties` - a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
        `c` - the Closure to call
      See Also:
        newInstance(String, java.util.Properties)

    - #### public static void withInstance(String url, Properties properties, String driverClassName, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given JDBC connection URL, properties and driver classname. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `properties` - a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
        `driverClassName` - the fully qualified class name of the driver class
        `c` - the Closure to call
      See Also:
        newInstance(String, java.util.Properties, String)

    - #### public static void withInstance(String url, String user, String password, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given JDBC connection URL, user and password. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `user` - the database user on whose behalf the connection is being made
        `password` - the user's password
        `c` - the Closure to call
      See Also:
        newInstance(String, String, String)

    - #### public static void withInstance(String url, String user, String password, String driverClassName, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given JDBC connection URL. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `user` - the database user on whose behalf the connection is being made
        `password` - the user's password
        `driverClassName` - the fully qualified class name of the driver class
        `c` - the Closure to call
      See Also:
        newInstance(String, String, String, String)

    - #### public static void withInstance(String url, String driverClassName, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given JDBC connection URL. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `url` - a database url of the form `jdbc:subprotocol:subname`
        `driverClassName` - the fully qualified class name of the driver class
        `c` - the Closure to call
      See Also:
        newInstance(String, String)

    - #### public static void withInstance(@NamedParam(value = "url", type = String.class, required = true)
      @NamedParam(value = "properties", type = Properties.class)
      @NamedParam(value = "driverClassName", type = String.class)
      @NamedParam(value = "driver", type = String.class)
      @NamedParam(value = "user", type = String.class)
      @NamedParam(value = "password", type = String.class)
      @NamedParam(value = "cacheNamedQueries", type = Boolean.class)
      @NamedParam(value = "cacheStatements", type = Boolean.class)
      @NamedParam(value = "enableNamedQueries", type = Boolean.class)
      @NamedParam(value = "resultSetConcurrency", type = Integer.class)
      @NamedParam(value = "resultSetHoldability", type = Integer.class)
      @NamedParam(value = "resultSetType", type = Integer.class)
      Map<String, Object> args, @ClosureParams(value=SimpleType.class, options="groovy.sql.Sql")
      Closure c)

      Invokes a closure passing it a new Sql instance created from the given map of arguments. The created connection will be closed if required.

      throws:
        SQLException if a database access error occurs
      throws:
        ClassNotFoundException if the driver class cannot be found or loaded
      Parameters:
        `args` - a Map contain further arguments
        `c` - the Closure to call
      See Also:
        newInstance(java.util.Map)

    - #### public void withStatement(@ClosureParams(value=SimpleType.class, options="java.sql.Statement")
      Closure configureStatement)

      Allows a closure to be passed in to configure the JDBC statements before they are executed. It can be used to do things like set the query size etc. When this method is invoked, the supplied closure is saved. Statements subsequently created from other methods will then be configured using this closure. The statement being configured is passed into the closure as its single argument, e.g.:

           sql.withStatement{ stmt -> stmt.maxRows = 10 }
           def firstTenRows = sql.rows("select * from table")

      Parameters:
        `configureStatement` - the closure

    - #### public void withTransaction(@ClosureParams(value=SimpleType.class, options="java.sql.Connection")
      Closure closure)

      Performs the closure within a transaction using a cached connection. If the closure takes a single argument, it will be called with the connection, otherwise it will be called with no arguments.

      throws:
        SQLException if a database error occurs
      Parameters:
        `closure` - the given closure