pymssql is a Python DB-API (PEP-249) interface to Microsoft SQL Server, built on top of FreeTDS. The 2.x branch, a complete rewrite using Cython, offers improved performance and Python 3 compatibility. It is actively maintained with regular releases, currently at version 2.3.13, and supports Python 3.9 and newer.
pip install pymssqlVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish a connection to a SQL Server database, execute a simple query, and fetch results using the `pymssql` module. It uses environment variables for credentials, which is a recommended practice for security. Results are fetched as dictionaries for easier access.
Review the official 'Migrating from 1.x to 2.x' documentation. Update connection parameters: `host` becomes `server`. Audit code for removed or changed functions.
Explicitly set `tds_version` in `pymssql.connect()` (e.g., `tds_version='7.3'` or `'8.0'`) or configure FreeTDS globally if experiencing connection issues or missing functionality.
For SSL/Azure or Kerberos authentication, you may need to install FreeTDS with SSL/Kerberos support on your system and then build `pymssql` from source against it, or use a Docker image that is pre-configured with the necessary FreeTDS libraries. Alternatively, consider using `pyodbc` for Azure SQL Database connections.
Ensure you have the correct version of Microsoft C++ Build Tools installed (often part of Visual Studio Community Edition or standalone build tools). Upgrade pip if it's too old to handle `manylinux` wheels.
Verify SQL Server configuration (SQL Server Configuration Manager, Surface Area Configuration). Check network firewalls. Use `tsql -H` from FreeTDS to diagnose connectivity issues independently of Python. Ensure `server` and `port` are correctly specified.
Always provide explicit aliases for aggregated columns or expressions in your SQL queries (e.g., `SELECT MAX(column_name) AS max_value FROM ...`).
Upgrade to Python 3.9 or newer to use current `pymssql` versions. If stuck on Python 2, you must use `pymssql` 2.1.4 or older (which is no longer maintained).
Install the package using pip: `pip install pymssql`. If using a virtual environment, ensure it is activated. If still failing, check the Python interpreter path in your IDE.
Verify the server hostname/IP and port (default 1433), ensure the SQL Server instance is running and configured for remote connections, check firewall rules on both client and server, and ensure the SQL Server Browser service is running if connecting to a named instance. Use `tsql -H <host> -p <port> -U <user>` to diagnose FreeTDS connectivity separately.
Double-check the username and password in your connection string. Ensure the SQL Server login exists and has permissions for the database. Also, be aware of password length limitations (e.g., historically 30 characters for some pymssql/FreeTDS versions).
Ensure the correct Microsoft Visual C++ Redistributable (e.g., 2015-2022) is installed for your system architecture. If installing from source, ensure you have the necessary build tools. Sometimes, using a pre-compiled wheel (`.whl` file) downloaded from a reliable source can bypass build issues.
Install the FreeTDS development package for your operating system (e.g., `sudo apt-get install freetds-dev` on Debian/Ubuntu, `brew install freetds` on macOS). After installing FreeTDS, try reinstalling `pymssql` again: `pip install pymssql`.