Getting Started

The easiest way to install k-cTDS is from PyPI using pip:

pip install k-ctds

Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (AMD64). The wheels bundle FreeTDS and OpenSSL so there is nothing else to install.

The rest of this page covers building from source, which is only necessary when linking against a custom build of FreeTDS.

Building From Source

k-cTDS is built on top of FreeTDS, which must be installed before compiling from source.

Installing FreeTDS

It is highly recommended to use the latest stable version of FreeTDS, if possible. If this is not possible, FreeTDS can be installed using your system’s package manager.

Warning

FreeTDS 1.0 or later is required. Older versions are not supported.

Installation From Source

FreeTDS can be easily built from the latest stable source for use in a virtualenv using the following:

# Create the virtual environment.
python3 -m venv ctds-venv && cd ctds-venv
wget 'https://www.freetds.org/files/stable/freetds-patched.tar.gz'
tar -xzf freetds-patched.tar.gz
pushd freetds-*

# The "--with-openssl" argument is required to connect to some databases,
# such as Microsoft Azure.
./configure \
        --prefix "$(dirname $(pwd))" \
        --with-openssl=$(openssl version -d | sed  -r 's/OPENSSLDIR: "([^"]*)"/\1/') \
    && make && make install
popd

Installation On Debian-based Systems

Both FreeTDS and the Python development headers can easily be installed using the system package manager on Debian-based systems, such as Ubuntu.

sudo apt-get install freetds-dev python3-dev

Installation On Mac OS X

On OS X, homebrew is recommended for installing FreeTDS.

brew update
brew install freetds

Installation On Windows

On Windows, FreeTDS should be installed from the latest source code. A powershell script is included which may aid in this.

You’ll need Visual Studio 2022 Build Tools and CMake, and 7-Zip installed.

Note

64-bit Python is required. The build toolchain targets amd64 and is only tested against 64-bit Python in CI.

# Add cmake to the path if necessary, using:  $env:Path += ";c:\Program Files\CMake\bin\"
./windows/freetds-install.ps1
# FreeTDS headers and include files are installed to ./build/include
# and ./build/lib

PIP Installation

Once FreeTDS is installed, k-cTDS can be installed from source using pip.

When using a non-system version of FreeTDS, set the following environment variables to point at your FreeTDS installation:

CTDS_INCLUDE_DIRS=$(pwd)/include \
    CTDS_LIBRARY_DIRS=$(pwd)/lib \
    CTDS_RUNTIME_LIBRARY_DIRS=$(pwd)/lib \
    pip install k-ctds --no-binary k-ctds

The three CTDS_* environment variables are read by setup.py during compilation of the C extension:

Variable	Purpose
`CTDS_INCLUDE_DIRS`	Directories containing FreeTDS header files (`sybdb.h`, `ctpublic.h`). Passed to the C compiler as include paths. Separate multiple directories with `:`.
`CTDS_LIBRARY_DIRS`	Directories containing FreeTDS shared libraries (`libsybdb`, `libct`). Passed to the linker as library search paths. Separate multiple directories with `:`.
`CTDS_RUNTIME_LIBRARY_DIRS`	Baked into the compiled extension as an RPATH so the dynamic linker can find FreeTDS at runtime without `LD_LIBRARY_PATH`. Not supported on Windows.

When using the system version of FreeTDS, no variables are needed:

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

When building on Windows, run the following in powershell:

# current directory must be the k-ctds root
$Env:CTDS_INCLUDE_DIRS = "$(pwd)/build/include"
$Env:CTDS_LIBRARY_DIRS = "$(pwd)/build/lib"
$Env:CTDS_RUNTIME_LIBRARY_DIRS = "$(pwd)/build/lib"
pip install -e .

# After pip install, copy FreeTDS DLLs alongside the installed extension:
Copy-Item "$Env:CTDS_LIBRARY_DIRS\*.dll" "$(python -c 'import site; print(site.getsitepackages()[0])')"

Alternatively, if you prefer not to copy DLLs, you can register the directory at runtime before importing. On Python 3.8+, Windows no longer searches PATH for DLL dependencies of extension modules, so os.add_dll_directory must be called before the first import:

import os
os.add_dll_directory(r'C:\path\to\freetds\lib')
import k_ctds