disable %sql/%%sql in databricks (#1048)

* don't use `%[%]sql` within Databricks

* Update CHANGELOG.md

* adjust line comment

* pkgmt format

* upgrade action

* doc fix

* doc updates, changelog, version

* add test

* skip test

* lint

---------

Co-authored-by: Eduardo Blancas <github@blancas.io>

Author: danielsparing

.github/workflows/ci.yaml

@@ -98,9 +98,8 @@ jobs:
       - name: Lint
         run: |
           python -m pip install --upgrade pip
-          python -m pip install --upgrade pkgmt codespell nox
+          python -m pip install --upgrade pkgmt nox
           pkgmt lint
-          codespell
 
       - name: Install dependencies
         run: |
@@ -113,7 +112,7 @@ jobs:
           nox --session test_unit --no-install --reuse-existing-virtualenvs
 
       - name: Upload failed images artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: failure()
         with:
          name: failed-image-artifacts ${{ matrix.os }} ${{ matrix.python-version }}
@@ -158,7 +157,7 @@ jobs:
           nox --session test_unit_sqlalchemy_one --no-install --reuse-existing-virtualenvs
 
       - name: Upload failed images artifacts sqlalchemyv1
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: failure()
         with:
          name: failed-image-artifacts-sqlalchemy ${{ matrix.os }} ${{ matrix.python-version }}

.readthedocs.yml

@@ -21,3 +21,4 @@ conda:
 sphinx:
   builder: html
   fail_on_warning: true
+  configuration: doc/_config.yml

CHANGELOG.md

@@ -1,6 +1,8 @@
 # CHANGELOG
 
-## 0.10.18dev
+## 0.11.0dev
+
+* [API Change] Disabled `%sql` and `%%sql` on Databricks ([#1047](https://github.com/ploomber/jupysql/issues/1047))
 
 ## 0.10.17 (2025-01-08)
 

doc/howto.md

@@ -361,7 +361,9 @@ some_engine = create_engine("sqlite:///some.db")
 
 ## Use `%sql`/`%%sql` in Databricks
 
-Databricks uses the same name (`%sql`/`%%sql`) for its SQL magics; however, JupySQL exposes a `%jupysql`/`%%jupysql` alias so you can use both:
+Databricks uses the same name (`%sql`/`%%sql`) for its SQL magics; however, since this
+clashes with Databricks' `%%sql` command, JupySQL will enable an `%jupysql`/`%%jupysql`
+alias if a `DATABRICKS_RUNTIME_VERSION` is declared:
 
 ```{code-cell} ipython3
 %jupysql duckdb://

scripts/large-table-gen.py

@@ -1,5 +1,4 @@
-"""Renter large-table-template.sql
-"""
+"""Renter large-table-template.sql"""
 
 from pathlib import Path
 from jinja2 import Template

src/sql/__init__.py

@@ -1,7 +1,7 @@
 from sql.magic import load_ipython_extension
 
 
-__version__ = "0.10.18dev"
+__version__ = "0.11.0dev"
 
 
 __all__ = ["load_ipython_extension"]

src/sql/column_guesser.py

@@ -7,6 +7,7 @@
 
 class Column(list):
     "Store a column of tabular data; record its name and whether it is numeric"
+
     is_quantity = True
     name = ""
 

src/sql/magic.py

@@ -1,4 +1,5 @@
 import json
+import os
 import re
 from pathlib import Path
 
@@ -704,7 +705,7 @@ def get_query_type(command: str):
 
 def set_configs(ip, file_path, alternate_path):
     """Set user defined SqlMagic configuration settings"""
-    sql = ip.find_cell_magic("sql").__self__
+    sql = ip.find_cell_magic("jupysql").__self__
     user_configs, loaded_from = util.get_user_configs(file_path, alternate_path)
     default_configs = util.get_default_configs(sql)
     table_rows = []
@@ -769,6 +770,12 @@ def load_SqlMagic_configs(ip):
 
 def load_ipython_extension(ip):
     """Load the magics, this function is executed when the user runs: %load_ext sql"""
+
+    # If running within Databricks, do not use the sql magics
+    if "DATABRICKS_RUNTIME_VERSION" in os.environ:
+        del SqlMagic.magics["cell"]["sql"]
+        del SqlMagic.magics["line"]["sql"]
+
     sql_magic = SqlMagic(ip)
     _set_sql_magic(sql_magic)
     ip.register_magics(sql_magic)

src/tests/test_magic.py

@@ -23,6 +23,8 @@
 from sql.run.resultset import ResultSet
 from sql import magic
 from sql.warnings import JupySQLQuotedNamedParametersWarning
+from sql._testing import TestingShell
+from sql.magic import load_ipython_extension
 
 
 from conftest import runsql
@@ -2767,3 +2769,27 @@ def test_disabled_named_parameters_shows_disabled_warning(ip):
     )
 
     assert expected_warning in str(excinfo.value)
+
+
+@pytest.mark.skip(
+    reason=(
+        "Running this breaks all subsequent tests because "
+        "TestingShell is a singleton. We need to find a way to isolate this test"
+    )
+)
+def test_databricks_sql_magic_disabled(monkeypatch):
+    monkeypatch.setenv("DATABRICKS_RUNTIME_VERSION", "10.0.0")
+    ip = TestingShell.preconfigured_shell()
+    load_ipython_extension(ip)
+
+    ip.run_cell("%jupysql duckdb://")
+    ip.run_cell("%jupysql select 1")
+
+    with pytest.raises(UsageError) as excinfo_line:
+        ip.run_cell("%sql select 1")
+
+    with pytest.raises(UsageError) as excinfo_cell:
+        ip.run_cell("%%sql\nselect 1")
+
+    assert "Line magic function `%sql` not found" in str(excinfo_line.value)
+    assert "Cell magic `%%sql` not found" in str(excinfo_cell.value)