fix: close oracle round 11 gaps

Author: yeongseon

README.md

@@ -44,7 +44,7 @@ Before writing any code, understand the dialect's capabilities and limits:
 | **ALTER TABLE** | ✅ (ADD/DROP/RENAME COLUMN) |
 | Raw DDL metadata sync (`text()` / `exec_driver_sql()`) | ✅ (`CREATE TABLE` / `ALTER TABLE` / `DROP TABLE`) |
 | **Foreign keys / indexes** | ❌ |
-| **UNIQUE / CHECK enforcement** | ❌ (accepted for compatibility; compile-time warnings are emitted for CREATE TABLE and ALTER TABLE ADD COLUMN) |
+| **UNIQUE / CHECK / FOREIGN KEY enforcement** | ❌ (accepted for compatibility; compile-time warnings are emitted for CREATE TABLE and ALTER TABLE ADD COLUMN) |
 | **Concurrent writes** | ❌ |
 | **Session.rollback()** | Partial (openpyxl with autocommit=False; graph: no-op) |
 
@@ -102,6 +102,11 @@ engine = create_engine("excel:////home/user/data.xlsx")
 
 # With engine options
 engine = create_engine("excel:///data.xlsx", connect_args={"engine": "openpyxl"})
+
+# URL query forwarding to excel-dbapi
+engine = create_engine(
+    "excel:///data.xlsx?data_only=true&sanitize_formulas=true&create=true&file_locking=false"
+)
 ```
 
 ## Type Mapping

docs/DEVELOPMENT.md

@@ -116,31 +116,43 @@ sqlalchemy-excel/
 │   ├── dialect.py            # ExcelDialect, ExcelGraphDialect
 │   ├── compiler.py           # ExcelCompiler (SQL compilation, HAVING guard)
 │   ├── ddl.py                # ExcelDDLCompiler (CREATE/DROP TABLE)
+│   ├── dml.py                # Excel INSERT ... ON CONFLICT helpers
 │   ├── types.py              # ExcelTypeCompiler (type mappings)
 │   ├── reflection.py         # ExcelInspectionMixin (schema inspection)
 │   └── py.typed              # PEP 561 marker file
-├── tests/                     # 371+ tests (>95% coverage)
+├── tests/                    # 18 test modules (400 passed, 2 xfailed)
 │   ├── conftest.py           # Shared fixtures
+│   ├── test_alter_table.py
 │   ├── test_dialect.py
 │   ├── test_compiler.py
 │   ├── test_compiler_guards.py
+│   ├── test_coverage_boost.py
 │   ├── test_ddl.py
+│   ├── test_default_guards.py
 │   ├── test_dml.py
 │   ├── test_e2e.py
 │   ├── test_graph_dialect.py
 │   ├── test_orm.py
+│   ├── test_orm_bulk.py
+│   ├── test_orm_relationships.py
 │   ├── test_reflection.py
 │   ├── test_reflection_full.py
 │   ├── test_type_compiler_full.py
-│   └── test_types.py
+│   ├── test_types.py
+│   └── test_upsert.py
 ├── docs/
 │   ├── USAGE.md              # Usage guide
 │   ├── DEVELOPMENT.md        # This file
+│   ├── COMPATIBILITY.md      # Version pairing and migration guidance
+│   ├── RELEASE_NOTES.md      # Release highlights and notes
 │   └── ROADMAP.md            # Project roadmap
 ├── pyproject.toml            # Project metadata (hatchling)
 ├── Makefile                  # Development commands
 ├── README.md
 ├── CHANGELOG.md
+├── SUPPORT.md
+├── CODE_OF_CONDUCT.md
+├── SECURITY.md
 ├── CONTRIBUTING.md
 └── LICENSE
 ```

docs/USAGE.md

@@ -28,6 +28,36 @@ engine = create_engine("excel:////Users/alice/Documents/data.xlsx")
 engine = create_engine("excel:///data.xlsx", connect_args={"engine": "openpyxl"})
 ```
 
+## URL Query Parameters
+
+The dialect forwards selected URL query parameters to `excel_dbapi.connect(...)`.
+
+Supported boolean query parameters:
+
+- `data_only`
+- `sanitize_formulas`
+- `create`
+- `file_locking`
+- `autocommit`
+
+`engine` is also accepted as a string query parameter.
+
+```python
+from sqlalchemy import create_engine
+
+engine = create_engine(
+    "excel:///data.xlsx?data_only=true&sanitize_formulas=true"
+)
+
+engine = create_engine(
+    "excel:///data.xlsx?create=false&file_locking=true&autocommit=false"
+)
+
+engine = create_engine("excel:///data.xlsx?engine=openpyxl")
+```
+
+Boolean values accept `true/false`, `1/0`, and `yes/no` (case-insensitive).
+
 **Important**: Absolute paths require **four slashes** total (`excel:////absolute/path.xlsx`).
 
 > **Source checkout note**: In development/source mode (without an installed entry point), import `sqlalchemy_excel` before `create_engine(...)` so SQLAlchemy registers `excel://` and `excel+graph://` dialects.
@@ -358,7 +388,7 @@ sqlalchemy-excel has some limitations due to the nature of Excel as a database:
 - **ORM relationship limits**: Lazy one-to-many relationship loading can return empty collections; use eager loading (`joinedload`) for reliable one-to-many reads.
 - **Many-to-many loading is unsupported**: Association table persistence works, but relationship loader SQL for many-to-many is not fully supported.
 - **No foreign keys or indexes**: Excel has no concept of these.
-- **UNIQUE/CHECK are not enforced**: They are accepted for SQLAlchemy compatibility, ignored by the backend, and compile-time warnings are emitted for `CREATE TABLE` and `ALTER TABLE ... ADD COLUMN`.
+- **UNIQUE/CHECK/FOREIGN KEY are not enforced**: They are accepted for SQLAlchemy compatibility, ignored by the backend, and compile-time warnings are emitted for `CREATE TABLE` and `ALTER TABLE ... ADD COLUMN`.
 - **Identifier restrictions**: Table and column names must match `[A-Za-z_][A-Za-z0-9_]*`.
 - **No concurrent writes**: Use a single-writer model.
 - **Rollback**: Partial support — works with the openpyxl backend when `autocommit=False` (snapshot/restore semantics). The Graph API backend treats rollback as a no-op.

src/sqlalchemy_excel/compiler.py

@@ -92,6 +92,41 @@ class ExcelCompiler(compiler.SQLCompiler):
     _subquery_depth: int = 0
     _has_join: bool = False
 
+    @staticmethod
+    def _raise_if_schema_qualified(table: Any) -> None:
+        if getattr(table, "schema", None) is not None:
+            raise exc.CompileError("Excel dialect does not support schemas")
+
+    def visit_table(
+        self,
+        table: Any,
+        asfrom: bool = False,
+        iscrud: bool = False,
+        ashint: bool = False,
+        fromhints: Any = None,
+        use_schema: bool = True,
+        from_linter: Any = None,
+        ambiguous_table_name_map: Any = None,
+        enclosing_alias: Any = None,
+        **kwargs: Any,
+    ) -> str:
+        self._raise_if_schema_qualified(table)
+        return cast(
+            "str",
+            super().visit_table(
+                table,
+                asfrom=asfrom,
+                iscrud=iscrud,
+                ashint=ashint,
+                fromhints=fromhints,
+                use_schema=use_schema,
+                from_linter=from_linter,
+                ambiguous_table_name_map=ambiguous_table_name_map,
+                enclosing_alias=enclosing_alias,
+                **kwargs,
+            ),  # type: ignore[no-untyped-call]
+        )
+
     @staticmethod
     def _is_true_onclause(onclause: Any) -> bool:
         node = onclause
@@ -376,6 +411,7 @@ def visit_insert(
         *args: Any,
         **kw: Any,
     ) -> str:
+        self._raise_if_schema_qualified(insert_stmt.table)
         visit_insert = cast("Callable[..., str]", super().visit_insert)
         return str(visit_insert(insert_stmt, *args, **kw))
 

src/sqlalchemy_excel/ddl.py

@@ -11,7 +11,7 @@
 from typing import Any
 
 from sqlalchemy import exc
-from sqlalchemy.schema import CheckConstraint, UniqueConstraint
+from sqlalchemy.schema import CheckConstraint, ForeignKeyConstraint, UniqueConstraint
 from sqlalchemy.sql import compiler
 
 
@@ -24,6 +24,7 @@ def _warn_unsupported_constraints(
         context_msg: str,
         seen_unique: set[tuple[str, ...]],
         seen_check: set[str],
+        seen_foreign_key: set[tuple[str, ...]],
     ) -> None:
         if column.unique is True:
             key = (column.name,)
@@ -54,6 +55,17 @@ def _warn_unsupported_constraints(
                     )
                     seen_check.add(check_key)
 
+        if column.foreign_keys:
+            fk_key = tuple(
+                sorted(str(fk.target_fullname) for fk in column.foreign_keys)
+            )
+            if fk_key not in seen_foreign_key:
+                warnings.warn(
+                    f"Excel dialect does not enforce FOREIGN KEY constraints ({context_msg})",
+                    stacklevel=2,
+                )
+                seen_foreign_key.add(fk_key)
+
     @staticmethod
     def _warn_unsupported_generated_columns(column: Any) -> None:
         if getattr(column, "computed", None) is not None:
@@ -67,6 +79,11 @@ def _warn_unsupported_generated_columns(column: Any) -> None:
                 stacklevel=2,
             )
 
+    @staticmethod
+    def _raise_if_schema_qualified(table: Any) -> None:
+        if getattr(table, "schema", None) is not None:
+            raise exc.CompileError("Excel dialect does not support schemas")
+
     def _format_alter_table_name(self, operation: Any) -> str:
         schema = getattr(operation, "schema", None)
         if schema is not None:
@@ -93,6 +110,7 @@ def visit_create_table(self, create: Any, **kw: Any) -> str:
         Format: CREATE TABLE name (col1 TYPE, col2 TYPE, ...)
         """
         table = create.element
+        self._raise_if_schema_qualified(table)
         table_name = self.preparer.format_table(table)
 
         columns = []
@@ -103,6 +121,7 @@ def visit_create_table(self, create: Any, **kw: Any) -> str:
         inline_pk = len(pk_columns) == 1
         seen_unique: set[tuple[str, ...]] = set()
         seen_check: set[str] = set()
+        seen_foreign_key: set[tuple[str, ...]] = set()
         for col in table.columns:
             col_name = self.preparer.format_column(col)
             col_type = self.dialect.type_compiler.process(col.type)
@@ -116,6 +135,7 @@ def visit_create_table(self, create: Any, **kw: Any) -> str:
                 context_msg="CREATE TABLE",
                 seen_unique=seen_unique,
                 seen_check=seen_check,
+                seen_foreign_key=seen_foreign_key,
             )
             self._warn_unsupported_generated_columns(col)
             suffix = f" {' '.join(constraints)}" if constraints else ""
@@ -141,12 +161,25 @@ def visit_create_table(self, create: Any, **kw: Any) -> str:
                         stacklevel=2,
                     )
                     seen_check.add(check_key)
+            if isinstance(constraint, ForeignKeyConstraint):
+                fk_key = tuple(
+                    sorted(
+                        str(element.target_fullname) for element in constraint.elements
+                    )
+                )
+                if fk_key not in seen_foreign_key:
+                    warnings.warn(
+                        "Excel dialect does not enforce FOREIGN KEY constraints (CREATE TABLE)",
+                        stacklevel=2,
+                    )
+                    seen_foreign_key.add(fk_key)
 
         return f"CREATE TABLE {table_name} ({', '.join(columns)})"
 
     def visit_drop_table(self, drop: Any, **kw: Any) -> str:
         """Compile DROP TABLE."""
         table = drop.element
+        self._raise_if_schema_qualified(table)
         table_name = self.preparer.format_table(table)
         return f"DROP TABLE {table_name}"
 
@@ -168,6 +201,7 @@ def visit_add_column(self, create: Any, **kw: Any) -> str:
             context_msg="ALTER TABLE ADD COLUMN",
             seen_unique=set(),
             seen_check=set(),
+            seen_foreign_key=set(),
         )
         self._warn_unsupported_generated_columns(column)
         suffix = f" {' '.join(constraints)}" if constraints else ""

src/sqlalchemy_excel/dialect.py

@@ -10,6 +10,7 @@
 
 from sqlalchemy import event, pool
 from sqlalchemy.engine import default
+from sqlalchemy.exc import CompileError
 from sqlalchemy.schema import Table
 
 from .compiler import ExcelCompiler, ExcelIdentifierPreparer
@@ -368,6 +369,7 @@ def do_execute(
     ) -> None:
         """Execute a statement, normalizing whitespace for excel-dbapi."""
         normalized = _normalize_statement_whitespace_quote_aware(statement)
+        self._guard_alter_add_column_constraints(cursor, normalized)
         pre_alter_meta = self._read_pre_alter_metadata(cursor, normalized)
         cursor.execute(_statement_for_driver_execution(normalized), parameters)
         self._sync_create_table_metadata(cursor, normalized)
@@ -382,6 +384,7 @@ def do_execute_no_params(
     ) -> None:
         """Execute a statement with no parameters."""
         normalized = _normalize_statement_whitespace_quote_aware(statement)
+        self._guard_alter_add_column_constraints(cursor, normalized)
         pre_alter_meta = self._read_pre_alter_metadata(cursor, normalized)
         cursor.execute(_statement_for_driver_execution(normalized), None)
         self._sync_create_table_metadata(cursor, normalized)
@@ -413,6 +416,38 @@ def _read_pre_alter_metadata(
         current = excel_dbapi.read_table_metadata(raw_conn, table_name) or []
         return [dict(column) for column in current]
 
+    def _guard_alter_add_column_constraints(self, cursor: Any, statement: str) -> None:
+        add_match = _parse_alter_add_column(statement)
+        if add_match is None:
+            return
+
+        raw_table_name, _raw_col_name, remainder = add_match
+        tail = remainder.upper()
+        requires_existing_rows_backfill = "NOT NULL" in tail or "PRIMARY KEY" in tail
+        if not requires_existing_rows_backfill:
+            return
+
+        if self._table_has_existing_rows(cursor, raw_table_name):
+            table_name = self._unquote_identifier(raw_table_name)
+            raise CompileError(
+                "Excel dialect cannot add NOT NULL or PRIMARY KEY columns to "
+                f"non-empty table '{table_name}'"
+            )
+
+    @staticmethod
+    def _table_has_existing_rows(cursor: Any, table_name: str) -> bool:
+        cursor.execute(f"SELECT 1 FROM {table_name} LIMIT 1", None)
+
+        fetchone = getattr(cursor, "fetchone", None)
+        if callable(fetchone):
+            return fetchone() is not None
+
+        fetchall = getattr(cursor, "fetchall", None)
+        if callable(fetchall):
+            return bool(fetchall())
+
+        return False
+
     @staticmethod
     def _unquote_identifier(identifier: str) -> str:
         if len(identifier) >= 2 and identifier[0] == identifier[-1] == '"':