sql2json: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) and other coding agents when working with code in this repository.

Read this first

1. Follow WORKFLOW.md and WORKFLOW.local.md for board usage, branch naming, PR lifecycle, validation gates, and release discipline.
2. This is a public repository. Keep commits, PR bodies, and checked-in docs public-safe: no secrets, local-only absolute paths, private board details, or agent-generated footers.
3. Use francisco-boards for maintainer/agent task status. Project key: S2J; base branch: master; branch format: feature/S2J-N.

Commands

# Install dependencies
uv sync

# Run all tests (fast, in-memory SQLite — no Docker)
uv run pytest

# Run a single test
uv run pytest tests/test_parameter.py::test_parse_parameter

# Run the real-database integration suite (PostgreSQL + MySQL via docker compose)
# Provisions services, runs the `integration`-marked tests, then tears down.
./scripts/test-integration.sh

# Lint
uv run flake8

# Format
uv run black .

# Type check
uv run --extra dev mypy

# Tests with coverage (gated at 90% via fail_under in pyproject.toml)
uv run --extra dev pytest --cov

# Run the CLI tool (since 0.2.1; `python -m sql2json ...` is equivalent)
sql2json --name default --query default

# Run the official Docker Hub image (multi-arch linux/amd64 + linux/arm64)
podman run --rm docker.io/fsistemas/sql2json --query "SELECT 1 AS a, 2 AS b"
# Docker equivalent:
docker run --rm docker.io/fsistemas/sql2json --query "SELECT 1 AS a, 2 AS b"
# Docker Hub: https://hub.docker.com/r/fsistemas/sql2json

# Build the Docker image (installs sql2json from PyPI; pass VERSION to pin a
# release, omit it for the latest). `podman build ...` works identically.
docker build -t sql2json .                      # latest PyPI release
docker build --build-arg VERSION=0.3.0 -t sql2json .
# The official image is published at docker.io/fsistemas/sql2json (see RELEASING.md).

Architecture

sql2json is a CLI tool that runs SQL queries via SQLAlchemy and outputs JSON, CSV, or Excel. Since 0.2.1 it is invoked as the sql2json console command (declared in [project.scripts], target sql2json.__main__:main); the equivalent python -m sql2json form still works. Both dispatch through fire.