Skip to content

BUILDGUIDE.md

Latest commit

 

History

History
191 lines (139 loc) · 4.7 KB

BUILDGUIDE.md

File metadata and controls

191 lines (139 loc) · 4.7 KB

Build Guide for Contributors

Welcome to the development build guide for the mssql-python project!
This guide will help you set up your environment, build the native bindings, and package the project as a Python wheel.

Table of Contents

Prerequisites

  • Python: Minimum supported version is 3.10.
    Ensure python and pip commands refer to your Python 3.10+ installation.
  • pybind11: Used for C++/Python bindings.
  • CMake: For Unix and macOS builds.
  • Microsoft ODBC Driver: For packaging driver dependencies and header files such as sql.h, sqlext.h etc.
  • setuptools, wheel, pytest: For building and testing (pip install setuptools wheel pytest).

Platform-Specific Setup

Windows

  1. Install Python (3.10+ from python.org).
  2. Install Visual Studio Build Tools
    • Include the “Desktop development with C++” workload.
    • CMake is included by default.
  3. Install Microsoft ODBC Driver for SQL Server:
    Download here.
  4. Install required Python packages: 
    # Will install pybind11, setuptools etc.
pip install -r requirements.txt

macOS

  1. Install Python (3.10+ from python.org).
  2. Install CMake: 
    brew install cmake
  3. Install Microsoft ODBC Driver for SQL Server:
  4. Install Python requirements: 
    # Will install pybind11, setuptools etc.
pip install -r requirements.txt

Linux

  1. Install Python and development tools: 
    sudo apt-get update
sudo apt-get install python3 python3-dev python3-pip build-essential cmake
    Ensure python and pip refer to Python 3.10+.
  2. Install Microsoft ODBC Driver for SQL Server:
  3. Install Python packages: 
    # Will install pybind11, setuptools etc.
pip install -r requirements.txt

Building Native Bindings

The native bindings are in the pybind directory.

Windows

Open a Developer Command Prompt for VS and run:

cd pybind
build.bat

This will:

  • Clean previous builds
  • Configure with CMake
  • Build the extension
  • Copy the generated .pyd file to the correct location

macOS & Linux

cd pybind
./build.sh

This will:

  • Clean previous builds
  • Configure with CMake
  • Build the extension
  • Copy the generated .so file to the correct location

Running Tests

Tests require a database connection string. Set the DB_CONNECTION_STRING environment variable before running tests:

Windows (Command Prompt)

set DB_CONNECTION_STRING=your-connection-string-here
python -m pytest -v

macOS & Linux (bash/zsh)

export DB_CONNECTION_STRING=your-connection-string-here
python -m pytest -v

Building the Python Wheel (.whl)

The wheel includes the native bindings.
You must build the native bindings first (see above).

Windows

From the project root:

python setup.py bdist_wheel

The wheel file will be created in the dist/ directory.

macOS & Linux

From the project root:

# Build the bindings first!
cd pybind
./build.sh
cd ..

# Then build the wheel:
python setup.py bdist_wheel

The wheel file will be created in the dist/ directory.

Directory Structure

  • pybind/ — Native C++/pybind11 bindings and platform build scripts
  • mssql_python/ — Python package source
  • tests/ — Test suite
  • dist/ — Built wheel packages

Troubleshooting

  • Ensure all prerequisites are installed and on your PATH.
  • If a build fails, clean up old artifacts and try again (pybind/build.bat clean or ./build.sh clean).
  • For wheel issues, ensure the native binding (.pyd or .so) is present in the expected location before building the wheel.
  • For test failures, double-check your DB_CONNECTION_STRING.

For more details on the native bindings, see pybind/README.md.

Happy coding!