pymssql - Simple MSSQL Python extension module
by Park joon-cheol <jooncheol@gmail.com> (Initial Version Developer)
Andrzej Kukula <akukula@gmail.com> (Active Developer)

License change: due to demand from pymssql users author decided to change
pymssql licence from GPL to LGPL. pymssql 0.8.0 is the first version
released under LGPL.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
-----------------------------------------------------------------------

About pymssql
=============
This module provides access to Microsoft SQL Servers from Python scripts.
It's the most efficient method of accessing MS SQL Server's data from Python
scripts. If you care about performance, you can give it a try.

Supported Platforms
===================

pymssql 0.8.0 has been tested on Linux with kernel 2.6, Windows XP,
FreeBSD 6.1, and NetBSD 3.1. It should also run on other platforms.
pymssql 0.8.0 has been tested with Python 2.4 and Python 2.5. Warning:
previous versions will segfault when compiled and run with Python 2.5.

pymssql 0.7.4 has been tested (among others) on Mac OS X 10.4.7
(thanks Sebastien Arnaud).

pymssql 0.7.1 has been tested on FreeBSD 5.4 and 6.0, NetBSD 2.0.2, Linux
with kernel 2.6, Solaris 10/x86, Mac OS X (thanks Joseph Kocherhans) and
Windows XP. It should also run on other platforms.

If you have any experience with other platforms, just let me know and I'll
add the info here.

Supported SQL Server versions
=============================
pymssql 0.8.0 on *BSD, Linux and Windows were successfully tested with:
- SQL Server 2000 RTM, SP3a, SP4 and post-SP4 (versions 8.00.760, 2139,
  2140, and 2187),
- SQL Server 2005 Enterprise Edition RTM and SP1 (versions 9.00.1399.06 and
  9.00.2047.00),
- SQL Server 2005 Express Edition SP1 (version 9.00.2047.00). 

Features
========
Supports connecting to Microsoft SQL 2000 and SQL 2005 servers, all editions
and service pack levels (see also FAQ / Troubleshooting page).
Supports named instances and non-standard port numbers.
Great performance: it uses MS SQL DB-Library for C instead of Win32 ODBC.
Multiple Query/Multiple Result.
Supports "almost all" of the DB-API 2.0.

Current version is pymssql v0.8.0 released 2006-09-24.

Building
========
If you need to compile pymssql by hand, check whether requirements shown below
are met, unpack source files to a directory of your choice and issue (as root):
# python setup.py install
This will compile and install pymssql.

Warning: if you're on Mandriva Linux and want to compile pymssql, edit setup.py
and change:
libraries = ["sybdb"]
into:
libraries = ["sybdb_mssql"]
Be sure to install freetds_mssql package first.

Build Requirements
------------------
Python 2.4 or newer, 2.5 confirmed, but only with pymssql 0.8.0 or newer.
Linux, *nix and Mac OS X: FreeTDS 0.63 or newer. NOTE: FreeTDS must be
configured with --enable-msdblib to return correct dates! See README.freetds
for details.
Windows: SQL Developer Tools, to be found on MS SQL 2000 installation media.
You need to install MS SQL Client Tools with Developer Tools.
Windows: Microsoft Visual C++ .NET 2003 or Microsoft Visual Studio .NET 2003.
These are usual Python 2.4 build requirements. 

Runtime Requirements
--------------------
Python 2.4 or newer (the code requires datetime module, and the API
functions to manipulate datetime, that's why it won't run on Python earlier
than 2.4, thanks Jakub Labath for pointing that out.)
Linux, *nix and Mac OS X: FreeTDS 0.63 or newer.
NOTE: FreeTDS must be configured with --enable-msdblib to return correct
dates! See README.freetds for details.
Windows: pymssql is equipped with ntwdblib.dll version 2000.80.2087.0
distributed by MS in SQL 2000 post-SP4 hotfix - see KB916287, which supports
connecting to MS SQL 2000 and 2005 servers. This library is redistributable
-- see REDIST.txt in SQL Server 2000 installation package, or in SQL Server
2000 SP4 installation package. You don't have to install full MS SQL Client
Tools unless you want to use advanced client configuration tools available
in that package.

NOTE: pymssql doesn't invalidate the requirement for an SQL Client Access
Licence for every host you want to run it on, be it Windows or *nix, if your
SQL Server is licenced per user or per device connected. 

FAQ / Troubleshooting
=====================

General problems
================

Q: Does pymssql support SQL Server 2005 {Express | Workgroup | Standard |
Enterprise } edition?
A: Yes it does. I've tested it with almost all available SQL 2000/2005
releases, see the front page for details. To be able to connect to SQL 2005
you must select "Client components" and then "Connectivity components" upon
installation of SQL 2005. Also keep in mind that SQL 2005 doesn't accept
remote connections by default. You need to enable them in SQL Server Surface
Area Configuration applet.

---------------------------------------

Q: I cannot connect to MS SQL at all! It's up and working, and other hosts
connect to it normally. What's up?

A: Every time I receive such support request, it turns out that it's the
<put your favorite network security term here> problem: a packet filter,
a firewall, an IPS/IDS or other network device prevents your client host
from connecting to MS SQL Server. Check those conditions carefully as they
are sometimes very difficult to diagnose remotely. If you're 100% sure that
it's not the network problem, try other FAQs, they describe other 
connectivity problems. 

---------------------------------------

Q: What means "Unicode data in a Unicode-only collation or ntext data
cannot be sent to clients using DB-Library"?

A: If you connect to a SQL Server 2000 SP4 or SQL Server 2005, and if
you make a SELECT query on a table that contains a column of type NTEXT,
you may encounter the following error:
  _mssql.error: SQL Server message 4004, severity 16, state 1, line 1:
Unicode data in a Unicode-only collation or ntext data cannot be sent
to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier.

It's the SQL Server complaining that it doesn't support pure Unicode via
TDS or older versions of ODBC. There's no fix for this error. Microsoft has
deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native
Client. Many new features of SQL 2005 aren't accessible via DB-Library so
if you need them, you have to switch away from pymssql or other tools based
on TDS and DB-Library.

A workaround is to change the column type to NVARCHAR (it doesn't exhibit
this behaviour), or TEXT.

Linux/*nix Problems
===================

Q: What do I need FreeTDS for?

A: FreeTDS library is the communication layer, which is used on *nix systems
by pymssql to connect to MS SQL server and exchange data with it. It works
similarly in other MS SQL plugins, be it Perl or PHP.

---------------------------------------

Q: How to connect to non-default (named) instance?

A: First, make sure that the SQL Server instance you're connecting to is
configured to listen on a static TCP port. It can be set on the server using
Server Network Utility available in the Microsoft SQL Server start menu
group -- or in SQL Server Configuration Utility in case of SQL 2005.
The simplest method to connect to this instance is then to use:
conn = _mssql.connect('sqlhost:4801', 'user', 'password')
(the port number shown is an example)

---------------------------------------

Q: How can I set the MS SQL port number? There's no such option in pymssql.
A: There are two methods. You can use the following notation:
conn = _mssql.connect('sqlhost:1433', 'user', 'password')
Or, alternatively, you can set up server aliases in freetds.conf. See below.

---------------------------------------

Q: How to configure freetds.conf?
Q: It keeps displaying:
src/tds/login.c: tds_connect: 192.168.0.222:4000: Connection refused
What's with that port 4000? I've not set it anywhere!

A: Port number can be set in freetds.conf, along with some other options.
The default for FreeTDS is port 4000, hence that error. Here's an example
that shows how to configure MS SQL hosts and instances. There are two
MS SQL instances installed on the same Windows 2000 computer. This
configuration is currently in effect in one of my sites (here it's
obfuscated, naturally...)

# the default instance
[SQL_A]
	host = sqlserver.example.com
	port = 1433
	tds version = 7.0

# second (named) instance; the instance name is not used on *nix
# I configured this instance to listen statically on port 1444
# Network configuration -> TCP/IP -> Properties -> Default port
[SQL_B]
	host = sqlserver.example.com
	port = 1444
	tds version = 7.0

To connect use the name in [...]:
conn_a = _mssql.connect('SQL_A', 'userA', 'passwordA')
conn_b = _mssql.connect('SQL_B', 'userB', 'passwordB')

More examples can be found here:
http://www.freetds.org/userguide/freetdsconf.htm

Remember that FreeTDS library must be able to find your freetds.conf, and must
have permissions to read it. The default is system-wide /etc/freetds.conf
(or similar), but if you aren't root, just be aware that FreeTDS looks for
config in the following places:

1. The environment variable FREETDSCONF can point to specific config, for
example: FREETDSCONF=/usr/pkg/etc/freetds.conf
2. Next it is being looked for in ~/.freetds.conf -- where ``~'' is home
directory of the user running this Python process,
3. In a default system configuration directory, for example /etc/freetds.conf
on Linux, /usr/local/etc/freetds.conf on FreeBSD, /usr/pkg/etc/freetds.conf
on NetBSD, /opt/csw/etc/freetds.conf on Solaris. Beware your vendor can specify
another default place for freetds.conf, one that I'm aware of is Mandriva and
/etc/freetds_mssql.conf.

You can mix SQL 2000 and SQL 2005 instances on one machine, if you need to.
pymssql will have no problems connecting to them.

---------------------------------------

Q: I can't use it, Python displays the following:
>>> import _mssql
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ImportError: Shared object "libsybdb.so.3" not found

A: Do check that your /etc/ld.so.conf contains the directory where you
installed libsybdb.so.3. It can be /usr/lib, /usr/local/lib or
/usr/pkg/freetds/lib on NetBSD. Put proper directory in /etc/ld.so.conf
then do ``ldconfig''. On Solaris I set LD_LIBRARY_PATH to the directory
with libdb.so.* before launching Python.

---------------------------------------

Q: All dates returned from queries have month shifted back by one, e.g. it
returns 2005-00-01 where it should be 2005-01-01. What can I do?

A: The proper solution is to recompile FreeTDS with --enable-msdblib option,
and the problem will disappear itself. If it's not possible, the workaround
is to redesign your queries to return date converted to string instead of
bare datetime. For example if the original is:
    SELECT date FROM table
you can change it to:
    SELECT CONVERT(CHAR(10),date,120) AS date FROM table
Then SQL will return string instead of date and FreeTDS + pymssql will not
have to process (and destroy) it...

---------------------------------------

Q: I've got problems with text truncation -- strings returned from SQL are
shorter than I'd expect.
A: See info on text truncation here:
http://www.freetds.org/userguide/troubleshooting.htm


Windows Problems
================

Q: How to connect to non-default (named instance?)

A: Just use the same notation as with other Windows applications connecting
to MS SQL:
conn_a = _mssql.connect('sqlhost', 'userA', 'passwordA')
conn_b = _mssql.connect('sqlhost\instancename', 'userB', 'passwordB')

If you also need to specify a port number in addition to the instance, use
the following syntax:
conn_c = _mssql.connect('sqlhost\\instancename,portnumber', 'userC', 'passwordC')

---------------------------------------

Q: Strings longer than 255 characters get truncated. Why?

A: All strings longer than 255 characters get truncated. It appears that
types varchar and nvarchar are affected. You have to cast them to text to
get what you expect. This is a gift from Microsoft, an expression of their
lack of support for DB-Library. For the curious - for strings longer than
255 characters DB-Library function dbdatlen() returns 255, as well as
function dbcollen() which holds maximum possible length for the column.
dbdata() also returns already truncated string. 

Links
=====
Sourceforge.net pymssql project page: pymssql.sourceforge.net

