راه‌اندازی PostgreSQL با Docker

در مسیر یادگیری PostgreSQL به‌ویژه در سطح مهندسی داده، داشتن یک محیط ایزوله، تکرارپذیر و قابل حذف اهمیت زیادی دارد.
استفاده از Docker دقیقاً به همین دلیل یکی از بهترین گزینه‌هاست:

• نیازی به نصب مستقیم PostgreSQL روی سیستم نیست.
• می‌توانیم چند نسخه یا چند نود PostgreSQL را هم‌زمان اجرا کنیم.
• به‌سادگی می‌توانیم داده‌ها را در مسیر دلخواه mount کنیم و بعد از پایان کار محیط را پاک کنیم بدون اینکه اثری روی سیستم باقی بماند.

در تمام جلسات آتی دوره (از جمله مباحث Replication, Failover, و HA) از محیط Docker استفاده خواهیم کرد.

---

⚙️ فایل Docker Compose پایه

در این بخش، فایل docker-compose.yml زیر را بررسی می‌کنیم که شامل دو سرویس اصلی است:

1. PostgreSQL
2. pgAdmin4 (ابزار گرافیکی برای مدیریت PostgreSQL)

version: '3.4'
services:
  postgres:
    container_name: postgres
    hostname: postgres
    image: docker.arvancloud.ir/library/postgres:18
    volumes:
      - ./db_data:/var/lib/postgresql
      - ./postgres-init:/docker-entrypoint-initdb.d  # Mounting the init script
      - ./dump:/dump
      - ./space:/space
    environment:
      - POSTGRES_PASSWORD=postgres123
      - POSTGRES_USER=postgres
      - POSTGRES_DB=sepahram
      - POSTGRES_HOST_AUTH_METHOD=trust
    networks:
      - services
    ports:
      - ۵۴۳۴:۵۴۳۲
    restart: always

  pgadmin:
    container_name: pgadmin4
    hostname: pgadmin4
    image: dpage/pgadmin4
    restart: always
    profiles:
      - pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@admin.com
      PGADMIN_DEFAULT_PASSWORD: pgadmin123
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    ports:
      - "۵۰۵۰:۸۰"
    networks:
      - services 

volumes:
  db_data:
  pgadmin_data:

networks: 
  services:
    name: ${APP_NAME:-sepahram}_network

---

🧩 توضیح جزئیات و اجزای فایل

🔹 نسخه و ساختار کلی

version: '3.4'

نسخه‌ی فایل Compose را مشخص می‌کند. نسخه ۳.۴ برای استفاده با Docker Compose مدرن مناسب است.

---

🔹 سرویس PostgreSQL

  postgres:
    container_name: postgres
    hostname: postgres
    image: docker.arvancloud.ir/library/postgres:18

در این بخش:

• نام کانتینر را postgres گذاشتیم.
• از ایمیج رسمی PostgreSQL نسخه‌ی ۱۸ استفاده می‌کنیم (از رجیستری ArvanCloud برای سرعت بیشتر).
• نام میزبان (hostname) نیز postgres تنظیم شده که برای ارتباط سرویس‌های دیگر مفید است.

---

🔹 Volumeها (مسیرهای Mount شده)

    volumes:
      - ./db_data:/var/lib/postgresql
      - ./postgres-init:/docker-entrypoint-initdb.d
      - ./dump:/dump
      - ./space:/space

در این بخش مسیرهایی از سیستم میزبان به کانتینر mount شده‌اند:

• db_data: محل ذخیره داده‌های PostgreSQL (پایدار بین ری‌استارت‌ها).
• postgres-init: پوشه‌ای برای اسکریپت‌های SQL یا Shell که در اولین اجرای کانتینر به‌صورت خودکار اجرا می‌شوند.
• dump: محلی برای نگهداری فایل‌های بک‌آپ و بازیابی داده.
• space: مسیر سفارشی برای تمرین‌های مربوط به tablespace در جلسات بعدی.

---

🔹 متغیرهای محیطی

    environment:
      - POSTGRES_PASSWORD=postgres123
      - POSTGRES_USER=postgres
      - POSTGRES_DB=sepahram
      - POSTGRES_HOST_AUTH_METHOD=trust

پارامترهای مهم راه‌اندازی PostgreSQL:

• نام کاربر پیش‌فرض: postgres
• رمز عبور: postgres123
• دیتابیس پیش‌فرض: sepahram
• حالت احراز هویت: trust (برای محیط توسعه، بدون نیاز به پسورد در اتصال محلی)

---

🔹 پورت و شبکه

    ports:
      - ۵۴۳۴:۵۴۳۲

پورت ۵۴۳۲ داخل کانتینر به پورت ۵۴۳۴ روی سیستم میزبان نگاشت شده است، بنابراین با localhost:5434 می‌توان به PostgreSQL متصل شد.

    networks:
      - services

سرویس به شبکه‌ی اختصاصی services متصل است که ارتباط بین PostgreSQL و pgAdmin را فراهم می‌کند.

---

🔹 سرویس pgAdmin

  pgadmin:
    image: dpage/pgadmin4
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@admin.com
      PGADMIN_DEFAULT_PASSWORD: pgadmin123
    ports:
      - "۵۰۵۰:۸۰"

ابزار گرافیکی مدیریت PostgreSQL که از طریق مرورگر در آدرس http://localhost:5050 در دسترس است.
می‌توان با ایمیل و رمز فوق وارد شد و به سرور PostgreSQL متصل گردید.

---

🔹 Volume و Networkها

volumes:
  db_data:
  pgadmin_data:

این بخش حجم‌های داده را تعریف می‌کند تا اطلاعات بین اجراهای مختلف حذف نشود.

networks: 
  services:
    name: ${APP_NAME:-sepahram}_network

شبکه‌ای خصوصی با نام پویا (بر اساس متغیر محیطی APP_NAME) ایجاد می‌شود که هر دو سرویس در آن قرار دارند.

---

🚀 نحوه اجرا

۱. فایل را با نام docker-compose.yml در پوشه‌ی پروژه ذخیره کنید.
۲. دستور زیر را اجرا کنید:

docker compose up -d

۳. پس از بالا آمدن سرویس‌ها، با اجرای دستور زیر می‌توانید وضعیت را بررسی کنید:

docker ps

۴. برای اتصال به PostgreSQL:

psql -h localhost -p 5434 -U postgres -d sepahram

۵. برای ورود به pgAdmin در مرورگر:

http://localhost:5050

---

🧹 توقف و پاک‌سازی محیط

برای خاموش کردن کانتینرها:

docker compose down

برای حذف داده‌ها و شروع از ابتدا:

docker compose down -v

---

---

اتصال به PostgreSQL در محیط Docker

پس از اجرای کانتینرهای PostgreSQL و pgAdmin با Docker Compose، سه روش اصلی برای اتصال به پایگاه داده وجود دارد:

---

اتصال از طریق pgAdmin

• آدرس ورود به pgAdmin:

http://localhost:5050

• اطلاعات پیش‌فرض ورود:

Email: admin@admin.com  
Password: pgadmin123

• برای ثبت یک سرور جدید در pgAdmin:
  • General: نام دلخواه سرور
  • Connection:
    • Host name/address: postgres
    • Port: ۵۴۳۲
    • Maintenance database: sepahram
    • Username: postgres
    • Password: postgres123

توجه: در محیط Docker، pgAdmin و PostgreSQL در یک شبکه داخلی مشترک قرار دارند، بنابراین باید از hostname کانتینر (postgres) استفاده شود.

---

اتصال با DBeaver یا سایر کلاینت‌های دسکتاپ

• نوع اتصال: PostgreSQL
• اطلاعات اتصال:

Host: localhost
Port: 5434
Database: sepahram
Username: postgres
Password: postgres123

توضیح: پورت داخلی ۵۴۳۲ کانتینر به پورت ۵۴۳۴ سیستم میزبان فوروارد شده است، بنابراین کلاینت‌های خارج از Docker باید به localhost:5434 متصل شوند.

---

اتصال مستقیم با psql از داخل کانتینر

• ورود به شل کانتینر:

docker exec -it postgres bash

• تغییر به کاربر PostgreSQL و اجرای psql:

su - postgres
psql

• دستورات پایه:

\l             -- نمایش لیست دیتابیس‌ها
\c sepahram    -- اتصال به دیتابیس sepahram
\dt            -- نمایش جدول‌ها
select version(); -- نمایش نسخه PostgreSQL

• خروج:

\q
exit

---

جمع‌بندی روش‌ها

روش اتصال	ابزار	آدرس اتصال	پورت	توضیح
pgAdmin	مرورگر وب	postgres (شبکه داخلی Docker)	۵۴۳۲	مدیریت گرافیکی پایگاه داده
DBeaver	سیستم میزبان	localhost	۵۴۳۴	اتصال دسکتاپ برای توسعه و تست
psql	ترمینال داخل کانتینر	داخلی	—	دسترسی مستقیم به محیط PostgreSQL و بررسی متادیتا

---

🎯 نتیجه‌گیری

با این ساختار، ما یک محیط کاملاً ایزوله، امن و قابل توسعه داریم که در ادامه‌ی دوره از آن برای پیاده‌سازی مفاهیم Replication، HA، Tablespace، Template Databases و Performance Tuning استفاده خواهیم کرد.
این محیط به ما اجازه می‌دهد بدون نگرانی از خراب شدن سیستم محلی، به‌صورت آزادانه آزمایش و تمرین کنیم.

---