Home

mxODBC Connect User Manual and Installation Guide

Contents

1. uninstall This will guide you through the uninstall process The uninstaller will ask you whether you would like to keep the configuration files If you answer yes only the product files that can be safely removed from the system will be uninstalled If you answer no the complete installation will be removed including any configuration files and or certificates the mxodbc user account and group Note The complete removal mode will also delete any customizations you have applied to the server configuration so be sure to backup your configuration files and certificates before uninstalling if you intend to reinstall the server in the future Reinstallation or upgrading Running the install script from the newly downloaded installer will reinstall or upgrade the server The installer will automatically take care of uninstalling old components and replace them with updated versions Note After upgrading please check your server configuration file server config ini and compare it to the new default configuration file which will have been installed as server config ini original It is also a good idea to review your changes of the server configuration against the new mxODBC Connect User Manual mxODBC Connect Server Configuration The server configuration INI file is named server config ini and located in the configuration directory of the mxODBC Connect Server It s location depends on the operating system 18
2. This is the length of inactivity period after the TCP connection should be dropped You should not need to modify this option Use Activity max waiting time instead Options for SSL Encrypted Connections The following options below are only relevant if SSL is to be used on the connection allow _ssl 0 Setting allow_ss1 to a non zero value enables the secure socket layer SSL support on this connection You can use SSL to encrypt all communication and also to authenticate clients via certificate verification Note that the server can handle both plain text and SSL connections on the same port if allow_ss1 is set to a non zero value If you want to disable plain text connections set require ssl to a non zero value instead Default is to only accept plain text connections allow ssl 0 22 2 mxODBC Connect Server Installation require ssl 0 Setting require _ss1 to a non zero value disables plain text connections on this connection The client has to start a SSL connection if it wants to communicate with the server If the require _ss1 setting is enabled allow_ss1 is enabled implicitly i e set to a true value Default is to accept both plain text and SSL encrypted connections if allow_ssl is enabled server private key file server pkey Name of the server s SSL private key file This option is required for all SSL connections The installer provides a default self signed key pair You can replac
3. ceessssessecscecssecsseceseceseeeseeeseeeseeeees 4 Security Related Changes sceccsescesseeeseeeseecseeceaecssecsseeeseeeseeeaes 4 Network Related Changes sscssecesscsseceseeeseeeseesseeesneeeneeeneeenaes 4 MXODBC Feature Changes cescssecssecssecsseceseeeseeeseeesseesneeeneeenees 5 2 2 mxODBC Connect Server Installation on Windows 5 2 2 1 PFEPEQUISILCS i 3ceceess cdessvecusbvsessdbsveossacevsosssbersvossevesesesucdsvessetesosdovedssetbetsses 5 2 2 2 PROCCQUIE 8 csesesss ssusssentaseazsonsieusndielizpeussesriovetasstedesisesetudaresys verre EE 6 Step by step Installation ee eee eeeeseeeneecnsecsseceseeeseeeseeeseeeeeeees 7 Server Tray ON oriri rriar ar E R 12 Config ring the Firewalls sis s sssssvectsetaraevedssdecssevasaarestasessesescderaeisesys 12 Edit the Configuration ceseesecesecesceeseceseeeeeeeeseecseecsaecnaeeaeees 12 Controlling Automatic Startup of the Server ce eseseeeeeeeseeereees 12 Troubleshooting isus esecsessseesevivedveesied Goueshsdessecesncebsa bea sbesibecesasovtestis 12 2 2 3 Uninstall aene e a Ere a eE E REE 13 2 3 2 3 1 2 3 2 2 3 3 2 3 4 2 4 2 4 1 2 4 2 2 4 3 2 4 4 2 4 5 mxODBC Connect Python Database Interface Reinstallation Or upgrading esseseceseceereseeeeeseeeseecseecnaecaecnaeeeeens 13 mxODBC Connect Server Installation on Unix 13 PREPEQUISILES urosis aeoaea AEE AE E ECAA EAN AEAEE EANET 1
4. 2 4 1 2 mxODBC Connect Server Installation e Windows Located in your documents and settings folder may be called differently on non English Windows versions in the All Users Application Data eGenix com mxODBC Connect Server folder e Linux Located in mxodbc i e the home directory of the mxodbc user that was created during the installation process Please make sure the server daemon has read access to all of its configuration files It also needs write permission for its home directory in order to create and append to the log file Note that the name and location of the log file can be configured The installer will configure the access rights for you You only need to take special care when relocating the server installation or otherwise modifying its setup mxODBC Connect Configuration File Syntax The mxODBC Connection configuration files use an INI file like syntax global option 2 Sectionl1 option a option b option c xil abc h html text with spaces Section2 option a option b 2 3 option a string The INI file structure is the same for all supported platforms both on the server and the client side You can use Unix or Windows line endings and the forward slash as path separator on both systems but it s recommended to use the backslash on Windows The INI files are parsed using the following rules e Entries in square brackets indicate new subsections e Global va
5. Note Please run the installer uninstaller as administrator on Windows XP 2003 and later Please uninstall any existing version of mxODBC Connect Server if you have a previous version installed see section 2 2 3 for details After you have downloaded the Windows installer of the egenix mxodbc connect server distribution double click on the executable to start the installation process Depending on your OS version you may need to click through a user account control UAC security dialog to proceed Then follow the instructions of the installer If you run into a problem during the installation process please consult section 7 Troubleshooting 2 mxODBC Connect Server Installation Note You have to provide a valid mxODBC Connect Server license to use the service It s possible to install without a valid license file but the service won t start Step by step Installation The following screenshots demonstrate a typical installation Please note that the screens may look different depending on your version of the installer and OS After you double click on the installer the installation wizard starts up TE Setup eGenix com mxODBC Connect Server ce E fees Welcome to the eGenix com mxODBC Connect Server Setup Wizard This will install eGenix com mxODBC Connect Server on your computer It is recommended that you dose all other applications before continuing Click Next to continue or Cancel to e
6. This icon indicates whether the eGenix com mxODBC Connect Server is running red arrow and icon or not grey cross and icon A right click on the icon will open a menu that allows you to easily start stop and restart the server There are also shortcuts to open the configuration file configure user access check the server log file and open the documentation Configuring the Firewall The installer registers a service named mxODBC Connect Server This will listen on TCP port localhost 6632 by default i e the server will only accept connections from the local machine on port 6632 TCP port 6632 is used for both plain and secure SSL connections It s a IANA registered service port for eGenix mxODBC Connect with name mxodbc connect You may have to configure your firewall to allow connections on port 6632 if you want to permit connections from a local subnet Edit the Configuration After installation you must edit the configuration file of the mxODBC Connect Server to fit your needs e g have it listen for connections from the local subnet and then restart the service in order for the changes to take effect See section 2 4 mxODBC Connect Server Configuration for details on how this is done Controlling Automatic Startup of the Server The mxODBC Connect Server service will be started automatically on each system startup by default The startup type can be changed in the Control Panel Administrative Tools Services Window
7. 1 Network communication compression Setting this variable to 1 will enable compression of TCP packets sent by the server setting the variable to 0 causes compression to be disabled Compression is enabled per default in order to reduce network traffic and enhance roundtrip times On very fast networks or local connections you may want to disable compression for enhanced performance We have found that even on Gigabit Ethernet networks enabling compression does provide a performance increase compression ratio 2 Compression ratio to use for network communication compression 25 mxODBC Connect Python Database Interface Valid values are 1 least compression fast 9 best compression slow The default value of 2 is a good compromise for fast networks You may want to experiment with the setting to tune it for best performance on your network In some setups e g fast server and slow clients it may be wise to use different compression ratios for clients and servers The server setting affects packets sent from the server to the client whereas the client setting affects packets sent from the client to the server max chunk length 64000 Maximum chunk length for TCP read write operations You will normally not need to change this value receive timeout 10 Timeout for one TCP receive operation in seconds You will normally not need to change this value send timeout 10 Timeout for one TCP send o
8. Unlike many ODBC drivers mxODBC Connect comes with optional support for SSL based encryption of all communication making it possible to send queries and data over public or otherwise unsafe networks Security can further be enhanced by enabling certificate verification which will lower the risk introduced by the possibility of stolen database passwords or security holes in the database server or the underlying network architecture Note Only the communication between the mxODBC Connect Client and Server is encrypted The ODBC driver used by the mxODBC Connect Server may still send unencrypted data and queries over the network Please consult your ODBC driver documentation for details You can minimize this risk by installing the mxODBC Connect Server directly on the database server e g the Windows machine running SQL Server In most cases the ODBC driver of the target database will then use lower level interfacing techniques such as shared memory pipes or domain sockets to communicate with the database kernel so that no communication is sent over the network Scope This manual only explains features and configuration of the mxODBC Connect product Please refer to the mxODBC User Manual for mxODBC and Python DB API 2 0 specific details The mxODBC User Manual contains all the needed details to develop against the mxODBC API exposed by the mxODBC Connect product 2 1 2 1 1 2 mxODBC Connect Server Installation m
9. mxODBC Connect Python Database Interface mxODBC Connect Client Configuration ceeeeeeeeeee 45 mxODBC Connect Client Configuration File Format eeseeeees 45 Connection NAME cccecicsesssnclectecseteedseend setevedessaue e EEEa ieaie a EEn 45 Communication seeci sie esti ea ree terek p eE Errori rA s It EE ESTE Saeki E 47 Authentication cccficeskeetestt votescetebecsnsescensisctesulersteedsestvbeSeescdcurerectes 48 SESSION scree e en ss osesovets ouvectedestssettacstesSeettevescacesshadestcvebieeetessaeaiebs 48 LOS SING EE cet natin sndeth ai sstas TT 49 MAE SALON Jr ETE E EN ANNARS NENS 50 Configuration Dictionary Format seeseseeseeseseeseessesreereseesserreeseeseeseees 50 mxODBC Connect Client Configuration Hints eesseeeseeseeseeeeereeseses 51 mxODBC Connect Client Example ssseeeseeeeeseseserresereees 52 Client Configuration irsi peene ierre e etar iS 52 Connecting to the mxODBC Connect Server cesceeceeeeeereeeseeenees 52 Storing ServerSessions as module globals eseeseecsseceseeeeees 53 Exception Handling seserinis ete E EREET EEEE E 54 TESNE sisa oes ieres E NA RIEKIE EAEE EINSA 54 LESEE PVC OPUlONS upane an a A AOO A restea woot 55 mxODBC Connect Client Python API 56 APIDOSISM nnana a o das wagers 56 Multi Threaded Applications eeeesseeeseeeeeeserrseersresereseereeese 57 Recommended Setups saccade acai 57 LOSS ING oinar ATE A TE T 58 SEVERE SU
10. 28 Even more secure SSL only Connections ssseeeseseeeesereresresersreees 28 Listening On More than one POFt eeeeseeseecseecseeceseceseceeeeeeeeeee 29 Configuring Certificate Based Authentication 2 0 0 0 ceseeeeeeereeereeenees 29 Using a file with client Certificates ee lees ceseceeeceseceteeeeeeeseeeees 30 Using a directory with client certificates 00 0 eee eeeeeeeeeeeeeeeeeeees 30 Using a list of SHA1 digests in the configuration file 30 Using a file with SHA1 digests ee eeeessescesseceseceeeeseeeseeeseeeees 31 Configuring User Authentication cssceseceseceseceseceeeeeeeeeeseeeneeenees 31 Authentication Protocols seere eree re Ee ESEESE EES 31 2 5 2 5 1 2 5 2 3 1 3 1 1 3 2 3 2 1 3 2 2 3 2 3 3 3 3 3 1 3 3 2 3 3 3 3 3 4 3 3 5 4 1 Contents Password File authorized users txt cccccscecesesscseessseesceseseeeeaeees 31 Using the password tool scesecescceseceeeceeeeeeeeeeseecseeceaecnaeenseees 32 Command line Options of the password tOol eeseeeseceseeeseees 32 Interactive Mode of the password tool eseeseeeseeeseeceeeceseeeseees 33 ODBC Driver Configuration Hints ceeeeeeeeseeeseeeees 34 Setting up the optimal communication technique eceseeseereee 34 Disabling options that are not needed for local connections 35 mxODBC Connect Client Installation 36 Upgrading mxODBC Connect Cl
11. 5 mxODBC Connect Client Python API This is only available after opening the session Session id None Session ID string Object Methods close Closes the session This method is automatically called when the session object is garbage collected You can call this method to explicitly close the connection before deleting the session open username session _id None Connect to the first object password module name None available and working server connection listed in the mxODBC Connect Client configuration The method raises an mx ODBCConnect Error OperationalError if no connection can be established Returns a module proxy object that exposes the mxODBC package API of the module_name package of mxODBC on the server side username and password must be given if the server uses user authentication They must be set to the user authentication credentials defined on the server side module_name defaults to the mxODBC package name defined in the client configuration parameter Session remote module This is usually set to Manager so that the server s platform default ODBC manager is used session_id may be given to reestablish the connection to a server session e g in case the network was down or unavailable for only a short period of time mxODBC Connect Client Errors All mxODBC Connect the mx ODBCConnect errors raised on the client side are availab
12. 7 1 10 Error handlers don t seem to work ceeeceeeeeseeeseeeeecnsecsecnaeeeseens 74 7 1 11 Printing exception tracebacks does not include the server side 74 7 1 12 InterfaceError Connection limit exceeded Your license allows 20 physical database CONNECTIONS eeseceseceseceseceseceseeeseeceeecsaecsaecaeesseeeseeeseeeseeeees 74 8 Hints amp Links to other Resources 00008 76 8 1 More Sources of Information ceeseccessseeeesneeeeseeeeees 76 9 SUPPO iescecscssccenseessacsssusseddnasdenssesccessennsessocssennnsse 78 10 History amp Changes e seeessoessoosseosseoessosssoesseosseoe 79 Changes from 1 0 2 to 200 ner etot entor eiieeii 79 Changes from 1 0 1 t0 1 02ain e ii eerie eea 82 Changes from 1 0 0 1012011 iasorseeererror seriosi nerit seess 82 Changes from 0 9 3 to 1 0 02 0 eecesecesecescceeeceseeeeseeeseecseecaeeeseens 82 Changes fr0m 0 9 2 t0 0 9 3 esei sessceieereietiteesreir eskier roeirier te iis 83 Changes from 0 9 1 to 0 9 2 0 eeeesceseeseeeeeeeeeeeeseeeseecsaecaeeseees 83 11 Copyright amp LICENSE cscccssccssesssescerssereees OF 11 1 eGenix com Commercial License Agreement 05 84 Contents 11 2 Third Party LICENSES onesie aaa 95 1 1 1 Introduction Introduction mxODBC has proven to be the most stable and versatile ODBC interface available for Python It has been in use by many Python users and companies for years and is acti
13. Because this is a useful setting we have made it the default in the client configuration If you want to make it explicit simply configure the clients to use the Manager module Session remote_module Manager 51 4 3 4 3 1 4 3 2 mxODBC Connect Python Database Interface mxODBC Connect Client Example First you have to setup a working mxODBC Connect Server on the machine that has the ODBC drivers installed see above Client Configuration After you have a working server you ll have to create a client side configuration file Contents of the example connect config ini Logging log_file client log Server Connection host 192 168 1 100 port 6632 using ssl 0 The client in the above example will connect to a Windows based mxODBC Connect Server which listens on 192 168 1 100 6632 for plain text unencrypted connections Connecting to the mxODBC Connect Server Your stand alone mxODBC based application usually connects to the database like this import mx ODBC Windows as ODBC and then uses the ODBC object to reference the mxODBC API In order to use the mxODBC Connect Client you have to successfully connect to an mxODBC Connect Server first to get a reference to an object implementing the mxODBC API from mx ODBCConnect Client import ServerSession session ServerSession connect config ini ODBC session open Creating a ServerSession instance connects to the mxODBC Connect Ser
14. G nix com mxODBC Connect Database Interface for Python Version 2 0 Copyright 2000 2012 by eGenix com GmbH Langenfeld All rights reserved No part of this work may be reproduced or used in any form or by any means without written permission of the publisher All product names and logos are trademarks of their respective owners The product names mxBeeBase mxCGlPython mxCounter mxCrypto mxDateTime mxHTMLTools mxIP mxLicenseManager mxLog mxNumber mxODBC mxODBC Connect mxODBC Zope DA mxObjectStore mxProxy mxQueue mxStack mxTextTools mxTidy mxTools mxUID mxURL mxXMLTools eGenix Application Server PyRun PythonHTML eGenix and eGenix com and corresponding logos are trademarks or registered trademarks of eGenix com GmbH Langenfeld Printed in Germany Contents Contents 1 e Introduction A EEEE 1 1 Technical OvervieWw essssseessssessseesssessssersseresseressreesssessses 1 1 2 SecUrity ssisenvsaiscssuesensass daisassssaueuassevaboovesdveasensdevcesaessescerivaness 2 1 3 SCOPE icine nine open aE I 2 2 mxODBC Connect Server Installation 3 2 1 Upgrading mxODBC Connect Server cceeceesseeeeeeeeeees 3 2 1 1 Upgrading from 1 0 to 2 0 iecscscssssciescescsscossaesnesepsesentoscesrsunedseasenseeess 3 Windows Service Changes cesccssscsesceeseeeseeeseeceaecsaecsaeenaeeaeees 3 Configuration File Changes
15. Operating System any compatible operating system Authorizations eGenix com hereby authorizes Licensee to copy install compile modify and use the Software on the following Installation Targets under the terms of this License Agreement Installation Targets one 1 CPU 91 mxODBC Connect Python Database Interface Use of the Software for any other purpose or redistribution IS NOT PERMITTED BY THIS PROOF OF AUTHORIZATION Proof This Proof of Authorization was issued by lt name gt lt title gt Langenfeld lt date gt Proof of Authorization Key lt license key gt 92 11 Copyright amp License EGENIX COM PROOF OF AUTHORIZATION 1 Developer CPU License Example This is an example of a Proof of Authorization for a 1 Developer CPU License These proofs are either wet signed by the eGenix com staff or digitally PGP signed using an official eGenix com PGP key License Grant eGenix com Software Skills and Services GmbH eGenix com having an office at Pastor Loeh Str 48 D 40764 Langenfeld Germany hereby grants the Individual or Organization Licensee Licensee lt name of the licensee gt a non exclusive world wide license to use the software listed below in source or binary form and its associated documentation the Software under the terms and conditions of this License Agreement and to the extent authorized by this Proof of Authorization Covered Software Software Name lt pr
16. Then follow the instructions of the installer script in order to install the server If you run into a problem during the installation process please consult section 7 Troubleshooting Note You have to uninstall any old version of the mxODBC Connect Server prior to installing a new version The installer will ask you to do so and assist in uninstalling your old server Step by step Installation The following is a transcript of a typical installation session install 14 2 mxODBC Connect Server Installation The eGenix mxODBC Connect Server product requires that you set up an account that can print be used by the server Please enter the account name Both a group and user with the given account name will be created if they don t already exist in the system If you have an existing installation of eGenix mxODBC Connect Server please enter the account name used by that installation Account name mxodbc The server is run under the given user account and group Both are created by the installer automatically Where should the eGenix mxODBC Connect Server be installed on the system opt eGenix mxODBC Connect Server The directory opt eGenix mxODBC Connect Server does not exist Create it yes no yes The default location of the server is under the opt directory You can change this directory to a different one but care must be taken to make sure that the user account s home directory is set to
17. limitation please make sure that the parameter values you pass to the cursor execute methods only use supported data types No support for Python 2 7 memoryviews Unfortunately and unlike many other basic Python types Python 2 7 memoryviews cannot be pickled As a result they cannot be used as parameters to cursor execute methods and are not available for passing data to the server database 67 6 2 2 6 2 3 mxODBC Connect Python Database Interface Garbage collection and closing of connections cursors mxODBC Connect Client manages a cache of objects in order to increase performance and provide more reliability Due to this cache garbage collection of e g database connection or cursor objects may not directly result in the objects to get implicitly closed This may result in a situation where e g connections are kept open on the server side longer than necessary and even result in the application hitting a database connection license limit on the server more often than necessary You can easily prevent this by explicitly closing cursor and connection objects after use Example connection session DriverConnect cursor connection cursor do some work with cursor cursor close connection close Exceptions Exception classes must be imported from mx ODBCConnect Error instead of mx ODBC Error which may require slight modification to existing application code Unlike in mxODBC the exc
18. module proxy object will then work in a nearly identical way as the ODBC module from the stand alone version of mxODBC If you have multiple connections defined in your mxODBC Connect Client configuration then open will try the connections in the order specified by the Communication server connections parameter In the following sections we describe APIs that are special to the mxODBC Connect version of mxODBC Once you have a module proxy object you can use the standard mxODBC connection and cursor APIs described in the mxODBC User Manual and Reference Guide Multi Threaded Applications mxODBC Connect works well in multi threaded applications and is written in a thread safe way In order to make the best use of the available technology you should consider the options that you have to manage connections between threads as outlined in the following sections Note that mxODBC Connect itself will not start new threads so you can safely use it in non threaded applications as well Recommended Setups If you intend to use mxODBC Connect with a multi threaded application you have two possibilities 57 5 2 2 mxODBC Connect Python Database Interface 1 use a single ServerSession for the application connected to the mxODBC Connect Server and have one or more database connections open per thread of your application this does not work for SSL connections or 2 have one ServerSession object per thread that needs
19. platforms If you want to use encryption you will also need the Python standard library module ssi which is available in Python 2 6 and later or our eGenix pyOpenSSL Distribution package However this is not essential for working with mxODBC Connect 65 6 1 2 6 1 3 6 1 4 6 1 5 mxODBC Connect Python Database Interface Improved data type support Since the mxODBC Connect Server always runs on Python 2 7 the decimal and datetime modules are always available on the server side This allows clients still running on Python 2 5 or 2 6 to communicate with the database using types from these packages The Python datetime module and decimal module can be fully utilized with Python 2 5 and 2 6 clients Improved Scalability You can separate your client application and database server for improved performance and scalability e g to work around problems with the Python Global Interpreter Lock GIL They can reside on different physical or virtual machines or just run on different CPU cores Asynchronous Execution Support using gevent mxODBC Connect Client 2 0 supports the gevent module for running tasks asynchronously without using threads or by combining asynchronous execution with threads This allows for better scaling of Python client side applications especially on multi core machines Please see section 5 3 gevent Support for details Automatic Fail over You can list multiple servers in your client configu
20. port 6632 mxodbc connect for both plain text and SSL encrypted communication Added STARTTLS support to be able to use a single port for both unencrypted and SSL encrypted communication mxODBC Connect Client no longer requires a client certificate and key for SSL connections mxODBC Connect Client now allows selecting the used SSL module from two available options Python standard lib ssl module and pyOpenSsSL 80 10 History amp Changes e Upgraded to pyOpenSSL 0 13 0 1 0 0j on the server side e mxODBC Connect Server will now use SHA1 digests for client certificate checks instead of MD5 to improve security e mxODBC Connect Client can now additionally read client certificate and private key from the config_data dictionary instead of from files only provided that pyOpenSSL is used Python s ssl module doesn t support this e Client certificate checks are now also supported when using the standard Python ssl module on the client side Fixes e mxODBC Connect Server will now return ProtocolErrors to the client side and close the connection in case it finds that it cannot decode the client side pickle e Fixed a problem with database connections being kept alive in sessions that were not explicitly closed by the client application e mxODBC Connect pure Python prebuilt archives did not always install on non Linux platforms e ServerSession close will no longer cause error messages at Python exit time if the cl
21. the log file itself Otherwise you could end up seeing mangled output in the log file 58 5 3 5 3 1 5 3 2 5 4 5 mxODBC Connect Client Python API gevent Support Tested with gevent 0 13 4 and greenlet 0 3 1 mxODBC Connect Client can optionally integrate with the greenlets via the Python package gevent and using the ibevent polling library To enable gevent support for the mxODBC Connect Client please enable the integration setting in the client side configuration Integration gevent 1 mxODBC Connect Client will then use gevent APIs for communicating with the server side allowing other greenlets to run asynchronously while the client waits for the server response Import Order For best compatibility please import the gevent package before importing the mxODBC Connect Client into your Python application gevent Monkey Patching The client does not require enabling the gevent monkey patching features nor does it enable these itself We have tested mxODBC Connect Client in a gevent monkey patched environment but recommend using gevent APIs directly rather than through the monkey patched setup mxODBC Connect Client ServerSession Object A ServerSession object manages the connection of a client application to the mxODBC Connect Server It provides all the necessary networking logic to proxy requests to mxODBC package module APIs to the server side in an efficient and reliable way 59 mxODBC Conn
22. to connect to the database this is the preferred method Please do not try to share database connections between threads This is not supported by the mxODBC Connect Client and not needed due to the way mxODBC Connect works Also note that for SSL connections you can only use option 2 since the OpenSSL library used by mxODBC Connect does not support sharing SSL connections between threads Both options allow using the mxODBC Connect Server from the multiple threads that open database connections However there is one important difference all connections opened by a single ServerSession are mapped to a single thread on the server As a result the operations on the session are serialized on the server and thus do not run in parallel For applications that run many quick queries the difference will likely not be noticeable but if you have long running queries you should definitely choose the second method in order to have full flexibility of running the queries in parallel The difference in amount of resources used by the two methods is negligible You should only consider using the first method or a combination of the two in case you are planning to have many threads running in parallel each connected to a database Logging If you intend to use custom mx Log logging objects via the logging parameter in ServerSession objects please make sure that you share the logging object if you want to log to the same log file not
23. 4 Proced r ee aseena e ee e e ee a EE EN esor EI TERETE 14 Step by step Installation eee eeeceseeeeeeseeeeeeeeseecseeceaecnseeaeens 14 Server User Account and Group esceseceeeeeseceeeeeeseeeneecneesnaeens 16 Configuring the Firewall cescescsssceseeeeeeeeeeeseeeseecsaecnseeaeens 16 Edit the Configuration eeeeeseeseeeseecseecssecssecesecsseeeeeeseeeneeees 17 Starting Stopping the Server eesesecsseceseceseceeeeeseeeseeceaecsaeenseees 17 Controlling Automatic Startup of the Server 17 Troubleshooting sie annone a i 17 UninstallatiOn gai eoni a a EE R 18 Reinstallation or upgrading eessseeseesseseessrseeseeseeseeeseseeserresserrenseeseeses 18 mxODBC Connect Server Configuration sseeeseeseeseeeeeeee 18 mxODBC Connect Configuration File Syntax ceeeeesecsseceeeeeeees 19 mxODBC Connect Server Configuration File seeeeeseeseseesesseeeeereeeeses 20 Connection Namel cerete irene erderen eteisen bestelectoedadebtenctes 20 A thentication eneeier eeaeee aE Eea e ER Ee SRE OEE i PE 24 SESSION aia rar EE ARE O E E R teats 25 AEEA E E E E E 26 Windows esvscscetecsscewatietaseecoteseaiuetensvees E O SEE AE SEE EE EAE 26 Pa e AA A AEE E E T 26 Logging innir e e E E E OE ENSA 27 Server CONNMECUON SEUD aoia rea E OS OEEO ER EES 27 Basic configurations essesreiri resse inaia ieser eana vesitas iee eir 28 Adding SSL support iS easy ssssseeseseeesesssssrssrrsresseseessesressesreeseesses
24. 6 2 1 Parameter Data Type Suryrerica diini orr ANE 67 No support for Python 2 7 memoryviews ssssesseseeeeseereesrrseesresreses 67 6 2 2 Garbage collection and closing of connections CUISOIS se0 68 6 2 3 EXCODUONS a nT E E TENE ENA 68 6 2 4 Convener FUNCIONS aaa E E ET T TE 69 6 2 5 Error Handlers ssc oieee as te a aE elite iene 69 Database Warnings csscsseceseceseceseceeneeeeeeeseeeseecsaecnaecaeseaeee 69 6 2 6 Server Side ExCeptiOnS s Assee sieved esceestecyuees certs seteedasoevebde svsiaaeedoets 69 7 Troubleshooting seesseosseoessosssoosseosseosssoesseessee 7 I 7 1 Frequently Asked Questions FAQ sssssseeseeereeerreerrereeeee 71 mxODBC Connect Python Database Interface 7 1 1 Where can find the server log file on Windows 2 ceseeeseeeeeeeees 71 7 1 2 Where can find the server log file ON UNIX ceeeeeceseeeeeeeseeeeeeeees 71 7 1 3 The Windows installer stops with a message that a file cannot be installed 71 7 1 4 mxODBC Connect Server for Windows doesn t Start ceseeeseees 72 7 1 5 mxODBC Connect Server for Unix doesn t start eeeeseeesseceeeeeeeees 72 7 1 6 Importing exceptions from mx ODBC Error fails no such module 73 7 1 7 Exceptions are not caught as expected at client side eee 73 7 1 8 Client cannot connect to the mxODBC Connect Server sesse 73 7 1 9 Converter function has been set but not called cccccceesseeeeeeees 74
25. Genix com Please see the eGenix comWebsite for details about the license ordering process By downloading copying installing or otherwise using the software you agree to be bound by the terms and conditions of the following eGenix com Commercial License Agreement and the terms and conditions of the third party licenses listed in section 11 2 Third Party Licenses eGenix com Commercial License Agreement 84 11 Copyright amp License EGENIX COM COMMERCIAL LICENSE AGREEMENT Version 1 3 0 Introduction This License Agreement is between eGenix com Software Skills and Services GmbH eGenix com having an office at Pastor Loeh Str 48 D 40764 Langenfeld Germany and the Individual or Organization Licensee accessing and otherwise using this software in source or binary form and its associated documentation the Software Terms and Definitions The Software covered under this License Agreement includes without limitation all object code source code help files publications documentation and other programs products or tools that are included in the official Software Distribution available from eGenix com The Proof of Authorization for the Software is a written and signed notice from eGenix com providing evidence of the extent of authorizations the Licensee has acquired to use the Software and of Licensee s eligibility for future upgrade program prices if announced and
26. Next regarding configuration and use of the mxODBC Connect Server The mxODBC Connect Server has been installed as Windows service and is configured to start automatically at system startup time You may have to open port 6632 in the firewall configuration to make it accessible to mxODBC Connect Clients on your network m If you run into problems please check the Windows Event Log and the mxODEC Connect Server log file and then consult the Troubleshooting section of the mxODBC Connect User Manual Thank you for choosing an eGenix com product As last step the installer will ask you whether it should automatically start the eGenix mxODBC Connect Server and the associated tray icon If you choose not to start the server and or tray icon application you can always go back to the start menu to start them manually oe ee ep wera ey facse t 53 Completing the eGenix com mxODBC Connect Server Setup Wizard Setup has finished installing eGenix com mxODBC Connect Server on your computer The application may be launched by selecting the installed icons Click Finish to exit Setup F Start eGenix com mxODBC Connect Server tray applet Click Finish to exit the installer 11 mxODBC Connect Python Database Interface Server Tray Icon If you have enabled both checkboxes in the final dialog of the installation wizard you should now see a small red icon in your system tray bar
27. PPONE A ELEAN E PERAR 59 Import Order ieee a hice ts canoe eee E EE E 59 gevent Monkey Patching cescsseceseceseceseceseceseeesneeeneeeseeeseeeneeenees 59 mxODBC Connect Client ServerSession Object 59 MOU iscceccceses EEE EE EE E EE EE E 60 Object Constructor rriei e eiir ee e E T 60 Object Attributes seriernes srra reesei oeeie eenei 60 Contents Object Methods irene a ee ee i sels 61 5 5 mxODBC Connect Client Errors sseesesssssessseesseresssessssess 61 5 5 1 Server Side Errors anres sarete iiini ch teens oA EE EREE E ai 62 5 5 2 mxODBC Connect Error MOdUIe eceseeseeeseeeeecseeceeeceaeceeeeneeens 63 5 5 3 SESSION LITOT S ccecevesvecsseoveesescesvs coveteesesveceecousbecceesessteesuesveceessecvecsussres 64 5 6 MXODBC API nareset aga Erena E iE aS 64 6 Differences between mxODBC and mxODBC Connect 65 6 1 Additional Features in mxODBC Connect essseessseeeseese 65 6 1 1 Improved portability ses isisisioereserioreinsisinisiiosissistasiseiivreseiieedieiiis 65 6 1 2 Improved data type support 0 0 eee eeeeeeeeeeeeeeeeeneeeneecsaeceaeceaeeeseees 66 6 1 3 Improved Scalability sanien aneii eeir ei 66 6 1 4 Asynchronous Execution Support using gevent esseeeseseesereersreee 66 6 1 5 Automatic Fail Ovet ceee seie tig neiaie seapea ae aese EEE EE EEE Eee 66 6 1 6 Data COMPIeSSION aerieni aT TEE ANTEE AT EE 67 6 2 Differences and Limitations ssssssssesssssssseseressssreseressese 67
28. ackage It allows to connect your mxODBC compatible application to an ODBC compatible database over a network In order to connect to a database you need to run a properly configured mxODBC Connect Server on the machine with the target ODBC driver usually the machine running the target database itself Prerequisites e Python 2 5 or later installed See http www python org for details and download instructions 38 3 2 2 3 2 3 3 mxODBC Connect Client Installation e eGenix s mx Base extension installed See http www egenix com products python mxBase for details and download instructions e For SSL support optional you should either have eGenix s pyOpenSSL Distribution installed or use the Python standard lib module ssl See http www egenix com products python pyOpenSSL for details for details and download instructions of eGenix s pyOpenSSL distribution Note that using SSL encrypted communication is not allowed in all countries Please check with your local authorities whether you are permitted to use encryption The client has been tested with the official Python 2 5 2 6 and 2 7 installers Python 2 4 and below are not supported Procedure Note You may need administrative privileges on Windows XP 2003 and later to successfully complete the installation or un installation process Please uninstall any existing version of mxODBC Connect Client if you have one installed see section 3 2 3 for detai
29. ast 29 2 MB of free disk space is required The server will also install a startup menu which provides access to the documentation the uninstaller and a few utilities 2 mxODBC Connect Server Installation CARRS EE ss Setup eGenix com mxODBC Connect Server E Ej Pe Select Start Menu Folder Where should Setup place the program s shortcuts EE al Setup will create the program s shortcuts in the following Start Menu folder To continue cick Next If you would like to select a different folder cick Browse Genix com mxODBC Connect Server Browse E Don t create a Start Menu folder s The installer is now ready to install the server Please check the settings and then click on Install TE Setup eGenix com mxODBC Connect Server fo a Ready to Install Setup is now ready to begin installing eGenix com mxODBC Connect Server on your computer Click Install to continue with the installation or dick Back if you want to review or change any settings Destination location 2 C Program Files eGenix com mxODBC Connect Server Start Menu folder eGenix com mxODBC Connect Server During the installation process the installer will create example server and client SSL certificates that you can use to setup the server to accept SSL encrypted connections See section 2 4 mxODBC Connect Server Configuration for more details The installer will also ask you for the mxodbc_connect_s
30. ation has been configured and found working To enable user authentication edit the server config ini file and set the auth_mode setting in the Authentication section to file without the quotes Authentication Protocol The authentication protocol implemented by mxODBC Connect follows a similar scheme as the HTTP Basic Authentication protocol and provides a comparable level of security It is usually better to always use SSL encrypted connections to prevent someone from stealing the session cookie of a logged in session or applying a replay attack to get access to the mxODBC Connect Server Password File authorized users txt You can then either create a password file based on the example file authorized users example txt shipped with the server or use the password tool to create and administer the file When creating the file it is a good idea to make sure that the file can only be read by the server daemon or service It is also possible to change the 31 mxODBC Connect Python Database Interface default name authorized users txt of the password file by adjusting the password file entry of the Authentication section The file format of the password file is similar to that of a web server password file User entries are of the form username hash value with one line per entry Empty lines lines starting with or are ignored so that you can add comments as necessary Example User MD5 Hex Dige
31. b63842defa7d 24 2 mxODBC Connect Server Installation The file should only be readable by the mxODBC Connect Server daemon login salt lt internal default gt In order to provide some extra protection when sending the login request over the network client and server can be configured to add a salt string to the hashed login credentials Only set this if you want to override the internal default or need to separate multiple mxODBC Connect installations from each other The salt string should not be too long and should not contain spaces If given the server setting for this variable must match those of the clients that want to connect to the server The login_salt can be thought of as shared secret Session This section controls the details of the communication between the server and clients Each client will normally open one session to the server A session can host multiple physical database connections max _ sessions 400 Maximum number of concurrent sessions allowed by the server This parameter is intended to prevent Denial of Service DOS attacks on the server You can also use it for debugging purposes or to reduce the load on the server Clients will get a connection error in case the server has reached the maximum number of concurrent sessions Note that this is not the same as the number of concurrent database connections Those are limited by the server license you have installed nable compression
32. base for using the optimal communication technique for local connections Disabling options that are not needed for local connections Also make sure that you have additional features such as connection encryption switched off for ODBC data sources that you intend to use with mxODBC Connect Server Since the communication never leaves the server encrypting it would only cause a performance hit and not result in better security 3 MS SQL Server 2005 and later use the SQL Server Native Client as ODBC driver The communication protocols for this driver are defined in the SQL Server Configuration Manager 35 mxODBC Connect Python Database Interface mxODBC Connect Client Installation The mxODBC Connect product consists of a stand alone server component and client packages for various platforms The installers for both components are distributed separately You only need to integrate the client side package in your application for ODBC functionality over the network With mxODBC Connect it is no longer necessary to have an ODBC driver installed on the machine where you run your Python based applications The mxODBC Connect Client package is distributed as an add on for the eGenix com mx Base Distribution egenix mx base Please visit http www egenix com products python mxBase to download the latest version of the eGenix com mx Base Distribution for your platform and Python version If you also want to benefit from encryp
33. ble to 0 causes compression to be disabled Compression is enabled per default in order to reduce network traffic and enhance roundtrip times On very fast networks or local connections you may want to disable compression for enhanced performance We have found that even on Gigabit Ethernet networks enabling compression does provide a performance increase compression ratio 2 Compression ratio to use for network communication compression Valid values are 1 least compression fast 9 best compression slow The default value of 2 is a good compromise for fast networks You may want to experiment with the setting to tune it for best performance on your network In some setups e g fast server and slow clients it may be wise to use different compression ratios for clients and servers The server setting affects packets sent from the server to the client whereas the client setting affects packets sent from the client to the server max chunk length 64000 Maximum chunk length for TCP read write operations You normally don t have to change this value receive timeout 10 Timeout for one TCP receive operation in seconds You will normally not need to change this value send timeout 10 Timeout for one TCP send operation in seconds You will normally not need to change this value Logging This section defines the details of logging output 49 4 2 2 mxODBC Connect Python Database Interface log_leve
34. connection Clarified the INI file format used by mxODBC Connect Server and Client and added an extra section for this to the documentation Changes from 1 0 0 to 1 0 1 Added cursor iterator support to mxODBC Connect Client Upgraded mxODBC version included in mxODBC Connect Server to 3 0 3 Fixed a problem with database connections being kept alive in sessions that were not explicitly closed by the client application Fixed a bug in print_resultset due to a missing import in one of the modules mxODBC Connect Client prebuilt archives failed to install on non Linux platforms mxODBC Connect Client s ServerSession close will no longer cause error messages at Python exit time if the close event cannot be communicated to the server Changes from 0 9 3 to 1 0 0 Further improved the mxODBC Connect network layer resulting in much better fetch and round trip performance esp for SSL connections 82 10 History amp Changes Improved the documentation added screenshots and more configuration notes as well as tips on how to tune the network performance Fixed a problem with a full Windows event log causing the mnxODBC Connect Server not to start The main_timeout configuration setting in both client and server configurations was split into send_timeout and receive_timeout for better customization on asymmetric network setups The default for the client s server_connections configuration option now is the sorted list o
35. ct Server using the Windows control panel 2 restart the machine and then 3 proceed with the version 2 0 mxODBC Connect Server installation Configuration File Changes When upgrading from 1 0 to 2 0 you can leave the configuration files in place Version 2 0 of the server still knows about the 1 0 configuration settings and will apply them in the same way Unlike version 1 0 version 2 0 is now using a single port to implement SSL and plain text communication As a result the configuration setting using_ssl was replaced with require _ssl and allow ssl This offers more flexibility in the setup You can still use a two port configuration if you like but the default port no longer switches from 6632 to 6633 in case you enable SSL in the connection section Security Related Changes mxODBC Connect Server 2 0 uses SHA1 digest values instead of MD5 digest values This change will increase security of the client certificate checks Affected are the server configuration options client certificate digest and client certificate digest file Both now require SHA1 HEX digests instead of MD5 HEX digests as was needed for mxODBC Connect Server 1 0 Network Related Changes For the version 2 0 of the server we have registered the port 6632 used by mxODBC Connect with IANA as mxodbc connect service Since assigned ports are a rare resource port 6633 is no longer used by the server per default However you can still configure the se
36. ctions and one for SSL only connections you can define more than one connection section in the configuration file Connection Office interface 192 168 0 12 netmask 255 255 255 0 port 6632 Connection Office SSL interface 192 168 0 12 netmask 255 255 255 0 port 6633 require ssl 1 The above setup emulates the setup which was used by mxODBC Connect 1 0 where two ports were used for the communication one for plain text the other for SSL connections With mxODBC Connect 2 0 and later this is no longer necessary since the server can now switch between plain text and SSL as necessary Configuring Certificate Based Authentication The mxODBC Connect Server can perform certificate based authentication checks when a client connects to it via SSL For this to work the connection needs to be configured to require SSL e g Connection SSL interface 192 168 0 12 netmask 255 255 255 0 require ssl 1 The server provides these ways of securing SSL connections e providing a file which contains all allowed client certificates e placing the allowed client certificate files into a directory e providing a list of allowed client certificate SHA1 digests in the server configuration file e providing a list of allowed client certificate SHA1 digests in a separate file All options are read and processed at server startup time so any change will only take affect after a server restart 29 mxODBC Connect Pyt
37. ditions of this License Agreement eGenix com hereby grants Licensee a non exclusive world wide license to 1 use the Software to the extent of authorizations Licensee has acquired and 2 distribute make and install copies to support the level of use authorized providing Licensee reproduces this License Agreement and any other legends of ownership on each copy or partial copy of the Software If Licensee acquires this Software as a program upgrade Licensee s authorization to use the Software from which Licensee upgraded is terminated 86 11 Copyright amp License Licensee will ensure that anyone who uses the Software does so only in compliance with the terms of this License Agreement Licensee may not 1 use copy install compile modify or distribute the Software except as provided in this License Agreement 2 reverse assemble reverse engineer reverse compile or otherwise translate the Software except as specifically permitted by law without the possibility of contractual waiver or 3 rent sublicense or lease the Software Authorizations The extent of authorization depends on the ownership of a Proof of Authorization for the Software Usage of the Software for any other purpose not explicitly covered by this License Agreement or granted by the Proof of Authorization is not permitted and requires the written prior permission from eGenix com Modifications Software modifications may only be distributed
38. e package module top level ie mx ODBCConnect ProgrammingError does not work Instead you have to refer to the exception classes via the mx ODBCConnect Error module e g from mx ODBCConnect Error import ProgrammingError or import mx ODBCConnect Error try except mx ODBCConnect Error ProgrammingError 63 mxODBC Connect Python Database Interface 5 5 3 Session Errors 5 6 ConfigurationError Raised for errors found in the client or server configuration files or data ConnectionFailureError Raised when connection closed prematurely and in other cases ODBCConnectError This is the base class for all mxODBC Connect related errors e g ones raised due to protocol or policy errors It is a subclass of the server error InterfaceError to allow catching the error in DB API compatible applications which were not specifically written for mxODBC Connect PolicyViolationError Error caused by configuration limits on the server side ProtocolHhrror Error in the mxODBC Connect protocol e g due to a version mismatch between client and server TimeoutError Error due to a connection or server timeout mxODBC API All other aspects of creating connections and cursors can be taken straight from the stand alone version of mxODBC Please see the mxODBC User Manual and Reference Guide for details on the connection and cursor APIs The differences between the mxODBC Connect Client and th
39. e it with your own PEM encoded private key file Server dercifticate file server cert Name of the server s SSL certificate file This option is required for all SSL connections The installer provides a default self signed key pair You can replace it with your own PEM encoded certificate file client_certificate file has no default value Name of the file that contains concatenated certificates for client certificate verification client certificate dir has no default value Name of a directory that contains files with single certificates for client certificate verification client certificate digest has no default value Space separated list of SHA1 digest values of accepted client certificates It s recommended to use client certificate digest file if you have many digest values to prevent cluttering up the configuration file and allow sharing of digest list between connections client certificate digest file has no default value Name of a file that contains SHA1 certificate digests for client certificate verification The file can contain more than one digest value one per line 23 mxODBC Connect Python Database Interface Client Certificate Access Rules A client may connect only if at least one of the above client certificate verification rules matches the certificate presented by the client If none of the verification options are defined then all clients are accepted regardless the content of th
40. e stand alone version of mxODBC are described in the next section 64 6 1 6 1 1 6 Differences between mxODBC and mxODBC Connect Differences between mxODBC and mxODBC Connect The most important difference between the stand alone product mxODBC and the client server product mxODBC Connect is the ability to separate the requirements regarding the ODBC driver setup and configuration from the requirements of client application using mxODBC With mxODBC Connect database access becomes mostly independent of the differences between the server running the database and the client machine running your application They may have different number of CPUs bit architectures byte ordering LSB MSB and operating systems Windows Linux eGenix has tried hard to make porting of mxODBC applications to mxODBC Connect as easy as possible Most features available in the stand alone mxODBC are also available in mxODBC Connect However there are a few minor differences between direct and networked access to mxODBC Additional Features in mxODBC Connect Improved portability The mxODBC Connect Client can be installed on any platform that is supported by the eGenix_mx Base Distribution package which is pretty much any platform that Python itself runs on There is no need to find a suitable ODBC driver for the platform on which you intend to install the client This removes one of the major obstacles in getting mxODBC to run on more exotic
41. ect Python Database Interface Module mx ODBCConnect Client ServerSession ServerSession The class is also available directly via the mx oDBCConnect Client module Usage Example from mx ODBCConnect Client import ServerSession Setup a server session session ServerSession config file client config ini Connect to the mxODBC Connect Server server session open Connect to a database connection server DriverConnect DSN UID PWD Object Constructor ServerSession config file None config data None logging None Initialize and configure an mxODBC Connect server session config_file can be given to specify a configuration file If no configuration file is specified defaults are used instead config data can be given as dictionary to override settings from the config file or the defaults The dictionary has to include one dictionary per INI section of the configuration that should be overridden It is possible to provide all configuration parameters via config data logging may be given to have the session use a different mx Log object The default log object is setup using the configuration details from the config file and or config data Base class es object Object Attributes closed True State of the session True or False 1 or 0 depending on whether the session is connected or not Server version Version string of the mxODBC Connect Server 60 5 5
42. eir client certificates The server log file lists the SHA1 digest values of all accepted certificates on each server start It also logs the SHA1 digests of all client certificates it accepts if one of the verification options is enabled Authentication The mxODBC Connect Server can be protected against unauthorized access using different authentication mechanisms This section configures how authentication is handled by the server Note that these authentication checks are not very secure It is generally better to use SSL connections only and implement access control via client certificate checking than relying just on authentication using a username and a password auth_mode none Authentication mode to use Possible values e none no authentication e file password file based authentication password file authorized users txt If auth_mode is set to file password_file must point to a text file defining the users that are allowed to access the mxODBC Connect Server The file format of the password file uses one line entries of the form user md5 hex digest for each user Empty lines and lines starting with or are ignored The md5 hex digest must be set to the 2 digit hex encoded MD5 digest of the user password The hex digest may include or spaces to enhance readability Example User MD5 Hex Digest of the Password joeuser 900150983cd24fb0d6963f7d28e17 72 foobar 4ed9407630eb1000c0f6
43. eption classes are not available via the top level mx ODBCConnect module ie mx ODBCConnect ProgrammingError does not resolve to the ProgrammingError exception class Note that all exceptions are subclassed from the same built in exception classes as their mxODBC equivalents so generic error handlers will work without modifications The client should be modified to catch the new exceptions of the mxODBC Connect Client API such as loss of network connection However this is only required if you need advanced connection handling and automatic fail over 68 6 2 4 6 2 5 6 2 6 6 Differences between mxODBC and mxODBC Connect Converter Functions Converter functions are not supported They may be supported by a later version of mxODBC Connect Error Handlers Error handlers are not fully supported They may be supported by a later version of mxODBC Connect It is possible to register an error handler with mxODBC Connect Client but the exceptions will still always be raised This is mainly due to the fact that error handlers run on the client side Database Warnings For the most common case of using error handlers ignoring database warnings you can use the warningformat connection cursor attribute which allows choosing from different mechanisms to e g ignore warnings on the server side Example from mx ODBCConnect Client import ServerSession Setup a server session session ServerSession conf
44. erver_license py file that you should have obtained from eGenix com by email when signing mxODBC Connect Python Database Interface up for an evaluation or after purchase of an mxODBC Connect Server license Please select your license gO Ji mxodbc connect server licenses X 4 l Search P By Organize gaa Views v BR New Folder Name Date modif Type Favorite Links Hl Desktop E Recent Places jE Computer E Documents E Pictures E Music Recently Changed BB Searches J Public Folders a File name mxodbc_connect_server_license py X Python Files py Z If you haven t yet downloaded and unzipped the license archive that was attached to the eGenix email please do so now and point the installer to the location where you extracted the mxodbc_connect_server_license py and mxodbc_connect_server_license txt file for your installation Note that the installer will just ask for the mxodbc_connect_server_license py file and expect the mxodbc_connect_server_license txt to be in the same directory After installation of the server and license files a read me style notice will be displayed with a few helpful tips that you should read carefully 10 2 mxODBC Connect Server Installation TE Setup eGenix com mxODBC Connect Server Information Please read the following important information before continuing When you are ready to continue with Setup dick
45. et timeout Non TCP socket timeout in seconds or None for disabling connection timeout This is the length of inactivity period after the TCP connection should be dropped You should normally not have to use this option Options for SSL Encrypted Connections These options are only needed for SSL encrypted connections using ssl 0 Setting a non zero value enables the secure socket layer SSL wrapper 46 4 Using mxODBC Connect You can use SSL to encrypt all communication and authenticate your clients via certificate verification see the documentation of the server side SSL configuration Client Certificate Access Rules on page 24 For SSL connections a client certificate and private key can be provided as either file or string to enhance security and allow client authentication based on client certificates client private key file client pkey Name of the client s PEM encoded private key file client CerLiticale file lient cert Name of the client s PEM encoded certificate file The server can authenticate clients by verifying their certificates You must provide a valid and authorized certificate in order to connect to a server protected based on certificates client private key string String with the client s PEM encoded private key client certificate string String with the client s PEM encoded certificate The server installer provides a default self signed certificate key pair c
46. f connection section names Changes from 0 9 2 to 0 9 3 Enhanced the mxODBC Connect client server performance substantially Added optional compression of all network communication enabled per default Fixed a bug related to a missing DLL in the Windows installer of 0 9 2 Fixed a problem with fail over on SSL enabled connections Changes from 0 9 1 to 0 9 2 Enhanced the SQL Server in the Linux mxODBC Connect Server version Improved the documentation and clarified a few things Added more FAQs Added Python 2 6 support 83 11 11 1 mxODBC Connect Python Database Interface Copyright amp License 1997 2000 Copyright by IKDS Marc Andr Lemburg All Rights Reserved mailto ma lemburg com 2000 2012 Copyright by eGenix com Software GmbH Langenfeld Germany All Rights Reserved mailto info egenix com This software is covered by the eGenix com Commercial License Agreement which is included in the following section 11 1 The text of the license is also included as file LICENSE in the package s main directory The software also includes third party software which is covered by other licenses The text of those licenses is included in the following section xxx Please note that using this software is not free of charge You may use the software during an evaluation period as specified in the license but subsequent use requires the ownership of a Proof of Authorization which you can buy online from e
47. h any connection related exceptions and reconnect as necessary Logging This section defines the details of logging output log_ level mx Log SYSTEM IMPORTANT Log level See mxLog for details log file server log Name of the log file to use Please ensure that the server can create the log file and append to existing one Failing to do so will kill the server with access denied exception Server Connection Setup In order to accept connections from the network you will have to customize the server configuration to your needs This section explains how connections are setup The mxODBC Connect Server supports listening on multiple ports and interfaces Each connection configuration needs to be placed into its own section of the configuration file The server detects the connection sections by looking at the section title All sections that start with Connection are interpreted as connection configuration sections 27 mxODBC Connect Python Database Interface Basic configuration This is a basic configuration which listens on subnet 129 168 0 12 24 for plain text unencrypted connections Connection Office interface 192 168 0 12 netmask 255 255 255 0 This connection will not accept SSL encrypted connections and also reject any connections from other subnets Adding SSL support is easy The server installation will create two certificate files for you server pkey the priva
48. hat e the configuration file doesn t have any errors e g duplicate section names illegal values mistyped option names etc e the license files configuration file and certificates are readable by the service user mxODBC Connect Server for Unix doesn t start If you have correctly installed the server licenses but the server fails to start please have a look at the server log file See FAQ entry 7 1 2 for details on where this file is stored If the log file mentions a missing libodbc so 1 or libiodbc so 2 file then the server cannot find your ODBC manager installation Please check the following e You have one of iODBC or unixODBC installed 72 7 1 6 7 1 7 7 1 8 7 Troubleshooting e You have installed the correct version of the eGenix mxODBC Connect Server for your platform ie the x86 version for a 32 bit Linux and the x64 version for a 64 bit Linux e The dynamic linker usually d so is setup to find the shared libraries of the installed ODBC manager ldconfig p should list the libodbc so or libiodbc so files e The mxodbc user account has permission to access the shared library files Importing exceptions from mx ODBC Error fails no such module You have to import the mxODBC related exception classes from mx ODBCConnect Error instead of mx ODBC Error when using mxODBC Connect Client Simply search amp replace your imports and insert Connect in the appropriate places Exceptions are n
49. he Product or for any other purpose not expressly licensed hereunder 3 the Product does not provide functions or capabilities similar to those of the Software itself i e the Product does not introduce commercial competition for the Software as sold by eGenix com 4 Licensee has obtained Developer CPU Licenses for all developers and CPUs used in developing the Product Redistribution Installation Targets any number of CPUs capable of running the Product and the Software 8 Proof This Proof of Authorization was issued by lt name gt lt title gt Langenfeld lt date gt 94 11 Copyright amp License Proof of Authorization Key lt license key gt 11 2 Third Party Licenses eGenix com mxODBC Connect Server contains the following open source third party software components e Python Object Oriented Programming Language e pyOpenSSL Python Interface to OpenSSL e OpenSSL Secure Socket Layer SSL Implementation On Windows the mxODBC Connect Server also uses e pywin32 Python for Windows extensions e Microsoft Visual C 9 0 Runtime DLLs These may only be used with the mxODBC Connect Server installation e Silk Icon Set Icons used for the application on Windows eGenix com mxODBC Connect Client can optionally use and or include following third party software components e pyOpenSSL Python Interface to OpenSSL e OpenSSL Secure Socket Layer SSL Implementation For copyrights notices and l
50. he local system user by default not as the administrative user you used for installation e On 64 bit Windows systems please make sure that you are configuring the right ODBC manager variant for the version of mxODBC Connect you have installed Windows provides the ODBC manager as 32 bit version and 64 bit version each with a separate list of data sources If you install the 64 bit version of mxODBC Connect the default ODBC manager from the C Windows System32 directory should be used If you are using the 32 bit version of mxODBC Connect on Windows x64 please mxODBC Connect Python Database Interface use the 32 bit version instead You can usually find it in the C Windows SysWOW64 _ directory After installation of the mxODBC Connect Server you will find an entry Start the ODBC Manager in its start menu which will point to the right manager for your installation e Please make sure that all your data sources are accessible This can be tested in the Microsoft ODBC Manager at the end of the DSN configuration wizard e The mxODBC Connect Server does not require any version of Python to be installed since it comes with it s own Python runtime and the required set of libraries The server will not interfere or depend on any existing Python installation on your server e You may need administrator privileges on Windows XP 2003 and later to successfully complete the installation or un installation process 2 2 2 Procedure
51. hon Database Interface Using a file with client certificates With this option the incoming client certificates are checked against a file which contains the allowed client certificates concatenated in PEM format To enable this client certificate check please add the client certificates to a file on the server and then add the path to this file to the configuration file e g Name of the file that contains concatenated certificates for client certificate verification client_certificate_file allowed_client_certificate cert The path may be given relative to the server configuration file s directory Using a directory with client certificates With this option the incoming client certificates are checked against a directory listing the allowed client certificates in PEM file format The files have to use the extension cert to be included in the search To enable this client certificate check please add the client certificates to a directory on the server and then add the path to this directory to the configuration file e g Name of a directory that contains files with single certificates for client certificate verification client_certificate_dir allowed_client_certificates The directory may be given relative to the server configuration file s directory Using a list of SHA1 digests in the configuration file With this option the incoming client certificates are checked against a list of allowed SHA1 certif
52. icate digests To enable this client certificate check please add the SHA1 digests in hex format to the configuration file as space separated entry e g Space separated list of SHA1 digest values of accepted client certificates client_certificate digest OC5BD019D9A5C2D4279CC3E4E340E17F OCS5BD019D9A5C2D4279cc3E4e340e180 OC5BD019D9A5C2D427 9CC3E4E340E181 You can use the backslash at the end of a line to split the setting across multiple lines PEM format is a special text file format which can easily be edited using a text editor 30 2 4 5 2 mxODBC Connect Server Installation Using a file with SHA1 digests With this option the incoming client certificates are also checked against a list of allowed SHAT certificate digests In this case the digest values are read from a file To enable this client certificate check please add the SHA1 digests in hex format to a file and then add the path to this file to the configuration file e g Name of a file that contains SHA1 certificate digests for client certificate verification client certificate digest file allowed clients SHAI Configuring User Authentication The mxODBC Connect Server provides a user authentication mechanism to protect the server itself not only the database from unauthorized access User authentication is disabled by default to make a first time configuration easier but should be setup once the basic client server communic
53. icense texts please see the eGenix com Third Party Licenses 2 0 document which is included in the product documentation directory and also available from the eGenix com web site 95
54. ient ccc eeeeeeeeseeeeeee 37 Upgrading from 1 0 to 2 0 0 eee eeseceseceseceseceseeeseeesescneeceaecnaecsaeseaeens 37 Network Related Changes cssecssseesreeseeeseeeseecseecaeceaeeseees 37 Configuration File Changes scssessseesceeseecseecseeceeceseceseenseens 37 MXODBC Feature Changes csscsscssccssrceseeeseeeseecseecaecsaeenseens 38 mxODBC Connect Client Installation on Windows 38 PFEFEQUISITES 35 tceRe dec EA EE AOA evvendee sven Tey eved tes 38 PFOCEDUIEs fei aeee nes ona eari E AEE E ENE A EEE E O AEE E EALE Eie 39 OaE re E E E E E E A 39 mxODBC Connect Client Installation on Unix 40 PETE QUISILES oo ocesiseuetiaedtbet se ge A E etre 40 Installation using prebuilt package archives seeseesseceeceeeeseees 41 System wide Installation eseeeeeeeeeeeseseseeesrsressesressesresserrerseesssee 41 User Installation iissa ee cesecesecsseceseceseeeseesseeeseeesaeeeneecnaecnaecaeeeaeens 41 Uninstall when using prebuilt package archives 42 Installation using egg archives eesssesssseeereseesreeseseessesresserrensesrerseesss 42 Uninstall when using egg package archives cseesseecsecsseceseenseees 43 Using MXODBC Connect scsscsocsssesreeseeeee 44 Architecture of MXODBC Connect ceecceccssseeecceeeeeeceees 44 4 2 4 2 1 4 2 2 4 2 3 4 3 4 3 1 4 3 2 4 3 3 4 4 5 1 5 2 5 2 1 5 2 2 5 3 5 3 1 5 3 2 5 4
55. ig file client config windows ini Connect to the mxODBC Connect Server server session open Connect to a database connection server DriverConnect DSN sqlserver2008 UID sa Ignore warnings issued by the database e g for context switches connection warningformat server IGNORE_WARNINGFORMAT Please see the Database Warning section in the mxODBC documentation for more details Server side Exceptions When printing exceptions raised on the server side the client will only display a partial traceback containing the client side traceback information All other exception information is preserved Note that server side exceptions are logged by mxODBC Connect Server including their full traceback 69 mxODBC Connect Python Database Interface This limitation can also be considered a feature since it prevents accidental leakage of confidential information from the server to the client side 70 7 1 7 1 1 7 1 2 7 1 3 7 Troubleshooting Troubleshooting Please always consult the FAQs before contacting eGenix Support support egenix com Frequently Asked Questions FAQ This section lists frequently asked questions regarding mxODBC Connect Where can I find the server log file on Windows If you have installed the mxODBC Connect Server tray icon helper you can open this file using the tray icon s menu entry Show Log File The server log file is located in the C lt documents a
56. ils on the syntax and has the following sections and options with their default values Connection_Name Each named connection section defines a network connection used to connect to a running mxODBC Connect Server Multiple connections with different names can be specified to provide fail over with multiple servers The only requirement is that the section names contain the term Connection or connection 45 mxODBC Connect Python Database Interface Examples Connection_Local Connection_SSL RemoteConnection FailOverConnection CompanyVPNConnection Note that the order of connection sections is not preserved so the client will try to connect to the servers in undefined order You can define the order of connection attempts by defining the Communication server connections option see below host 127 0 0 1 IP address of the mxODBC Connect Server The server must listen on this address and must be configured to accept connections from the client s IP address port 6632 Port number to connect to Default port number is 6632 IANA name mxodbc connect which is used for both plain and secure SSL connections and is a IANA registered port for eGenix mxODBC Connect The mxODBC Connect Server must listen on this port Please ensure that no firewall is blocking the communication between the client and the server Advanced Connection Options You normally do not need to adjust these sock
57. in form of patches to the original files contained in the Software Distribution The patches must be accompanied by a legend of origin and ownership and a visible message stating that the patches are not original Software delivered by eGenix com nor that eGenix com can be held liable for possible damages related directly or indirectly to the patches if they are applied to the Software Experimental Code or Features The Software may include components containing experimental code or features which may be modified substantially before becoming generally available These experimental components or features may not be at the level of performance or compatibility of generally available eGenix com products eGenix com does not guarantee that any of the experimental components or features contained in the eGenix com will ever be made generally available 87 10 mxODBC Connect Python Database Interface Expiration and License Control Devices Components of the Software may contain disabling or license control devices that will prevent them from being used after the expiration of a period of time or on Installation Targets for which no license was obtained Licensee will not tamper with these disabling devices or the components Licensee will take precautions to avoid any loss of data that might result when the components can no longer be used NO WARRANTY eGenix com is making the Software available to Licensee on an AS IS bas
58. in future versions of the mxODBC Connect Client test pyc Options package Name of the mxODBC package to test dsn ODBC datasource connection string client conftig Location of the mxODBC Connect Client configuration file client log Location of the mxODBC Connect Client log file This is optional The script defaults to logging everything to stderr For more information on the parameters run test pyc with option help It will then print a help screen with available options Note The mxODBC subpackage to be used will be determined by the Session remote module setting in you test configuration file This is Manager by default which means the default ODBC manager installed on the server side 55 5 1 mxODBC Connect Python Database Interface mxODBC Connect Client Python API The mxODBC Connect Client provides a way to easily access the mxODBC package API of the mxODBC Python extension on the mxODBC Connect Server All the network communication proxying and error handling is done transparently by the mxODBC Connect client server logic to make using the client API as easy as using the stand alone version of mxODBC Applications that were written for mxODBC should not require significant changes when porting them to mxODBC Connect API Design Since mxODBC Connect works in a client server setup the client will first have to initialize a server session This is done by creating a Se
59. is SUBJECT TO ANY STATUTORY WARRANTIES WHICH CAN NOT BE EXCLUDED EGENIX COM MAKES NO REPRESENTATIONS OR WARRANTIES EXPRESS OR IMPLIED BY WAY OF EXAMPLE BUT NOT LIMITATION EGENIX COM MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS LIMITATION OF LIABILITY TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN NO EVENT SHALL EGENIX COM BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR I ANY INCIDENTAL SPECIAL OR CONSEQUENTIAL DAMAGES OR LOSS INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS BUSINESS INTERRUPTION LOSS OF BUSINESS INFORMATION OR OTHER PECUNIARY LOSS AS A RESULT OF USING MODIFYING OR DISTRIBUTING THE SOFTWARE OR ANY DERIVATIVE THEREOF EVEN IF ADVISED OF THE POSSIBILITY THEREOF OR Il ANY AMOUNTS IN EXCESS OF THE AGGREGATE AMOUNTS PAID TO EGENIX COM UNDER THIS LICENSE AGREEMENT DURING THE TWELVE 12 MONTH PERIOD PRECEEDING THE DATE THE CAUSE OF ACTION AROSE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE ABOVE EXCLUSION OR LIMITATION MAY NOT APPLY TO LICENSEE Termination This License Agreement will automatically terminate upon a material breach of its terms and conditions if not cured within thirty 30 days of written 88 11 12 13 14 11 Copyright amp License n
60. ived a translation into another language it has been provided for Licensee s convenience only Agreement By downloading copying installing or otherwise using the Software Licensee agrees to be bound by the terms and conditions of this License Agreement For question regarding this License Agreement please write to eGenix com Software Skills and Services GmbH Pastor Loeh Str 48 D 40764 Langenfeld Germany 90 11 Copyright amp License EGENIX COM PROOF OF AUTHORIZATION 1 CPU License Example This is an example of a Proof of Authorization for a 1 CPU License These proofs are either wet signed by the eGenix com staff or digitally PGP signed using an official eGenix com PGP key License Grant eGenix com Software Skills and Services GmbH eGenix com having an office at Pastor Loeh Str 48 D 40764 Langenfeld Germany hereby grants the Individual or Organization Licensee Licensee lt name of the licensee gt a non exclusive world wide license to use the software listed below in source or binary form and its associated documentation the Software under the terms and conditions of this License Agreement and to the extent authorized by this Proof of Authorization Covered Software Software Name lt product name gt Software Version lt product version gt including all patch level releases Software Distribution As officially made available by eGenix com on http www egenix com
61. l mx Log SYSTEM IMPORTANT Log level See mxLog for details iog file client log This is the name of the log file to use Please make sure your client application has write permission to this file and possibly the directory Integration This section defines configuration details needed for integrating mxODBC Connect Client with third party software ssl_module no default value Defines which SSL module mxODBC Connect Client should try to import and use on the client side Possible values are ss1 or pyOpensSsL When not set mxODBC Connect Client will first try to import the pyOpenSSL module and fallback to the Python standard library ssl module available in Python 2 6 and later if this doesn t work gevent 0 mxODBC Connect Client comes with gevent support If you are using the gevent library you can set this setting to 1 in order to enable mxODBC Connect Client s gevent support It will then integrate with the gevent library and use the asynchronous versions of the socket and ssl modules instead of the regular ones The Integration section was added in version 2 0 Configuration Dictionary Format The mxODBC Connect Client session constructor ServerSession takes a parameter config data which can be used to configure the session without requiring installation of a client side configuration INI file or to override certain settings from the configuration file with new values The config_data dictionary mu
62. le through Error module The errors are grouped into errors which originate on the server side and get reraised on the clie nt side Server Side Errors and ones which are raised 61 5 5 1 mxODBC Connect Python Database Interface by the session logic Session Errors The latter are mostly related to network problems A client application should try to catch these errors and issue a reconnect The Server Side Errors are also available via the mxODBC connection object as attributes just like they are in the stand alone mxODBC product Server Side Errors Error Baseclass for all other exceptions related to database or interface errors You can use this class to catch all errors related to database or interface failures error is just an alias to Error needed for DB API 1 0 compatibility Error is a subclass of exceptions StandardError Warning Exception raised for important warnings like data truncations while inserting etc Warning is a subclass of exceptions StandardError This may change in a future release to some other baseclass indicating warnings InterfaceError Exception raised for errors that are related to the interface rather than the database itself DatabaseError Exception raised for errors that are related to the database DataError Exception raised for errors that are due to problems with the processed data like division by zero numeric out of range etc Opera
63. lient pkey and client cert which can be used by clients Communication Settings for network connections Note This section is only needed if you want to configure a fail over setup for your client application server connections defaults to the list of all defined connection sections This option must list connection section names as comma separated list It can be used to determine the order in which the client will attempt to find a working server or to enable disable some connection sections in the configuration file Default is to try all connection sections defined in the file sorted by name 47 mxODBC Connect Python Database Interface Example server connections PrimaryServer SecondaryServer The client will try to connect to the mxODBC Connect Servers in the order given in this list It will use the first successful connection An OperationalError is raised if none of the configured mxODBC Connect servers allowed connections Listing multiple connections is useful to provide a fail over setup Note that the client application must catch connection errors and has to try to reconnect multiple times in order to implement a viable fail over solution Authentication The mxODBC Connect Server can be protected against unauthorized access using different authentication mechanisms This section configures how authentication is handled by the server Note that these authentication checks are not very
64. ls Please download the Windows installer from eGenix com that matches your Python version Double click on the executable you downloaded to begin the installation process Depending on the Windows version you may have to click through a security dialog to proceed Then follow the instructions of the installer You can access the packages as mx ODBCConnect Client For more information please see the detailed usage instructions in section 4 Using mxODBC Connect Uninstall The Windows installer will automatically register the installed software with the standard Windows Software Setup tool 39 3 3 3 3 1 mxODBC Connect Python Database Interface To uninstall the server run the Windows Software Setup tool and select the eGenix mxODBC Connect Client x x x entry for uninstallation This will remove the package from your Python installation mxODBC Connect Client Installation on Unix The mxODBC Connect Client is a regular Python package It allows to connect your mxODBC compatible application to an ODBC compatible database over a network In order to connect to a database you need to run a properly configured mxODBC Connect Server on the machine with the target ODBC driver usually the machine running the target database itself Prerequisites e Python 2 5 or later installed See http www python org for details and download instructions e eGenix s mx Base extension installed See http www egenix com products pyth
65. nd settings gt lt all users gt lt application data gt eGenix com mxODBC Connect Server directory the exact names of the path components depend on your Windows installation Where can I find the server log file on Unix It is located in the home directory of the mxodbc user usually opt eGenix mxODBC Connect Server The Windows installer stops with a message that a file cannot be installed This sometimes happens when you reinstall or update the mxODBC Connect Server Please try the following e Make sure that you have shutdown a possibly running mxODBC Connect Server using the tray applet 71 7 1 4 7 1 5 mxODBC Connect Python Database Interface e Close the mxODBC Connect Server tray applet e Make sure that you have no running processes that start with mxODBC Connect e Click on Retry in the installer message dialog If the problem persists you will have to cancel the installation and restart the system before retrying the installation Since the mxODBC Connect Server runs as Windows service it is possible that a system process still references it or one of its DLLs mxODBC Connect Server for Windows doesn t start If you have correctly installed the server licenses but the server fails to start please have a look at the server log file See FAQ entry 7 1 1 for details on how to open this log file The log should provide an explanation of what caused the startup failure Please make sure t
66. ne Starting Stopping the Server The installer will ask you to start the server at the end of the installation This can easily be done using the provided init d script if you chose to install it etc init d mxodbc connect start etc init d mxodbc connect restart etc init d mxodbc connect stop or by running the server as mxodbc user directly sudo u mxodbc bin mxodbc connect server start sudo u mxodbc bin mxodbc connect server restart sudo u mxodbc bin mxodbc connect server stop Controlling Automatic Startup of the Server The installer will attempt to register the mxodbc connect server daemon and add the appropriate init d script to your system This may not always work due to the many different ways Unix derivatives implement the system startup process Please test the automatic server startup after reboot prior to installing the server on a production machine Troubleshooting If the mxODBC Connect Server service fails to start please have a look at the server log file and consult section 7 Troubleshooting The server log file is available in the home directory of the mxodbc user as server log file If you still have problems please contact eGenix com Support support egenix com 17 2 3 3 2 3 4 2 4 mxODBC Connect Python Database Interface Uninstallation To uninstall the mxODBC Connect Server run the uninstall script from your binary distribution or the server s application directory
67. nnect Server 1 0 mxODBC Connect Server now features all the ODBC driver compatibility enhancements provided by mxODBC 3 2 including better support for MS SQL Server Native Client Oracle Instant Client Sybase ASE IBM DB2 Teradata and Netezza mxODBC Connect Client comes with all mxODBC 3 2 enhancements including o connection and cursor objects can be used as context managers 79 mxODBC Connect Python Database Interface o adjustable parameter styles qmark or named connection autocommit attribute to easily switch on autocommit o adjustable timestamp resolution o new possibilities to set connection and cursor options to adjust the ODBC objects to your application needs e g set a connection read only or set a query timeout o adjustable decimal datetime and string formats o adjustable warning format to be able to handle server warnings without client interaction o greatly improved result set scrolling support o Unicode support for all catalog methods o Access to additional result set meta data via cursor getcolattribute See the included mxODBC 3 2 documentation for more details Asynchronous Execution mxODBC Connect Client now integrates directly with gevent allowing client applications to run asynchronous tasks while performing remote database queries mxODBC Connect Client also works with a monkey patched gevent environment Security mxODBC Connect now uses the official IANA registered
68. nnect Server running on the machine that provides the ODBC drivers for your database This will typically be your database server Architecture of mxODBC Connect The typical mxODBC Connect setup looks like this TCP IP network with optional SSL encryption 44 4 2 4 2 1 4 Using mxODBC Connect The upper blue part in the diagram executes within the process of the Python application The green part usually runs in a separate process and usually also on a different machine mxODBC Connect makes your client application fairly independent of the database server You can use the same client with 32 bit or 64 bit servers without modifications It is also possible to use mxODBC Connect on the same machine e g if you have a 64 bit Python application that needs to use a 32 bit ODBC driver mxODBC Connect Client Configuration Since the mxODBC Connect product is client server based the mxODBC Connect Client will have to know where to find the corresponding mxODBC Connect Server The configuration data can either be stored in a client side INI style configuration file or passed to the client session constructor as dictionary of dictionaries containing one dictionary per section mxODBC Connect Client Configuration File Format If you are using a configuration file please make sure your client application has read access to this file The configuration file uses an INI file format see section 2 4 1 on page 19 for deta
69. ns the script goes into interactive mode Options explained in more detail file arg Edit the password file arg The default is to use the file specified in the server configuration as password file sadd arg Add a new user arg to the password file update arg Update the user arg s password file entry ie set a new password delete arg Delete user arg from the password file list List all entries currently found in the password file password arg Provide the password to use for any subsequent action on the command line If this option is not used the script will read the password from the terminal or stdin without displaying it Interactive Mode of the password tool When called without any options the password tool goes into an interactive mode which allows editing the password file using a set of basic commands On Windows this can also be done by clicking on the product s Configure User Access start menu entry or from the tray icon menu After start up the password tool shows a dialog and asks for action command input 33 2 5 2 5 1 mxODBC Connect Python Database Interface Possible actions add add a new user update update an exiting user delete delete an existing user Tist list all users quit quit the application gt S You enter the action commands at the gt gt gt prompt followed by return Only the first character of the actions has to be ente
70. nstalled as server config ini original It is also a good idea to review your changes of the server configuration against the new mxODBC Connect User Manual mxODBC Connect Server Installation on Unix On Linux mxODBC Connect Server is installed using a command line installer The installer includes support for iODBC and unixODBC ODBC managers one of which is usually preinstalled on Linux systems 13 2 3 1 2 3 2 mxODBC Connect Python Database Interface You can use the available GUl configuration helpers for these ODBC managers to configure your ODBC data sources which then become available to the mxODBC Connect Server and can be used by all applications connecting to the server using the mxODBC Connect Client Prerequisites e You need root access to the target machine e Please make sure that you have a working unixODBC or iODBC installation prior to continuing with the installation e You will need Unix ODBC drivers for all databases you wish to connect to If you can t find the driver you are looking for have a look at section 8 Hints amp Links to other Resources Procedure Please download the binary distribution of mxODBC Connect Server for your version of the installed OS Extract the binary distribution use the name of the file you downloaded tar xf egenix mxodbc connect server 1 0 0 linux i686 tar gz Enter into the subdirectory created by tar and then execute the installer script install
71. oduct name gt Software Version lt product version gt including all patch level releases Software Distribution As officially made available by eGenix com on http www egenix com Operating System any compatible operating system Authorizations 7 1 Application Development eGenix com hereby authorizes Licensee to copy install compile modify and use the Software on the following Developer Installation Targets for the purpose of developing products using the Software as integral part 93 mxODBC Connect Python Database Interface Developer Installation Targets one 1 Developer CPU 7 2 Redistribution eGenix com hereby authorizes Licensee to redistribute the Software bundled with a product developed by Licensee on the Developer Installation Targets the Product subject to the terms and conditions of this License Agreement for installation and use in combination with the Product on the following Redistribution Installation Targets provided that 1 Licensee shall not and shall not permit or assist any third party to sell or distribute the Software as a separate product 2 Licensee shall not and shall not permit any third party to i market sell or distribute the Software to any end user except subject to the terms and conditions of this License Agreement ii rent sell lease or otherwise transfer the Software or any part thereof or use it for the benefit of any third party iii use the Software outside t
72. ogs if needed e g to track down problems related to database ODBC drivers 7 1 12 InterfaceError Connection limit exceeded Your license allows 20 physical database connections This error is the result of having too many physical database connections open on the server side Database connections on the server side are opened and closed following the connect and close calls on the client side However in some cases e g due to errors in the client side application these may not get called and result in the connections to stay open on the server side 74 7 Troubleshooting Please always explicitly close your client side database connections using the connection object s close method Another situation where this may happen can occur when not explicitly closing the ServerSession object on the client side or having this close process fail due to network problems The server will only check client connections every few seconds so the connections may be kept open on the server side even though the client application has already terminated If you frequently start client applications which don t close their ServerSession object this may result in the number of concurrently open connections to reach the license limit giving the above error message Please always explicitly close the ServerSession object using its close method 75 8 1 mxODBC Connect Python Database Interface Hints amp Links to other Resou
73. on If you are using a Python UCS2 build then you can install the egg archives using this command easy install i http downloads egenix com python index ucs2 egenix mxodbc connect client For UCS4 builds please use this command easy install i http downloads egenix com python index ucs4 egenix mxodbc connect client The command line parameters for other tools such as pip are similar Please consult their documentation for details Manual Download and Installation In some cases easy_install and other download tools cannot map the platform name to the name used in the egg archive If you get errors during the installation please manually download the right egg archive and then run the command directly on the downloaded egg archive easy install egenix mxodbc connect client 2 0 0 py2 7 egg Uninstall when using egg package archives Since setuptools doesn t provide an uninstall command you have to manually remove the installation 1 remove the egenix mxodbc connect client egg directory from your Python site packages directory and 2 edit the file easy install pth in that directory to remove the corresponding egg entry 43 4 1 mxODBC Connect Python Database Interface Using mxODBC Connect The mxODBC Connect product provides a client server based access to the ODBC API of ODBC managers and drivers over a network In order to connect to a database you need to have a properly configured mxODBC Co
74. on mxBase for details and download instructions e For SSL support optional you should either have eGenix s pyOpenSSL Distribution installed or use the Python standard lib module ssl See http www egenix com products python pyOpenSSL for details for details and download instructions of eGenix s pyOpenSSL distribution Note that using SSL encrypted communication is not allowed in all countries Please check with your local authorities whether you are permitted to use encryption The client has been tested with the official Python 2 5 2 6 and 2 7 installers Python 2 4 and below are not supported 40 3 mxODBC Connect Client Installation 3 3 2 Installation using prebuilt package archives Note You may need root privileges to successfully complete the installation or un installation process Please uninstall any existing version of mxODBC Connect Client if you have one installed see section 3 3 5 below for details To reduce the number of binaries that we have to create for each release we have adapted a new generic distribution format that works on all Python platforms the Prebuilt Distribution Format Technically this format is a standard Python distutils distribution but with only the build directory and without the source tree After installation you can access the packages as mx ODBCConnect Client For more information please see the detailed usage instructions in section 4 Using mxODBC Connect S
75. on of available ODBC driver packages This should be the first place to look in case you are searching for OBDC connectivity to your database 77 mxODBC Connect Python Database Interface Support eGenix com is providing commercial support for this package including adapting it to special needs for use in customer projects If you are interested in receiving information about this service please see the eGenix com Support Conditions 78 10 10 History amp Changes History amp Changes For more recent changes please visit the product page on the eGenix com website Changes from 1 0 2 to 2 0 0 Integration mxODBC Connect Server is now also available as native 64 bit build for Windows 2008R2 Vista and 7 x64 All mxODBC Connect Server executables are now signed on Windows to reduce the number of UAC dialogs during installation and use The mxODBC Connect tray app was rewritten in C to reduce the memory footprint The mxODBC Connect Server tray application was updated to work on Windows 7 as well mxODBC Connect now supports Python 2 7 both on the client and server side mxODBC Connect Server now supports unixODBC 2 3 or later on Unix platforms unixODBC 2 2 is no longer supported on 64 bit systems API Enhancements mxODBC Connect Server now uses mxODBC 3 2 internally and makes its API available in the mxODBC Connect Client This is a major step forward from the mxODBC 3 0 version used in mxODBC Co
76. ores per processor does not count towards this license limitation Virtual machines always count as one 1 CPU If a Developer CPU is used by more than one developer Licensee must obtain additional Developer CPU licenses to cover the total number of developers using the CPU Commercial Environment refers to any application environment which is aimed at directly or indirectly generating profit This includes without limitation for profit organizations private educational institutions work as independent contractor consultant and other profit generating relationships with organizations or individuals Governments and related agencies or organizations are also regarded as being Commercial Environments Non Commercial Environments are all those application environments which do not directly or indirectly generate profit Public educational institutions and officially acknowledged private non profit organizations are regarded as being Non Commercial Environments in the aforementioned sense Educational Environments are all those application environments which directly aim at educating children pupils or students This includes without limitation class room installations and student server installations which are intended to be used by students for educational purposes Installations aimed at administrational or organizational purposes are not regarded as Educational Environment License Grant Subject to the terms and con
77. ort to implement SSL and plain text communication As a result the configuration setting using_ss1 no longer switches the default port from 6632 to 6633 If you have not changed your server configuration to only use and listen on the single port 6632 you will have to explicitly add the port 6633 definition in the client configuration Connection RemoteServer host database example net using ssl 1 port 6633 37 3 2 3 2 1 mxODBC Connect Python Database Interface Please see section 2 1 Upgrading mxODBC Connect Server for details on how to update the server configuration which allows avoiding such client side configuration changes mxODBC Feature Changes mxODBC Connect Server uses the new mxODBC 3 2 version on the server side which provide better compatibility with current ODBC drivers and also include a number of new features compared to the older mxODBC 3 0 version included in mxODBC Connect Server 1 0 Please see the mxODBC User Manual and Reference Guide for details on the mxODBC API changes mxODBC Connect Client supports all features of the mxODBC 3 2 API with the exception of a few details that are outlined in section 6 Differences between mxODBC and mxODBC Connect Note that unlike the mxODBC 3 2 stand alone version mxODBC Connect Client is compatible with gevent See 5 3 gevent Support for details mxODBC Connect Client Installation on Windows The mxODBC Connect Client is a regular Python p
78. ose action cannot be communicated to the server e mxODBC Connect Client will now raise a mx ODBCConnect Error ConnectionFailureError in case of server connection failures due to timeouts e Fixed a bug in session open which caused the module_name parameter not to get used Misc e Python 2 3 and 2 4 support was removed from mxODBC Connect Client e The start menu entry on Windows now includes a link to the correct ODBC manager to be used with mxODBC Connect Server This helps finding the right one on Windows x64 platforms which provide two versions e mxODBC Connect Client will now directly install into the correct directories on Linux distributions that use different directories for platform dependent and non dependent directories e g 64 bit RedHat 81 mxODBC Connect Python Database Interface and 64 bit OpenSUSE without needing additional options on the install command Added backwards compatibility support for the old style using ssl way of configuring server connections Changes from 1 0 1 to 1 0 2 Upgraded the eGenix pyOpenSSL version included in mxODBC Connect Server to 0 9 0 0 9 8k Fixed a problem with connections sometimes timing out after 10 seconds of inactivity Connection errors now cause an implicit immediate close of the connection without having to wait for a timeout This allows the client to shutdown much faster when exiting the Python client application in the situation of a broken server
79. ot caught as expected at client side You have to import the mxODBC related exception classes from mx ODBCConnect Error instead of mx ODBC Error when using mxODBC Connect Client All exceptions imported from mx ODBCConnect Error are subclassed from the same built in exceptions as the original mxODBC ones Client cannot connect to the mxODBC Connect Server e Ensure that your mxODBC Connect Server is configured correctly and the service or daemon runs without a fatal error e Check the server logs for connection attempts e Ensure that no firewall block the connection on either side 73 7 1 9 mxODBC Connect Python Database Interface e Check your client certificate if the server has client certificate verification turned on Converter function has been set but not called Converter functions are not supported in the current release of mxODBC Connect They might be supported by a later release Please report your problem to eGenix com to let us know about your requirements 7 1 10 Error handlers don t seem to work 7 1 11 Exception will always be raised even if the error handlers don t reraised them This is due to the fact that error handler must run on the client side and therefore cannot influence how the mxODBC Connect Server handles in process error situations Printing exception tracebacks does not include the server side Server side exceptions with full tracebacks can be read in the server l
80. otice by eGenix com Upon termination Licensee shall discontinue use and remove all installed copies of the Software Indemnification Licensee hereby agrees to indemnify eGenix com against and hold harmless eGenix com from any claims lawsuits or other losses that arise out of Licensee s breach of any provision of this License Agreement Third Party Rights Any software or documentation in source or binary form provided along with the Software that is associated with a separate license agreement is licensed to Licensee under the terms of that license agreement This License Agreement does not apply to those portions of the Software Copies of the third party licenses are included in the Software Distribution High Risk Activities The Software is not fault tolerant and is not designed manufactured or intended for use or resale as on line control equipment in hazardous environments requiring fail safe performance such as in the operation of nuclear facilities aircraft navigation or communication systems air traffic control direct life support machines or weapons systems in which the failure of the Software or any software tool process or service that was developed using the Software could lead directly to death personal injury or severe physical or environmental damage High Risk Activities Accordingly eGenix com specifically disclaims any express or implied warranty of fitness for High Risk Activities Licensee ag
81. peration in seconds You will normally not need to change this value This value should allow fairly fast transfers You normally don t need to modify it unless the server or client platform have specific requirements with respect to TCP packet sizes Unix This section is only used on Unix systems such as Linux and FreeBSD pid file server pid Name of the PID file to store the server s PID Windows This section is only used on Windows and currently does not have any options Activity This section defines settings which affect the way it handles timeouts and administrative tasks 26 2 4 3 2 mxODBC Connect Server Installation check interval 2 The time period in seconds of checking server threads for finished threads and errors This is required to clean up internal data structures max request _ execution time 86400 Maximum time allowed to execute a client request in seconds This should be twice the time required to complete your longest SQL query It is used to detect timeout conditions and needed to free resources max waiting time 86400 Maximum amount of time in seconds a working thread in the server waits for a command from a client After this time the connection will be dropped and the client must reconnect The client can prevent the timeout by executing dummy like operations such as a query that doesn t return any values e g SELECT 0 WHERE 1 0 The client could then also catc
82. potential special or promotional opportunities As such the Proof of Authorization becomes part of this License Agreement Installation of the Software Installation refers to the process of unpacking or copying the files included in the Software Distribution to an Installation Target Installation Target refers to the target of an installation operation Targets are defined among other parameters in terms of the following definitions 1 CPU refers to a central processing unit which is able to store and or execute the Software a server personal computer virtual machine or other computer like device using at most two 2 processors 2 Site refers to a single site of a company 3 Corporate refers to an unlimited number of sites of the company 4 Developer CPU refers to a single CPU used by at most one 1 developer Additional terms may be defined as part of the Proof of Authorization 85 mxODBC Connect Python Database Interface When installing the Software on a server CPU for use by other CPUs in a network Licensee must obtain a License for the server CPU and for all client CPUs attached to the network which will make use of the Software by copying the Software in binary or source form from the server into their CPU memory If a CPU makes use of more than two 2 processors Licensee must obtain additional CPU licenses to cover the total number of installed processors The number of c
83. ration Your ServerSession will connect to the first working server in the configured list You can also provide exception handlers for automatic reconnection on connection lost errors and you have full control over the order in which the connections attempts are done The Python Global Interpreter Lock GIL serializes access to the Python interpreter only one thread can execute Python code at a time 66 6 Differences between mxODBC and mxODBC Connect 6 1 6 Data compression 6 2 6 2 1 mxODBC Connect uses data compression for communication between the client and server This reduces the network traffic load and results in faster roundtrips As a result using mxODBC Connect is often faster then using mxODBC together with a client side ODBC driver Differences and Limitations Parameter Data Types Since mxODBC Connect runs all database operations on the server side it has to transfer the Python objects passed as parameters to the cursor execute methods and other methods accepting arbitrary objects over the network in serialized form This operation will only succeed for basic pickleable Python types Unicode string numbers etc as well as eGenix mxDateTime instances since the server only provides support for these types Other objects types such as user defined subclasses cannot be unserialized on the server side and thus may result in mxODBC Connect exceptions to be raised In order to work around this
84. rces More Sources of Information There are several resources available online that should help you getting started with ODBC Here is a small list of links useful for further reading Microsoft MDAC Site Microsoft is constantly developing new forms of database access For a close up on what they have come up recently take a look at their ODBC site Note that they now call their ODBC SDK Microsoft Data Access Components SDK MDAC It does not only focus on ODBC but also on OLE DB and ADO Note If you are not happy about the size of the SDK download over 31MB you can also grab the older 3 0 SDK which might still be available from a FTP server Look for odbc3sdk exe using e g FTP Search Microsoft also supports a whole range of desktop ODBC drivers for various databases and file formats These are available under the name ODBC Desktop Database Drivers search the MS web site for the exact URL wx1350 exe and also included in the more up to date Microsoft Data Access Components MDAC archive mdac_typ exe Microsoft ODBC Portal This portal page has a few interesting links into the Microsoft ODBC site If you re looking for the latest SQL Server or Oracle ODBC drivers this is the place to look first ODBC Documentation The ODBC documentation is included in the free MS MDAC SDK which you can download from their ODBC site SQLSummit List of ODBC drivers 76 8 Hints amp Links to other Resources A collecti
85. red The various actions will then ask for more input as necessary To exit the password tool enter q followed by return Note In interactive mode the password tool will always edit the password file configured in the server config ini file usually authorized users txt ODBC Driver Configuration Hints The typical installation of a mxODBC Connect will have the server part installed directly on the database server and the client parts on the machines running the application Setting up the optimal communication technique In order to benefit from the locality of having the mxODBC Connect Server installation running directly on the database you have to make sure that the ODBC data sources configured on the database server use the best available communication protocol for connecting to a local database server Choosing a TCP IP connection type for the ODBC data sources will not give you the best performance If possible you should select communication options such as Shared Memory Named Pipes Domain Sockets or similar communication methods that allow fast and direct communication between the ODBC driver and the database kernel 34 2 5 2 2 mxODBC Connect Server Installation For MS SQL Server 2000 this option would be Named Pipes MS SQL Server 2005 and later also support the more efficient Shared Memory communication method Please refer to your database documentation on how to setup the ODBC driver and data
86. ree that eGenix com will not be liable for any claims or damages arising from the use of the Software or any software tool process or service that was developed using the Software in such applications General Nothing in this License Agreement affects any statutory rights of consumers that cannot be waived or limited by contract Nothing in this License Agreement shall be deemed to create any relationship of agency partnership or joint venture between eGenix com and Licensee 89 15 mxODBC Connect Python Database Interface If any provision of this License Agreement shall be unlawful void or for any reason unenforceable such provision shall be modified to the extent necessary to render it enforceable without losing its intent or if no such modification is possible be severed from this License Agreement and shall not affect the validity and enforceability of the remaining provisions of this License Agreement This License Agreement shall be governed by and interpreted in all respects by the law of Germany excluding conflict of law provisions It shall not be governed by the United Nations Convention on Contracts for International Sale of Goods This License Agreement does not grant permission to use eGenix com trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee or any third party The controlling language of this License Agreement is English If Licensee has rece
87. riables may be set prior to starting any subsection e Empty lines and lines starting with or comments are ignored 19 mxODBC Connect Python Database Interface e Indentation is not necessary Lines can start at any column e Entries may span multiple lines by using continuations at the line ends The lines are stripped of any white space before removing the trailing and concatenating them Comment lines are removed as well Example Continuation a first line second line Some additional notes regarding the INI file format used by mxODBC Connect e Comments may be used in the INI file but only on separate lines i e a comment after a value is not permitted and will likely cause problems when parsing the option value e All pathnames in the configuration file are relative to the directory of the configuration file You can use absolute pathnames to point any file in the file system 2 4 2 mxODBC Connect Server Configuration File The configuration file uses a standard INI file format see section 2 4 1 on page 19 and has the following sections and options with their default values some are OS dependant Most settings have default values so you only need to provide those settings which you intend to change from their default All file names defined in the server configuration file are interpreted as relative to the server configuration file If you intend to change these file names to locations o
88. rver to use this port if needed Port 6632 can now be used for both SSL and plain text communication It is even possible to have a mixed setup where some clients use plain text and others use SSL communication over that port 2 2 2 2 1 2 mxODBC Connect Server Installation mxODBC Feature Changes mxODBC Connect Server uses the new mxODBC 3 2 version on the server side which provide better compatibility with current ODBC drivers and also include a number of new features compared to the older mxODBC 3 0 version included in mxODBC Connect Server 1 0 Please see the mxODBC User Manual and Reference Guide for details on the mxODBC ODBC driver support enhancements mxODBC Connect Server Installation on Windows The mxODBC Connect Server installer for Windows includes support for the Microsoft ODBC Manager so you can use all available Windows system tools to configure your ODBC data sources Prerequisites e You will need ODBC drivers for all database servers you wish to connect to Windows comes with a very complete set of such drivers and most database vendors also provide Windows ODBC drivers for their databases but if you can t find the driver you are looking for have a look at section 8 Hints amp Links to other Resources e Configure all your databases in Microsoft ODBC Manager as System Data Sources System Data Sources are preferred since any local user can access them Note that the mxODBC Connect Server runs as t
89. rverSession object The ServerSession object maintains the configuration information and deals with the network communication between the client and the mxODBC Connect Server Since mxODBC supports multiple subpackages to implement access to different ODBC manager and drivers the ServerSession object allows connecting the session to one of these packages The default package is defined by the remote module setting in the Session section of the configuration file or settings If not given mxODBC Connect will use the mx ODBC Manager package which always defaults to the standard ODBC manager on the platform where mxODBC Connect Server is installed e g mx ODBC Windows on Windows mx ODBC iODBC on Mac OS X and one of mx ODBC unixODBC or mx ODBC iODBC on other Unix platforms In order to connect a ServerSession object to the remote mxODBC package on the server side an application must call the open method on the object to open and initialize the connection to the server 56 5 2 5 2 1 5 mxODBC Connect Client Python API mxODBC Connect Client will then return a module proxy object that makes the package s API available on the client side This works very much like an import in Python e g instead of writing from mx ODBC import Manager as ODBC in the stand alone version of mxODBC you d write from mx ODBCConnect Client import ServerSession session ServerSession config file conf ini ODBC session open The ODBC
90. s panel or an similar configuration tool after installation Troubleshooting If the mxODBC Connect Server service fails to start please have a look at the server log file and consult section 7 Troubleshooting The server log file is available via the tray icon menu entry Show Log File 12 2 2 3 2 2 4 2 3 2 mxODBC Connect Server Installation If you still have problems please contact eGenix com Support support egenix com Uninstall The Windows installer will automatically register the installed software with the standard Windows Software Setup tool To uninstall the server run the Windows Software Setup tool and select the eGenix com mxODBC Connect Server x x x entry for uninstallation This will stop and unregister the server service then uninstall all files that can be safely removed from the system It will not remove the configuration files log and certificate files by default You are asked whether to remove those as well at the end of the uninstallation process We suggest to backup your configuration directory before removing it Reinstallation or upgrading You can reinstall or upgrade the mxODBC Connect Server by simply uninstalling it without removing its configuration directory and then proceeding with the installation of the upgrade Note After upgrading please check your server configuration file server config ini and compare it to the new default configuration file which will have been i
91. se edit and update the configuration file opt eGenix mxODBC Connect Server server config ini and start the server using etc init d mxodbc connect server start You can now start the server for the first time and check the mxodbc server log file for successful startup Server User Account and Group mxODBC Connect Server runs as it s own mxodbc user for security reasons and stores all of it s configuration and log files under the home directory of this user The user account and directories are created automatically during the installation process Configuring the Firewall The installer registers a daemon named mxodbc connect serve This will listen on TCP port localhost 6632 by default ie the server will only accept connections from the local machine on port 6632 TCP port 6632 is used for both plain and secure SSL connections It s a IANA registered service port for eGenix mxODBC Connect with name mxodbc connect You may have to configure your firewall to allow connections on this port if you want to permit connections from a local subnet 16 2 mxODBC Connect Server Installation Edit the Configuration After installation you must edit the configuration file of the mxODBC Connect Server to fit your needs e g have it listen for connections from the local subnet and then restart the service in order for the changes to take effect See section 2 4 mxODBC Connect Server Configuration for details on how this is do
92. seconds see Activity check interval in the server configuration file documentation on page 26 Exception Handling Exception classes originally imported from mx ODBC Error will have to be imported from mx ODBCConnect Error when using the mxODBC Connect Client This may require slight modifications to your client application All exception classes imported from mx ODBCConnect Error are subclassed from the same built in exception classes as their original counterparts from mx ODBC Error so generic except clauses should work as expected See the sections below for additional features differences and limitations Testing To thoroughly test your mxODBC Connect setup you can use the new mxODBC test script test pyc on the client side which has the ability to run tests against the mxODBC API through an mxODBC Connect Server You have to specify ODBCConnect as package and pass the name of your test configuration file to test pyc python mx ODBCConnect Misc test pyc package ODBCConnect dsn DSN UID PWD client config client config ini client log client log all on one line and without the backslashes 54 4 Using mxODBC Connect This will test a lot of mxODBC and database features many of which are only supported by a few databases so expect quite a few not supported messages Note test pyc currently only supports anonymous server logins This may change
93. secure It is generally better to use SSL connections only and implement access control via client certificate checking than relying just on authentication using a username and a password login salt lt internal default gt In order to provide some extra protection when sending the login request over the network client and server can be configured to add a salt string to the hashed login credentials Only set this if you want to override the internal default or need to separate multiple mxODBC Connect installations from each other The salt string should not be too long and should not contain spaces If given the server setting for this variable must match those of the clients that want to connect to the server The login_salt can be thought of as shared secret Session This section controls the details of the communication with the server remote module Manager Name of the mx ODBC subpackage to be used to connect the database on the server side regardless of the OS the client runs on Possible values Windows iODBC unixODBC and Manager 48 4 Using mxODBC Connect The default value Manager will have the server will use the default ODBC manager on the server side This allows the client to be mostly independent of the server s configuration nable compression 1 Network communication compression Setting this variable to 1 will enable compression of TCP packets sent by the client setting the varia
94. st of the Password joeuser 900150983cd24fb0d6963f7d28e17 72 foobar 4ed9407630eb1000c0f6b63842defa7d The hash values given for each user must be 2 digit standard MD5 hex digests of the password These can easily be generated using md5sum on Unix However it is usually easier to use the password tool command line application for editing the file since this provides all the necessary encoding of the password Using the password tool The password tool command line application is available as bin password tool in the Unix installation of the server and as password tool exe in the Windows installation Both provide a command line option based interface and an interactive shell like interface to edit the password file Command line Options of the password tool The password tool application prints out a list of options when started with h option Synopsis password tool options Options and default settings f arg password file authorized users txt file arg password file authorized users txt add arg add user arg update arg update user arg delete arg delete user arg list list all entries p arg password password arg password y generate verbose output verbose generate verbose output 32 2 mxODBC Connect Server Installation f show this help text help show this help text debug enable debugging copyright show copyright examples show examples of usage Note When started without optio
95. st provide the same data as an INI file but prepared as dictionary of dictionaries with one dictionary per INI section e g config data Logging 4 leg file elient log 50 4 2 3 4 Using mxODBC Connect hy Communication server connections Connection SSL Connection fy Connection hoste 1192 168 1 100 port 6632 Fr Connection SSL host 1192 168 1 100 pork 66327 using ssl 1 For details on section names and options please see section 4 2 1 mxODBC Connect Client Configuration File Format For details on the ServerSession Constructor API please see section 5 2 Multi Threaded Applications If both config_file and the config data dictionary are given on the ServerSession Constructor the values from config_data are merged into the values read from the configuration file or override them mxODBC Connect Client Configuration Hints Since the mxODBC Connect Server runs on the server machine the client applications cannot or should not always know which ODBC manager the server machine uses as default For this reason mxODBC Connect Server provides a generic interface to the server s default ODBC manager The corresponding mxODBC sub package is called mx ODBC Manager By configuring all mxODBC Connect Clients to use this package as server side package you make sure that the clients will always use the default ODBC manager on the server side
96. stallation options run the install script using the help options python setup py install help To uninstall follow the same steps as above but use the command uninstall instead sudo python setup py uninstall home home user Hint On some Linux distributions you may get an error when using the home option In such cases please try using the prefix option instead Uninstall when using prebuilt package archives The easiest way to uninstall the mxODBC Connect Client package is to unzip the pre built binary package and then run sudo python setup py uninstall Depending on how you have installed the package you have to provide additional options to the uninstall command If that doesn t work in your case you can also simply remove the ODBCConnect subdirectory from your path to Python site packages mx directory of your Python installation the exact location depends on your Python installation Installation using egg archives The egg archives we provide are made available through two PyPI style indexes which the egg tools setuptools easy_install pip zc buildout can access to automatically download and install the right egg archive There are two indexes one for Python UCS2 builds http downloads egenix com python index ucs2 and one for Python UCS4 builds 42 3 3 5 3 mxODBC Connect Client Installation http downloads egenix com python index ucs4 Automatic Download and Installati
97. stered port for eGenix mxODBC Connect You are free to use any free port number as long as you follow the convention that unprivileged users and non standardized services need to use port numbers above 1024 However any change you make on the server side will also have to be reflected on the client side Note Using obscure port numbers will not increase your security since a simple port scanner utility can reveal your port number Advanced Options You typically do not need to modify the following options Not specifying them will have the server use the given default values 21 mxODBC Connect Python Database Interface allow reuse address 1 Enables the SO_REUSEADDR socket option This socket option tells the kernel to use the port even if it is currently busy in the TIME_WAIT state If the port is busy but with another state you will still get an address already in use error This option is useful when restarting the server daemon keepalive 1 Enables SO_KEEPALIVE socket option which ensures that client connections will not be dropped due to long inactivity It is recommended to keep this option enabled request queus size 10 The TCP request queue size Maximum number of client connections that can wait to be accepted Increase only if you expect a large number of connection attempts per second socket timeout Non TCP socket timeout in seconds or None for disabling connection timeout
98. te key file and server cert the public key certificate file You can use these generated files as initial setup and later on replace them with your own public key certificate files if you wish Since the above two file names are used per default enabling SSL connections on the server port is done by simply adding allow _ssl 1 to the connection configuration Connection Office interface 192 168 0 12 netmask 255 255 255 0 allow_ssl 1 If you are using custom certificates you can also point the server to those files Connection Office interface 192 168 0 12 netmask 255 255 255 0 allow_ssl 1 server private key file server certificate file my private key file pkey my public key file cert Note that using allow_ssl 1 will not force clients to connect using SSL Plain text connections are still possible as well Please see the next section on how to disable plain text connections altogether Even more secure SSL only connections The communication can also be restricted to SSL only This effectively disables plain text connections on the server port All you have to do is add the require _ssl 1 line to the configuration Connection Office interface 192 168 0 12 netmask 255 255 2550 require ssl 1 28 2 4 4 2 mxODBC Connect Server Installation Listening on more than one port If you have special setup requirements where you want to use more than one port e g one for plain text conne
99. ted connections between the mxODBC Connect Client and Server then you additionally need the Python standard library module ss1 installed which is available in Python 2 6 and later or the eGenix com pyOpenSSL Distribution egenix pyopenss1 Please visit Attp www egenix com products python pyOpenSSL to download the latest version of the eGenix com pyOpenSSL Distribution 36 3 1 3 1 1 3 mxODBC Connect Client Installation IMPORTANT NOTE Before installing the egenix mxodbc connect client package you will have to install the egenix mx base distribution which contains packages needed by mxODBC Connect Even though both distributions use the same installation procedure please refer to the egenix mx base installation instructions on how to install that package Upgrading mxODBC Connect Client Upgrading from 1 0 to 2 0 Network Related Changes For the version 2 0 of the server we have registered the port 6632 used by mxODBC Connect with IANA as mxodbc connect service Since assigned ports are a rare resource port 6633 is no longer used by the server per default However you can still configure the server to use this port if needed Port 6632 can now be used for both SSL and plain text communication It is even possible to have a mixed setup where some clients use plain text and others use SSL communication over that port Configuration File Changes Unlike version 1 0 version 2 0 is now using a single p
100. the same directory Creating group mxodbc Creating user account mxodbc Please extract the license archive you received from eGenix and enter the pathname of the directory containing your license files license py and license txt opt eGenix mxODBC Connect Server Could not find the license py file in that directory Please retry The license files have to be unzipped in the newly created server directory If the installer cannot find the files it continues asking for a new directory until it succeeds opt eGenix mxODBC Connect Server Installing application files Setting up file permissions Creating initial example certificates The installer will create a set of server and client certificates that can be used to setup SSL connections You can replace these later on with your own certificates if needed The eGenix mxODBC Connect Server product comes with an init 15 mxODBC Connect Python Database Interface script that can be used to automatically start the server when the system starts up Install and enable the init script yes no yes Installing init d script mxodbc connect server The init script provides a convenient way of starting stopping the server The installer will try to register the script with the system but this may not always work due to the many ways of how Unix systems expect this to be done eGenix mxODBC Connect Server 1 0 0 was successfully installed Plea
101. tionalError Exception raised for errors that are related to the database s operation and not necessarily under the control of the programmer e g an unexpected disconnect occurs the data source name is not found a transaction could not be processed a memory allocation error occurred during processing etc 62 5 5 2 5 mxODBC Connect Client Python API IntegrityError Exception raised when the relational integrity of the database is affected e g a foreign key check fails InternalError Exception raised when the database encounters an internal error e g the cursor is not valid anymore the transaction is out of sync etc ProgrammingError Exception raised for programming errors e g table not found or already exists syntax error in the SQL statement wrong number of parameters specified performing operations on closed connections etc NotSupportedError Exception raised in case a method or database API was used which is not supported by the database e g requesting a rollback on a connection that does not support transaction or has transactions turned off This is the exception inheritance layout StandardError __ Warning Error __ InterfaceError DatabaseError _ DataError _ OperationalError __IntegrityError __InternalError __ProgrammingError _ NotSupportedError mxODBC Connect Error Module Note that unlike mxODBC the exception classes are not available at th
102. to the way Python s garbage collection works so closing the session explicitly is the preferred way to close the session Storing ServerSessions as module globals Please note that if you store the ServerSession object as module global the object will likely only be garbage collected at Python interpreter shutdown time i e when exiting the application Since Python cleans up the various module namespaces in more or less random order the implicit closing of the session may not succeed Python may have already removed part of the mxODBC Connect Client libraries needed to communicate with the server If you use the ServerSession object as module please register its close method as Python atexit function Python will then call the close method just before starting to shutdown all modules when exiting the application Register atexit function to make sure that the session object gets closed before the module gets destroyed import atexit atexit register ODBC close 53 4 3 3 4 4 mxODBC Connect Python Database Interface Note that mxODBC Connect Server will automatically free up resources on the server side if it detects a broken connection to the client Even without successfully calling the close method the database connections will get closed on the server side However there is a slight delay compared to the explicit approach since the server only checks connections in regular intervals usually every 2
103. utside the normal server installation or configuration directory please make sure that the server has permission to access these files and or directories Connection_Name These named sections each define a network connection to be opened and managed by the server 20 2 mxODBC Connect Server Installation You can add more sections with different names to define multiple connections of your server The only requirement is that the section names contain the term Connection or connection Please use distinctive section names such as _ Connection_Local RemoteConnection or CompanyVPNConnection to prevent future collision with predefined section names All connection sections have the following common attributes interface 127 0 0 1 IP address of the network interface to listen on 127 0 0 1 will only allow connections from the local host netmask 255 0 0 0 Netmask of the interface You should adjust this setting to the layout of the subnet The server will only allow connections from the subnet defined by the interface IP address and netmask Note IP based access control is not considered as a real security feature You need an SSL connection precise rules for database access and difficult to guess passwords to secure your database server port 6632 Port number to listen on Default port number is 6632 IANA name mxodbc connect which is used for both plain and secure SSL connections and is a IANA regi
104. vely maintained by eGenix com to meet the requirements of modern database applications which our customers have built on top of mxODBC This manual will give you an in depth overview of mxODBC Connect the new networked client server edition of mxODBC providing ease of configuration ease of deployment and scalability for all your mxODBC applications It is written as technical manual so background in Python and database programming is needed Technical Overview mxODBC Connect allows your existing mxODBC based applications to access ODBC databases over a TCP IP network and enables you to implement load balancing fail over virtualisation and related technologies for your application mxODBC Connect consists of a stand alone server and client packages which emulate the mxODBC API on the client side The mxODBC Connect Server is available for Windows where it runs as Windows service and on Unix platforms where it can be deployed as daemon process The client package emulates the native mxODBC API so you can continue to use your application code when porting from the stand alone version of mxODBC to mxODBC Connect Furthermore mxODBC Connect will allow you to port your application to platforms which were previously not supported by mxODBC due to limited availability of ODBC drivers 1 For the list of available platforms please see the eGenix com website 1 2 1 3 mxODBC Connect Python Database Interface Security
105. ver The ServerSession instance represents your connection to the mxODBC Connect Server so you have to keep a reference to the object or your connection will be lost 52 4 Using mxODBC Connect The open method returns an efficient proxy object which implements the same API as mxODBC s subpackages have The subpackage you are proxying requests to depends on the client configuration setting Session remote module It defaults to mx ODBC Manager which is an alias to the server platform s default ODBC manager and should be a reasonable choice in most cases Please see the mxODBC documentation for details on how the mx ODBC Manager alias is chosen After this initial setup has been done you can use the ODBC object as if you were running the application on the mxODBC Connect Server machine e g connection ODBC DriverConnect DSN myDSN UID user PWD pwd cursor connect cursor cursor execute select from mytable results cursor fetchall cursor close connection close Once you are done using the ODBC session object you should call the close method on the session object in order to free the resources on the server side and close any still open database connections associated with the client ODBC close The ServerSession object will also close itself at garbage collection time ie when all references to it have been removed from Python namespaces however it is not always clear when this happens due
106. xODBC Connect Server Installation The mxODBC Connect product consists of a stand alone server component and client packages for various platforms The installers for both components are distributed separately The mxODBC Connect Server needs to be installed and configured only on the machine that has the ODBC driver you wish to use This will typically be the database server itself The mxODBC Connect Server is a stand alone product and comes with its own Python run time so you don t need to install Python separately on the server Existing Python installations on the server are not modified in any way by the mxODBC Connect Server Upgrading mxODBC Connect Server Upgrading from 1 0 to 2 0 Windows Service Changes If you have version 1 0 of the mxODBC Connect Server running on a machine please stop the server prior to upgrading Not doing so can lead to error messages during the installation of version 2 0 e g due to timing and lock issues The version 2 0 installer will try to shutdown the 1 0 installation prior to continuing with the installation but since this is done asynchronously by Windows it is possible that the 1 0 server hasn t completely shut down in time for the version 2 0 installer to proceed with the installation If you get error message like service marked for deletion during an upgrade please follow these steps mxODBC Connect Python Database Interface 1 manually uninstall the version 1 0 mxODBC Conne
107. xit Setup Clicking Next will take you to the next screen Cancel aborts this installation process First you have to accept the license agreement mxODBC Connect Python Database Interface License Agreement Please read the following important information before continuing Please read the following License Agreement You must accept the terms of this agreement before continuing with the installation EGENIX COM COMMERCIAL LICENSE AGREEMENT VERSION 1 3 0 1 Introduction This License Agreement is between eGenix com Software Skills and Services GmbH eGenix com having an office at Pastor Loeh Str 48 D 40764 Langenfeld Germany and the Individual or Organization Licensee accessing and otherwise using this software in source or binary form and its associated documentation the Software I accept the agreement I do not accept the agreement Next you have to select the location where the server should be installed on your local disk drive In most cases you can simply accept the default value If the folder does not exist the installer will ask you whether it should create it Where should eGenix com mxODBC Connect Server be installed j Setup will install eGenix com mxODBC Connect Server into the following folder To continue dick Next If you would like to select a different folder dick Browse mxODBC Connect Server Browse Atle
108. ystem wide Installation In order to install such a distribution please follow these instructions 1 Download and unzip the archive into a temporary directory 2 Change into the distribution directory 3 Run the following command using the Python interpreter with which you intend to work this could be the default one or an application specific one depending on your needs sudo python setup py install The distribution will then be installed into the standard directory for Python extensions of your Python installation usually the site packages subdirectory of the Python standard library directory To uninstall follow the same steps as above but use the command uninstall instead sudo python setup py uninstall User Installation You will need to be able to sudo on the target machine or know the root password for the above to work If you don t have permission to install packages as root you can still install the distribution into a local directory e g lib python2 7 by using the following installation command 41 3 3 3 3 3 4 mxODBC Connect Python Database Interface python setup py install home home user This will install the distribution into the directory home user lib python In order to have Python see this directory and make it useable for import you have to adjust the PYTHONPATH environment variable to include this directory e g export PYTHONPATH home user lib python To see all the possible in

Download Pdf Manuals

Related Search

Related Contents

comsphere 3600 series data service units models 3610 and 3611  Couler ou flotter en plongée : mode d`emploi  T'nB IPHAIRV1 holder  AristoFeed 30-4W MA6 AristoFeed 30-4W MA6  SLE3600 INOSYS  Build Your Own MC68HC11 Computer Trainer  ビルメンテナンス業における リスクアセスメントマニュアル  Wheel end bearing and seal installation guide  Hikvision Digital Technology DS-2CE56C2T-IRM surveillance camera  ぞ賀 業x - ご利用の条件｜取扱説明書｜ケンウッド  

Copyright © All rights reserved. Failed to retrieve file