1.1 New in This Release
2.0 Operating System Support
3.0 Installation Considerations
4.0 General Considerations
4.1 Features Not Included
4.2 Syntax for the ingresdbi.connect() Method
4.3 Syntax for the Ingres Extension Cursor.prepared Attribute
5.0 Building and Installing the Ingres Python DBI Driver
5.1 Building the Driver
5.2 Installing the Driver
6.0 Example Code
7.0 Known Issues
8.0 Contact Customer Support
This readme contains all the documentation on the Ingres Python DBI driver.
Please review this readme before building or installing this software. We encourage users to test the software and provide feedback.
The latest additions to the Ingres DBI 2.0.0 driver bring the driver to nearly 100% compliance to the DBI 2.0 specification, including both core and extended specifications. These additions to the Ingres Python DBI driver ease application migration.
The following changes have been made to the driver since its last release:
This Ingres Python DBI driver supports all of the platforms supported by Ingres, including:
If the "dsn" keyword is specified, the other keywords are optional. If the database is specified, the other keywords are optional. If the vnode keyword is specified, and the connection is local, the value "(LOCAL)" can be used as the vnode definition, or the vnode attribute can be omitted.
If the "connectstr" keyword is specified, the other keywords are optional. The "connectstr" keyword specifies an ODBC connection string. For examples of valid Ingres ODBC connection strings, see the Ingres Connectivity Guide.
All of the above keywords reference string values except for the "trace" keyword. The "trace" keyword references a tuple with two members. The first member is the tracing level, which can be a value of 0 through 7. The second member is a string that describes the trace file. If the second member has a value of "None", the tracing is written to the standard output.
If "INGRES" is not specified, the "servertype" values require access to an Ingres (that is, Enterprise Access) or EDBC gateway server. Otherwise, no gateway is required. The default is "INGRES".
Select loops usually have the best performance. However, only one select loop can be active at a time. Cursor loops support unlimited multiple active result sets, but can be slower in performance.
Following is an example of a valid instantiation of the ingresdbi connection object, using all keywords:
conn = ingresdbi.connect(dsn ="myDSN", database "myDB", vnode = "(LOCAL)", uid = "myUID", pwd = "myPWD", dbms_pwd = "myDbmsPWD", group = "myGroup", rolename = "myRoleName", rolepwd = "myRolePwd", selectloops = "Y", autocommit = "Y", servertype = "INGRES", driver = "Ingres", catschemanull = "off", catconnect = "Off", numeric_overflow = "yes", connectStr = "DSN=myDSN", trace = (7, "dbi.log") )
Connection objects can be constructed without keywords. If keywords are not used, arguments must follow the order: dsn, database, vnode, uid, pwd, selectloops, autocommit, servertype, and trace. An example without keywords is shown here:
conn = ingresdbi.connect("myDSN", "myDB", "(LOCAL)", "MnyUID", "myPWD", "Y", "Yes", "INGRES", "Ingres 3.0", "myRoleName", "myrolePWD", "myGroup", "n", "NO", "YES", "yes", "N", "myDbmsPwd", "DSN=myDSN", (7, "dbi.log"))
Although PEP 249 requires all queries to be prepared, the Ingres DBI driver does not prepare queries by default. Instead, the Cursor attribute "prepared" can be deployed.
If Cursor.prepared is set to "y", "yes", or "on", subsequent queries specified in the Cursor.execute() or Cursor.executemany() methods are executed as prepared. However, only one query string is allowed for each cursor instantiation. If the query string is changed, a warning is issued, and the Ingres DBI driver resorts to direct query execution.
The Cursor.callproc() method raises an exception if the Cursor.prepared attribute is set to "y", "yes", or "on".
The build process has been simplified by the use of the Python DistUtils package. Start the build process by extracting the necessary files from the Ingres DBI compressed archive:
Linux and Non-Windows
tar zxvf ingresdbi-1.9.6.tar.gz
python setup.py build
Note: You can skip this and jump straight to the install process as this will automatically build.
Note for Microsoft Windows: Make sure the Microsoft Visual Tools environment is set up before this step.
As with the build process, the installation process makes use of DistUtils. By default, the Ingres Python DBI driver is installed into Python's site-packages directory. The ability to provide alternate installation locations has not been investigated at this time. The only requirement for installing is to be able to write to the site-packages directory.
To install, execute the following command:
python setup.py install
To create a deliverable source package, execute the following command:
python setup.py sdist
The following code provides a simple Python database example using the Ingres Python DBI driver:
import ingresdbi import pprint """ import os username=os.getenv('test_username') password=os.getenv('test_password') vnode=os.getenv('test_vnode') database=os.getenv('test_database') trace=None """ enable_trace = 0 if enable_trace == 1: trace=(7, None) else: trace=(0, None) database='iidbdb' vnode='(local)' prog_str = 'DEMO SIMPLE SELECT' print prog_str, "connecting to database: " + database dc=ingresdbi.connect(database=database, vnode=vnode, trace=trace) print prog_str, "Creating new cursor()" c=dc.cursor() print prog_str, "About to call cursor.execute()" c.execute("select * from iidbconstants") print "cursor.description = " description = c.description pprint.pprint (description ) print prog_str, "cursor.fetchall()" rows = c.fetchall() print "rows = ", rows row_count = 0 for row in rows: row_count = row_count + 1 print 'Row #', row_count count = 0 for column in row: print description[count] , ': ', column count = count + 1 print "-----------------------------" print prog_str, "connection.commit()" dc.commit() print prog_str, "connection.close()" dc.close()
error: Python was built with version 6 of Visual Studio, and extensions need to be built with the same version of the compiler, but it isn't installed.
and you do have Visual Studio version 6 installed, run Microsoft Visual C++ 6.0 msdev.exe (the GUI), quit out, and then retry the build. For further information, see Python mailing list http://mail.python.org/pipermail/python-dev/2003-November/040478.html.
For online technical assistance and a complete list of locations, primary service hours, and telephone numbers, contact technical support at http://www.ingres.com/support.