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 authenticates with
user and password.  Failed connections are retried for tries times
at retrytime interval.  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.
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 1 if the commit
succeeded, 0 if it failed and -1 if an
error occurred.
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 SQLRDEBUG to "ON"
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.
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: 
  oracle8, 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 1 if the rollback
succeeded, 0 if it failed and -1 if an
error occurred.
selectDatabase(self, database)
Sets the current database/schema to "database"
serverVersion(self)
Returns the version of the SQL Relay server version
setTimeout(self, timeoutsec, timeoutusec)
Sets the server connect timeout in seconds
and milliseconds.  Setting either parameter
to -1 disables the timeout.
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.
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.
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.