Installation

Docker (recommended)

The fastest way to get pg_orrery running. The Docker image ships PostgreSQL 17 with pg_orrery pre-compiled.

1. Pull the image:

   docker pull git.supported.systems/warehack.ing/pg_orrery:pg17

2. Start the container:

   docker run -d --name pg_orrery \
     -e POSTGRES_PASSWORD=orbit \
     -p 5499:5432 \
     git.supported.systems/warehack.ing/pg_orrery:pg17

3. Connect and enable the extension:

   psql -h localhost -p 5499 -U postgres -c "CREATE EXTENSION pg_orrery;"

Tip

Port 5499 avoids conflicts with any existing PostgreSQL on 5432. Adjust as needed.

Build from Source

Requires PostgreSQL 17 development headers and a C toolchain.

1. Clone the repository:

   git clone https://git.supported.systems/warehack.ing/pg_orrery.git
   cd pg_orrery
   git submodule update --init

2. Build and install:

   make PG_CONFIG=/usr/bin/pg_config
   sudo make install PG_CONFIG=/usr/bin/pg_config

3. Enable in your database:

   CREATE EXTENSION pg_orrery;

4. Verify installation:

   SELECT planet_observe(5, '40.0N 105.3W 1655m'::observer, now());

Note

The build compiles pure C throughout --- both pg_orrery and the vendored SGP4/SDP4 library in src/sgp4/. No C++ compiler or runtime is required.

Docker Compose

For integration with existing PostgreSQL-based applications.

services:
  db:
    image: git.supported.systems/warehack.ing/pg_orrery:pg17
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-orbit}
      POSTGRES_DB: ${POSTGRES_DB:-orbit}
    ports:
      - "${PGPORT:-5499}:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Then:

docker compose up -d
psql -h localhost -p 5499 -U postgres -d orbit -c "CREATE EXTENSION pg_orrery;"

Running the test suite

If building from source, the regression tests verify all functions across 15 test suites:

make installcheck PG_CONFIG=/usr/bin/pg_config

This runs the tests listed in the REGRESS variable: TLE parsing, SGP4 propagation, coordinate transforms, pass prediction, GiST indexing, convenience functions, star observation, Keplerian propagation, planet observation, moon observation, Lambert transfers, DE ephemeris, orbit determination, SP-GiST visibility index, and the 518 Vallado test vectors.

Upgrading

If you have a previous version installed, upgrade in place:

-- From v0.1.0 (satellite-only) to v0.2.0 (solar system)
ALTER EXTENSION pg_orrery UPDATE TO '0.2.0';

-- From v0.2.0 to v0.3.0 (DE ephemeris support)
ALTER EXTENSION pg_orrery UPDATE TO '0.3.0';

-- From v0.3.0 to v0.4.0 (orbit determination)
ALTER EXTENSION pg_orrery UPDATE TO '0.4.0';

-- From v0.4.0 to v0.5.0 (OD enhancements: multi-observer, Gibbs IOD, covariance)
ALTER EXTENSION pg_orrery UPDATE TO '0.5.0';

-- From v0.5.0 to v0.6.0 (range rate, weighted obs, Gauss angles-only IOD)
ALTER EXTENSION pg_orrery UPDATE TO '0.6.0';

Each migration adds new functions while preserving existing data and functions.