== Cursors and streaming

By default prepared query execution fetches all rows, you can use a
`link:../../yardoc/VertxSqlClient/Cursor.html[Cursor]` to control the amount of rows you want to read:

[source,ruby]
----
require 'vertx-sql-client/tuple'
connection.prepare("SELECT * FROM users WHERE age > ?") { |ar1_err,ar1|
  if (ar1_err == nil)
    pq = ar1

    # Create a cursor
    cursor = pq.cursor(VertxSqlClient::Tuple.of(18))

    # Read 50 rows
    cursor.read(50) { |ar2_err,ar2|
      if (ar2_err == nil)
        rows = ar2

        # Check for more ?
        if (cursor.has_more?())
          # Repeat the process...
        else
          # No more rows - close the cursor
          cursor.close()
        end
      end
    }
  end
}

----

PostreSQL destroys cursors at the end of a transaction, so the cursor API shall be used
within a transaction, otherwise you will likely get the `34000` PostgreSQL error.

Cursors shall be closed when they are released prematurely:

[source,ruby]
----
cursor.read(50) { |ar2_err,ar2|
  if (ar2_err == nil)
    # Close the cursor
    cursor.close()
  end
}

----

A stream API is also available for cursors, which can be more convenient, specially with the Rxified version.

[source,ruby]
----
require 'vertx-sql-client/tuple'
connection.prepare("SELECT * FROM users WHERE age > ?") { |ar1_err,ar1|
  if (ar1_err == nil)
    pq = ar1

    # Fetch 50 rows at a time
    stream = pq.create_stream(50, VertxSqlClient::Tuple.of(18))

    # Use the stream
    stream.exception_handler() { |err|
      puts "Error: #{err.get_message()}"
    }
    stream.end_handler() { |v|
      puts "End of stream"
    }
    stream.handler() { |row|
      puts "User: #{row.get_string("last_name")}"
    }
  end
}

----

The stream read the rows by batch of `50` and stream them, when the rows have been passed to the handler,
a new batch of `50` is read and so on.

The stream can be resumed or paused, the loaded rows will remain in memory until they are delivered and the cursor
will stop iterating.