Installation

Docker (recommended)

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

1. Pull the image:

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

2. Start the container:

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

3. Connect and enable the extension:

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

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/C++ toolchain.

1. Clone the repository:

   git clone https://git.supported.systems/warehack.ing/pg_orbit.git
   cd pg_orbit
   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_orbit;

4. Verify installation:

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

Note

The build compiles both C source (pg_orbit) and C++ source (sat_code library for SGP4/SDP4). The C++ runtime (-lstdc++) is linked automatically.

Docker Compose

For integration with existing PostgreSQL-based applications.

services:
  db:
    image: git.supported.systems/warehack.ing/pg_orbit: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_orbit;"

Running the test suite

If building from source, the regression tests verify all 57 functions across 11 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, and Lambert transfers.

Upgrading from v0.1.0

If you have pg_orbit 0.1.0 installed (satellite-only), upgrade to 0.2.0:

ALTER EXTENSION pg_orbit UPDATE TO '0.2.0';

This adds all solar system functions (planets, moons, stars, comets, radio, Lambert transfers) while preserving your existing TLE data and satellite functions.