@@ -66,6 +66,7 @@ $ docker compose run --rm mysql
66
66
$ docker compose run --rm oracle
67
67
$ docker compose run --rm postgres
68
68
$ docker compose run --rm sqlite
69
+ $ docker compose run --rm sqlite-lib
69
70
```
70
71
71
72
Each of the above commands will run the test suite for a different supported
@@ -204,7 +205,14 @@ The versions of various backend services can be switched by setting these enviro
204
205
| ` ORACLE_VERSION ` | ` 23.5.0.0 ` | Version of Oracle container image to use |
205
206
| ` POSTGRESQL_VERSION ` | ` 14 ` | Version of PostgreSQL container image to use |
206
207
| ` POSTGIS_VERSION ` | ` 3.1 ` | Version of PostGIS extension to use |
208
+ | ` SQLITE_VERSION ` | ` 3.31.0 ` | Version of SQLite to compile and use |
207
209
210
+ > [ !NOTE]
211
+ >
212
+ > Using a specific SQLite version requires compiling it from source. To
213
+ > customize the ` CFLAGS ` used for the compilation, you can set the
214
+ > ` SQLITE_CFLAGS ` environment variable. See the [ ` .env ` ] [ 10 ] file for its
215
+ > default value. For more details, see [ SQLite Versions] ( #SQLite-Versions ) .
208
216
209
217
### Python Versions
210
218
@@ -229,7 +237,8 @@ restrictions with respect to the range of versions available.
229
237
### Database Versions
230
238
231
239
Most database container images are pulled from [ Docker Hub] [ 2 ] . Oracle database
232
- is pulled from the [ Oracle Container Registry] [ 3 ] .
240
+ is pulled from the [ Oracle Container Registry] [ 3 ] . Specific versions of SQLite
241
+ are compiled directly from the tags in the [ official Git mirror] [ 11 ] .
233
242
234
243
You can switch the version of the database you test against by changing the
235
244
appropriate environment variable. Available options and their defaults can be
@@ -273,6 +282,41 @@ To determine what database versions can be used you can check the release notes
273
282
for the branch of Django that you have checked out, or alternatively there is
274
283
the [supported database versions][4] page on Django's Trac Wiki.
275
284
285
+ #### SQLite Versions
286
+
287
+ SQLite is normally bundled in the Python installation using the version
288
+ available on the system where Python is compiled. We use the Python Docker image
289
+ based on Debian `bookworm`, which has SQLite 3.40.1.
290
+
291
+ To use a different version, we compile SQLite from source and load the library
292
+ dynamically using `LD_PRELOAD`. There are a few caveats as a result:
293
+
294
+ - Some SQLite features are only available if certain flags are set during
295
+ compilation. SQLite is known to change these flags in newer releases, such as
296
+ to enable features by default that were previously opt-in. When Python is
297
+ compiled, it inspects the system's SQLite to determine features that are
298
+ included in the `sqlite` module. A mismatch in the module and the dynamically
299
+ loaded library may result in Python failing to load, which may happen if we
300
+ use an SQLite version that is older than the system version.
301
+ - Debian and Ubuntu use a custom `CFLAGS` variable to compile their distributed
302
+ SQLite. Historically, Django's CI has only been configured with SQLite
303
+ versions that come with the operating system. If SQLite is compiled with
304
+ different flags, some tests may fail.
305
+
306
+ We currently work around the above caveats by setting the simplest `CFLAGS`
307
+ value that allows all the tests to pass. In the future, the Django codebase may
308
+ be more robust when tested against the different SQLite configurations and these
309
+ workarounds may no longer be necessary.
310
+
311
+ Running the tests against a specific SQLite version must be done using the
312
+ `sqlite-lib` container instead of `sqlite`.
313
+
314
+ ```console
315
+ $ docker compose run --rm sqlite-lib
316
+ ```
317
+
318
+ This is done to avoid compiling SQLite when you are not testing against a
319
+ specific version.
276
320
277
321
### Other Versions
278
322
@@ -309,3 +353,5 @@ with no promises that they'll be delivered:
309
353
[ 7 ] : https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/unit-tests/#running-the-unit-tests
310
354
[ 8 ] : https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/unit-tests/#running-the-selenium-tests
311
355
[ 9 ] : https://docs.djangoproject.com/en/stable/ref/contrib/gis/testing/#geodjango-tests
356
+ [ 10 ] : .env
357
+ [ 11 ] : https://github.com/sqlite/sqlite
0 commit comments