== Vert.x Common SQL interface

The common SQL interface is used to interact with Vert.x SQL services.

You obtain a connection to the database via the service interface for the specific SQL service that
you are using (e.g. JDBC/MySQL/PostgreSQL).

To use this project, add the following dependency to the _dependencies_ section of your build descriptor:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-sql-common</artifactId>
  <version>3.1.0</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
compile io.vertx:vertx-sql-common:3.1.0
----

== The SQL Connection

A connection to the database is represented by `link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html[SQLConnection]`.

=== Auto-commit

When you obtain a connection auto commit is set to `true`. This means that each operation you perform will effectively
execute in its own transaction.

If you wish to perform multiple operations in a single transaction you should set auto commit to false with
`link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#setAutoCommit(boolean,%20io.vertx.core.Handler)[setAutoCommit]`.

When the operation is complete, the handler will be called:

[source,java]
----
connection.setAutoCommit(false, { res ->
  if (res.succeeded()) {
    // OK!
  } else {
    // Failed!
  }
})

----

=== Executing queries

To execute a query use `link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#query(java.lang.String,%20io.vertx.core.Handler)[query]`

The query string is raw SQL that is passed through without changes to the actual database.

The handler will be called with the results, represented by `link:../dataobjects.html#ResultSet[ResultSet]` when the query has
been run.

[source,java]
----
connection.query("SELECT ID, FNAME, LNAME, SHOE_SIZE from PEOPLE", { res ->
  if (res.succeeded()) {
    // Get the result set
    def resultSet = res.result()
  } else {
    // Failed!
  }
})

----

The `link:../dataobjects.html#ResultSet[ResultSet]` instance represents the results of a query.

The list of column names are available with `link:../dataobjects.html#ResultSet#getColumnNames()[getColumnNames]`, and the actual results
available with `link:../dataobjects.html#ResultSet#getResults()[getResults]`

The results are a list of `JsonArray` instances, one for each row of the results.

[source,java]
----

def columnNames = resultSet.columnNames

def results = resultSet.results

results.each { row ->

  def id = row[0]
  def fName = row[1]
  def lName = row[2]
  def shoeSize = row[3]

}


----

You can also retrieve the rows as a list of Json object instances with `link:../dataobjects.html#ResultSet#getRows()[getRows]` -
this can give you a somewhat simpler API to work with, but please be aware that SQL results can contain duplicate
column names - if that's the case you should use `link:../dataobjects.html#ResultSet#getResults()[getResults]` instead.

Here's an example of iterating through the results as Json object instances:

[source,java]
----

def rows = resultSet.rows

rows.each { row ->

  def id = row.ID
  def fName = row.FNAME
  def lName = row.LNAME
  def shoeSize = row.SHOE_SIZE

}


----

=== Prepared statement queries

To execute a prepared statement query you can use
`link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#queryWithParams(java.lang.String,%20io.vertx.core.json.JsonArray,%20io.vertx.core.Handler)[queryWithParams]`.

This takes the query, containing the parameter place holders, and a `JsonArray` or parameter
values.

[source,java]
----

def query = "SELECT ID, FNAME, LNAME, SHOE_SIZE from PEOPLE WHERE LNAME=? AND SHOE_SIZE > ?"
def params = [
  "Fox",
  9
]

connection.queryWithParams(query, params, { res ->

  if (res.succeeded()) {
    // Get the result set
    def resultSet = res.result()
  } else {
    // Failed!
  }
})


----

=== Executing INSERT, UPDATE or DELETE

To execute an operation which updates the database use `link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#update(java.lang.String,%20io.vertx.core.Handler)[update]`.

The update string is raw SQL that is passed through without changes to the actual database.

The handler will be called with the results, represented by `link:../dataobjects.html#UpdateResult[UpdateResult]` when the update has
been run.

The update result holds the number of rows updated with `link:../dataobjects.html#UpdateResult#getUpdated()[getUpdated]`, and
if the update generated keys, they are available with `link:../dataobjects.html#UpdateResult#getKeys()[getKeys]`.

[source,java]
----

def columnNames = resultSet.columnNames

def results = resultSet.results

results.each { row ->

  def id = row[0]
  def fName = row[1]
  def lName = row[2]
  def shoeSize = row[3]

}


----

=== Prepared statement updates

To execute a prepared statement update you can use
`link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#updateWithParams(java.lang.String,%20io.vertx.core.json.JsonArray,%20io.vertx.core.Handler)[updateWithParams]`.

This takes the update, containing the parameter place holders, and a `JsonArray` or parameter
values.

[source,java]
----

def update = "UPDATE PEOPLE SET SHOE_SIZE = 10 WHERE LNAME=?"
def params = [
  "Fox"
]

connection.updateWithParams(update, params, { res ->

  if (res.succeeded()) {

    def updateResult = res.result()

    println("No. of rows updated: ${updateResult.updated}")

  } else {

    // Failed!

  }
})


----

=== Executing other operations

To execute any other database operation, e.g. a `CREATE TABLE` you can use
`link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#execute(java.lang.String,%20io.vertx.core.Handler)[execute]`.

The string is passed through without changes to the actual database. The handler is called when the operation
is complete

[source,java]
----

def sql = "CREATE TABLE PEOPLE (ID int generated by default as identity (start with 1 increment by 1) not null,FNAME varchar(255), LNAME varchar(255), SHOE_SIZE int);"

connection.execute(sql, { execute ->
  if (execute.succeeded()) {
    println("Table created !")
  } else {
    // Failed!
  }
})


----

=== Using transactions

To use transactions first set auto-commit to false with `link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#setAutoCommit(boolean,%20io.vertx.core.Handler)[setAutoCommit]`.

You then do your transactional operations and when you want to commit or rollback use
`link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#commit(io.vertx.core.Handler)[commit]` or
`link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#rollback(io.vertx.core.Handler)[rollback]`.

Once the commit/rollback is complete the handler will be called and the next transaction will be automatically started.

[source,java]
----

// Do stuff with connection - updates etc

// Now commit

connection.commit({ res ->
  if (res.succeeded()) {
    // Committed OK!
  } else {
    // Failed!
  }
})


----

=== Closing connections

When you've done with the connection you should return it to the pool with `link:groovydoc/io/vertx/groovy/ext/sql/SQLConnection.html#close(io.vertx.core.Handler)[close]`.