EZ-Homelab/docs/service-docs/postgresql.md

PostgreSQL - Database Services

Table of Contents

• Overview
• What is PostgreSQL?
• Why Use PostgreSQL?
• Configuration in AI-Homelab
• Official Resources
• Database Instances

Overview

Category: Relational Database
Docker Image: postgres
Default Stack: development.yml
Ports: 5432 (internal)

What is PostgreSQL?

PostgreSQL is an advanced open-source relational database. It's more feature-rich than MySQL/MariaDB, with better support for complex queries, JSON, full-text search, and extensions. Many consider it the best open-source database.

Key Features

• ACID Compliant: Reliable transactions
• JSON Support: Native JSON/JSONB
• Extensions: PostGIS, pg_trgm, etc.
• Full-Text Search: Built-in FTS
• Complex Queries: Advanced SQL
• Replication: Streaming replication
• Performance: Excellent for complex queries
• Free & Open Source: PostgreSQL license

Why Use PostgreSQL?

1. Feature-Rich: More features than MySQL
2. Standards Compliant: SQL standard
3. JSON Support: Native JSON queries
4. Extensions: Powerful ecosystem
5. Reliability: ACID compliant
6. Performance: Great for complex queries
7. Community: Strong development

Configuration in AI-Homelab

AI-Homelab uses separate PostgreSQL instances for different applications.

Official Resources

• Website: https://www.postgresql.org
• Documentation: https://www.postgresql.org/docs
• Docker Hub: https://hub.docker.com/_/postgres

Database Instances

GitLab Database (gitlab-postgres)

gitlab-postgres:
  image: postgres:14
  container_name: gitlab-postgres
  restart: unless-stopped
  networks:
    - traefik-network
  environment:
    - POSTGRES_DB=gitlabhq_production
    - POSTGRES_USER=gitlab
    - POSTGRES_PASSWORD=${GITLAB_DB_PASSWORD}
  volumes:
    - /opt/stacks/development/gitlab-postgres/data:/var/lib/postgresql/data

Purpose: GitLab platform database
Location: /opt/stacks/development/gitlab-postgres/data

Development Database (postgres)

postgres:
  image: postgres:latest
  container_name: postgres
  restart: unless-stopped
  networks:
    - traefik-network
  ports:
    - "5432:5432"
  environment:
    - POSTGRES_USER=admin
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    - POSTGRES_DB=postgres
  volumes:
    - /opt/stacks/development/postgres/data:/var/lib/postgresql/data

Purpose: General development database
Location: /opt/stacks/development/postgres/data

Management

Access Database

# Connect to PostgreSQL
docker exec -it postgres psql -U admin -d postgres

# Or specific database
docker exec -it postgres psql -U admin -d dbname

Common Commands

-- List databases
\l

-- Connect to database
\c database_name

-- List tables
\dt

-- Describe table
\d table_name

-- List users
\du

-- Quit
\q

Backup Database

# Backup single database
docker exec postgres pg_dump -U admin dbname > backup.sql

# Backup all databases
docker exec postgres pg_dumpall -U admin > all_dbs_backup.sql

# Restore database
docker exec -i postgres psql -U admin -d dbname < backup.sql

Create Database/User

-- Create database
CREATE DATABASE myapp;

-- Create user
CREATE USER myuser WITH PASSWORD 'password';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE myapp TO myuser;

Summary

PostgreSQL provides advanced database services for:

• GitLab (if using PostgreSQL backend)
• Development applications
• Applications needing JSON support
• Complex query requirements
• Extensions like PostGIS

Key Points:

• More advanced than MySQL
• Native JSON support
• Powerful extensions
• ACID compliance
• Excellent performance
• Standards compliant
• Free and open-source

Remember:

• Use strong passwords
• Regular backups critical
• Monitor disk space
• VACUUM periodically
• Use pgAdmin for GUI management
• Test backups work
• Separate containers for isolation

PostgreSQL powers your advanced applications!