fix: harden SQL execution normalization and reflection consistency

Author: yeongseon

docs/COMPATIBILITY.md

@@ -44,8 +44,10 @@ adaptation) and `excel-dbapi` (execution engine and workbook semantics).
 `sqlalchemy-excel` does not provide full ACID transactional guarantees.
 
 - `Session.commit()` persists changes to the workbook as expected.
-- `Session.rollback()` is effectively a no-op for local workbook writes in
-  standard usage; treat writes as durable once executed.
+- `Session.rollback()` for local workbooks (`engine=openpyxl` with
+  `autocommit=False`) restores the latest committed snapshot.
+- Graph backend connections (`engine=graph`) do not support rollback and treat
+  rollback calls as a no-op.
 - Use a single-writer model. Concurrent writes to the same workbook are not
   supported and can lead to conflicts/corruption.
 - If you need strict transaction isolation, rollback guarantees, and
@@ -101,11 +103,12 @@ Practical guidance:
 
 - No CTE support.
 - No window functions (`OVER`).
-- No `ALTER TABLE` migration primitives.
+- `ALTER TABLE` supports `ADD COLUMN`, `DROP COLUMN`, and `RENAME COLUMN`.
 - No foreign key/index enforcement.
 - No correlated subqueries.
 - Constrained JOIN `ON` clauses (equality joins across sources).
 - No concurrent multi-writer guarantees.
-- `Session.rollback()` does not provide traditional database rollback semantics.
+- Rollback semantics depend on backend (`openpyxl` snapshot/restore;
+  `graph` no rollback support).
 
 When these limitations are blockers, prefer a traditional database backend.

src/sqlalchemy_excel/__init__.py

@@ -2,10 +2,15 @@
 
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, version
+
 from .dialect import ExcelDialect, ExcelGraphDialect
 from .dml import Insert, insert
 
-__version__ = "0.4.0"
+try:
+    __version__ = version("sqlalchemy-excel")
+except PackageNotFoundError:
+    __version__ = "0.5.4"
 
 __all__ = [
     "ExcelDialect",

src/sqlalchemy_excel/compiler.py

@@ -47,6 +47,7 @@
 
 
 _SUPPORTED_FUNCTIONS = {"count", "sum", "avg", "min", "max"}
+_BARE_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
 
 
 class ExcelIdentifierPreparer(compiler.IdentifierPreparer):
@@ -60,10 +61,19 @@ def __init__(self, dialect: Any) -> None:
         super().__init__(dialect, initial_quote="", final_quote="")
         self.reserved_words = set()
 
+    @staticmethod
+    def _validate_identifier(ident: str) -> None:
+        if not _BARE_IDENTIFIER_RE.fullmatch(ident):
+            raise exc.CompileError(
+                "Excel dialect identifiers must match [A-Za-z_][A-Za-z0-9_]*"
+            )
+
     def quote_identifier(self, value: str) -> str:
+        self._validate_identifier(value)
         return value
 
     def quote(self, ident: str, force: Any = None) -> str:
+        self._validate_identifier(ident)
         return ident
 
 

src/sqlalchemy_excel/dialect.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import re
 import warnings
 from typing import TYPE_CHECKING, Any, Literal, cast
 from urllib.parse import unquote as _url_unquote
@@ -79,8 +78,48 @@ def _after_drop(
 
 
 # Register DDL events globally for all Table objects
-event.listen(Table, "after_create", _after_create)
-event.listen(Table, "after_drop", _after_drop)
+event.listen(Table, "after_create", _after_create, propagate=False)
+event.listen(Table, "after_drop", _after_drop, propagate=False)
+
+
+def _normalize_statement_whitespace_quote_aware(statement: str) -> str:
+    out: list[str] = []
+    in_quote = False
+    quote_char = ""
+    i = 0
+    length = len(statement)
+
+    while i < length:
+        ch = statement[i]
+
+        if in_quote:
+            out.append(ch)
+            if ch == quote_char:
+                if i + 1 < length and statement[i + 1] == quote_char:
+                    out.append(statement[i + 1])
+                    i += 1
+                else:
+                    in_quote = False
+            i += 1
+            continue
+
+        if ch in ("'", '"'):
+            in_quote = True
+            quote_char = ch
+            out.append(ch)
+            i += 1
+            continue
+
+        if ch.isspace():
+            if out and out[-1] != " ":
+                out.append(" ")
+            i += 1
+            continue
+
+        out.append(ch)
+        i += 1
+
+    return "".join(out).strip()
 
 
 class ExcelDialect(  # type: ignore[misc]  # pyright: ignore[reportIncompatibleMethodOverride]
@@ -153,7 +192,7 @@ def create_connect_args(self, url: URL) -> ConnectArgsType:
             excel:////absolute/path.xlsx  →  file_path="/absolute/path.xlsx"
         """
         # url.database contains the path after the third slash
-        file_path = url.database
+        file_path = _url_unquote(url.database) if url.database else None
         if not file_path:
             raise ValueError("No file path in URL. Use excel:///path/to/file.xlsx")
 
@@ -193,7 +232,7 @@ def do_execute(
         context: Any = None,
     ) -> None:
         """Execute a statement, normalizing whitespace for excel-dbapi."""
-        normalized = re.sub(r"\s+", " ", statement).strip()
+        normalized = _normalize_statement_whitespace_quote_aware(statement)
         cursor.execute(normalized, parameters)
         self._sync_alter_table_metadata(cursor, normalized)
 
@@ -204,7 +243,7 @@ def do_execute_no_params(
         context: Any = None,
     ) -> None:
         """Execute a statement with no parameters."""
-        normalized = re.sub(r"\s+", " ", statement).strip()
+        normalized = _normalize_statement_whitespace_quote_aware(statement)
         cursor.execute(normalized, None)
         self._sync_alter_table_metadata(cursor, normalized)
 

src/sqlalchemy_excel/reflection.py

@@ -14,6 +14,7 @@
     "TEXT": sa_types.String,
     "INTEGER": sa_types.Integer,
     "FLOAT": sa_types.Float,
+    "REAL": sa_types.Float,
     "BOOLEAN": sa_types.Boolean,
     "DATE": sa_types.Date,
     "DATETIME": sa_types.DateTime,

tests/test_compiler_guards.py

@@ -447,6 +447,8 @@ def test_compiler_visit_label_and_group_by_paths(tmp_xlsx: str) -> None:
     preparer = engine.dialect.identifier_preparer
     assert preparer.quote_identifier("users") == "users"
     assert preparer.quote("users") == "users"
+    with pytest.raises(exc.CompileError, match=r"\[A-Za-z_\]\[A-Za-z0-9_\]\*"):
+        preparer.quote_identifier("bad name")
 
     engine.dispose()
 
@@ -505,6 +507,23 @@ def execute(self, statement: str, parameters: object) -> None:
     dialect.do_execute_no_params(cursor, "SELECT   1\nFROM   users")
     assert cursor.calls == [("SELECT 1 FROM users", None)]
 
+    cursor_quotes = CursorStub()
+    dialect.do_execute_no_params(
+        cursor_quotes,
+        "SELECT   'a   b', \"x   y\"   FROM\t users  WHERE  id = 1",
+    )
+    assert cursor_quotes.calls == [
+        ('SELECT \'a   b\', "x   y" FROM users WHERE id = 1', None)
+    ]
+
+    cursor_params = CursorStub()
+    dialect.do_execute(
+        cursor_params,
+        "SELECT   'a   b'  FROM\t users  WHERE  id = ?",
+        (1,),
+    )
+    assert cursor_params.calls == [("SELECT 'a   b' FROM users WHERE id = ?", (1,))]
+
     assert dialect._check_unicode_returns(connection=None) is True
     assert dialect._check_unicode_description(connection=None) is True
 

tests/test_dialect.py

@@ -83,6 +83,14 @@ def test_connect_args_file_path(self, tmp_xlsx):
         assert kwargs["autocommit"] is False
         engine.dispose()
 
+    def test_connect_args_percent_decodes_local_path(self):
+        engine = create_engine("excel:///placeholder.xlsx")
+        dialect = engine.dialect
+        url = make_url("excel:///folder%20name/test%20file.xlsx")
+        _, kwargs = dialect.create_connect_args(url)
+        assert kwargs["file_path"] == "folder name/test file.xlsx"
+        engine.dispose()
+
 
 class TestConnection:
     """Test basic connection operations."""

tests/test_e2e.py

@@ -3368,6 +3368,23 @@ def test_e2e_alter_table_add_column(tmp_path) -> None:
     engine.dispose()
 
 
+def test_e2e_alter_table_add_float_column_reflects_as_float(tmp_path) -> None:
+    engine = _engine_for(tmp_path)
+    metadata = MetaData()
+    _users_table(metadata)
+    metadata.create_all(engine)
+
+    with engine.connect() as conn:
+        conn.exec_driver_sql("ALTER TABLE users ADD COLUMN score FLOAT")
+        conn.commit()
+
+    columns = inspect(engine).get_columns("users")
+    score = next(col for col in columns if col["name"] == "score")
+    assert isinstance(score["type"], sa.Float)
+
+    engine.dispose()
+
+
 def test_e2e_alter_table_drop_column(tmp_path) -> None:
     engine = _engine_for(tmp_path)
     metadata = MetaData()

tests/test_reflection.py

@@ -13,6 +13,8 @@
     inspect,
 )
 
+from sqlalchemy_excel.reflection import _sa_type_from_name
+
 
 @pytest.fixture
 def metadata():
@@ -92,6 +94,9 @@ def test_column_has_type(self, populated_engine):
             assert "type" in col
             assert col["type"] is not None
 
+    def test_real_type_name_maps_to_float(self):
+        assert isinstance(_sa_type_from_name("REAL"), Float)
+
 
 class TestGetPKConstraint:
     """Test get_pk_constraint — from metadata sheet."""