sqlcsv-exporter 1.0.0__tar.gz

sqlcsv_exporter-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordi Corbilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlcsv_exporter-1.0.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.1
+Name: sqlcsv-exporter
+Version: 1.0.0
+Summary: CLI utility to stream SQL Server query results into CSV files.
+License: MIT
+Keywords: sql-server,csv,cli,export,pyodbc
+Author: Your Team
+Author-email: team@example.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Dist: pyodbc (>=5.0.1)
+Requires-Dist: rich (>=13.7.0)
+Description-Content-Type: text/markdown
+
+# sqlcsv-exporter
+
+`sqlcsv-exporter` is a publishable CLI package for streaming SQL Server query results into CSV files without loading the full result set into memory.
+
+## Features
+
+- Reads SQL from a `.sql` file
+- Rewrites a declared `@InAsOfDate` value when present
+- Supports trusted or SQL authentication
+- Streams rows with chunked `fetchmany()` and chunked CSV writes
+- Shows live Rich progress while the export runs
+- Ships with pytest coverage for core behavior
+
+## Install
+
+```bash
+poetry install
+```
+
+## Run
+
+```bash
+poetry run sqlcsv-exporter \
+  --sql ./queries/report.sql \
+  --output ./exports/report.csv \
+  --server my-sql-server \
+  --database Reporting
+```
+
+With SQL authentication:
+
+```bash
+poetry run sqlcsv-exporter \
+  --sql ./queries/report.sql \
+  --output ./exports/report.csv \
+  --server my-sql-server \
+  --database Reporting \
+  --sql-auth \
+  --username reporting_user \
+  --password secret
+```
+
+Override the as-of date used in a declared `@InAsOfDate` variable:
+
+```bash
+poetry run sqlcsv-exporter \
+  --sql ./queries/report.sql \
+  --output ./exports/report.csv \
+  --server my-sql-server \
+  --database Reporting \
+  --date 2026-03-26
+```
+
+## Publish
+
+```bash
+poetry build
+poetry publish
+```
+

sqlcsv_exporter-1.0.0/README.md

@@ -0,0 +1,59 @@
+# sqlcsv-exporter
+
+`sqlcsv-exporter` is a publishable CLI package for streaming SQL Server query results into CSV files without loading the full result set into memory.
+
+## Features
+
+- Reads SQL from a `.sql` file
+- Rewrites a declared `@InAsOfDate` value when present
+- Supports trusted or SQL authentication
+- Streams rows with chunked `fetchmany()` and chunked CSV writes
+- Shows live Rich progress while the export runs
+- Ships with pytest coverage for core behavior
+
+## Install
+
+```bash
+poetry install
+```
+
+## Run
+
+```bash
+poetry run sqlcsv-exporter \
+  --sql ./queries/report.sql \
+  --output ./exports/report.csv \
+  --server my-sql-server \
+  --database Reporting
+```
+
+With SQL authentication:
+
+```bash
+poetry run sqlcsv-exporter \
+  --sql ./queries/report.sql \
+  --output ./exports/report.csv \
+  --server my-sql-server \
+  --database Reporting \
+  --sql-auth \
+  --username reporting_user \
+  --password secret
+```
+
+Override the as-of date used in a declared `@InAsOfDate` variable:
+
+```bash
+poetry run sqlcsv-exporter \
+  --sql ./queries/report.sql \
+  --output ./exports/report.csv \
+  --server my-sql-server \
+  --database Reporting \
+  --date 2026-03-26
+```
+
+## Publish
+
+```bash
+poetry build
+poetry publish
+```

sqlcsv_exporter-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "sqlcsv-exporter"
+version = "1.0.0"
+description = "CLI utility to stream SQL Server query results into CSV files."
+authors = ["Your Team <team@example.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "sqlcsv_exporter", from = "src" }]
+keywords = ["sql-server", "csv", "cli", "export", "pyodbc"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Database",
+  "Topic :: Utilities",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+pyodbc = ">=5.0.1"
+rich = ">=13.7.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0.0"
+
+[tool.poetry.scripts]
+sqlcsv-exporter = "sqlcsv_exporter.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/__init__.py

@@ -0,0 +1,5 @@
+"""sqlcsv_exporter package."""
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/__main__.py

@@ -0,0 +1,5 @@
+from sqlcsv_exporter.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/cli.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Sequence
+
+from rich.console import Console
+
+from sqlcsv_exporter import __version__
+from sqlcsv_exporter.config import (
+    DEFAULT_CHUNK_SIZE,
+    DEFAULT_DATE_PARAMETER,
+    DEFAULT_DRIVER,
+    DEFAULT_ENCODING,
+    DEFAULT_LOGIN_TIMEOUT_SECONDS,
+    DEFAULT_QUERY_TIMEOUT_SECONDS,
+    ConfigError,
+    ExportConfig,
+    resolve_as_of_date,
+)
+from sqlcsv_exporter.exporter import ExportError, execute_query_to_csv
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sqlcsv-exporter",
+        description="Execute a SQL Server query from a file and stream the result into CSV.",
+    )
+    parser.add_argument("--sql", required=True, help="Path to the .sql file to execute.")
+    parser.add_argument("--output", required=True, help="Destination CSV file path.")
+    parser.add_argument("--server", required=True, help="SQL Server hostname or instance.")
+    parser.add_argument("--database", required=True, help="Database name.")
+    parser.add_argument(
+        "--date",
+        help="As-of date injected into a declared @InAsOfDate parameter. Defaults to yesterday.",
+    )
+    parser.add_argument(
+        "--date-parameter",
+        default=DEFAULT_DATE_PARAMETER,
+        help=f"Declared SQL variable to rewrite. Default: {DEFAULT_DATE_PARAMETER}.",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=DEFAULT_CHUNK_SIZE,
+        help=f"Rows to fetch and write per batch. Default: {DEFAULT_CHUNK_SIZE}.",
+    )
+    parser.add_argument(
+        "--delimiter",
+        default=",",
+        help="Single-character CSV delimiter. Default: ','.",
+    )
+    parser.add_argument(
+        "--encoding",
+        default=DEFAULT_ENCODING,
+        help=f"Output file encoding. Default: {DEFAULT_ENCODING}.",
+    )
+    parser.add_argument("--no-header", action="store_true", help="Do not write CSV column headers.")
+    parser.add_argument(
+        "--driver",
+        default=DEFAULT_DRIVER,
+        help=f"ODBC driver name. Default: {DEFAULT_DRIVER}.",
+    )
+    parser.add_argument("--sql-auth", action="store_true", help="Use SQL authentication instead of trusted connection.")
+    parser.add_argument("--username", help="SQL username for --sql-auth.")
+    parser.add_argument("--password", help="SQL password for --sql-auth.")
+    parser.add_argument(
+        "--login-timeout",
+        type=int,
+        default=DEFAULT_LOGIN_TIMEOUT_SECONDS,
+        help=f"Connection timeout in seconds. Default: {DEFAULT_LOGIN_TIMEOUT_SECONDS}.",
+    )
+    parser.add_argument(
+        "--query-timeout",
+        type=int,
+        default=DEFAULT_QUERY_TIMEOUT_SECONDS,
+        help=f"Query timeout in seconds. Default: {DEFAULT_QUERY_TIMEOUT_SECONDS}.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def build_config(args: argparse.Namespace) -> ExportConfig:
+    return ExportConfig(
+        sql_file=Path(args.sql),
+        output_csv=Path(args.output),
+        server=args.server,
+        database=args.database,
+        as_of_date=resolve_as_of_date(args.date),
+        chunk_size=args.chunk_size,
+        delimiter=args.delimiter,
+        encoding=args.encoding,
+        include_header=not args.no_header,
+        trusted_connection=not args.sql_auth,
+        username=args.username,
+        password=args.password,
+        driver=args.driver,
+        date_parameter_name=args.date_parameter,
+        login_timeout_seconds=args.login_timeout,
+        query_timeout_seconds=args.query_timeout,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    console = Console(stderr=True)
+    parser = build_parser()
+
+    try:
+        args = parser.parse_args(argv)
+        config = build_config(args)
+        execute_query_to_csv(config, console=console)
+        return 0
+    except (ConfigError, ExportError, FileNotFoundError, RuntimeError) as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        return 1
+    except KeyboardInterrupt:
+        console.print("[bold red]Error:[/bold red] Export cancelled.")
+        return 130

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/config.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from pathlib import Path
+
+DEFAULT_CHUNK_SIZE = 50_000
+DEFAULT_DATE_PARAMETER = "@InAsOfDate"
+DEFAULT_DRIVER = "ODBC Driver 17 for SQL Server"
+DEFAULT_ENCODING = "utf-8-sig"
+DEFAULT_LOGIN_TIMEOUT_SECONDS = 15
+DEFAULT_QUERY_TIMEOUT_SECONDS = 600
+
+
+class ConfigError(ValueError):
+    """Raised when CLI options cannot be turned into a valid config."""
+
+
+def resolve_as_of_date(value: str | None, *, now: datetime | None = None) -> str:
+    if value:
+        try:
+            return datetime.strptime(value, "%Y-%m-%d").strftime("%Y-%m-%d")
+        except ValueError as exc:
+            raise ConfigError("Date must use YYYY-MM-DD format.") from exc
+
+    current_time = now or datetime.now()
+    return (current_time - timedelta(days=1)).strftime("%Y-%m-%d")
+
+
+@dataclass(frozen=True)
+class ExportConfig:
+    sql_file: Path
+    output_csv: Path
+    server: str
+    database: str
+    as_of_date: str
+    chunk_size: int = DEFAULT_CHUNK_SIZE
+    delimiter: str = ","
+    encoding: str = DEFAULT_ENCODING
+    include_header: bool = True
+    trusted_connection: bool = True
+    username: str | None = None
+    password: str | None = field(default=None, repr=False)
+    driver: str = DEFAULT_DRIVER
+    date_parameter_name: str = DEFAULT_DATE_PARAMETER
+    login_timeout_seconds: int = DEFAULT_LOGIN_TIMEOUT_SECONDS
+    query_timeout_seconds: int = DEFAULT_QUERY_TIMEOUT_SECONDS
+
+    def __post_init__(self) -> None:
+        if not self.server.strip():
+            raise ConfigError("Server is required.")
+        if not self.database.strip():
+            raise ConfigError("Database is required.")
+        if self.chunk_size <= 0:
+            raise ConfigError("Chunk size must be greater than zero.")
+        if len(self.delimiter) != 1:
+            raise ConfigError("Delimiter must be exactly one character.")
+        if self.login_timeout_seconds <= 0:
+            raise ConfigError("Login timeout must be greater than zero.")
+        if self.query_timeout_seconds <= 0:
+            raise ConfigError("Query timeout must be greater than zero.")
+        if not self.date_parameter_name.startswith("@"):
+            raise ConfigError("Date parameter name must start with '@'.")
+
+        if not self.trusted_connection:
+            if not self.username:
+                raise ConfigError("Username is required when SQL authentication is enabled.")
+            if not self.password:
+                raise ConfigError("Password is required when SQL authentication is enabled.")

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/connection.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from types import ModuleType
+
+from sqlcsv_exporter.config import ExportConfig
+
+
+def load_pyodbc() -> ModuleType:
+    try:
+        import pyodbc  # type: ignore
+    except ImportError as exc:
+        raise RuntimeError(
+            "pyodbc is required to connect to SQL Server. Install system ODBC drivers and the pyodbc package."
+        ) from exc
+
+    return pyodbc
+
+
+def build_connection_string(config: ExportConfig) -> str:
+    driver_name = config.driver.strip().strip("{}")
+    parts = [
+        f"DRIVER={{{driver_name}}}",
+        f"SERVER={config.server}",
+        f"DATABASE={config.database}",
+        "APP=sqlcsv-exporter",
+    ]
+
+    if config.trusted_connection:
+        parts.append("Trusted_Connection=yes")
+    else:
+        parts.append(f"UID={config.username}")
+        parts.append(f"PWD={config.password}")
+
+    return ";".join(parts) + ";"
+
+
+def open_connection(config: ExportConfig):
+    pyodbc = load_pyodbc()
+    return pyodbc.connect(
+        build_connection_string(config),
+        timeout=config.login_timeout_seconds,
+    )

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/exporter.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import csv
+import time
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable, Iterator, Sequence
+
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+
+from sqlcsv_exporter.config import ExportConfig
+from sqlcsv_exporter.connection import open_connection
+from sqlcsv_exporter.sql_rewriter import read_sql_file, replace_declared_date_parameter
+
+ProgressCallback = Callable[[int, int], None]
+
+
+class ExportError(RuntimeError):
+    """Raised when the export pipeline cannot complete successfully."""
+
+
+@dataclass(frozen=True)
+class ExportResult:
+    output_csv: Path
+    row_count: int
+    column_count: int
+    file_size_bytes: int
+    duration_seconds: float
+    date_parameter_replaced: bool
+
+
+def iter_row_chunks(cursor, chunk_size: int) -> Iterator[Sequence[Sequence[object]]]:
+    while True:
+        rows = cursor.fetchmany(chunk_size)
+        if not rows:
+            break
+        yield rows
+
+
+def write_rows_to_csv(
+    output_path: Path,
+    columns: Sequence[str],
+    row_chunks: Iterable[Sequence[Sequence[object]]],
+    *,
+    delimiter: str,
+    encoding: str,
+    include_header: bool,
+    progress_callback: ProgressCallback | None = None,
+) -> tuple[int, int]:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    total_rows = 0
+    with output_path.open("w", newline="", encoding=encoding) as handle:
+        writer = csv.writer(handle, delimiter=delimiter)
+
+        if include_header:
+            writer.writerow(columns)
+
+        for chunk in row_chunks:
+            writer.writerows(chunk)
+            total_rows += len(chunk)
+
+            if progress_callback is not None:
+                progress_callback(total_rows, handle.tell())
+
+    return total_rows, output_path.stat().st_size
+
+
+def _format_size(num_bytes: int) -> str:
+    if num_bytes < 1024:
+        return f"{num_bytes} B"
+    if num_bytes < 1024 * 1024:
+        return f"{num_bytes / 1024:.1f} KiB"
+    return f"{num_bytes / (1024 * 1024):.1f} MiB"
+
+
+def _render_run_summary(console: Console, config: ExportConfig, date_replaced: bool) -> None:
+    summary = Table.grid(padding=(0, 2))
+    summary.add_column(style="cyan")
+    summary.add_column()
+    summary.add_row("SQL file", str(config.sql_file))
+    summary.add_row("Output", str(config.output_csv))
+    summary.add_row("Server", config.server)
+    summary.add_row("Database", config.database)
+    summary.add_row("As-of date", config.as_of_date)
+    summary.add_row("Chunk size", f"{config.chunk_size:,}")
+    summary.add_row("Date rewritten", "yes" if date_replaced else "no")
+    console.print(summary)
+
+
+def _apply_query_timeout(connection: object, cursor: object, timeout_seconds: int) -> None:
+    if hasattr(cursor, "timeout"):
+        with suppress(Exception):
+            setattr(cursor, "timeout", timeout_seconds)
+            return
+
+    if hasattr(connection, "timeout"):
+        with suppress(Exception):
+            setattr(connection, "timeout", timeout_seconds)
+
+
+def execute_query_to_csv(config: ExportConfig, *, console: Console | None = None) -> ExportResult:
+    console = console or Console(stderr=True)
+    sql_text = read_sql_file(config.sql_file)
+    sql_text, date_replaced = replace_declared_date_parameter(
+        sql_text,
+        config.as_of_date,
+        parameter_name=config.date_parameter_name,
+    )
+
+    _render_run_summary(console, config, date_replaced)
+
+    started_at = time.perf_counter()
+    connection = None
+    cursor = None
+
+    try:
+        with console.status("Connecting to SQL Server..."):
+            connection = open_connection(config)
+            cursor = connection.cursor()
+            cursor.arraysize = config.chunk_size
+            _apply_query_timeout(connection, cursor, config.query_timeout_seconds)
+
+        with console.status("Executing query..."):
+            cursor.execute(sql_text)
+
+        if cursor.description is None:
+            raise ExportError(
+                "The SQL completed without returning a result set. Ensure the script ends with a SELECT query."
+            )
+
+        columns = [column[0] or f"column_{index + 1}" for index, column in enumerate(cursor.description)]
+        console.print(f"Columns detected: [bold]{len(columns)}[/bold]")
+
+        progress = Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            TextColumn("{task.fields[row_text]}"),
+            TextColumn("{task.fields[size_text]}"),
+            TimeElapsedColumn(),
+            console=console,
+        )
+
+        with progress:
+            task_id = progress.add_task(
+                "Writing CSV",
+                total=None,
+                row_text="0 rows",
+                size_text="0 B",
+            )
+            completed_rows = 0
+
+            def on_progress(total_rows: int, size_bytes: int) -> None:
+                nonlocal completed_rows
+                progress.update(
+                    task_id,
+                    advance=0,
+                    row_text=f"{total_rows:,} rows",
+                    size_text=_format_size(size_bytes),
+                )
+                progress.advance(task_id, total_rows - completed_rows)
+                completed_rows = total_rows
+
+            row_count, file_size_bytes = write_rows_to_csv(
+                config.output_csv,
+                columns,
+                iter_row_chunks(cursor, config.chunk_size),
+                delimiter=config.delimiter,
+                encoding=config.encoding,
+                include_header=config.include_header,
+                progress_callback=on_progress,
+            )
+
+        duration_seconds = time.perf_counter() - started_at
+        console.print(
+            f"Export complete: [bold]{row_count:,}[/bold] rows, "
+            f"[bold]{len(columns)}[/bold] columns, {_format_size(file_size_bytes)} written."
+        )
+        return ExportResult(
+            output_csv=config.output_csv,
+            row_count=row_count,
+            column_count=len(columns),
+            file_size_bytes=file_size_bytes,
+            duration_seconds=duration_seconds,
+            date_parameter_replaced=date_replaced,
+        )
+    finally:
+        if cursor is not None:
+            with suppress(Exception):
+                cursor.close()
+        if connection is not None:
+            with suppress(Exception):
+                connection.close()

sqlcsv_exporter-1.0.0/src/sqlcsv_exporter/sql_rewriter.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+def read_sql_file(path: Path) -> str:
+    if not path.exists():
+        raise FileNotFoundError(f"SQL file not found: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def replace_declared_date_parameter(
+    sql_text: str,
+    date_value: str,
+    *,
+    parameter_name: str,
+) -> tuple[str, bool]:
+    escaped_name = re.escape(parameter_name)
+    pattern = (
+        rf"((?:DECLARE\s+{escaped_name}\s+(?:DATE|DATETIME|DATETIME2)"
+        rf"|SET\s+{escaped_name})\s*=\s*')([^']*)(')"
+    )
+    rewritten_sql, replacements = re.subn(
+        pattern,
+        rf"\g<1>{date_value}\g<3>",
+        sql_text,
+        flags=re.IGNORECASE,
+    )
+    return rewritten_sql, replacements > 0