Migrate to paramstyle="pyformat", following crate-python 2.2.0

.github/workflows/tests.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         os: ['ubuntu-22.04']
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
         cratedb-version: ['nightly']
         sqla-version: ['<1.4', '<1.5', '<2.1', '<2.2']
         pip-allow-prerelease: ['false']
@@ -34,12 +34,6 @@ jobs:
           - python-version: '3.14'
             sqla-version: '<1.4'
 
-          # SQLAlchemy 2.1 requires Python 3.9+.
-          - python-version: '3.7'
-            sqla-version: '<2.2'
-          - python-version: '3.8'
-            sqla-version: '<2.2'
-
         # Another CI test matrix slot to test against prerelease versions of Python packages.
         include:
           - os: 'ubuntu-latest'

CHANGES.md

@@ -1,4 +1,6 @@
 # Changelog
+
+## Unreleased
 - Types: Added method `ObjectArray.as_generic` for better reverse type lookups
 - Types: Improved type mappings for better reverse type lookups / reflections
   - Consequently used upper-case type definitions from `sqlalchemy.types`
@@ -11,6 +13,7 @@
   'visit_on_conflict_do_update'` by forwarding calls to
   `PGCompiler.visit_on_conflict_do_update`
 - Dialect: Added methods concerned with isolation levels as no-ops
+- Migrated to `paramstyle="pyformat"`, following crate-python 2.2.0
 
 ## 2026/05/28 0.42.0
 - Added support for SQL Alchemy 2.1

pyproject.toml

@@ -24,7 +24,7 @@ license = { text = "Apache License 2.0" }
 authors = [
   { name = "Crate.io", email = "office@crate.io" },
 ]
-requires-python = ">=3.6"
+requires-python = ">=3.10"
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Environment :: Plugins",
@@ -43,10 +43,6 @@ classifiers = [
   "Operating System :: Unix",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.6",
-  "Programming Language :: Python :: 3.7",
-  "Programming Language :: Python :: 3.8",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -83,7 +79,7 @@ dynamic = [
 ]
 dependencies = [
   "backports.zoneinfo<1; python_version<'3.9'",
-  "crate>=2,<3",
+  "crate>=2.2.1b3,<3",
   "geojson>=2.5,<4",
   "importlib-metadata; python_version<'3.8'",
   "importlib-resources; python_version<'3.9'",

src/sqlalchemy_cratedb/dialect.py

@@ -190,7 +190,7 @@ def process(value):
 class CrateDialect(default.DefaultDialect):
     name = "crate"
     driver = "crate-python"
-    default_paramstyle = "qmark"
+    default_paramstyle = "pyformat"
     statement_compiler = statement_compiler
     ddl_compiler = CrateDDLCompiler
     type_compiler = CrateTypeCompiler

tests/array_test.py

@@ -81,29 +81,40 @@ def test_create_with_array(self):
         t1.create(self.engine)
         fake_cursor.execute.assert_called_with(
             ("\nCREATE TABLE t (\n\tint_array ARRAY(INT), \n\tstr_array ARRAY(STRING)\n)\n\n"),
-            (),
+            sa.util.immutabledict({}),
         )
 
     def test_array_insert(self):
         trillian = self.User(name="Trillian", friends=["Arthur", "Ford"])
         self.session.add(trillian)
         self.session.commit()
         fake_cursor.execute.assert_called_with(
-            ("INSERT INTO users (name, friends, scores) VALUES (?, ?, ?)"),
-            ("Trillian", ["Arthur", "Ford"], None),
+            (
+                "INSERT INTO users (name, friends, scores) "
+                "VALUES (%(name)s, %(friends)s, %(scores)s)"
+            ),
+            {"friends": ["Arthur", "Ford"], "name": "Trillian", "scores": None},
         )
 
     def test_any(self):
         s = self.session.query(self.User.name).filter(self.User.friends.any("arthur"))
+        # SA 1.4+ uses the column name as the bind param; SA 1.3 uses a generic "param_1".
+        param = "friends_1" if SA_VERSION >= SA_1_4 else "param_1"
         self.assertSQL(
-            "SELECT users.name AS users_name FROM users WHERE ? = ANY (users.friends)", s
+            f"SELECT users.name AS users_name FROM users WHERE %({param})s = ANY (users.friends)",
+            s,
         )
 
     def test_any_with_operator(self):
         s = self.session.query(self.User.name).filter(
             self.User.scores.any(6, operator=operators.lt)
         )
-        self.assertSQL("SELECT users.name AS users_name FROM users WHERE ? < ANY (users.scores)", s)
+        # SA 1.4+ uses the column name as the bind param; SA 1.3 uses a generic "param_1".
+        param = "scores_1" if SA_VERSION >= SA_1_4 else "param_1"
+        self.assertSQL(
+            f"SELECT users.name AS users_name FROM users WHERE %({param})s < ANY (users.scores)",
+            s,
+        )
 
     def test_multidimensional_arrays(self):
         t1 = sa.Table(

tests/bulk_test.py

@@ -98,12 +98,63 @@ def test_bulk_save_legacy(self):
         self.session.bulk_save_objects(chars)
         (stmt, bulk_args), _ = fake_cursor.executemany.call_args
 
-        expected_stmt = "INSERT INTO characters (name, age) VALUES (?, ?)"
+        expected_stmt = "INSERT INTO characters (name, age) VALUES (%(name)s, %(age)s)"
         self.assertEqual(expected_stmt, stmt)
 
-        expected_bulk_args = (("Arthur", 35), ("Banshee", 26), ("Callisto", 37))
+        expected_bulk_args = (
+            {"age": 35, "name": "Arthur"},
+            {"age": 26, "name": "Banshee"},
+            {"age": 37, "name": "Callisto"},
+        )
         self.assertSequenceEqual(expected_bulk_args, bulk_args)
 
+    @skipIf(SA_VERSION >= SA_2_0, "SQLAlchemy 2.x uses modern bulk INSERT mode")
+    def test_executemany_pyformat_dicts_arrive_positional_at_client(self):
+        """
+        Verify the full pipeline for legacy bulk INSERT:
+          SA generates %(name)s SQL + dict rows  →  cursor.executemany()
+          →  crate-python _convert_named_bulk_params()
+          →  Client.sql() receives $N SQL + list-of-lists bulk_parameters
+
+        test_bulk_save_legacy uses FakeCursor and only verifies what SA passes
+        to the cursor interface.  This test patches Client.sql instead, letting
+        the real cursor code run, and asserts the wire-format conversion.
+        """
+        chars = [
+            self.character(name="Arthur", age=35),
+            self.character(name="Banshee", age=26),
+            self.character(name="Callisto", age=37),
+        ]
+
+        with patch(
+            "crate.client.http.Client.sql",
+            autospec=True,
+            return_value={
+                "cols": [],
+                "rows": [],
+                "rowcount": -1,
+                "results": [{"rowcount": 1}, {"rowcount": 1}, {"rowcount": 1}],
+                "duration": 0,
+            },
+        ) as client_mock:
+            self.session.bulk_save_objects(chars)
+
+        self.assertTrue(client_mock.called, "Client.sql was never called")
+        _self_arg, stmt, parameters, bulk_parameters = client_mock.call_args[0]
+
+        # crate-python must have converted %(name)s → $N before sending
+        self.assertNotIn("%(", stmt, f"stmt still contains %(name)s placeholders: {stmt!r}")
+        self.assertRegex(stmt, r"\$\d", f"stmt should contain $N positional markers: {stmt!r}")
+
+        # parameters (single-row) must be None for a bulk call
+        self.assertIsNone(parameters)
+
+        # bulk_parameters must be a list of positional lists, not dicts
+        self.assertIsInstance(bulk_parameters, list)
+        self.assertEqual(len(bulk_parameters), 3)
+        for row in bulk_parameters:
+            self.assertIsInstance(row, list, f"expected positional list, got {type(row)}: {row!r}")
+
     @skipIf(SA_VERSION < SA_2_0, "SQLAlchemy 1.x uses legacy bulk INSERT mode")
     @patch("crate.client.connection.Cursor", FakeCursor)
     def test_bulk_save_modern(self):
@@ -153,17 +204,20 @@ def test_bulk_save_modern(self):
         self.session.commit()
         (stmt, bulk_args), _ = fake_cursor.execute.call_args
 
-        expected_stmt = "INSERT INTO characters (name, age) VALUES (?, ?), (?, ?), (?, ?)"
+        expected_stmt = (
+            "INSERT INTO characters (name, age) "
+            "VALUES (%(name__0)s, %(age__0)s), (%(name__1)s, %(age__1)s), (%(name__2)s, %(age__2)s)"
+        )
         self.assertEqual(expected_stmt, stmt)
 
-        expected_bulk_args = (
-            "Arthur",
-            35,
-            "Banshee",
-            26,
-            "Callisto",
-            37,
-        )
+        expected_bulk_args = {
+            "age__0": 35,
+            "name__0": "Arthur",
+            "age__1": 26,
+            "name__1": "Banshee",
+            "age__2": 37,
+            "name__2": "Callisto",
+        }
         self.assertSequenceEqual(expected_bulk_args, bulk_args)
 
     @skipIf(sys.version_info < (3, 8), "SQLAlchemy/pandas is not supported on Python <3.8")

tests/compiler_test.py

@@ -97,7 +97,7 @@ def test_select_with_ilike_no_escape(self):
                 dedent("""
                 SELECT mytable.name, mytable.data 
                 FROM mytable 
-                WHERE mytable.name ILIKE ?
+                WHERE mytable.name ILIKE %(name_1)s
             """).strip(),
             )  # noqa: W291
         else:
@@ -106,7 +106,7 @@ def test_select_with_ilike_no_escape(self):
                 dedent("""
                 SELECT mytable.name, mytable.data 
                 FROM mytable 
-                WHERE lower(mytable.name) LIKE lower(?)
+                WHERE lower(mytable.name) LIKE lower(%(name_1)s)
             """).strip(),
             )  # noqa: W291
 
@@ -122,7 +122,7 @@ def test_select_with_not_ilike_no_escape(self):
                 dedent("""
                 SELECT mytable.name, mytable.data 
                 FROM mytable 
-                WHERE lower(mytable.name) NOT LIKE lower(?)
+                WHERE lower(mytable.name) NOT LIKE lower(%(name_1)s)
             """).strip(),
             )  # noqa: W291
         else:
@@ -131,7 +131,7 @@ def test_select_with_not_ilike_no_escape(self):
                 dedent("""
                 SELECT mytable.name, mytable.data 
                 FROM mytable 
-                WHERE mytable.name NOT ILIKE ?
+                WHERE mytable.name NOT ILIKE %(name_1)s
             """).strip(),
             )  # noqa: W291
 
@@ -167,11 +167,13 @@ def test_select_with_offset(self):
         statement = str(selectable.compile(bind=self.crate_engine))
         if SA_VERSION >= SA_1_4:
             self.assertEqual(
-                statement, "SELECT mytable.name, mytable.data \nFROM mytable\n LIMIT ALL OFFSET ?"
+                statement,
+                "SELECT mytable.name, mytable.data \nFROM mytable\n LIMIT ALL OFFSET %(param_1)s",
             )
         else:
             self.assertEqual(
-                statement, "SELECT mytable.name, mytable.data \nFROM mytable \n LIMIT ALL OFFSET ?"
+                statement,
+                "SELECT mytable.name, mytable.data \nFROM mytable \n LIMIT ALL OFFSET %(param_1)s",
             )
 
     def test_select_with_limit(self):
@@ -180,7 +182,9 @@ def test_select_with_limit(self):
         """
         selectable = self.mytable.select().limit(42)
         statement = str(selectable.compile(bind=self.crate_engine))
-        self.assertEqual(statement, "SELECT mytable.name, mytable.data \nFROM mytable \n LIMIT ?")
+        self.assertEqual(
+            statement, "SELECT mytable.name, mytable.data \nFROM mytable \n LIMIT %(param_1)s"
+        )
 
     def test_select_with_offset_and_limit(self):
         """
@@ -189,7 +193,9 @@ def test_select_with_offset_and_limit(self):
         selectable = self.mytable.select().offset(5).limit(42)
         statement = str(selectable.compile(bind=self.crate_engine))
         self.assertEqual(
-            statement, "SELECT mytable.name, mytable.data \nFROM mytable \n LIMIT ? OFFSET ?"
+            statement,
+            "SELECT mytable.name, mytable.data \n"
+            "FROM mytable \n LIMIT %(param_1)s OFFSET %(param_2)s",
         )
 
     def test_insert_multivalues(self):
@@ -220,7 +226,10 @@ def test_insert_multivalues(self):
         records = [{"name": f"foo_{i}"} for i in range(3)]
         insertable = self.mytable.insert().values(records)
         statement = str(insertable.compile(bind=self.crate_engine))
-        self.assertEqual(statement, "INSERT INTO mytable (name) VALUES (?), (?), (?)")
+        self.assertEqual(
+            statement,
+            "INSERT INTO mytable (name) VALUES (%(name_m0)s), (%(name_m1)s), (%(name_m2)s)",
+        )
 
     @skipIf(
         SA_VERSION < SA_2_0,
@@ -263,7 +272,7 @@ def test_insert_manyvalues(self):
         records = [{"name": f"foo_{i}"} for i in range(record_count)]
         insertable = self.mytable.insert()
         statement = str(insertable.compile(bind=self.crate_engine))
-        self.assertEqual(statement, "INSERT INTO mytable (name, data) VALUES (?, ?)")
+        self.assertEqual(statement, "INSERT INTO mytable (name, data) VALUES (%(name)s, %(data)s)")
 
         with mock.patch(
             "crate.client.http.Client.sql", autospec=True, return_value={"cols": []}
@@ -278,12 +287,18 @@ def test_insert_manyvalues(self):
             client_mock.mock_calls,
             [
                 mock.call(
-                    mock.ANY, "INSERT INTO mytable (name) VALUES (?), (?)", ("foo_0", "foo_1"), None
+                    mock.ANY,
+                    "INSERT INTO mytable (name) VALUES ($1), ($2)",
+                    ["foo_0", "foo_1"],
+                    None,
                 ),
                 mock.call(
-                    mock.ANY, "INSERT INTO mytable (name) VALUES (?), (?)", ("foo_2", "foo_3"), None
+                    mock.ANY,
+                    "INSERT INTO mytable (name) VALUES ($1), ($2)",
+                    ["foo_2", "foo_3"],
+                    None,
                 ),
-                mock.call(mock.ANY, "INSERT INTO mytable (name) VALUES (?)", ("foo_4",), None),
+                mock.call(mock.ANY, "INSERT INTO mytable (name) VALUES ($1)", ["foo_4"], None),
             ],
         )