shoveler 0.1.0__tar.gz

shoveler-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*.pyo
+
+# PyInstaller output — commit the .spec file, not the output
+dist/
+build/
+
+# uv — commit uv.lock to the repo, ignore the venv
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Local agent instructions
+.github/copilot-instructions.md
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Github
+.github/

shoveler-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

shoveler-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: shoveler
+Version: 0.1.0
+Summary: Shoveler: A minimal desktop SQL workbench for DuckDB
+License: MIT
+Keywords: duckdb,education,sql,workbench
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=0.10
+Requires-Dist: pyside6>=6.6
+Description-Content-Type: text/markdown
+
+# DuckDB Workbench
+
+A minimal desktop SQL workbench for DuckDB, built with Python and PySide6.
+
+## Setup (uv)
+
+```shell
+git clone https://github.com/mrmatho/shoveler
+cd shoveler
+uv sync
+```
+
+`uv sync` creates a `.venv`, installs all dependencies including the dev group,
+and respects `uv.lock` if it exists. Run it again after pulling changes.
+
+## Running
+
+```shell
+uv run python -m shoveler
+```
+
+## Testing
+
+```shell
+uv run pytest
+```
+
+## Managing dependencies
+
+```shell
+uv add somepackage              # add a runtime dependency
+uv add --dev somepackage        # add to the dev group (not published to PyPI)
+uv remove somepackage           # remove a dependency
+uv lock                         # regenerate uv.lock without installing
+uv sync                         # install from uv.lock
+```
+
+Commit `uv.lock` to the repository. It pins exact versions for reproducible installs.
+
+## Usage
+
+- **Open File** — connect to an existing `.duckdb` or `.db` file (green indicator)
+- **New In-Memory** — scratch database; data is lost when closed (amber indicator)
+- **File > Save Database As...** — save current database state to a `.duckdb` file
+- **Checkpoint** — flush the write-ahead log to disk (file databases only)
+- **F5 or Ctrl+Enter** — run query
+- Select part of your SQL to run only that selection
+- Double-click a table name in the schema panel to insert it into the editor
+- **View > Syntax highlighting** — toggle SQL highlighting on or off; enabled by default and remembered between launches
+
+## Building a standalone Windows executable
+
+The project includes `shoveler.spec` with the correct PyInstaller
+configuration. Use this rather than running `pyinstaller` with flags directly —
+the spec handles a non-obvious issue with DuckDB's compiled extension.
+
+```shell
+uv run pyinstaller shoveler.spec
+```
+
+Output is in `dist/Shoveler/`. Distribute that folder as a zip.
+
+**Why --onedir and not --onefile?**
+`--onefile` extracts everything to a temp directory on every launch, which makes
+startup noticeably slow for a PySide6 app. `--onedir` is faster and easier to
+debug if something goes wrong.
+
+**Known PyInstaller issue with DuckDB:**
+DuckDB's compiled core (`_duckdb.pyd` on Windows) lives outside the `duckdb/`
+package directory. PyInstaller does not find it automatically. The spec file
+uses `collect_all('duckdb')` which handles this correctly. If you ever regenerate
+the spec from scratch, make sure this is included or the packaged app will fail
+to start.
+
+## Extending
+
+|Feature|Where to add it|
+|---|---|
+|More export formats|Add menu items in `ResultsPanel._show_export_menu()` — raw data is in `_last_rows` / `_last_columns`|

shoveler-0.1.0/README.md

@@ -0,0 +1,79 @@
+# DuckDB Workbench
+
+A minimal desktop SQL workbench for DuckDB, built with Python and PySide6.
+
+## Setup (uv)
+
+```shell
+git clone https://github.com/mrmatho/shoveler
+cd shoveler
+uv sync
+```
+
+`uv sync` creates a `.venv`, installs all dependencies including the dev group,
+and respects `uv.lock` if it exists. Run it again after pulling changes.
+
+## Running
+
+```shell
+uv run python -m shoveler
+```
+
+## Testing
+
+```shell
+uv run pytest
+```
+
+## Managing dependencies
+
+```shell
+uv add somepackage              # add a runtime dependency
+uv add --dev somepackage        # add to the dev group (not published to PyPI)
+uv remove somepackage           # remove a dependency
+uv lock                         # regenerate uv.lock without installing
+uv sync                         # install from uv.lock
+```
+
+Commit `uv.lock` to the repository. It pins exact versions for reproducible installs.
+
+## Usage
+
+- **Open File** — connect to an existing `.duckdb` or `.db` file (green indicator)
+- **New In-Memory** — scratch database; data is lost when closed (amber indicator)
+- **File > Save Database As...** — save current database state to a `.duckdb` file
+- **Checkpoint** — flush the write-ahead log to disk (file databases only)
+- **F5 or Ctrl+Enter** — run query
+- Select part of your SQL to run only that selection
+- Double-click a table name in the schema panel to insert it into the editor
+- **View > Syntax highlighting** — toggle SQL highlighting on or off; enabled by default and remembered between launches
+
+## Building a standalone Windows executable
+
+The project includes `shoveler.spec` with the correct PyInstaller
+configuration. Use this rather than running `pyinstaller` with flags directly —
+the spec handles a non-obvious issue with DuckDB's compiled extension.
+
+```shell
+uv run pyinstaller shoveler.spec
+```
+
+Output is in `dist/Shoveler/`. Distribute that folder as a zip.
+
+**Why --onedir and not --onefile?**
+`--onefile` extracts everything to a temp directory on every launch, which makes
+startup noticeably slow for a PySide6 app. `--onedir` is faster and easier to
+debug if something goes wrong.
+
+**Known PyInstaller issue with DuckDB:**
+DuckDB's compiled core (`_duckdb.pyd` on Windows) lives outside the `duckdb/`
+package directory. PyInstaller does not find it automatically. The spec file
+uses `collect_all('duckdb')` which handles this correctly. If you ever regenerate
+the spec from scratch, make sure this is included or the packaged app will fail
+to start.
+
+## Extending
+
+|Feature|Where to add it|
+|---|---|
+|More export formats|Add menu items in `ResultsPanel._show_export_menu()` — raw data is in `_last_rows` / `_last_columns`|

shoveler-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shoveler"
+version = "0.1.0"
+description = "Shoveler: A minimal desktop SQL workbench for DuckDB"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["duckdb", "sql", "workbench", "education"]
+dependencies = [
+    "PySide6>=6.6",
+    "duckdb>=0.10",
+]
+
+# gui-scripts suppresses the Windows console window; use this instead of scripts
+[project.gui-scripts]
+shoveler = "shoveler.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shoveler"]
+
+# dependency-groups are uv/PEP 735 dev-only deps.
+# They are NOT published to PyPI — use [project.optional-dependencies] for that.
+# Install with: uv sync  (dev group is included by default)
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pyinstaller>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shoveler-0.1.0/shoveler.spec

@@ -0,0 +1,57 @@
+# shoveler.spec
+#
+# Build with:  uv run pyinstaller shoveler.spec
+# Output:      dist/Shoveler/   (--onedir, recommended)
+#
+# Why --onedir and not --onefile:
+#   --onefile extracts everything to a temp directory on every launch,
+#   making startup slow. --onedir is faster and easier to debug.
+#   Distribute the dist/DuckDB Workbench/ folder as a zip.
+
+from PyInstaller.utils.hooks import collect_all
+
+# collect_all picks up:
+#   - the duckdb Python package
+#   - _duckdb.pyd (the compiled extension, which lives outside the package dir)
+#   - any data files shipped with duckdb
+# Without this, the packaged app fails at runtime with an ImportError on _duckdb.
+duckdb_datas, duckdb_binaries, duckdb_hiddenimports = collect_all("duckdb")
+
+a = Analysis(
+    ["src/shoveler/__main__.py"],
+    pathex=[],
+    binaries=duckdb_binaries,
+    datas=duckdb_datas,
+    hiddenimports=duckdb_hiddenimports,
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+)
+
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,  # required for COLLECT (onedir mode)
+    name="Shoveler",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    console=False,  # no console window — same effect as gui-scripts in pyproject.toml
+    disable_windowed_traceback=False,
+)
+
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name="Shoveler",
+)

shoveler-0.1.0/src/shoveler/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("shoveler")
+except PackageNotFoundError:
+    # Running from source without being installed
+    __version__ = "0.0.0.dev"

shoveler-0.1.0/src/shoveler/__main__.py

@@ -0,0 +1,20 @@
+import sys
+from PySide6.QtWidgets import QApplication
+
+try:
+    from .main_window import MainWindow
+except ImportError:
+    # PyInstaller may execute this file as a top-level script during startup.
+    from shoveler.main_window import MainWindow
+
+
+def main():
+    app = QApplication(sys.argv)
+    app.setStyle("Fusion")
+    window = MainWindow()
+    window.show()
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

shoveler-0.1.0/src/shoveler/db.py

@@ -0,0 +1,112 @@
+import duckdb
+import os
+import time
+from typing import Literal
+
+
+class Database:
+    def __init__(self):
+        self.conn = None
+        self.mode: Literal["file", "memory"] | None = None
+        self.path: str | None = None
+
+    def open_file(self, path: str):
+        self._close_existing()
+        self.conn = duckdb.connect(path)
+        self.mode = "file"
+        self.path = path
+
+    def new_memory(self):
+        self._close_existing()
+        self.conn = duckdb.connect(":memory:")
+        self.mode = "memory"
+        self.path = None
+
+    def checkpoint(self):
+        if self.mode == "file" and self.conn:
+            self.conn.execute("CHECKPOINT")
+
+    def save_as(self, path: str) -> str:
+        if not self.conn:
+            raise RuntimeError("No database connected.")
+
+        target_path = os.path.abspath(path)
+        if self.mode == "file" and self.path and os.path.abspath(self.path) == target_path:
+            self.checkpoint()
+            return target_path
+
+        source_catalog = self.conn.execute("PRAGMA database_list").fetchone()[1]
+        source_catalog_escaped = source_catalog.replace('"', '""')
+        target_path_escaped = target_path.replace("'", "''")
+        target_catalog = "shoveler_save_target"
+
+        self.conn.execute(f"ATTACH '{target_path_escaped}' AS {target_catalog}")
+        try:
+            self.conn.execute(
+                f'COPY FROM DATABASE "{source_catalog_escaped}" TO {target_catalog}'
+            )
+        finally:
+            self.conn.execute(f"DETACH {target_catalog}")
+
+        self.open_file(target_path)
+        return target_path
+
+    def execute(self, sql: str) -> dict:
+        """Returns dict: columns, rows, elapsed, error"""
+        if not self.conn:
+            return {
+                "columns": [],
+                "rows": [],
+                "elapsed": 0.0,
+                "error": "No database connected.",
+            }
+        start = time.perf_counter()
+        try:
+            result = self.conn.execute(sql)
+            elapsed = time.perf_counter() - start
+            if result.description:
+                columns = [desc[0] for desc in result.description]
+                rows = result.fetchall()
+            else:
+                columns = []
+                rows = []
+            return {"columns": columns, "rows": rows, "elapsed": elapsed, "error": None}
+        except Exception as e:
+            elapsed = time.perf_counter() - start
+            return {"columns": [], "rows": [], "elapsed": elapsed, "error": str(e)}
+
+    def get_tables(self) -> list[str]:
+        if not self.conn:
+            return []
+        try:
+            result = self.conn.execute("SHOW TABLES").fetchall()
+            return [row[0] for row in result]
+        except Exception:
+            return []
+
+    def get_columns(self, table: str) -> list[tuple[str, str]]:
+        if not self.conn:
+            return []
+        try:
+            # DESCRIBE returns: column_name, column_type, null, key, default, extra
+            result = self.conn.execute(f"DESCRIBE {table}").fetchall()
+            return [(row[0], row[1]) for row in result]
+        except Exception:
+            return []
+
+    def _close_existing(self):
+        if self.conn:
+            try:
+                self.conn.close()
+            except Exception:
+                pass
+            self.conn = None
+
+    def close(self):
+        self._close_existing()
+        self.mode = None
+        self.path = None
+
+    @property
+    def is_connected(self) -> bool:
+        return self.conn is not None

shoveler-0.1.0/src/shoveler/db_status_widget.py

@@ -0,0 +1,123 @@
+import os
+
+from PySide6.QtWidgets import (
+    QWidget,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QFileDialog,
+    QFrame,
+)
+from PySide6.QtCore import Signal, Qt
+
+
+# Colour constants — change here to restyle the indicator globally
+COLOUR_FILE   = "#2a9d2a"   # green   → file-backed database
+COLOUR_MEMORY = "#e6a817"   # amber   → in-memory (unsaved)
+COLOUR_NONE   = "#999999"   # grey    → nothing connected
+
+
+class DatabaseStatusWidget(QFrame):
+    """
+    Toolbar-level widget showing connection state with a colour-coded dot.
+
+    Signals:
+        file_opened(path)      — user selected a .duckdb file
+        memory_requested()     — user clicked New In-Memory
+        checkpoint_requested() — user clicked Checkpoint
+    """
+
+    file_opened = Signal(str)
+    memory_requested = Signal()
+    checkpoint_requested = Signal()
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.setFrameShape(QFrame.Shape.StyledPanel)
+        self.setFixedHeight(38)
+
+        layout = QHBoxLayout(self)
+        layout.setContentsMargins(10, 0, 10, 0)
+        layout.setSpacing(10)
+
+        # Colour dot
+        self.dot = QLabel("●")
+        self.dot.setFixedWidth(16)
+        self.dot.setAlignment(Qt.AlignmentFlag.AlignVCenter)
+        layout.addWidget(self.dot)
+
+        # Status text
+        self.db_label = QLabel()
+        self.db_label.setStyleSheet("font-size: 12px;")
+        layout.addWidget(self.db_label)
+
+        layout.addStretch()
+
+        # Buttons
+        self.open_btn = QPushButton("Open File…")
+        self.open_btn.setFixedWidth(95)
+        self.open_btn.clicked.connect(self._on_open_file)
+        layout.addWidget(self.open_btn)
+
+        self.memory_btn = QPushButton("New In-Memory")
+        self.memory_btn.setFixedWidth(115)
+        self.memory_btn.clicked.connect(self.memory_requested.emit)
+        layout.addWidget(self.memory_btn)
+
+        self.checkpoint_btn = QPushButton("Checkpoint")
+        self.checkpoint_btn.setFixedWidth(95)
+        self.checkpoint_btn.setToolTip(
+            "Flush the write-ahead log to disk (file databases only)"
+        )
+        self.checkpoint_btn.clicked.connect(self.checkpoint_requested.emit)
+        layout.addWidget(self.checkpoint_btn)
+
+        self._set_state_disconnected()
+
+    # ── Public state setters ────────────────────────────────────────────────
+
+    def set_file_mode(self, path: str):
+        filename = os.path.basename(path)
+        self._apply(
+            colour=COLOUR_FILE,
+            text=f"<b>{filename}</b>  <span style='color:#888'>({path})</span>",
+            checkpoint_enabled=True,
+        )
+
+    def set_memory_mode(self):
+        self._apply(
+            colour=COLOUR_MEMORY,
+            text="<b>In-memory</b>  <span style='color:#888'>(unsaved — data is lost when closed)</span>",
+            checkpoint_enabled=False,
+        )
+
+    def notify_checkpoint_ok(self):
+        """Brief visual confirmation after a successful checkpoint."""
+        current = self.db_label.text()
+        # Append a transient tick — main window resets this on next open
+        if "✓" not in current:
+            self.db_label.setText(current + "  ✓")
+
+    # ── Internals ───────────────────────────────────────────────────────────
+
+    def _set_state_disconnected(self):
+        self._apply(
+            colour=COLOUR_NONE,
+            text="No database connected",
+            checkpoint_enabled=False,
+        )
+
+    def _apply(self, colour: str, text: str, checkpoint_enabled: bool):
+        self.dot.setStyleSheet(f"font-size: 18px; color: {colour};")
+        self.db_label.setText(text)
+        self.checkpoint_btn.setEnabled(checkpoint_enabled)
+
+    def _on_open_file(self):
+        path, _ = QFileDialog.getOpenFileName(
+            self,
+            "Open DuckDB Database",
+            "",
+            "DuckDB Files (*.duckdb *.db);;All Files (*)",
+        )
+        if path:
+            self.file_opened.emit(path)