| 1 |
# mssql-django Development Environment Setup |
| 2 |
|
| 3 |
This guide covers setting up a development environment for mssql-django, a Django database backend for Microsoft SQL Server. |
| 4 |
|
| 5 |
## Quick Start |
| 6 |
|
| 7 |
```bash |
| 8 |
# 1. Install mssql-django in development mode |
| 9 |
pip install -e ".[test]" |
| 10 |
|
| 11 |
# 2. Start SQL Server (Docker) |
| 12 |
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=MyPassword42" \ |
| 13 |
-p 1433:1433 --name sqlserver -d mcr.microsoft.com/mssql/server:2022-latest |
| 14 |
|
| 15 |
# 3. Run mssql-django tests |
| 16 |
python manage.py test --noinput |
| 17 |
``` |
| 18 |
|
| 19 |
## Test Options |
| 20 |
|
| 21 |
| Test Type | Tests | Time | Guide | |
| 22 |
|-----------|-------|------|-------| |
| 23 |
| mssql-django unit tests | ~42 | ~22s | [mssql-django-run-unit-tests.prompt.md](mssql-django-run-unit-tests.prompt.md) | |
| 24 |
| Django full test suite | ~6200 | ~45min | [mssql-django-run-django-test-suite.prompt.md](mssql-django-run-django-test-suite.prompt.md) | |
| 25 |
|
| 26 |
## Project Structure |
| 27 |
|
| 28 |
``` |
| 29 |
mssql-django/ |
| 30 |
├── mssql/ # Main backend code |
| 31 |
│ ├── base.py # DatabaseWrapper, connection management |
| 32 |
│ ├── compiler.py # Query compiler, SQL generation |
| 33 |
│ ├── schema.py # Schema editor, migrations |
| 34 |
│ ├── operations.py # Database operations, SQL functions |
| 35 |
│ ├── features.py # Backend feature flags |
| 36 |
│ ├── introspection.py # Database introspection |
| 37 |
│ └── creation.py # Test database creation |
| 38 |
├── testapp/ # Test application |
| 39 |
│ ├── settings.py # Django settings, test exclusions |
| 40 |
│ ├── runners.py # Custom test runner |
| 41 |
│ ├── models.py # Test models |
| 42 |
│ └── tests/ # mssql-django unit tests |
| 43 |
├── django/ # NOT in repo — cloned at runtime by test.sh |
| 44 |
├── test.sh # Script to run Django's full test suite |
| 45 |
├── tox.ini # Test matrix configuration |
| 46 |
└── azure-pipelines.yml # CI configuration |
| 47 |
``` |
| 48 |
|
| 49 |
## Requirements |
| 50 |
|
| 51 |
### System Requirements |
| 52 |
|
| 53 |
- Python 3.8+ (3.12+ recommended; supports up to 3.14) |
| 54 |
- SQL Server 2017, 2019, 2022, 2025 or Azure SQL DB / Managed Instance |
| 55 |
- ODBC Driver 17 or 18 for SQL Server |
| 56 |
|
| 57 |
### Python Dependencies |
| 58 |
|
| 59 |
```bash |
| 60 |
# Development install with test dependencies |
| 61 |
pip install -e ".[test]" |
| 62 |
|
| 63 |
# Core dependencies (installed automatically) |
| 64 |
# - Django >= 3.2, < 6.1 |
| 65 |
# - pyodbc >= 3.0 |
| 66 |
# - pytz |
| 67 |
``` |
| 68 |
|
| 69 |
## Configuration |
| 70 |
|
| 71 |
### Database Settings (`testapp/settings.py`) |
| 72 |
|
| 73 |
```python |
| 74 |
DATABASES = { |
| 75 |
"default": { |
| 76 |
"ENGINE": "mssql", |
| 77 |
"NAME": "default", # Database name |
| 78 |
"USER": "sa", # SQL Server user |
| 79 |
"PASSWORD": "MyPassword42", # Password |
| 80 |
"HOST": "localhost", # Server host |
| 81 |
"PORT": "1433", # Port |
| 82 |
"OPTIONS": { |
| 83 |
"driver": "ODBC Driver 18 for SQL Server", |
| 84 |
"return_rows_bulk_insert": True, |
| 85 |
"extra_params": "TrustServerCertificate=yes" # For self-signed certs |
| 86 |
}, |
| 87 |
}, |
| 88 |
} |
| 89 |
``` |
| 90 |
|
| 91 |
### Test Exclusions |
| 92 |
|
| 93 |
Tests known to fail due to SQL Server limitations are excluded in `testapp/settings.py`: |
| 94 |
|
| 95 |
```python |
| 96 |
EXCLUDED_TESTS = [ |
| 97 |
# Tuple lookups - SQL Server doesn't support (col1, col2) IN syntax |
| 98 |
'foreign_object.test_tuple_lookups.TupleLookupsTests.test_exact', |
| 99 |
# ... see settings.py for full list |
| 100 |
] |
| 101 |
``` |
| 102 |
|
| 103 |
## Common Commands |
| 104 |
|
| 105 |
```bash |
| 106 |
# Install in development mode |
| 107 |
pip install -e ".[test]" |
| 108 |
|
| 109 |
# Run mssql-django tests only |
| 110 |
python manage.py test --noinput |
| 111 |
|
| 112 |
# Run Django's full test suite |
| 113 |
bash test.sh |
| 114 |
|
| 115 |
# Run specific Django test module |
| 116 |
cd django && python tests/runtests.py --settings=testapp.settings composite_pk |
| 117 |
|
| 118 |
# Check Python syntax |
| 119 |
python -m py_compile mssql/compiler.py |
| 120 |
|
| 121 |
# View generated SQL |
| 122 |
python -c " |
| 123 |
from myapp.models import MyModel |
| 124 |
print(MyModel.objects.filter(...).query) |
| 125 |
" |
| 126 |
``` |
| 127 |
|
| 128 |
## SQL Server Limitations |
| 129 |
|
| 130 |
Key limitations that affect the backend implementation: |
| 131 |
|
| 132 |
| Limitation | Description | Workaround | |
| 133 |
|------------|-------------|------------| |
| 134 |
| No LIMIT clause | Must use TOP or OFFSET-FETCH | compiler.py handles this | |
| 135 |
| OFFSET requires ORDER BY | Can't paginate without sorting | compiler.py adds default ORDER BY | |
| 136 |
| No tuple IN | `(a, b) IN (...)` not supported | Tests excluded | |
| 137 |
| No native boolean | Uses BIT type | Automatic conversion | |
| 138 |
| Identifier quoting | Must use `[]` not `""` | operations.py quote_name() | |
| 139 |
| ORDER BY duplicates | Same column can't appear twice | compiler.py deduplicates | |
| 140 |
| ~2100 parameter limit | SQL Server max params per query | Temp table splitting in functions.py | |
| 141 |
| No boolean in SELECT | `supports_boolean_expr_in_select_clause = False` | CASE WHEN wrapping | |
| 142 |
|
| 143 |
## Debugging |
| 144 |
|
| 145 |
### Enable SQL Logging |
| 146 |
|
| 147 |
In `testapp/settings.py`: |
| 148 |
```python |
| 149 |
DEBUG = True # Enables SQL logging to logs/django_sql.log |
| 150 |
``` |
| 151 |
|
| 152 |
### View Generated SQL |
| 153 |
|
| 154 |
```python |
| 155 |
from django.db import connection |
| 156 |
qs = MyModel.objects.filter(...) |
| 157 |
print(qs.query) # Shows SQL without parameters |
| 158 |
print(connection.queries) # Shows executed queries with timing |
| 159 |
``` |
| 160 |
|
| 161 |
## CI/CD |
| 162 |
|
| 163 |
- **CI Platform:** Azure DevOps |
| 164 |
- **Config:** `azure-pipelines.yml` |
| 165 |
- **Test Matrix:** `tox.ini` (Python 3.8-3.14 × Django 3.2-6.0) |
| 166 |
- **SQL Server:** Windows hosted agents with SQL Server 2019+ |
| 167 |
|
| 168 |
## Contributing |
| 169 |
|
| 170 |
1. Create a feature branch |
| 171 |
2. Make changes to `mssql/` files |
| 172 |
3. Add tests to `testapp/tests/` if needed |
| 173 |
4. Run `python manage.py test` to verify |
| 174 |
5. For SQL changes, run `bash test.sh` for full validation |
| 175 |
6. Submit PR against `dev` branch |