Debian Codegraph @

.github/prompts/mssql-django-dev-environment-setup.prompt.md

raw
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