Operations Database (ops-db)#

✓
Documentation Verified Last checked: 2025-01-21 Reviewer: Christof Buchbender

The ops-db package provides the core PostgreSQL database schema and SQLAlchemy ORM layer for the CCAT Data Center operations database. This is the single source of truth for all operational metadata: from observation planning through execution, data transfer, archival, to final publication.

This documentation covers the DATABASE SCHEMA ONLY - not infrastructure deployment (see CCAT System Integration Documentation) or the REST API layer (see Operations Database API (ops-db-api)) or the web interface (see Operations Database UI (ops-db-ui)). /docs/operations/index explains how all these components work together and are deployed and maintained.

The database serves as the backend for:

  • ops-db-ui - Web interface for browsing observations and monitoring system state

  • ops-db-api - RESTful API for instruments to register observations and data

  • data-transfer - Automated workflows that move data through its lifecycle

What’s in the Database#

The ops-db tracks:

  • Observatory Infrastructure - Observatories, telescopes, instruments, and modules

  • Scientific Programs - Observing programs, sub-programs, and observation units

  • Observation Execution - Executed observation units with timing and conditions

  • Data Files and Packages - Raw data files, packages, and physical copies across locations

  • Transfer Infrastructure - Sites, locations, routes, and transfer records

  • Long-Term Archive - Archive transfers and staging jobs for processing

  • Access Control - Users, roles, and API tokens

  • Future Extensions - Reduction pipelines and workflows, Scientific Data Products, Publications, etc.

For complete details on all models, see the Table Reference and Models API Reference documentation.

Documentation Structure#

Concepts

Understanding the database design and entity relationships

Overview

Schema Reference

Database diagram and auto-generated table documentation

Database Layout

API Reference

Python API for working with the database

Core Database Functions

Configuration

How to configure database connections and settings

Configuration

Integration

How this fits with other CCAT components

Related Components

Operations

Migration workflow and deployment runbook

Database Migrations

Getting Started for Developers#

To use ops-db in your Python code:

  1. Install the package:

    pip install -e /path/to/ops-db

  2. Initialize a database connection:

    from ccat_ops_db import init_ccat_ops_db
session, engine = init_ccat_ops_db()

  3. Use the ORM models:

    from ccat_ops_db.models import ObsUnit, ExecutedObsUnit
obs_unit = session.query(ObsUnit).filter_by(name="my_obs").first()

For detailed function documentation, see the Core Database Functions section.

To set up a fresh database instance, use the opsdb_init command-line tool. See Utilities for details.

Documentation Contents#