koushikghosh86/postgres-pgivm repository overview

⁠PostgreSQL with pg_ivm Extension Docker Image

A ready-to-use Docker image of PostgreSQL with the pg_ivm⁠ (Incremental View Maintenance) extension pre-installed.

⁠🌟 Features

• 🐘 PostgreSQL 17 on Alpine Linux 3.22 (minimal footprint)
• 📦 Pre-installed extensions:
  • pg_ivm (v1.11) - Incremental View Maintenance
• 🔒 Security-focused:
  • Regular updates from base PostgreSQL image
  • Minimal attack surface (Alpine Linux)
  • Built with clang-19 and hardened compilation flags
• 🚀 Production-ready:
  • Properly configured shared memory
  • Optimized default PostgreSQL configuration
  • Health checks included

⁠🛠️ Getting Started

⁠Quick Start

docker run -d --name postgres-ivm \
  -e POSTGRES_PASSWORD=yoursecurepassword \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  yourusername/postgres-pgivm:17-alpine3.22

⁠Using Docker Compose

version: '3.8'

services:
  postgres:
    image: yourusername/postgres-pgivm:17-alpine3.22
    environment:
      POSTGRES_PASSWORD: yoursecurepassword
      POSTGRES_USER: customuser
      POSTGRES_DB: mydatabase
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

⁠🧰 Using pg_ivm Extension

After starting your container:

-- Enable the extension
CREATE EXTENSION pg_ivm;

-- Create an incremental materialized view
CREATE INCREMENTAL MATERIALIZED VIEW sales_summary AS
SELECT product_id, SUM(quantity) AS total_quantity, SUM(price) AS total_sales
FROM sales
GROUP BY product_id;

-- The view automatically maintains itself as data changes
INSERT INTO sales VALUES (1, 5, 19.99);
-- View stays updated without manual REFRESH

⁠🏗️ Build Custom Version

To build with different PostgreSQL versions or customize extensions:

git clone https://github.com/yourusername/postgres-pgivm.git
cd postgres-pgivm

# Build with default options
docker build -t custom-postgres-pgivm .

# Build with different PostgreSQL version
docker build --build-arg PG_VERSION=15 -t custom-postgres-pgivm:15 .

⁠🤝 Contributing

We welcome contributions! Here's how you can help:

1. Report bugs - Open an issue with detailed reproduction steps
2. Suggest features - Share your ideas for improvements
3. Submit PRs - Follow these guidelines:
   • Keep changes focused on a single purpose
   • Maintain backward compatibility
   • Include tests and documentation updates
4. Improve documentation - Help make the project more accessible

⁠Development Setup

# 1. Fork and clone the repository
git clone https://github.com/koushikeng/postgres-pgivm.git

# 2. Install pre-commit hooks
pre-commit install

# 3. Build test image
docker build -t test-pgivm .

# 4. Run tests
./test/test_extension.sh

⁠📜 License

PostgreSQL License (same as PostgreSQL itself)

⁠🙏 Acknowledgments

• PostgreSQL Global Development Group
• pg_ivm developers (@sraoss)
• Alpine Linux maintainers

⁠Key Elements for Collaboration

1. Clear Contribution Guidelines:

   • Explicit instructions for reporting bugs, suggesting features, and submitting PRs
   • Development environment setup

2. Project Badges:

   • Docker pulls, license, and issue tracking for transparency

3. Comprehensive Documentation:

   • Multiple usage examples (CLI, Docker Compose)
   • Extension usage samples
   • Custom build instructions

4. Modular Structure:

   • Easy to adapt for different PostgreSQL versions
   • Clear separation of concerns

5. Testing Information:

   • Implicit encouragement for contributors to add tests