k-cTDS

k-cTDS is a full Python DB API-2.0-compliant SQL Server database library for Linux, Windows, and Mac OS X supporting Python 3.

k-cTDS is a maintained fork of cTDS, originally developed by Zillow.

The full documentation for k-cTDS can be found here.

Features

• Supports Microsoft SQL Server 2008 and up.
• Complete DB API-2.0 support.
• Python 3.9-3.14 support.
• Bulk insert (bcp) support.
• Written entirely in C.
• Pre-built wheels with bundled FreeTDS and OpenSSL for Linux, macOS, and Windows.
• TLS/SSL support out of the box (OpenSSL 3.0).

Installation

Install from PyPI using pip. Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (AMD64):

pip install k-ctds

That's it — the wheels bundle FreeTDS and OpenSSL so there is nothing else to install. TLS/SSL connections to SQL Server (including Azure SQL) work out of the box.

Note

Pre-built wheels bundle OpenSSL 3.0 (Apache 2.0 license) and FreeTDS 1.5.x (LGPL-2.0, dynamically linked). See THIRD_PARTY_NOTICES for details.

Using a Custom FreeTDS

If you need to link against your own build of FreeTDS (for example, to use a newer version or one compiled with different options), install from source:

pip install k-ctds --no-binary k-ctds

Point the build at your FreeTDS installation using environment variables:

export CTDS_INCLUDE_DIRS=/path/to/freetds/include
export CTDS_LIBRARY_DIRS=/path/to/freetds/lib
export CTDS_RUNTIME_LIBRARY_DIRS=/path/to/freetds/lib
pip install k-ctds --no-binary k-ctds

On Debian/Ubuntu you can use the system FreeTDS:

sudo apt-get install freetds-dev python3-dev
pip install k-ctds --no-binary k-ctds

On macOS with Homebrew:

brew install freetds
pip install k-ctds --no-binary k-ctds

On Windows (requires Visual Studio 2022 Build Tools, CMake, and 7-Zip):

# Build FreeTDS from source (uses the included helper script)
./windows/freetds-install.ps1

$Env:CTDS_INCLUDE_DIRS = "$(pwd)/build/include"
$Env:CTDS_LIBRARY_DIRS = "$(pwd)/build/lib"
pip install k-ctds --no-binary k-ctds

Dependencies

When installed from a pre-built wheel: none — FreeTDS, OpenSSL, and all native dependencies are bundled.

When installed from source: FreeTDS and its development headers must be available on the system.

Releasing

Publishing new versions of the package and documentation is automated using Github Actions workflows. Official releases are marked using git tags. Pushing the tag to the git remote will trigger the automated deployment. E.g.

git tag -a v1.2.3 -m 'v1.2.3'
git push --tags

Documentation

Generate documentation using the following:

tox -e docs
# Generated to build/docs/

Documentation is hosted on GitHub Pages. As such, the source code for the documentation pages must be committed to the gh-pages branch in order to update the live documentation.

Development

Local development and testing is supported on Linux-based systems running tox and Docker. Docker containers are used for running a local instance of SQL Server on Linux. Only Docker and tox are required for running tests locally on Linux or OS X systems. pyenv is recommended for managing multiple local versions of Python. By default all tests are run against the system version of FreeTDS. GNU Make targets are provided to make compiling specific FreeTDS versions locally for testing purposes. For example:

# Run tests against FreeTDS version 1.1.24
make test-1.1.24

Development and testing will require an instance of SQL Server on Linux running for validation. A script, ./scripts/ensure-sqlserver.sh, is provided to start a Docker container running the database and create the login used by the tests.

# Start a docker-based SQL Server instance.
# The default tox targets will do this automatically for you.
make start-sqlserver

# Run tests as needed ...

# Stop the docker-base SQL Server instance.
make stop-sqlserver

Testing

Testing is designed to be relatively seamless using Docker containers and SQL Server on Linux. The pytest framework is used for running the automated tests.

To run the tests against the system version of FreeTDS and Python, use:

tox

GNU make targets are provided for convenience and to provide a standard method for building and installing the various versions of FreeTDS used in testing. Most targets are wrappers around tox or replicate some behavior in the CI/CD automation.

To run the tests against an arbitrary version of FreeTDS:

# Python X.Y & FreeTDS Z.ZZ.ZZ
make test_X.Y_Z.ZZ.ZZ

To run tests against all supported versions of FreeTDS and Python and additional linting and metadata checks:

make check

Valgrind

valgrind is utilized to ensure memory is managed properly and to detect defects such as memory leaks, buffer overruns, etc. Because valgrind requires Python is compiled with specific flags, a Docker file is provided to compile Python as necessary to run the test suite under valgrind.

To run test test suite under valgrind:

make valgrind