docker.recipes

Gin + PostgreSQL

intermediate

High-performance Go HTTP web framework with PostgreSQL.

Overview

Gin is a high-performance HTTP web framework written in Go, designed for speed and minimal memory footprint. Built around a radix tree-based router, Gin achieves exceptional routing performance while maintaining a clean, minimalist API that developers love for building REST APIs, microservices, and web applications. The framework's middleware architecture and JSON binding capabilities make it particularly suited for modern API development where performance matters. This stack combines Gin's lightning-fast HTTP handling with PostgreSQL's robust relational database capabilities, creating a powerful foundation for data-driven applications. The Gin framework excels at handling high-concurrency HTTP requests while PostgreSQL provides ACID-compliant transactions, complex query capabilities, and reliable data persistence. This pairing is particularly effective because Go's excellent database/sql package and libraries like GORM provide smooth integration between Gin's HTTP layer and PostgreSQL's data layer. Development teams building API-first applications, SaaS platforms, or high-performance web services will find this combination valuable for its balance of simplicity and capability. Startups appreciate Gin's rapid development cycle and PostgreSQL's ability to handle complex data relationships as they scale, while enterprise teams benefit from PostgreSQL's proven reliability and Gin's excellent performance characteristics under load.

Key Features

  • Radix tree-based HTTP router delivering 40x faster routing than traditional multiplexers
  • Zero-allocation router with custom memory pool for minimal garbage collection overhead
  • Rich middleware ecosystem including recovery, logging, CORS, and authentication handlers
  • Built-in JSON, XML, and form data binding with validation using struct tags
  • PostgreSQL's JSONB support for hybrid relational-document data modeling
  • ACID-compliant transactions with advanced isolation levels for data consistency
  • PostgreSQL's full-text search capabilities with ranking and highlighting
  • Hot-reload development workflow with Air or similar Go tools

Common Use Cases

  • 1REST API backends for React, Vue, or Angular single-page applications
  • 2High-throughput microservices requiring sub-millisecond response times
  • 3E-commerce platforms needing complex product catalogs with PostgreSQL's advanced querying
  • 4Financial applications requiring ACID transactions and audit trails
  • 5Content management systems leveraging PostgreSQL's full-text search capabilities
  • 6Real-time analytics dashboards with PostgreSQL's window functions and aggregations
  • 7Multi-tenant SaaS applications using PostgreSQL's row-level security features

Prerequisites

  • Go 1.19+ installed for local development and custom application builds
  • Docker Engine 20.10+ and Docker Compose v2 for container orchestration
  • Minimum 1.5GB RAM (256MB for PostgreSQL + 512MB for Gin + system overhead)
  • Port 8080 available for Gin HTTP server access
  • Basic understanding of SQL and Go programming fundamentals
  • Familiarity with Go modules and dependency management

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  gin: 
3    build: .
4    container_name: gin
5    environment: 
6      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
7    ports: 
8      - "8080:8080"
9    depends_on: 
10      - postgres
11    networks: 
12      - gin-network
13
14  postgres: 
15    image: postgres:16-alpine
16    environment: 
17      POSTGRES_DB: ${DB_NAME}
18      POSTGRES_USER: ${DB_USER}
19      POSTGRES_PASSWORD: ${DB_PASSWORD}
20    volumes: 
21      - postgres_data:/var/lib/postgresql/data
22    networks: 
23      - gin-network
24
25volumes: 
26  postgres_data: 
27
28networks: 
29  gin-network: 
30    driver: bridge

.env Template

.env
1DB_NAME=gin
2DB_USER=gin
3DB_PASSWORD=changeme

Usage Notes

  1. 1Docs: https://gin-gonic.com/docs/
  2. 2Access at http://localhost:8080
  3. 3High-performance HTTP router (radix tree)
  4. 4Rich middleware ecosystem
  5. 5Use GORM or sqlx for database access
  6. 6Multi-stage Dockerfile: go build + scratch/alpine

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

gin
gin:
  build: .
  container_name: gin
  environment:
    DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
  ports:
    - "8080:8080"
  depends_on:
    - postgres
  networks:
    - gin-network
postgres
postgres:
  image: postgres:16-alpine
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - gin-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  gin:
5    build: .
6    container_name: gin
7    environment:
8      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
9    ports:
10      - "8080:8080"
11    depends_on:
12      - postgres
13    networks:
14      - gin-network
15
16  postgres:
17    image: postgres:16-alpine
18    environment:
19      POSTGRES_DB: ${DB_NAME}
20      POSTGRES_USER: ${DB_USER}
21      POSTGRES_PASSWORD: ${DB_PASSWORD}
22    volumes:
23      - postgres_data:/var/lib/postgresql/data
24    networks:
25      - gin-network
26
27volumes:
28  postgres_data:
29
30networks:
31  gin-network:
32    driver: bridge
33EOF
34
35# 2. Create the .env file
36cat > .env << 'EOF'
37DB_NAME=gin
38DB_USER=gin
39DB_PASSWORD=changeme
40EOF
41
42# 3. Start the services
43docker compose up -d
44
45# 4. View logs
46docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/gin-postgres/run | bash

Troubleshooting

  • connection refused on postgres:5432: Ensure depends_on is configured and PostgreSQL container is healthy before Gin starts
  • Gin panic on invalid JSON binding: Implement proper error handling middleware to catch binding errors and return appropriate HTTP status codes
  • PostgreSQL connection pool exhausted: Configure GORM or database/sql MaxOpenConns and MaxIdleConns based on expected concurrent users
  • slow query performance: Enable PostgreSQL query logging and use EXPLAIN ANALYZE to identify missing indexes on frequently queried columns
  • Gin middleware not executing: Verify middleware registration order as Gin executes middleware in the sequence they are registered
  • PostgreSQL data not persisting: Check that postgres_data volume is properly mounted and PostgreSQL has write permissions to /var/lib/postgresql/data

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

ginpostgres

Tags

#gin#go#postgres#performance

Category

Full Web Stacks

Related Recipes

Ad Space