Alpha

These pages are built from turborel-ruby’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Statements and Cursors

NAME

Turborel::Client::Connection: statements, prepared statements, cursors, and what the server tells of each; the session's control.

SYNOPSIS

connection.query(sql)                      # => Rows | Completion
connection.query_into(sql, sink)           # => Integer | Completion
connection.query_many(sql)                 # => Ran
connection.prepare(sql)                    # => Statement
connection.execute(statement, values = []) # => Rows | Completion
connection.open_cursor(statement, values = [], rows = 0)                 # => Batch
connection.open_cursor_numbered(statement, cursor, values = [], rows = 0) # => Batch
connection.fetch(statement, rows = 0, cursor: 0)                         # => Batch
connection.close(statement, cursor: 0)
connection.describe(statement)             # => Statement
connection.describe_cursor(statement, cursor = 0) # => Array<Column>
connection.deallocate(statement)

connection.in_transaction?   connection.autocommit   connection.autocommit = on
connection.completion        connection.rows_affected   connection.last_generated
connection.server_time       connection.commit_position connection.warning
connection.conditions        connection.take_conditions
connection.notice_handler = proc   connection.take_notices
connection.query_attributes  connection.query_attributes = [[name, value], ...]
connection.ping   connection.reset   connection.change_user(user, mechanism)

Turborel::Client::Rows.new(columns:, rows:)
Turborel::Client::Statement.new(number:, parameters:, columns:)
Turborel::Client::Batch.new(rows:, more:)
Turborel::Client::Ran.new(outcomes:, failure:)
Turborel::Client::Completion  # sqlcode, sqlstate, active, position, more, rows, generated, conditions, time
Turborel::Client::Timing      # total, queued, locks
Turborel::Client::Notice      # sqlstate, message, diagnostics

DESCRIPTION

query runs a statement in the session and gives a query's Rows, its columns and every row, or another statement's Completion. query_into gives a query's columns, then each batch of rows as it comes, to sink, whose columns and rows take them, and gives the number of rows. query_many runs a text of several statements in one request and gives each outcome, in order, and the Failure of the statement that stopped the rest; a failure that loses the connection is raised instead.

prepare gives a Statement numbered by the connection, from 0 up: its parameters in the order of their ? marks, a statement's inputs alone, and its columns, of a query, or of a CALL each ? of an OUT or INOUT parameter. execute runs it with a value for each parameter and gives a query's Rows, a CALL's one row of its output parameters, or another statement's Completion. open_cursor opens a query's cursor and gives at most rows of its rows, all if 0, as a Batch that says whether the cursor has more; fetch gives the next; the cursor closes once its last row is given, or by close. open_cursor_numbered opens the cursor of its number, several open at once; fetch and close take cursor:. describe gives the statement as the server prepares it now, describe_cursor an open cursor's columns, and deallocate lets the statement go.

The transaction begins with the first statement and lasts until COMMIT or ROLLBACK; in_transaction? says whether it is active, as the server said after the last statement. Under autocommit each statement query, query_into, execute and query_many run is its own transaction, ended within its request; a cursor's ends as the cursor does, where the server grants fetch-ends; a result that sent a locator keeps it.

Each statement's completion tells, where the server grants it, the rows it changed or a query's rows (rows_affected), the identity values an INSERT generated (last_generated), the server's time (server_time), the last commit's log position (commit_position), its warning's SQLSTATE (warning) and its conditions (conditions, take_conditions). Notices go to notice_handler as they come, or are kept, the last 64, for take_notices. query_attributes are carried by every later Query and Execute, where the server grants query-attributes.

ping asks whether the server answers. reset puts the session back as it was at login, its user and cancel key kept, telling each setting again. change_user authenticates the connection again as user by mechanism, renewing the session under a new cancel key, no transaction active after it.

ERRORS

SQLSTATE SQLCODE When
the server's the server's A statement that fails, as the server reports it: 07001 values short of the parameters, 24000 a cursor open or not as the call needs, 26000 no such statement, 37000 a statement that cannot be prepared, 2200W a value with no serialization, 40002 a commit that fails
TB920 -920 The statement cancelled
28000 -919 A change_user refused, which closes the connection
08006 -919 A method needing a capability the server did not grant, before anything is sent, the connection kept; a reply out of turn, malformed or too long, or a closed connection, the connection lost

EXAMPLES

conn = Turborel::Client.connect("127.0.0.1", 7422, user: "ann", mechanism: Turborel::Client::Trust.new)
conn.query("CREATE TABLE NUMBERS (N INTEGER)")
conn.query("INSERT INTO NUMBERS VALUES (1), (2), (3), (4), (5)")
all = conn.prepare("SELECT N FROM NUMBERS ORDER BY N")
p conn.open_cursor(all, [], 2)
p conn.fetch(all, 2)
p conn.fetch(all)
conn.open_cursor_numbered(all, 1, [], 1)
conn.open_cursor_numbered(all, 2, [], 3)
p conn.fetch(all, 1, cursor: 1).rows
p conn.describe_cursor(all, 2).map(&:name)
conn.close(all, cursor: 1)
conn.close(all, cursor: 2)
conn.query("COMMIT")
conn.terminate
#<data Turborel::Client::Batch rows=[[1], [2]], more=true>
#<data Turborel::Client::Batch rows=[[3], [4]], more=true>
#<data Turborel::Client::Batch rows=[[5]], more=false>
[[2]]
["N"]

STANDARD

[PROTOCOL Query 'Q'], [PROTOCOL Prepare 'P'], [PROTOCOL Execute 'E'], [PROTOCOL Fetch 'F'], [PROTOCOL Close 'C'], [PROTOCOL Deallocate 'D'], [PROTOCOL Describe 'Y'], [PROTOCOL Ping 'G'], [PROTOCOL Reset 'W'], [PROTOCOL ChangeUser 'U'], [PROTOCOL Complete 'K'] and [PROTOCOL Status 'T'] of The Native Protocol; [CLIENT Running statements], [CLIENT Prepared statements], [CLIENT XML values], [CLIENT UUIDs], [CLIENT What the server tells] and [CLIENT Controlling the session] of The Client Library.

SEE ALSO

Running Queries, Prepared Statements, Transactions, Errors, Values