Pymssql Documentation Release 2.2.0.Dev
Total Page:16
File Type:pdf, Size:1020Kb
pymssql Documentation Release 2.2.0.dev pymssql developers February 14, 2016 Contents 1 Introduction 1 1.1 Getting started..............................................1 1.2 Architecture...............................................3 1.3 Supported related software........................................3 1.4 Install...................................................3 1.5 Project Discussion............................................4 1.6 Project Status...............................................4 1.7 Current Development..........................................4 2 pymssql examples 5 2.1 Basic features (strict DB-API compliance)...............................5 2.2 Iterating through results.........................................6 2.3 Important note about Cursors......................................6 2.4 Rows as dictionaries...........................................7 2.5 Using the with statement (context managers).............................7 2.6 Calling stored procedures........................................7 2.7 Using pymssql with cooperative multi-tasking systems.........................8 3 _mssql examples 9 3.1 Quickstart usage of various features...................................9 3.2 An example of exception handling.................................... 10 3.3 Custom message handlers........................................ 10 4 Release notes 13 4.1 pymssql 2.0.0............................................... 13 5 FreeTDS 15 5.1 Installation................................................ 15 5.2 Configuration............................................... 16 6 pymssql module reference 19 6.1 Module-level symbols.......................................... 19 6.2 Functions................................................. 19 6.3 Connection class........................................... 21 6.4 Cursor class.............................................. 22 6.5 Exceptions................................................ 24 7 _mssql module reference 27 7.1 Module-level symbols.......................................... 27 i 7.2 Functions................................................. 27 7.3 MSSQLConnection class....................................... 27 7.4 MSSQLStoredProcedure class................................... 31 7.5 Module-level exceptions......................................... 32 8 Migrating from 1.x to 2.x 33 8.1 str vs. unicode ............................................ 33 8.2 Handling of uniqueidentifier columns.............................. 34 8.3 Arguments to pymssql.connect .................................. 34 8.4 Parameter substitution.......................................... 34 9 Frequently asked questions 37 9.1 Cannot connect to SQL Server...................................... 37 9.2 Returned dates are not correct...................................... 39 9.3 Queries return no rows.......................................... 39 9.4 Results are missing columns....................................... 40 9.5 pymssql does not unserialize DATE and TIME columns to datetime.date and datetime.time instances................................................. 41 9.6 Shared object “libsybdb.so.3” not found................................. 41 9.7 “DB-Lib error message 20004, severity 9: Read from SQL server failed” error appears........ 42 9.8 More troubleshooting.......................................... 42 10 Building and developing pymssql 43 10.1 Building................................................. 43 10.2 Testing.................................................. 45 11 FreeTDS and dates 47 11.1 Summary................................................. 47 11.2 Details.................................................. 47 12 Change log 49 13 TODO 65 13.1 Documentation.............................................. 65 Python Module Index 67 ii CHAPTER 1 Introduction 1.1 Getting started Generally, you will want to install pymssql with: pip install pymssql FreeTDS is required. On some platforms, we provide a pre-compiled FreeTDS to make installing easier, but you may want to install FreeTDS before doing pip install pymssql if you run into problems or need features or bug fixes in a newer version of FreeTDS. You can build FreeTDS from source if you want the latest. If you’re okay with the latest version that your package manager provides, then you can use your package manager of choice to install FreeTDS. E.g.: • Ubuntu/Debian: sudo apt-get install freetds-dev • Mac OS X with Homebrew: brew install freetds 1.1.1 Docker (Experimental) Another possible way to get started quickly with pymssql is to use a Docker image. See the Docker docs for installation instructions for a number of platforms; you can try this link: https://docs.docker.com/installation/#installation There is a pymssql docker image on the Docker Registry at: https://registry.hub.docker.com/u/pymssql/pymssql/ It is a Docker image with: • Ubuntu 14.04 LTS (trusty) • Python 2.7.6 • pymssql 2.1.2.dev • FreeTDS 0.91 • SQLAlchemy 0.9.8 1 pymssql Documentation, Release 2.2.0.dev • Alembic 0.7.4 • Pandas 0.15.2 • Numpy 1.9.1 • IPython 2.3.1 To try it, first download the image (this requires Internet access and could take a while): docker pull pymssql/pymssql Then run a Docker container using the image with: docker run -it --rm pymssql/pymssql By default, if no command is specified, an IPython shell is invoked. You can override the command if you wish – e.g.: docker run -it --rm pymssql/pymssql bin/bash Here’s how using the Docker container looks in practice: $ docker pull pymssql/pymssql ... $ docker run -it --rm pymssql/pymssql Python 2.7.6(default, Mar 22 2014, 22:59:56) Type "copyright", "credits" or "license" for more information. IPython 2.1.0 -- An enhanced Interactive Python. ? -> Introduction and overview of IPython's features. %quickref -> Quick reference. help -> Python's own help system. object? -> Details about 'object', use 'object??' for extra details. In[1]: import pymssql; pymssql.__version__ Out[1]: u'2.1.1' In[2]: import sqlalchemy; sqlalchemy.__version__ Out[2]: '0.9.7' In[3]: import pandas; pandas.__version__ Out[3]: '0.14.1' 2 Chapter 1. Introduction pymssql Documentation, Release 2.2.0.dev 1.2 Architecture The pymssql package consists of two modules: • pymssql – use it if you care about DB-API compliance, or if you are accustomed to DB-API syntax, • _mssql – use it if you care about performance and ease of use (_mssql module is easier to use than pymssql). And, as of version 2.1.x it uses the services of the db-lib component of FreeTDS. See the relevant FreeTDS docu- mentation for additional details. 1.3 Supported related software Python Python 2.x: 2.7 or newer. Python 3.x: 3.3 or newer. FreeTDS 0.91 or newer. Cython 0.15 or newer. Microsoft SQL Server 2005 or newer. 1.4 Install Remember to install FreeTDS first. 1.4.1 pip pip install pymssql 1.2. Architecture 3 pymssql Documentation, Release 2.2.0.dev will install pymssql from PyPI. This PyPI page contains: • source distribution (.tar.gz) • wheels (.whl) for Windows 1.5 Project Discussion Discussions and support take place on pymssql mailing list here: http://groups.google.com/group/pymssql, you can participate via web, e-mail or read-only subscribing to the mailing list feeds. This is the best place to get help, please feel free to drop by and ask a question. 1.6 Project Status Current release: 2.x is the branch under current development. It is a complete rewrite using Cython and the latest FreeTDS libraries (which remove many of the limitations of previous versions of FreeTDS). Legacy release: 1.0.3 is the legacy version and is no longer under active development. Note: This documentation is for pymssql 2.x. The document set you are reading describes exclusively the code base of pymssql 2.x and newer. All description of functionality, workarounds, limitations, dependencies, etc. of older revisions has been removed. If you need help for building/using pymssql 1.x please refer to the old Google Code documentation Wiki. 1.7 Current Development Official development repositories and issue trackers have been moved to GitHub at https://github.com/pymssql/pymssql. We would be happy to have: • A couple more developers • Help from the community with maintenance of this documentation. If interested, please connect with us on the mailing list. 4 Chapter 1. Introduction CHAPTER 2 pymssql examples Example scripts using pymssql module. 2.1 Basic features (strict DB-API compliance) from os import getenv import pymssql server= getenv("PYMSSQL_TEST_SERVER") user= getenv("PYMSSQL_TEST_USERNAME") password= getenv("PYMSSQL_TEST_PASSWORD") conn= pymssql.connect(server, user, password,"tempdb") cursor= conn.cursor() cursor.execute(""" IF OBJECT_ID('persons','U') IS NOT NULL DROP TABLE persons CREATE TABLE persons ( id INT NOT NULL, name VARCHAR(100), salesrep VARCHAR(100), PRIMARY KEY(id) ) """) cursor.executemany( "INSERT INTO persons VALUES (%d, %s, %s)", [(1,'John Smith','John Doe'), (2,'Jane Doe','Joe Dog'), (3,'Mike T.','Sarah H.')]) # you must call commit() to persist your data if you don't set autocommit to True conn.commit() cursor.execute('SELECT * FROM persons WHERE salesrep=%s','John Doe') row= cursor.fetchone() while row: print("ID=%d, Name=%s"% (row[0], row[1])) row= cursor.fetchone() conn.close() 5 pymssql Documentation, Release 2.2.0.dev 2.2 Iterating through results You can also use iterators instead of while loop. conn= pymssql.connect(server, user, password,"tempdb") cursor= conn.cursor() cursor.execute('SELECT * FROM persons WHERE salesrep=%s','John Doe') for row in cursor: print('row