feat(generic): Reintroducing the generic SQL module by Tranquility2 · Pull Request #892 · testcontainers/testcontainers-python · GitHub

Related to #884
Trying to replace the old generic.py in core to a nicer version under the generic module.

SqlContainer its not as good (in being generic) as ServerContainer but it should allow us to deprecate core/testcontainers/core/generic.py with minimal effort for users, it could lead to a more Generic version like DBContainer in the future.

Update 1: Refactor to use SqlConnectWaitStrategy
Update 2: Now SqlConnectWaitStrategy is required and the users can provide SqlContainer with any wait strategy.
Update 3: Now utilizes all the latest improvements from WaitStrategy

Note: I think the added tests + documentation (provided in this PR) are by themselves a great improvement over the current generic.py

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.86%. Comparing base (af382f7) to head (d502fb6).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #892   +/-   ##
=======================================
  Coverage   78.86%   78.86%           
=======================================
  Files          14       14           
  Lines        1221     1221           
  Branches      142      142           
=======================================
  Hits          963      963           
  Misses        216      216           
  Partials       42       42

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

can we add a new extra? like a db (or more accurately, sql) extra? this is assuming we dont want to aim for complete removal.

Even if we do that, i dont like the _connect method on the container - i think connecting is the business of 1) app code 2) sql waiting strategy - so all the db interface has to do is tell someone how to connect - and maybe this can just return the url?

This second point is made further complicated by now you can only use this waiting strategy on container that have the interface implemented. i think maybe this waiting strategy can be parametrized - with information on how to build the url. this removes the need for the container to build its own url (finally). just a thought.

The new extra sound a bit like an overkill and could be a bit confusing for the users don't you think? My goal was to make the transition as seamless as possible but I agree it might be a good time to rethink some things. I just don't want to "branch out" too much, all in all its a very good point but I concerned it will be lost will all the other sql modules 😓
I totally understand your point regarding _connect , I had one iteration where all the logic was under ConnectWaitStrategy (with no _connect at all) and I assumed we want backward compatibility with DbContainer so it will be easier to move to (so we can remove generic.py), let me try and do another version without the connect and ConnectWaitStrategy more parametrized as you suggested.

New version is ready:

no more _connect
all extended logic moved to SqlConnectWaitStrategy (new file) making sql.py much cleaner and more generic
smaller improvements to make the code simpler and easier to maintain

You can now say SqlConnectWaitStrategy is basically sqlalchemyConnectWaitStrategy 😂 but this can also be improved and made more generic.

I like the new SqlConnectWaitStrategy a lot. Indirectly the _connect method paired with wait_container_is_ready did just that in many database modules.

Make one more critical improvement, now wait_strategy is a param for the SqlContainer, this

keeps it very generic - all the others can use it with ease
provides SqlConnectWaitStrategy if anyone needs its
allows each module to provide a custom wait_strategy (that can be as simple as waiting for some log string from the server)

@alexanderankin now using WaitStrategy._poll and with_transient_exceptions from your latest improvements.
This makes SqlConnectWaitStrategy much simpler cleaner, thanks 🙏

Tried to migrate Postgres and CrateDB module and it's fairly easy, I left a few nitpicks that you might use as inspiration, otherwise LGTM and I'd merge.

Overall clearly an improvement on the existing DbContainer. A few questions/ideas inline, many to clarify my own understanding of stuff.

Should this have a default implementation to just call _create_connection_url? The SimpleSqlContainer implements it in this way & this feels like a reasonable default. I suspect most users of this class would either duplicate the implementation, or call the private method anyway which I think we'd want to discourage.

SimpleSqlContainer is just a test, are you sure this is the default for all SQL related implementations?
for example Postgres needs driver so its not the exact same, but an extended build using the baseline _create_connection_url which is great. I personally like the current design and believe/hope it allows for max flexibility in the future.

This reverts commit f613a61.

🤖 I have created a release *beep* *boop* --- ## [4.15.0-rc.1](testcontainers-v4.14.2...testcontainers-v4.15.0-rc.1) (2026-04-07) ### Features * **compose:** add structured container inspect information ([#897](#897)) ([58459a1](58459a1)) * **core:** support SSH-based DOCKER_HOST ([#993](#993)) ([d48115d](d48115d)) * **generic:** Reintroducing the generic SQL module ([#892](#892)) ([2ca2321](2ca2321)) * **keycloak:** support for relative path and management relative path ([#982](#982)) ([898faf6](898faf6)) * **mqtt:** MosquittoContainer: Add version 2.1.2 ([#978](#978)) ([af382f7](af382f7)) ### Bug Fixes * **azurite:** make visible to type checkers ([#927](#927)) ([baa5668](baa5668)) * **clickhouse:** add `HttpWaitStrategy` instead of deprecated `wait_container_is_ready` ([#962](#962)) ([8034541](8034541)) * **compose:** return type in get_service_port docstring ([#939](#939)) ([fed65fe](fed65fe)) * **core:** Refactor copy file ([#996](#996)) ([0e0bb24](0e0bb24)) * **core:** wait for ryuk more reliably, improve tests: long_running, filter logs ([#984](#984)) ([b12ae13](b12ae13)) * **generic:** Migrate ServerContainer from deprecated decorator to HttpWaitStrategy ([#971](#971)) ([460b0d8](460b0d8)) * **kafka:** Use wait strategy instead of deprecated wait_for_logs ([#903](#903)) ([87332c1](87332c1)) * **postgres:** add py.typed marker to postgres module ([#849](#849)) ([c8a5bbd](c8a5bbd)) * **qdrant:** migrate Qdrant from deprecated decorator. ([#963](#963)) ([407f798](407f798)) * **redis:** Use wait strategy instead of deprecated decorator ([#914](#914)) ([e25713a](e25713a)) * **sftp:** Avoid using wait_for_logs in module. ([#995](#995)) ([83157eb](83157eb)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: David Ankin <daveankin@gmail.com>

Add a CrateDB module under testcontainers.community.cratedb, ported from testcontainers#888 onto the current src/ layout and refactored onto the generic DbContainer base (per testcontainers#892), following the PostgresContainer pattern. - CrateDBContainer extends core.generic.DbContainer; single-node command, HTTP (4200) wait strategy, crate:// SQLAlchemy connection URL - deprecation shim at testcontainers.cratedb - tests under tests/community/cratedb, docs, and the `cratedb` optional-dependency - sqlalchemy-cratedb added to the test dependency group Supersedes testcontainers#888. Co-authored-by: surister <surister98@gmail.com>

Add a CrateDB module under testcontainers.community.cratedb, ported from testcontainers#888 and built on the generic SqlContainer base reintroduced in testcontainers#892. - CrateDBContainer extends community.generic.sql.SqlContainer; single-node command, HTTP (4200) wait strategy so startup needs no DB client library, crate:// SQLAlchemy connection URL - deprecation shim at testcontainers.cratedb - tests under tests/community/cratedb, docs, mkdocs nav entry, and the `cratedb` optional-dependency (empty; sqlalchemy-cratedb is a test-group dep) Supersedes testcontainers#888. Co-authored-by: surister <surister98@gmail.com> Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add a CrateDB module under testcontainers.community.cratedb, ported from testcontainers#888 and built on the generic SqlContainer base reintroduced in testcontainers#892. - CrateDBContainer extends community.generic.sql.SqlContainer; single-node command, HTTP (4200) wait strategy so startup needs no DB client library, crate:// SQLAlchemy connection URL - deprecation shim at testcontainers.cratedb - tests under tests/community/cratedb, docs, mkdocs nav entry, and the `cratedb` optional-dependency (empty; sqlalchemy-cratedb is a test-group dep) Supersedes testcontainers#888. Co-authored-by: surister <surister98@gmail.com>

Add a CrateDB module under testcontainers.community.cratedb, ported from #888 and built on the generic SqlContainer base reintroduced in #892. - CrateDBContainer extends community.generic.sql.SqlContainer; single-node command, HTTP (4200) wait strategy so startup needs no DB client library, crate:// SQLAlchemy connection URL - deprecation shim at testcontainers.cratedb - tests under tests/community/cratedb, docs, mkdocs nav entry, and the `cratedb` optional-dependency (empty; sqlalchemy-cratedb is a test-group dep) Supersedes #888 --------- Co-authored-by: surister <surister98@gmail.com> Co-authored-by: Andreas Motl <andreas.motl@elmyra.de>

Tranquility2 mentioned this pull request Oct 2, 2025

What class to use to implement or migrate database modules #884

Closed

Tranquility2 linked an issue Oct 3, 2025 that may be closed by this pull request

What class to use to implement or migrate database modules #884

Closed

Tranquility2 changed the title feat(generic): Added generic SQL module feat(generic): Reintroducing the generic SQL module Oct 3, 2025

Tranquility2 requested a review from alexanderankin October 3, 2025 10:53

surister reviewed Oct 3, 2025

View reviewed changes

Comment thread modules/generic/testcontainers/generic/sql.py Outdated

Tranquility2 requested a review from surister October 4, 2025 10:22

Tranquility2 force-pushed the generic_sql branch from 91d8161 to a99045a Compare October 4, 2025 10:23

surister mentioned this pull request Oct 5, 2025

fix(modules): Fix postgres deprecation warning. #883

Closed

surister approved these changes Oct 5, 2025

View reviewed changes

Comment thread modules/generic/testcontainers/generic/sql.py Outdated

Comment thread modules/generic/testcontainers/generic/sql.py

Tranquility2 force-pushed the generic_sql branch 2 times, most recently from a05abdb to bf6a553 Compare October 5, 2025 14:51

rhoban13 reviewed Oct 8, 2025

View reviewed changes

surister mentioned this pull request Oct 16, 2025

feat(cratedb): Add Cratedb module #888

Open

Tranquility2 added 10 commits March 28, 2026 19:52

Remove comment line

470baf7

Added base generic db

41f3758

Rename test_generic

8ee2f1a

Renamed DB to SQL

190dbfb

Tests for SQL

6326c47

Update warnning

989f677

update docs

42f4aea

Fix doctests

791d6af

Add generic dep

21461e3

Update ref

7321fc2

Tranquility2 added 16 commits March 28, 2026 19:59

Replaced wait

619940d

Improve Strategy

60dcf01

Better Strategy

abd05d0

Remove _connect

56628aa

Refactor generic sql

51591ae

SQL container with configurable wait strategy

cdbdabb

use WaitStrategy._poll and with_transient_exceptions

ef4d571

Required wait_strategy

44a0343

Added note

de608a2

Move connector and Rename

0f0eb9e

Update doctests

f9bf8e2

Fix doctest

988a6ca

Remove extra validation + Improve testing

7fa1105

Omit generic.py from report

f613a61

Renamed sql_connector

07c8781

Renamed SqlConnectWaitStrategy

d59870a

Tranquility2 force-pushed the generic_sql branch from aacc13a to d59870a Compare March 28, 2026 20:07

Revert "Omit generic.py from report"

d502fb6

This reverts commit f613a61.

alexanderankin approved these changes Mar 29, 2026

View reviewed changes

alexanderankin merged commit 2ca2321 into testcontainers:main Mar 29, 2026
12 checks passed

github-actions Bot mentioned this pull request Mar 24, 2026

chore(main): release testcontainers 4.15.0-rc.1 #986

Merged

This was referenced Jun 11, 2026

fix(cratedb): add CrateDB community module #1051

Merged

Testing: Testcontainers for Python crate/cratedb-examples#72

Open

+                      Raises:
+                          NotImplementedError: Must be implemented by subclasses
+                      """
+                      raise NotImplementedError("Subclasses must implement get_connection_url()")

feat(generic): Reintroducing the generic SQL module by Tranquility2 · Pull Request #892 · testcontainers/testcontainers-python · GitHub

Uh oh!

feat(generic): Reintroducing the generic SQL module - #892

feat(generic): Reintroducing the generic SQL module#892alexanderankin merged 27 commits intotestcontainers:maintestcontainers/testcontainers-python:mainfrom Tranquility2:generic_sqlTranquility2/testcontainers-python:generic_sqlCopy head branch name to clipboard

Conversation

Tranquility2 commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

alexanderankin commented Oct 3, 2025

Uh oh!

Tranquility2 commented Oct 3, 2025

Uh oh!

Tranquility2 commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

surister commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Tranquility2 commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Tranquility2 commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

surister left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rhoban13 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rhoban13 Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Tranquility2 Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(generic): Reintroducing the generic SQL module#892
alexanderankin merged 27 commits into
testcontainers:mainfrom
Tranquility2:generic_sql

Tranquility2 commented Oct 2, 2025 •
edited
Loading

codecov Bot commented Oct 3, 2025 •
edited
Loading

Tranquility2 commented Oct 3, 2025 •
edited
Loading

surister commented Oct 3, 2025 •
edited
Loading

Tranquility2 commented Oct 4, 2025 •
edited
Loading

Tranquility2 commented Oct 4, 2025 •
edited
Loading