# pg_orrery

> Celestial mechanics types and functions for PostgreSQL. Native C extension with 151 SQL objects (135 user-visible functions + 16 GiST support), 9 custom types, GiST/SP-GiST indexing. Covers satellites (SGP4/SDP4), planets (VSOP87), Moon (ELP2000-82B), 19 planetary moons, stars (with proper motion), comets, asteroids (MPC catalog), Jupiter radio bursts, orbit determination, interplanetary Lambert transfers, equatorial RA/Dec coordinates, atmospheric refraction, light-time correction, annual stellar aberration, equatorial angular separation, rise/set prediction (geometric + refracted), constellation identification, and nutation. Optional JPL DE440/441 ephemeris for sub-arcsecond accuracy.

- [Source code](https://git.supported.systems/warehack.ing/pg_orrery)
- [Full LLM reference](https://pg-orrery.warehack.ing/llms-full.txt): All function signatures, types, body IDs, operators, and query patterns inline

## Getting Started

- [What is pg_orrery?](https://pg-orrery.warehack.ing/getting-started/what-is-pg-orrery/): Overview — the "PostGIS for space" analogy, domain coverage, design philosophy
- [Installation](https://pg-orrery.warehack.ing/getting-started/installation/): Build from source with PGXS or run via Docker (PostgreSQL 14–18)
- [Quick Start](https://pg-orrery.warehack.ing/getting-started/quick-start/): First queries — observe the ISS, track planets, predict passes

## Guides

- [Tracking Satellites](https://pg-orrery.warehack.ing/guides/tracking-satellites/): SGP4/SDP4 propagation, TLE parsing, batch observation over catalogs
- [Observing the Solar System](https://pg-orrery.warehack.ing/guides/observing-solar-system/): VSOP87 planets, ELP2000-82B Moon, Sun — topocentric observation from SQL
- [Cosmic Queries Cookbook](https://pg-orrery.warehack.ing/guides/cosmic-queries/): 9 cross-domain SQL recipes combining satellites, planets, moons, and stars
- [Planetary Moon Tracking](https://pg-orrery.warehack.ing/guides/planetary-moons/): L1.2 Galilean, TASS17 Saturn, GUST86 Uranus, MarsSat Mars moon theories
- [Star Catalogs in SQL](https://pg-orrery.warehack.ing/guides/star-catalogs/): J2000 coordinates, IAU 1976 precession, batch star observation
- [Comet & Asteroid Tracking](https://pg-orrery.warehack.ing/guides/comets-asteroids/): Keplerian propagation, MPC MPCORB.DAT import, orbital_elements type
- [Jupiter Radio Burst Prediction](https://pg-orrery.warehack.ing/guides/jupiter-radio-bursts/): Io phase angle, CML System III, Carr source region probability
- [Interplanetary Trajectories](https://pg-orrery.warehack.ing/guides/interplanetary-trajectories/): Lambert transfer solver, pork chop plots, C3 energy grids
- [Conjunction Screening](https://pg-orrery.warehack.ing/guides/conjunction-screening/): GiST-indexed altitude/inclination overlap, batch distance computation
- [JPL DE Ephemeris](https://pg-orrery.warehack.ing/guides/de-ephemeris/): Optional DE440/441 binary reader for sub-arcsecond planetary positions
- [Orbit Determination](https://pg-orrery.warehack.ing/guides/orbit-determination/): TLE fitting from ECI, topocentric, and angles-only observations
- [Satellite Pass Prediction](https://pg-orrery.warehack.ing/guides/pass-prediction/): AOS/TCA/LOS computation, visibility windows, minimum elevation filter
- [Building TLE Catalogs](https://pg-orrery.warehack.ing/guides/catalog-management/): CelesTrak/Space-Track import, catalog maintenance, bulk loading

## Workflow Translation

- [From Skyfield to SQL](https://pg-orrery.warehack.ing/workflow/from-skyfield/): Side-by-side migration from Python Skyfield to pg_orrery SQL
- [From JPL Horizons to SQL](https://pg-orrery.warehack.ing/workflow/from-jpl-horizons/): Replacing Horizons web API queries with pg_orrery functions
- [From GMAT to SQL](https://pg-orrery.warehack.ing/workflow/from-gmat/): Mission planning workflows translated to SQL
- [From Radio Jupiter Pro to SQL](https://pg-orrery.warehack.ing/workflow/from-radio-jupiter-pro/): Jupiter radio burst prediction comparison
- [From find_orb to SQL](https://pg-orrery.warehack.ing/workflow/from-find-orb/): Orbit determination comparison with Bill Gray's find_orb
- [From Poliastro to SQL](https://pg-orrery.warehack.ing/workflow/from-poliastro/): Lambert transfers and orbital maneuvers comparison
- [The SQL Advantage](https://pg-orrery.warehack.ing/workflow/sql-advantage/): Why database-native celestial mechanics vs. standalone tools

## Reference

- [Types](https://pg-orrery.warehack.ing/reference/types/): 9 fixed-size types — tle (112B), eci_position (48B), geodetic (24B), topocentric (32B), observer (24B), pass_event (48B), heliocentric (24B), orbital_elements (72B), equatorial (24B), plus observer_window composite
- [Functions: Satellite](https://pg-orrery.warehack.ing/reference/functions-satellite/): 22 functions — SGP4/SDP4 propagation, coordinate transforms, pass prediction, observation, satellite RA/Dec (topocentric + geocentric)
- [Functions: Solar System](https://pg-orrery.warehack.ing/reference/functions-solar-system/): VSOP87 planets, Sun, Moon — observation, heliocentric positions, equatorial RA/Dec, light-time corrected _apparent() variants
- [Functions: Moons](https://pg-orrery.warehack.ing/reference/functions-moons/): Galilean, Saturn, Uranus, Mars moon observation via analytical theories
- [Functions: Stars & Comets](https://pg-orrery.warehack.ing/reference/functions-stars-comets/): Star observation with proper motion, Keplerian propagation, comet/asteroid observation + RA/Dec, MPC parsing, orbital_elements functions
- [Functions: Radio](https://pg-orrery.warehack.ing/reference/functions-radio/): Jupiter decametric radio burst prediction — Io phase, CML, burst probability
- [Functions: Transfers](https://pg-orrery.warehack.ing/reference/functions-transfers/): Lambert transfer solver for interplanetary trajectory design
- [Functions: Refraction](https://pg-orrery.warehack.ing/reference/functions-refraction/): Bennett (1982) atmospheric refraction, P/T correction, apparent elevation, refracted pass prediction
- [Functions: Equatorial Spatial](https://pg-orrery.warehack.ing/reference/functions-equatorial/): Angular separation (Vincenty formula), cone search, `<->` operator on equatorial type
- [Functions: Rise/Set & Constellation](https://pg-orrery.warehack.ing/reference/functions-rise-set/): Rise/set prediction (geometric + refracted), status diagnostics, IAU constellation identification
- [Functions: DE Ephemeris](https://pg-orrery.warehack.ing/reference/functions-de/): Optional JPL DE440/441 variants of observation, equatorial, and apparent functions
- [Functions: Orbit Determination](https://pg-orrery.warehack.ing/reference/functions-od/): TLE fitting from ECI, topocentric, and angles-only observations
- [Operators & Indexes](https://pg-orrery.warehack.ing/reference/operators-gist/): GiST (&&, <->) and SP-GiST (&?) operator classes for orbital indexing
- [Body ID Reference](https://pg-orrery.warehack.ing/reference/body-ids/): Planet IDs 0–10, Galilean 0–3, Saturn 0–7, Uranus 0–4, Mars 0–1
- [Constants & Accuracy](https://pg-orrery.warehack.ing/reference/constants-accuracy/): WGS-72/WGS-84/IAU constants, accuracy budgets per theory

## Architecture

- [Design Principles](https://pg-orrery.warehack.ing/architecture/design-principles/): Hamilton's Development Before the Fact methodology applied to a PG extension
- [Constant Chain of Custody](https://pg-orrery.warehack.ing/architecture/constant-chain-of-custody/): Why WGS-72 for propagation, WGS-84 for output — and the consequences of mixing them
- [Observation Pipeline](https://pg-orrery.warehack.ing/architecture/observation-pipeline/): From orbital elements through frame rotation to observer-relative coordinates
- [Theory-to-Code Mapping](https://pg-orrery.warehack.ing/architecture/theory-to-code/): Each source paper mapped to its C implementation file and SQL function
- [Memory & Thread Safety](https://pg-orrery.warehack.ing/architecture/memory-thread-safety/): palloc/pfree, PARALLEL SAFE, no global mutable state, per-backend DE handles
- [SGP4 Integration](https://pg-orrery.warehack.ing/architecture/sgp4-integration/): Vendored Bill Gray sat_code, .cpp→.c rename, Vallado verification

## Optional

- [Benchmarks](https://pg-orrery.warehack.ing/performance/benchmarks/): Timing data — 12k TLEs in 17ms, 66k catalog operations, GiST/SP-GiST index performance