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.

The SQL-agent

NAME

Turborel::Client::Agent: a program's named connections, one current, and SQL-92's connection statements.

SYNOPSIS

agent = Turborel::Client::Agent.new(connector, connection = nil)  # connector.call(server, user) => Connection
agent.query(sql)                  # => Rows | Completion
agent.query_into(sql, sink)       # => Integer | Completion
agent.connection_statement(sql)   # => Completion, or nil
agent.current   agent.current_connection   agent.current_name
agent.canceller   agent.warning   agent.lost?   agent.terminate

DESCRIPTION

query runs CONNECT TO, SET CONNECTION and DISCONNECT itself, and sends every other statement to the current connection. CONNECT TO a server AS a name USER a user, each a character string literal, calls the connector with the server and the user, or nil for TO DEFAULT or no USER; the connection is named by its name, else its server, read as an identifier, and made current. SET CONNECTION makes the named one, or DEFAULT, current. DISCONNECT ends the named one, DEFAULT, CURRENT or ALL. An agent made with a connection holds it as the default connection, current. terminate ends every connection.

A statement is read as Turborel reads it: after its comments, simple or bracketed; a name a character string literal, national, introduced by a character set, or in parts a newline separates. A connection exception the agent raises, or its refusal to end a connection whose transaction is active, cites its rule of ISO/IEC 9075:1992 §15, as rule gives it, apart from its message.

ERRORS

SQLSTATE SQLCODE When
08003 -919 No current connection, or none of the name
08002 -919 CONNECT of a name already established
08001 -919 CONNECT to a server that cannot be reached
08004 -919 CONNECT the server refuses
0A001 -900 CONNECT or SET CONNECTION while the current connection's transaction is active
25000 -917 DISCONNECT of a connection whose transaction is active
28000 -104 A user that is no authorization identifier
2E000 -919 A connection name that is no identifier
2A000 -101, -102, -103 A connection statement with a comment that does not end, malformed, or naming by a literal no character string literal is
01002 0 DISCONNECT that met an error ending a connection, a warning

EXAMPLES

port = 7422
connector = ->(_server, user) { Turborel::Client.connect("127.0.0.1", port, user: user || "ann", mechanism: Turborel::Client::Trust.new) }
agent = Turborel::Client::Agent.new(connector)
agent.query("CONNECT TO 'db' AS 'one'")
begin
  agent.query("CONNECT TO 'db' AS 'one'")
rescue Turborel::Error => e
  p [e.sqlstate, e.message]
end
agent.terminate
["08002", "the connection ONE is established"]

STANDARD

[CLIENT The SQL-agent] of The Client Library.

SEE ALSO

Pipelines and Pools, Connections