pg-api

A high-performance PostgreSQL REST API driver built with Rust, featuring rate limiting, connection pooling, and comprehensive observability.

Features

• High Performance: Built with Rust and Axum for maximum throughput
• Connection Pooling: Efficient database connection management with deadpool-postgres
• Rate Limiting: Configurable per-account rate limits with sliding window algorithm
• Multi-tenancy: Support for multiple accounts with isolated configurations
• Observability: Built-in metrics, tracing, and optional OpenSearch integration
• Security: API token authentication, query timeouts, and audit logging
• License Management: Flexible offline/online license validation system
• Production Ready: SystemD integration, health checks, and graceful shutdown

Installation

From Source

# Clone the repository
git clone https://gitlab.com/alexandre/pg-api.git
cd pg-api

# Build in release mode
cargo build --release

# Run the binary
./target/release/pg-api

Using Cargo

cargo install pg-api

Configuration

The API uses JSON configuration files located in the config/ directory:

Server Configuration (config/server.json)

{
  "host": "127.0.0.1",
  "port": 8580,
  "max_connections": 100,
  "timeout_seconds": 30,
  "log_level": "info"
}

Account Configuration (config/accounts.json)

[
  {
    "id": "acc_example",
    "name": "Example Account",
    "api_token": "sk_live_example_token",
    "database_url": "postgresql://user:pass@localhost/dbname",
    "rate_limit": 100,
    "max_connections": 10,
    "allowed_operations": ["SELECT", "INSERT", "UPDATE", "DELETE"]
  }
]

API Usage

Authentication

All requests require an API token in the Authorization header:

curl -H "Authorization: Bearer sk_live_your_token" \
     https://api.example.com/v1/query

Query Execution

curl -X POST https://api.example.com/v1/query \
  -H "Authorization: Bearer sk_live_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE active = $1",
    "params": [true],
    "database": "main"
  }'

Health Check

curl https://api.example.com/health

Account Information

curl -H "Authorization: Bearer sk_live_your_token" \
     https://api.example.com/v1/account

Development

Prerequisites

• Rust 1.75 or higher
• PostgreSQL 12 or higher
• Optional: OpenSearch for observability

Running Tests

cargo test

Running with Hot Reload

cargo watch -x run

Linting

cargo clippy -- -D warnings

Formatting

cargo fmt --check

Environment Variables

# Application
APP__ADDR=127.0.0.1:8580
APP__LOG_LEVEL=info

# PostgreSQL
PG__MAX_CONNECTIONS=100
PG__POOL_SIZE=25

# License (required for production)
LICENSE_KEY=your_license_key

# OpenSearch (optional)
OPENSEARCH_API_URL=https://opensearch.example.com
OPENSEARCH_API_TOKEN=your_token
OPENSEARCH_ENABLED=true

Architecture

┌─────────────────┐
│   HTTP Client   │
└────────┬────────┘
         │
    ┌────▼────┐
    │  Axum   │
    │ Router  │
    └────┬────┘
         │
┌────────▼────────┐
│  Middleware     │
│  - Auth         │
│  - Rate Limit   │
│  - Metrics      │
└────────┬────────┘
         │
    ┌────▼────┐
    │ Handler │
    └────┬────┘
         │
┌────────▼────────┐
│  Connection     │
│     Pool        │
└────────┬────────┘
         │
    ┌────▼────┐
    │PostgreSQL│
    └─────────┘

Performance

Benchmark Results

Based on testing with standard hardware (8 CPU cores, 16GB RAM):

Key Performance Features

• Sub-millisecond latency for simple queries
• 10,000+ requests/second on modest hardware
• Efficient connection pooling reduces database load
• Rate limiting prevents abuse and ensures fair usage
• Query batching for optimized throughput

Running Benchmarks

# Run performance benchmarks
cargo bench

# Run load tests
python scripts/load_test.py --standalone

See docs/BENCHMARKS.md for detailed performance analysis.

Security

• API token authentication
• Per-query timeout enforcement
• SQL injection prevention through parameterized queries
• Audit logging for all database operations
• TLS/SSL support for encrypted connections

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting merge requests.

License

This project is dual-licensed under MIT OR Apache-2.0. See LICENSE for details.

Support

For issues and feature requests, please use the GitLab issue tracker.

Acknowledgments

• Built with Axum web framework
• Uses deadpool-postgres for connection pooling
• Observability powered by OpenTelemetry