Ingres Corporation

Ingres Python DBI Driver Version 2.0.0

1.0 Welcome
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

1.0 Welcome

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.

1.1 New in This Release

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:

2.0 Operating System Support

This Ingres Python DBI driver supports all of the platforms supported by Ingres, including:

3.0 Installation Considerations

To build and install the Ingres Python DBI interface, the following components are needed:

4.0 General Considerations

4.1 Features Not Included

The following features are currently not included in the Ingres Open Source Python DBI driver:

4.2 Syntax for the ingresdbi.connect() Method

Connection objects are constructed using the ingresdbi.connect() method. The following keywords are valid:

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.

The following values are valid for the "autocommit", "selectloops", "catconnect", "catschemanull", and "numeric_overflow" keyword attributes:
The following values are valid for the "servertype" keyword:

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"))

4.3 Syntax for the Ingres Extension Cursor.prepared Attribute

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 following values (entered in either uppercase or lowercase) are valid for the Cursor.prepared attribute:

5.0 Building and Installing the Ingres Python DBI Driver

5.1 Building the Driver

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
  1. Use WinZip (or similar product) to extract the directories and files from
  2. Enter the newly created source directory, ingresdbi-1.9.6:
    cd ingresdbi-1.9.6
  3. Initiate the build process.
    python 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.

5.2 Installing the Driver

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 install

To create a deliverable source package, execute the following command:

python sdist

6.0 Example Code

The following code provides a simple Python database example using the Ingres Python DBI driver:

import ingresdbi
import pprint
import os
enable_trace = 0
if enable_trace == 1:
   trace=(7, None)
   trace=(0, None)
print prog_str, "connecting to database: " + database
dc=ingresdbi.connect(database=database, vnode=vnode, trace=trace)
print prog_str, "Creating new 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][0] , ': ', column
   count = count + 1
print "-----------------------------"
print prog_str, "connection.commit()"
print prog_str, "connection.close()"

7.0 Known Issues

Known issues are as follows:

8.0 Contact Customer Support

For online technical assistance and a complete list of locations, primary service hours, and telephone numbers, contact technical support at

© 2006 Ingres Corporation. All rights reserved.