PySQLRClient |

`# Copyright (c) 2000 Roman Milner
# See the file COPYING for more information`

Modules

``

SQLRelay.CSQLRelay |  |  |

Classes

``

sqlrconnection
sqlrcursor

class sqlrconnection
`` | `A wrapper for the sqlrelay connection API. Closely follows the C++ API.`

Methods defined here:

__del__(self)

__init__(self, host, port, socket, user, password, retrytime=0, tries=1)
  `Opens a connection to the sqlrelay server and auths with
  user and password. Failed connections are retried for tries times,
  waiting retrytime seconds between each try. If tries is 0 then retries
  will continue forever. If retrytime is 0 then retries will be attempted
  on a default interval.`

autoCommitOff(self)
  `Instructs the database to wait for the
  client to tell it when to commit.`

autoCommitOn(self)
  `Instructs the database to perform a commit
  after every successful query.`

begin(self)
  `Begins a transaction. Returns true if the begin
  succeeded, false if it failed. If the database
  automatically begins a new transaction when a
  commit or rollback is issued then this doesn't
  do anything unless SQL Relay is faking transaction
  blocks.`

bindFormat(self)
  `Returns a string representing the format
  of the bind variables used in the db.`

clientVersion(self)
  `Returns the version of the SQL Relay client version`

commit(self)
  `Issues a commit, returns true if the commit
  succeeded, false if it failed.`

dbHostName(self)
  `Returns the host name of the database`

dbIpAddress(self)
  `Returns the ip address of the database`

dbVersion(self)
  `Returns the version of the database`

debugOff(self)
  `Turn verbose debugging off.`

debugOn(self)
  `Turn verbose debugging on.
  Another way to do this is to start a query with "-- debug
  ".
  Yet another way is to set the environment variable SQLR_CLIENT_DEBUG
  to "ON"`

disableEncryption(self)
  `Disables encryption.`

enableKerberos(self, service, mech, flags)
  `Enables Kerberos authentication and encryption.
  "service" indicates the Kerberos service name of the
  SQL Relay server. If left empty or NULL then the service
  name "sqlrelay" will be used. "sqlrelay" is the default
  service name of the SQL Relay server. Note that on Windows
  platforms the service name must be fully qualified,
  including the host and realm name. For example:
  "sqlrelay/sqlrserver.firstworks.com@AD.FIRSTWORKS.COM".
  "mech" indicates the specific Kerberos mechanism to use.
  On Linux/Unix platforms, this should be a string
  representation of the mechnaism's OID, such as:
  { 1 2 840 113554 1 2 2 }
  On Windows platforms, this should be a string like:
  Kerberos
  If left empty or NULL then the default mechanism will be
  used. Only set this if you know that you have a good
  reason to.
  "flags" indicates what Kerberos flags to use. Multiple
  flags may be specified, separated by commas. If left
  empty or NULL then a defalt set of flags will be used.
  Only set this if you know that you have a good reason to.
  Valid flags include:
  * GSS_C_MUTUAL_FLAG
  * GSS_C_REPLAY_FLAG
  * GSS_C_SEQUENCE_FLAG
  * GSS_C_CONF_FLAG
  * GSS_C_INTEG_FLAG
  For a full list of flags, consult the GSSAPI documentation,
  though note that only the flags listed above are supported
  on Windows.`

enableTls(self, version, cert, password, ciphers, validate, ca, depth)
  `Enables TLS/SSL encryption, and optionally authentication.
  "version" specifies the TLS/SSL protocol version that the
  client will attempt to use. Valid values include SSL2,
  SSL3, TLS1, TLS1.1, TLS1.2 or any more recent version of
  TLS, as supported by and enabled in the underlying TLS/SSL
  library. If left blank or empty then the highest supported
  version will be negotiated.
  "cert" is the file name of the certificate chain file to
  send to the SQL Relay server. This is only necessary if
  the SQL Relay server is configured to authenticate and
  authorize clients by certificate.
  If "cert" contains a password-protected private key, then
  "password" may be supplied to access it. If the private
  key is not password-protected, then this argument is
  ignored, and may be left empty or NULL.
  "ciphers" is a list of ciphers to allow. Ciphers may be
  separated by spaces, commas, or colons. If "ciphers" is
  empty or NULL then a default set is used. Only set this if
  you know that you have a good reason to.
  For a list of valid ciphers on Linux/Unix platforms, see:
  man ciphers
  For a list of valid ciphers on Windows platforms, see:
  https://msdn.microsoft.com/en-us/library/windows/desktop/aa375549%28v=vs.85%29.aspx
  On Windows platforms, the ciphers (alg_id's) should omit
  CALG_ and may be given with underscores or dashes.
  For example: 3DES_112
  "validate" indicates whether to validate the SQL Relay's
  server certificate, and may be set to one of the following:
  "no" - Don't validate the server's certificate.
  "ca" - Validate that the server's certificate was
  signed by a trusted certificate authority.
  "ca+host" - Perform "ca" validation and also validate
  that one of the subject altenate names (or the
  common name if no SANs are present) in the
  certificate matches the host parameter.
  (Falls back to "ca" validation when a unix
  socket is used.)
  "ca+domain" - Perform "ca" validation and also validate
  that the domain name of one of the subject
  alternate names (or the common name if no SANs
  are present) in the certificate matches the
  domain name of the host parameter. (Falls back
  to "ca" validation when a unix socket is used.)
  "ca" is the location of a certificate authority file to
  use, in addition to the system's root certificates, when
  validating the SQL Relay server's certificate. This is
  useful if the SQL Relay server's certificate is self-signed.
  On Windows, "ca" must be a file name.
  On non-Windows systems, "ca" can be either a file or
  directory name. If it is a directory name, then all
  certificate authority files found in that directory will be
  used. If it a file name, then only that file will be used.
  Note that the supported "cert" and "ca" file formats may
  vary between platforms. A variety of file formats are
  generally supported on Linux/Unix platfoms (.pem, .pfx,
  etc.) but only the .pfx format is currently supported on
  Windows. */`

endSession(self)
  `Ends the current session.`

errorMessage(self)
  `If the operation failed, the error message will be returned
  from this method. Otherwise, it returns None.`

errorNumber(self)
  `If an operation failed and generated an
  error, the error number is available here.
  If there is no error then this method
  returns 0.`

getClientInfo(self)
  `Returns the string that was set by setClientInfo().`

getConnectionPort(self)
  `Returns the inet port that the connection is
  communicating over. This parameter may be
  passed to another connection for use in
  the resumeSession() method.
  Note: the value returned by this method is
  only valid after a call to suspendSession().`

getConnectionSocket(self)
  `Returns the unix socket that the connection is
  communicating over. This parameter may be
  passed to another connection for use in
  the resumeSession() method.
  Note: the value returned by this method is
  only valid after a call to suspendSession().`

getCurrentDatabase(self)
  `Returns the database/schema that is currently in use.`

getDebug(self)
  `Returns 1 if debugging is turned on and 0 if debugging is turned off.`

getLastInsertId(self)
  `Returns the value of the autoincrement column for the last insert`

identify(self)
  `Returns the type of database:
  oracle, postgresql, mysql, etc.`

ping(self)
  `Returns 1 if the database is up and 0
  if it's down.`

resumeSession(self, port, socket)
  `Resumes a session previously left open
  using suspendSession().
  Returns 1 on success and 0 on failure.`

rollback(self)
  `Issues a rollback, returns true if the rollback
  succeeded, false if it failed.`

selectDatabase(self, database)
  `Sets the current database/schema to "database"`

serverVersion(self)
  `Returns the version of the SQL Relay server version`

setAuthenticationTimeout(self, timeoutsec, timeoutusec)
  `Sets the authentication timeout in seconds and
  milliseconds. Setting either parameter to -1 disables the
  timeout. You can also set this timeout using the
  SQLR_CLIENT_AUTHENTICATION_TIMEOUT environment variable.`

setClientInfo(self, clientinfo)
  `Allows you to set a string that will be passed to the
  server and ultimately included in server-side logging
  along with queries that were run by this instance of
  the client.`

setConnectTimeout(self, timeoutsec, timeoutusec)
  `Sets the server connect timeout in seconds and
  milliseconds. Setting either parameter to -1 disables the
  timeout. You can also set this timeout using the
  SQLR_CLIENT_CONNECT_TIMEOUT environment variable.`

setDebugFile(self, filename)
  `Allows you to specify a file to write debug to.
  Setting "filename" to NULL or an empty string causes debug
  to be written to standard output (the default).`

setResponseTimeout(self, timeoutsec, timeoutusec)
  `Sets the response timeout (for queries, commits, rollbacks,
  pings, etc.) in seconds and milliseconds. Setting either
  parameter to -1 disables the timeout. You can also set
  this timeout using the SQLR_CLIENT_RESPONSE_TIMEOUT
  environment variable.`

suspendSession(self)
  `Disconnects this connection from the current
  session but leaves the session open so
  that another connection can connect to it
  using resumeSession().`

class sqlrcursor
`` | `A wrapper for the sqlrelay cursor API. Closely follows the C++ API.`

Methods defined here:

__del__(self)

__init__(self, sqlrcon)

affectedRows(self)
  `Returns the number of rows that were
  updated, inserted or deleted by the query.
  Not all databases support this call. Don't
  use it for applications which are designed
  to be portable across databases. -1 is
  returned by databases which don't support
  this option.`

cacheOff(self)
  `Sets query caching off.`

cacheToFile(self, filename)
  `Sets query caching on. Future queries
  will be cached to the file "filename".
  The full pathname of the file can be
  retrieved using getCacheFileName().
  A default time-to-live of 10 minutes is
  also set.
  Note that once cacheToFile() is called,
  the result sets of all future queries will
  be cached to that file until another call
  to cacheToFile() changes which file to
  cache to or a call to cacheOff() turns off
  caching.`

clearBinds(self)
  `Clear all binds variables.`

closeResultSet()
  `Closes the current result set, if one is open. Data
  that has been fetched already is still available but
  no more data may be fetched. Server side resources
  for the result set are freed as well.`

colCount(self)
  `Returns the number of columns in the current result set.`

countBindVariables(self)
  `Parses the previously prepared query,
  counts the number of bind variables defined
  in it and returns that number.`

defineOutputBindBlob(self, variable)
  `Define an output bind varaible.`

defineOutputBindClob(self, variable)
  `Define an output bind varaible.`

defineOutputBindCursor(self, variable)
  `Define an output bind varaible.`

defineOutputBindDouble(self, variable)
  `Define a double precision floating point output bind varaible.`

defineOutputBindInteger(self, variable)
  `Define an integer output bind varaible.`

defineOutputBindString(self, variable, length)
  `Define a string output bind varaible.`

dontGetColumnInfo(self)
  `Tells the server not to send any column
  info (names, types, sizes). If you don't
  need that info, you should call this
  method to improve performance.`

endOfResultSet(self)
  `Returns 0 if part of the result set is still
  pending on the server and 1 if not. This
  method can only return 0 if
  setResultSetBufferSize() has been called
  with a parameter other than 0.`

errorMessage(self)
  `If the query failed, the error message will be returned
  from this method. Otherwise, it returns None.`

errorNumber(self)
  `If the query failed and generated an
  error, the error number is available here.
  If there is no error then this method
  returns 0.`

executeQuery(self)
  `Execute the query that was previously
  prepared and bound.`

fetchFromBindCursor(self)
  `Fetch from a cursor that was returned as
  an output bind variable.`

firstRowIndex(self)
  `Returns the index of the first buffered row.
  This is useful when buffering only part of
  the result set at a time.`

getCacheFileName(self)
  `Returns the name of the file containing the most
  recently cached result set.`

getColumnInfo(self)
  `Tells the server to send column info.`

getColumnIsAutoIncrement(self, col)
  `Returns 1 if the specified column auto-increments and
  0 otherwise.`

getColumnIsBinary(self, col)
  `Returns 1 if the specified column contains binary data
  and 0 otherwise.`

getColumnIsNullable(self, col)
  `Returns 1 if the specified column can contain nulls and
  0 otherwise.`

getColumnIsPartOfKey(self, col)
  `Returns 1 if the specified column is part of a composite
  key and 0 otherwise.`

getColumnIsPrimaryKey(self, col)
  `Returns 1 if the specified column is a primary key and
  0 otherwise.`

getColumnIsUnique(self, col)
  `Returns 1 if the specified column is unique and
  0 otherwise.`

getColumnIsUnsigned(self, col)
  `Returns 1 if the specified column is an unsigned number
  and 0 otherwise.`

getColumnIsZeroFilled(self, col)
  `Returns 1 if the specified column was created with the
  zero-fill flag and 0 otherwise.`

getColumnLength(self, col)
  `Returns the length of the specified column. col may
  be a name or number.`

getColumnList(sefl, table, wild)
  `Sends a query that returns a list of columns
  in the table specified by the "table" parameter
  matching "wild". If wild is empty or NULL then
  a list of all columns will be returned.`

getColumnName(self, col)
  `Returns the name of column number col.`

getColumnNames(self)
  `Returns a list of column names in the current result set.`

getColumnPrecision(self, col)
  `Returns the precision of the specified column.
  Precision is the total number of digits in a number.
  eg: 123.45 has a precision of 5. For non-numeric
  types, it's the number of characters in the string.`

getColumnScale(self, col)
  `Returns the scale of the specified column. Scale is
  the total number of digits to the right of the decimal
  point in a number. eg: 123.45 has a scale of 2.`

getColumnType(self, col)
  `Returns the type of the specified column. col may
  be a name or number.`

getDatabaseList(self, wild)
  `Sends a query that returns a list of
  databases/schemas matching "wild". If wild is empty
  or NULL then a list of all databases/schemas will be
  returned.`

getField(self, row, col)
  `Returns the value of the specified row and
  column. col may be a column name or number.`

getFieldAsDouble(self, row, col)
  `Returns the specified field as a double precision
  floating point number.`

getFieldAsInteger(self, row, col)
  `Returns the specified field as a long integer.`

getFieldLength(self, row, col)
  `Returns the length of the specified row and
  column. col may be a column name or number.`

getLongest(self, col)
  `Returns the length of the specified column. col may
  be a name or number.`

getNullsAsEmptyStrings(self)
  `Tells the cursor to return NULL fields and output
  bind variables as empty strings.
  This is the default.`

getNullsAsNone(self)
  `Tells the cursor to return NULL fields and output
  bind variables as NULL's.`

getOutputBindBlob(self, variable)
  `Get the value stored in a previously
  defined output bind variable.`

getOutputBindClob(self, variable)
  `Get the value stored in a previously
  defined output bind variable.`

getOutputBindCursor(self, variable)
  `Get the cursor associated with a previously
  defined output bind variable.`

getOutputBindDouble(self, variable)
  `Get the value stored in a previously
  defined output bind variable as a double
  precision floating point number.`

getOutputBindInteger(self, variable)
  `Get the value stored in a previously
  defined output bind variable as a long
  integer.`

getOutputBindLength(self, variable)
  `Retrieve the length of an output bind variable.`

getOutputBindString(self, variable)
  `Get the value stored in a previously
  defined output bind variable.`

getResultSetBufferSize(self)
  `Returns the number of result set rows that
  will be buffered at a time or 0 for the
  entire result set.`

getResultSetId(self)
  `Returns the internal ID of this result set.
  This parameter may be passed to another
  cursor for use in the resumeResultSet()
  method.
  Note: the value returned by this method is
  only valid after a call to suspendResultSet().`

getRow(self, row)
  `Returns a list of values in the given row.`

getRowDictionary(self, row)
  `Returns the requested row as values in a dictionary
  with column names for keys.`

getRowLengths(self, row)
  `Returns a list of lengths in the given row.`

getRowLengthsDictionary(self, row)
  `Returns the requested row lengths as values in a dictionary
  with column names for keys.`

getRowLengthsRange(self, beg, end)
  `Returns a list of lists of the lengths of rows between beg and end.
  Note: this function has no equivalent in other SQL Relay API's.`

getRowRange(self, beg, end)
  `Returns a list of lists of the rows between beg and end.
  Note: this function has no equivalent in other SQL Relay API's.`

getTableList(self, wild)
  `Sends a query that returns a list of tables
  matching "wild". If wild is empty or NULL then
  a list of all tables will be returned.`

inputBind(self, variable, value, precision=0, scale=0)
  `Define an input bind varaible.
  Returns true if the variable was successfully bound or false if the
  variable isn't a string, integer or decimal. If the value is a decimal
  then precision and scale may also be specified. If you don't have the
  precision and scale then set them both to 0. However in that case you
  may get unexpected rounding behavior if the server is faking binds.`

inputBindBlob(self, variable, value, length)
  `Define an input bind varaible.`

inputBindClob(self, variable, value, length)
  `Define an input bind varaible.`

inputBinds(self, variables, values, precisions=None, scales=None)
  `Define input bind variables.
  Returns true if the variables were successfully bound or false if one
  of the variables wasn't a string, integer or floating point number,
  or if precision and scale weren't provided for a floating point number.`

lowerCaseColumnNames(self)
  `Columns names are converted to lower case.`

mixedCaseColumnNames(self)
  `Columns names are returned in the same
  case as they are defined in the database.
  This is the default.`

openCachedResultSet(self, filename)
  `Open a result set after a sendCachedQeury`

prepareFileQuery(self, path, file)
  `Prepare to execute the contents of path/filename.`

prepareQuery(self, query)
  `Prepare to execute query.`

prepareQueryWithLength(self, query, length)
  `Prepare to execute "query" with length
  "length". This method must be used if the
  query contains binary data.`

resumeCachedResultSet(self, id, filename)
  `Resumes a result set previously left open
  using suspendSession() and continues caching
  the result set to "filename".
  Returns 1 on success and 0 on failure.`

resumeResultSet(self, id)
  `Resumes a result set previously left open
  using suspendSession().
  Returns 1 on success and 0 on failure.`

rowCount(self)
  `Returns the number of rows in the current result set.`

sendFileQuery(self, path, file)
  `Send the SQL query in path/file to the server and
  gets a result set.`

sendQuery(self, query)
  `Send a SQL query to the server and
  gets a result set.`

sendQueryWithLength(self, query, length)
  `Sends "query" with length "length" and gets
  a result set. This method must be used if
  the query contains binary data.`

setCacheTtl(self, ttl)
  `Sets the time-to-live for cached result
  sets. The sqlr-cachemanger will remove each
  cached result set "ttl" seconds after it's
  created.`

setResultSetBufferSize(self, rows)
  `Sets the number of rows of the result set
  to buffer at a time. 0 (the default)
  means buffer the entire result set.`

substitution(self, variable, value, precision=0, scale=0)
  `Define a substitution variable.
  Returns true if the variable was successfully substituted or false if
  the variable isn't a string, integer or floating point number, or if
  precision and scale aren't provided for a floating point number.`

substitutions(self, variables, values, precisions=None, scales=None)
  `Define substitution variables.
  Returns true if the variables were successfully substituted or false if
  one of the variables wasn't a string, integer or floating point number,
  or if precision and scale weren't provided for a floating point number.`

suspendResultSet(self)
  `Tells the server to leave this result
  set open when the cursor calls
  suspendSession() so that another cursor can
  connect to it using resumeResultSet() after
  it calls resumeSession().`

totalRows(self)
  `Returns the total number of rows that will
  be returned in the result set. Not all
  databases support this call. Don't use it
  for applications which are designed to be
  portable across databases. -1 is returned
  by databases which don't support this option.`

upperCaseColumnNames(self)
  `Columns names are converted to upper case.`

validBind(self, variable)
  `Returns true if "variable" was a valid
  input bind variable of the query.`

validateBinds(self)
  `If you are binding to any variables that
  might not actually be in your query, call
  this to ensure that the database won't try
  to bind them unless they really are in the
  query.`

Functions

``

getNumericFieldsAsNumbers()
  `Instructs the API to return numeric fields as numbers. Integer fields will
  be returned as integers and floating point fields will be returned as
  Decimals if that class is avialable or floats otherwise. The drawback to
  using numerics is that under some circumstances truncation can occur.`

getNumericFieldsAsStrings()
  `Instructs the API to return numeric fields as strings. This is the
  default setting. Truncation cannot occur if this setting is used.`