Skycat

Skycat is a standalone Python package and command-line tool for building, managing and querying versioned local PostgreSQL/PostGIS databases from mirrored astronomical reference catalogs.

It provides calibration, photometry, and observation-processing pipelines with a fast reproducible catalog layer that does not depend on the availability or performance of external catalog services. Skycat can discover and ingest known catalog releases, validate imported data, manage multiple versions of the same catalog, activate the release that should serve as the default, and retain older releases for reproducibility or comparison.

Its query interface supports spatial cone searches, catalog-native source lookups, magnitude and quality filtering, and efficient batch crossmatching using PostGIS spatial indexes. The overall goal is to provide astronomy software with a consistent, locally controlled source of catalog data for workflows that require reliable access to large astronomical reference catalogs.

Skycat installs:

• the skycat CLI;
• Python query APIs, including CatalogReader;
• SQLAlchemy models and registry logic;
• ingestion parsers, validators, and COPY loaders;
• Alembic migrations under skycat/migrations;
• support for APASS, VSX, Landolt, and Stetson catalog families.

Skycat does not install PostgreSQL, PostGIS, catalog source files, imported catalog rows, production credentials, backups, or a hosted query endpoint. Operators still provision the database and provide source data separately.

Supported Catalogs

Installation

From PyPI:

python -m pip install skycat

From the GitHub Release wheel:

python -m pip install \
  https://github.com/SkynetRTN/skycat/releases/download/v0.1.6/skycat-0.1.6-py3-none-any.whl

From a Git tag:

python -m pip install "git+https://github.com/SkynetRTN/skycat.git@v0.1.6"

See docs/operations/release.md for release, artifact, TestPyPI, and PyPI validation steps.

Quick Start

For local development:

uv sync --extra dev
uv run skycat --help

For a local PostgreSQL/PostGIS catalog database:

cp infra/docker/.env.example infra/docker/.env
cp infra/docker/.env.secrets.example infra/docker/.env.secrets
docker compose -f infra/docker/compose.yaml build skycat-postgres
docker compose -f infra/docker/compose.yaml up -d skycat-postgres
docker compose -f infra/docker/compose.yaml --profile skycat-tools run --rm skycat-init
docker compose -f infra/docker/compose.yaml --profile skycat-tools run --rm skycat-migrate

Then point SKYCAT_DATA_ROOT at mirrored source data, discover releases, and import deliberately:

export SKYCAT_DATA_ROOT=/srv/agents/catalogs
uv run skycat discover
uv run skycat import apass dr6 --activate
uv run skycat cone apass --ra 10.0 --dec 1.0 --radius-arcmin 5

The operational details are in docs/operations/runbook.md.

CLI

Run skycat --help for the full command list. The main commands are:

Examples:

skycat --json config
skycat releases apass
skycat cone apass --ra 10.0 --dec 1.0 --radius-arcmin 5 --order-by johnson_v_mag --limit 50
skycat lookup apass 090-0000001

--json is a group option, so it goes before the subcommand.

Python API

Use CatalogReader for application reads. It owns connection pooling, active release caching, and a default statement timeout. Query calls re-check a cached release against the registry before using it, so a release removed, failed, or deactivated behind a long-lived reader raises CatalogQueryError instead of looking like an empty cone.

from skycat import CatalogReader

with CatalogReader.from_env() as reader:
    stars = reader.cone(
        "apass",
        ra=10.0,
        dec=1.0,
        radius_arcmin=5,
        order_by="johnson_v_mag",
        limit=50,
    )
    hits = reader.crossmatch("vsx", [("target-1", 10.0, 1.0)], radius_arcsec=5)
    row = reader.lookup("apass", "090-0000001")

Pass order_by whenever you also pass limit. Without it, cone results are nearest-first by angular separation, which is not the same as brightest-first in dense fields.

See docs/reference/api-stability.md for the stable API surface and compatibility policy.

Release Model

Catalog releases are a database dimension, not a deployment artifact. Each family can have multiple imported releases, but only one active release serves default queries at a time. Use --release when you need a specific historical release for parity checks, rollback, or reproducibility.

Imports stage rows, validate them, build production partitions, mark releases ready, and activate only when explicitly requested. A failed import should not degrade the currently active release.

Re-running skycat import <family> <release> --activate is idempotent for an unchanged imported release: if it is already ACTIVE the command exits 0, and if it is READY or SUPERSEDED the command activates it when the validation gate allows activation.

The full architecture is documented in docs/reference/architecture.md, and source data provenance is covered in docs/guides/provenance.md.

Configuration

Skycat uses SKYCAT_DB_* for database settings and SKYCAT_* for catalog runtime paths and diagnostics.

Testing

Fast tests do not require a database:

uv run pytest tests -q -m "not postgis"

PostGIS tests require a throwaway catalog database. Do not point them at a catalog store you care about; fixtures import small samples with replacement.

uv run skycat health
uv run pytest tests -q --require-postgis

See docs/operations/ci.md for the CI matrix and docs/operations/runbook.md for operational safety notes.

Adding a Catalog Family

The implementation guide is docs/guides/add-family.md. The short checklist is:

1. Add a FamilyDef / ReleaseDef in skycat/registry/catalog_defs.py.
2. Add a typed model under skycat/models/.
3. Add a streaming parser under skycat/ingestion/parsers/.
4. Add an Alembic migration under skycat/migrations/versions/.
5. Add family-specific validation under skycat/validation/ when needed.
6. Add fixtures, tests, and a row in the supported-catalog table above.

Documentation

Working notes live under docs/working/; they are snapshots of open work, not current API references.

License

Skycat is licensed under the GNU General Public License v3.0. See LICENSE.