baseball.computer

Library powering the baseball.computer database.

Starts from a set of Retrosheet files dropped off by the Rust parser and builds a DuckDB database (bc.db) of the box-score, event, and seasonal models documented at docs.baseball.computer.

Build engine

SQLMesh-native. Models live under bc/models/ as MODEL(...) blocks; sources and seeds load via before_all Python @macros in bc/macros/_init_db.py.

uv sync --group build
just --list
just plan
just audit

Run these commands from the repository root. just plan builds the current branch's development environment. If production databases already exist, just bootstrap-dev seeds or refreshes the development copies; it overwrites existing dev databases. See the build conventions and performance guidance before a full build.

Source-table metadata (78 parquet sources) lives in bc/external_models.yaml — single source of truth for SQLMesh's external loader and _init_db.py's DDL emission. Shared docstrings live in bc/models/**/*.md doc-block files; @doc('key') refs in MODEL blocks resolve at parse time via bc/macros/_docs.py.

Development uses bc_dev.db and bc/bc_state_dev.db; production uses bc.db and bc/bc_state.db. The justfile sets the database paths for development recipes. Production changes use just promote-prod or just rebuild-prod, as described in the build conventions.

Before loading a Retrosheet update, use just compare-sources to compare the current raw tables with a frozen candidate extract. See the source comparison guide for coverage reports, saved snapshots, and repeatable commands.

Then use just build-source-candidate to build the branch against current and release sources in isolation, and just compare-models to compare the fully processed tables. The modeled comparison guide describes the builds, the three comparisons, and promotion acceptance.

Documentation

Start with the documentation guide for the complete map.

• Model and column reference
• Production publication and verification
• LLM schema context
• Research notes and implementation plans
• Open follow-ups
• Agent guide

Agent skills

.claude/skills/sqlmesh/ ships a project-agnostic SQLMesh reference skill (model authoring, plan/apply workflow, audits, CLI). Loaded automatically when working on SQLMesh code, or invoked explicitly with /sqlmesh.

Production query storage

The browser site queries a public DuckLake 1.0 catalog and immutable Parquet on R2. uv run --group build python scripts/publish_ducklake.py exports bc.db read-only and checks row-count parity. uv run --group build python scripts/upload_ducklake.py uploads data, schema metadata, and finally the catalog. For an existing Wrangler OAuth login, use --wrangler; a fresh version prefix can use --skip-purge.

Attach from DuckDB with:

INSTALL ducklake;
LOAD ducklake;
ATTACH 'ducklake:https://data.baseball.computer/baseball/v1/baseball.ducklake'
  AS baseball (READ_ONLY);
USE baseball.main_models;

See DuckLake production publication for publication and verification.