pg_exporter copilot-instructions.md

GitHub Copilot Instructions for pg_exporter

Project Overview

This is a PostgreSQL metrics exporter written in Rust. It collects metrics from PostgreSQL and exposes them in Prometheus format. Safety and reliability are paramount - all code must handle edge cases gracefully without panics.

Language & Tooling

• Language: Rust (latest stable)
• Formatting: cargo fmt --all -- --check
• Linting: cargo clippy --all-targets --all-features -- -D warnings
• Testing: just test (runs clippy, fmt, and all tests)
• Build Tool: just command runner (see .justfile)

Critical Safety Rules

1. Always Use try_get() Instead of get()

NEVER use row.get() - it panics on NULL or type mismatches.

// ❌ WRONG - Will panic on NULL
let value: i64 = row.get("column");

// ✅ CORRECT - Safe handling
let value: i64 = row.try_get("column").unwrap_or(0);

2. Always Cast SQL Numeric Columns

PostgreSQL NUMERIC type doesn't directly map to Rust types. Always use explicit casts.

// ❌ WRONG - Type mismatch
SELECT total_time FROM pg_stat_statements

// ✅ CORRECT - Explicit cast
SELECT total_time::double precision FROM pg_stat_statements
SELECT calls::bigint FROM pg_stat_statements

3. Always Check Denominator Before Division

Prevent division by zero in both SQL and Rust.

// ❌ WRONG - Division by zero
let ratio = hits / (hits + misses);

// ✅ CORRECT - Safe division
let total = hits + misses;
let ratio = if total > 0 { hits as f64 / total as f64 } else { 0.0 };

SQL version:

-- ✅ CORRECT
CASE WHEN (shared_blks_hit + shared_blks_read) > 0
     THEN shared_blks_hit::double precision / (shared_blks_hit + shared_blks_read)
     ELSE 0.0
END as cache_hit_ratio

4. Always Check Extension Availability

Handle missing extensions gracefully with fetch_optional().

// ✅ CORRECT - Check extension exists
let result = sqlx::query("SELECT * FROM pg_stat_statements LIMIT 1")
    .fetch_optional(&pool)
    .await?;

if result.is_none() {
    warn!("pg_stat_statements extension not available");
    return Ok(());
}