refactor!: Modernize DDL element APIs with variable positional arguments

BREAKING CHANGE: Updated all DDL element classes to use variable positional
arguments (*columns) instead of list-based parameters. This modernizes the API
while maintaining functionality but intentionally breaks backward compatibility.

Key Changes:
- ShardKey: Changed from ShardKey(['col1', 'col2']) to ShardKey('col1', 'col2')
- SortKey: Changed from SortKey(['col1']) to SortKey('col1')
- VectorKey: Changed from VectorKey(['col1']) to VectorKey('col1')
- FullTextIndex: Added ASC/DESC support and modernized API
- MultiValueIndex: Changed from MultiValueIndex('col') to MultiValueIndex('col1', 'col2')

All keyword arguments are now keyword-only for improved API clarity.
Updated 9 files including all examples, tests, and documentation.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: kesmit13

sqlalchemy_singlestoredb/ddlelement.py

@@ -51,7 +51,7 @@ class MultiColumnShardTable(Base):  # type: ignore
     amount = Column(Numeric(10, 2))
 
     __table_args__ = {
-        'info': {'singlestoredb_shard_key': ShardKey(['user_id', 'category_id'])},
+        'info': {'singlestoredb_shard_key': ShardKey('user_id', 'category_id')},
     }
 
 
@@ -94,7 +94,7 @@ class ComplexTable(Base):  # type: ignore
     __table_args__ = {
         'info': {
             'singlestoredb_shard_key': ShardKey('user_id'),
-            'singlestoredb_sort_key': SortKey(['order_id', 'amount']),
+            'singlestoredb_sort_key': SortKey('order_id', 'amount'),
         },
     }
 
@@ -111,7 +111,7 @@ class MultiColumnOnlyTable(Base):  # type: ignore
     __table_args__ = {
         'info': {
             'singlestoredb_shard_key': ShardKey(
-                ['user_id', 'region_id'], metadata_only=True,
+                'user_id', 'region_id', metadata_only=True,
             ),
         },
     }

sqlalchemy_singlestoredb/examples/shard_key_examples.py

@@ -86,7 +86,7 @@ def main() -> None:
         Column('user_id', Integer, primary_key=True),
         Column('region_id', Integer, primary_key=True),
         Column('amount', Integer),
-        ShardKey(['user_id', 'region_id']),
+        ShardKey('user_id', 'region_id'),
     )
     table4.create(mock_engine, checkfirst=False)
 
@@ -99,7 +99,7 @@ def main() -> None:
         Column('timestamp', String(50)),
         Column('event_type', String(50)),
         ShardKey('user_id'),
-        SortKey(['timestamp']),
+        SortKey('timestamp'),
     )
     table5.create(mock_engine, checkfirst=False)
 

sqlalchemy_singlestoredb/examples/table_constructor_examples.py

@@ -40,7 +40,7 @@ class MyTable(Base):  # type: ignore
         {
             'info': {
                 'singlestoredb_shard_key': ShardKey('id'),
-                'singlestoredb_sort_key': SortKey(['id', 'data']),
+                'singlestoredb_sort_key': SortKey('id', 'data'),
             },
         }
     )

sqlalchemy_singlestoredb/examples/universal/main.py

@@ -57,7 +57,7 @@ class Table(SQLATable):
     ...     Column('id', Integer, primary_key=True),
     ...     Column('title', String(200)),
     ...     Column('content', Text),
-    ...     FullTextIndex(['title', 'content']),  # Multiple columns, auto-named
+    ...     FullTextIndex('title', 'content'),  # Multiple columns, auto-named
     ...     FullTextIndex('title', name='ft_title', version=2)  # Single column, named v2
     ... )
 

sqlalchemy_singlestoredb/table.py

@@ -600,7 +600,7 @@ def test_fulltext_index_compilation_with_special_column_names(self) -> None:
 
         # Test multiple columns with special characters
         ft_idx = FullTextIndex(
-            ['title column', 'content-field'], name='search_idx',
+            'title column', 'content-field', name='search_idx',
         )
         result = compile_fulltext_index(ft_idx, None)
         expected = 'FULLTEXT search_idx (`title column`, `content-field`)'

sqlalchemy_singlestoredb/tests/test_advanced_indexes.py

@@ -29,10 +29,10 @@ def test_basic_shard_key(self) -> None:
 
     def test_multi_column_shard_key(self) -> None:
         """Test shard key with multiple columns."""
-        shard_key = ShardKey(['user_id', 'category_id'])
+        shard_key = ShardKey('user_id', 'category_id')
         assert shard_key.columns == ('user_id', 'category_id')
         assert shard_key.metadata_only is False
-        assert repr(shard_key) == "ShardKey(['user_id', 'category_id'])"
+        assert repr(shard_key) == "ShardKey('user_id', 'category_id')"
 
     def test_empty_shard_key(self) -> None:
         """Test empty shard key for keyless sharding."""
@@ -50,30 +50,22 @@ def test_shard_key_metadata_only_single_column(self) -> None:
 
     def test_shard_key_metadata_only_multi_column(self) -> None:
         """Test SHARD KEY ONLY with multiple columns."""
-        shard_key = ShardKey(['user_id', 'category_id'], metadata_only=True)
+        shard_key = ShardKey('user_id', 'category_id', metadata_only=True)
         assert shard_key.columns == ('user_id', 'category_id')
         assert shard_key.metadata_only is True
-        expected_repr = "ShardKey(['user_id', 'category_id'], metadata_only=True)"
+        expected_repr = "ShardKey('user_id', 'category_id', metadata_only=True)"
         assert repr(shard_key) == expected_repr
 
     def test_shard_key_metadata_only_empty(self) -> None:
         """Test SHARD KEY ONLY with no columns (should fallback to empty)."""
         shard_key = ShardKey(metadata_only=True)
         assert shard_key.columns == ()
         assert shard_key.metadata_only is True
-        assert repr(shard_key) == 'ShardKey(None, metadata_only=True)'
+        assert repr(shard_key) == 'ShardKey(metadata_only=True)'
 
 
 class TestShardKeyCompiler:
-    """Test ShardKey DDL compilation."""
-
-    def setup_method(self) -> None:
-        """Set up mock engine for DDL compilation."""
-        def dump(sql: Any, *multiparams: Any, **params: Any) -> None:
-            self.compiled_sql = str(sql.compile(dialect=self.mock_engine.dialect))
-
-        self.mock_engine = create_mock_engine('singlestoredb://', dump)
-        self.compiled_sql = ''
+    """Test ShardKey SQL compilation."""
 
     def test_compile_basic_shard_key(self) -> None:
         """Test compilation of basic shard key."""
@@ -87,7 +79,7 @@ def test_compile_multi_column_shard_key(self) -> None:
         """Test compilation of multi-column shard key."""
         from sqlalchemy_singlestoredb.ddlelement import compile_shard_key
 
-        shard_key = ShardKey(['user_id', 'category_id'])
+        shard_key = ShardKey('user_id', 'category_id')
         result = compile_shard_key(shard_key, None)
         assert result == 'SHARD KEY (user_id, category_id)'
 
@@ -111,7 +103,7 @@ def test_compile_shard_key_metadata_only_multi_column(self) -> None:
         """Test compilation of SHARD KEY ONLY with multiple columns."""
         from sqlalchemy_singlestoredb.ddlelement import compile_shard_key
 
-        shard_key = ShardKey(['user_id', 'category_id'], metadata_only=True)
+        shard_key = ShardKey('user_id', 'category_id', metadata_only=True)
         result = compile_shard_key(shard_key, None)
         assert result == 'SHARD KEY (user_id, category_id) METADATA_ONLY'
 
@@ -138,7 +130,7 @@ def test_compile_shard_key_with_special_column_names(self) -> None:
         assert result == 'SHARD KEY (`user id`)'
 
         # Test multiple columns with special characters
-        shard_key = ShardKey(['user-id', 'tenant id', 'normal_column'])
+        shard_key = ShardKey('user-id', 'tenant id', 'normal_column')
         result = compile_shard_key(shard_key, None)
         assert result == 'SHARD KEY (`user-id`, `tenant id`, normal_column)'
 
@@ -247,7 +239,7 @@ class MyTable(Base):  # type: ignore
             data = Column(String(50))
 
             __table_args__ = {
-                'info': {'singlestoredb_shard_key': ShardKey(['user_id', 'category_id'])},
+                'info': {'singlestoredb_shard_key': ShardKey('user_id', 'category_id')},
             }
 
         Base.metadata.create_all(self.mock_engine, checkfirst=False)
@@ -640,7 +632,7 @@ def test_table_constructor_multi_column_shard_key(self) -> None:
             Column('user_id', Integer, primary_key=True),
             Column('category_id', Integer, primary_key=True),
             Column('amount', Integer),
-            ShardKey(['user_id', 'category_id']),
+            ShardKey('user_id', 'category_id'),
         )
 
         # Verify info is set correctly
@@ -661,7 +653,7 @@ def test_table_constructor_with_both_keys(self) -> None:
             Column('order_id', Integer, primary_key=True),
             Column('created_at', String(50)),
             ShardKey('user_id'),
-            SortKey(['created_at']),
+            SortKey('created_at'),
         )
 
         # Verify info is set correctly
@@ -737,6 +729,6 @@ def test_table_constructor_multiple_sort_keys_error(self) -> None:
                 Column('id', Integer, primary_key=True),
                 Column('created_at', String(50)),
                 Column('updated_at', String(50)),
-                SortKey(['created_at']),
-                SortKey(['updated_at']),  # This should cause an error
+                SortKey('created_at'),
+                SortKey('updated_at'),  # This should cause an error
             )