Modernize questdb-connect: SQLAlchemy 2.0 full support & Superset v5 compatibility

[nwoolmer]

Summary

questdb-connect needs updates to fully support SQLAlchemy 2.0 and Apache Superset v5. While PR #16 added initial SA 2.0 compatibility, several gaps remain. Two open PRs (#33, #34) address parts of this but additional work is needed.

Open PRs to merge

• PR Fix SADeprecationWarning #33 — Add import_dbapi() classmethod (fixes SADeprecationWarning - Implement an import_dbapi() #9, SQLAlchemy SADeprecationWarning #31). Trivial, backward-compatible.
• PR Superset v5 compatibility #34 — Superset v5 method signature updates (fixes Not Compatible with Apache Superset 4.1.1 or 5.0.0 #28). Breaking change for Superset <5.

SQLAlchemy 2.0 fixes

• Remove future= parameter from create_engine() and create_superset_engine() helpers in dialect.py. This param is removed in SA 2.0 (always "future" mode). Can be conditionally passed for 1.4 compat via version check.
• Remove implicit_returning= parameter from engine helpers — deprecated in SA 2.0.
• Audit raw SQL execution — ensure all SQL strings go through text() constructs, as SA 2.0 no longer accepts bare strings in execute().
• Consider supports_statement_cache = True — currently False, which disables SA 2.0's statement caching and hurts performance. Safe to enable if compiled output is deterministic (likely is).
• Update stale SA 1.4 doc reference in dialect.py comment.

Packaging / pyproject.toml

• Declare runtime dependencies — currently dependencies = [], meaning sqlalchemy and psycopg2-binary are not listed. Users must guess what to install.
• Update test dependencies — currently pinned to SQLAlchemy>=1.4, <2, so SA 2.0 is never actually tested in CI.
• Add Python 3.12 / 3.13 classifiers — currently only 3.9–3.11.

Superset v5 compatibility

• Merge PR Superset v5 compatibility #34 (or equivalent) to update select_star() and execute() signatures.
• This is a breaking change — requires a major version bump (e.g., v2.0.0).

Backward compatibility notes

• SQLAlchemy 1.4 + 2.0 dual support is feasible — SA 1.4 was designed as a bridge to 2.0. import_dbapi() can coexist with dbapi(), future param can be conditionally passed, and text() works in both versions.
• Superset <5 + v5 dual support is impractical — method signatures changed in positional-breaking ways (select_star() removed schema param, execute() added database param). Using *args/**kwargs is fragile. Recommend a clean version boundary: v1.x for Superset <5, v2.x for Superset v5+.

Suggested versioning

questdb-connect	SQLAlchemy	Superset
v1.1.x (current)	1.4 + partial 2.0	3.x / 4.0
v1.2.x	1.4 + full 2.0	3.x / 4.0 (no Superset breaking changes)
v2.0.0	2.0+ (drop 1.4)	v5+

Related issues

• SADeprecationWarning - Implement an import_dbapi() #9 — SADeprecationWarning: import_dbapi()
• Improve SQLAlchemy dialect support #25 — Improve SQLAlchemy dialect support
• Not Compatible with Apache Superset 4.1.1 or 5.0.0 #28 — Not compatible with Superset 4.1.1 / 5.0.0
• SQLAlchemy SADeprecationWarning #31 — SADeprecationWarning