Docker Compose ile PostgreSQL kurulum rehberi

📅 25 Aralık 2025 — Emre Karabulut
⏱️ Yaklaşık 10 dakikalık okuma süresi

Elbette, Docker Compose ile PostgreSQL kurulumuna yönelik, uzman bir sistem yöneticisi bakış açısıyla hazırlanmış teknik blog yazınız aşağıdadır:

***

Docker Compose ile Üretim Ortamına Yakın PostgreSQL Kurulum Rehberi

Modern uygulama geliştirme süreçlerinde veritabanı yönetimi, karmaşık ve zaman alıcı bir görev olabilir. Ancak Docker ve Docker Compose gibi araçlar sayesinde, veritabanı kurulumları ve yönetimleri oldukça basitleştirilmiştir. Bu rehberde, Docker Compose kullanarak hızlı, izole edilmiş ve üretim ortamlarına yakın bir PostgreSQL veritabanı sunucusunu nasıl ayağa kaldıracağınızı adım adım inceleyeceğiz.

Docker Compose, çoklu kapsayıcı (multi-container) Docker uygulamalarını tanımlamak ve çalıştırmak için bir araçtır. Tek bir YAML dosyası ile uygulamanızın tüm servislerini (örneğin, bir web uygulaması, bir API servisi ve bir veritabanı) yapılandırabilir, başlatabilir ve yönetebilirsiniz. Bu, özellikle geliştirme ve test ortamlarında tutarlılık sağlamak için kritik öneme sahiptir.

Neden Docker Compose ile PostgreSQL?

  • İzolasyon: Veritabanı ve uygulamanız diğer sistem bileşenlerinden tamamen izole çalışır.
  • Taşınabilirlik: Aynı Docker Compose dosyası ile farklı ortamlarda (geliştirme, test, üretim) aynı veritabanı yapısını kolayca kurabilirsiniz.
  • Sürüm Yönetimi: Veritabanı sürümünü (örneğin PostgreSQL 16) kolayca belirleyip değiştirebilirsiniz.
  • Hızlı Kurulum ve Kaldırma: Tek komutla tüm veritabanı ortamını kurabilir veya kaldırabilirsiniz.
  • Veri Kalıcılığı: Verilerinizi kapsayıcıdan bağımsız olarak kalıcı depolama alanlarında saklayabilirsiniz.

Ön Gereksinimler

Bu rehberi takip edebilmek için sisteminizde aşağıdaki bileşenlerin kurulu olması gerekmektedir:

  • Docker Desktop: Docker Engine ve Docker Compose bileşenlerini içerir. Linux kullanıcıları için Docker Engine ve Docker Compose eklentisi.
  • Temel komut satırı (terminal) bilgisi.

Proje Yapısı ve Dosyaların Oluşturulması

Öncelikle projeniz için bir ana dizin oluşturalım ve içine gerekli dosyaları yerleştirelim:


mkdir my-pg-app
cd my-pg-app
touch docker-compose.yml .env
mkdir -p init-scripts
touch init-scripts/init.sql

Bu komutlar ile aşağıdaki dizin yapısını oluşturmuş olmalıyız:


my-pg-app/
├── docker-compose.yml
├── .env
└── init-scripts/
    └── init.sql

docker-compose.yml Dosyasının Hazırlanması

Bu dosya, PostgreSQL servisimizi tanımlayacağımız ana konfigürasyon dosyasıdır. Aşağıdaki içeriği docker-compose.yml dosyanıza ekleyin:


version: '3.8' # Docker Compose dosya formatının versiyonu

services:
  db: # Veritabanı servisimizi tanımlıyoruz
    image: postgres:16-alpine # PostgreSQL'in 16. sürümünü Alpine Linux üzerinde kullanıyoruz (daha küçük boyutlu)
    container_name: my_postgres_db # Kapsayıcıya okunabilir bir isim veriyoruz
    restart: unless-stopped # Kapsayıcı durdurulmadıkça veya bir hata nedeniyle çökmedikçe yeniden başlatılmasını sağlar
    environment: # PostgreSQL'in başlangıç ayarları için ortam değişkenleri
      POSTGRES_DB: ${POSTGRES_DB} # Veritabanı adı, .env dosyasından alınacak
      POSTGRES_USER: ${POSTGRES_USER} # Veritabanı kullanıcısı, .env dosyasından alınacak
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} # Veritabanı parolası, .env dosyasından alınacak
    ports:
      - "5432:5432" # Dışarıdan 5432 portundan gelen istekleri kapsayıcının 5432 portuna yönlendir
    volumes:
      - pgdata:/var/lib/postgresql/data # Veritabanı verilerini kalıcı olarak saklamak için named volume kullanıyoruz
      - ./init-scripts:/docker-entrypoint-initdb.d # Başlangıçta çalıştırılacak SQL scriptleri için bind mount
    healthcheck: # Kapsayıcının sağlıklı olup olmadığını kontrol etmek için sağlık kontrolü
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"] # Veritabanının hazır olup olmadığını kontrol eder
      interval: 5s # Her 5 saniyede bir kontrol et
      timeout: 5s # Kontrol için maksimum 5 saniye bekle
      retries: 5 # 5 başarısız denemeden sonra sağlıksız olarak işaretle
      start_period: 10s # Kapsayıcı başlangıcında ilk 10 saniye içinde başarısız olan kontrolleri göz ardı et

volumes:
  pgdata: # pgdata adında bir named volume tanımlıyoruz

Açıklamalar:

  • version: '3.8': Docker Compose dosya formatının sürümünü belirtir.
  • services: Docker Compose uygulamanızın ana bileşenlerini tanımlar.
  • db: PostgreSQL servisimizin adıdır.
  • image: postgres:16-alpine: Kullanılacak Docker imajını belirtir. alpine sürümü daha hafif ve daha güvenli olduğu için tercih edilir.
  • container_name: my_postgres_db: Oluşturulacak kapsayıcıya kolayca erişilebilecek bir isim verir.
  • restart: unless-stopped: Kapsayıcının beklenmedik bir şekilde durması veya sunucu yeniden başlatıldığında otomatik olarak tekrar başlamasını sağlar.
  • environment: PostgreSQL için başlangıç ayarlarını (veritabanı adı, kullanıcı adı, parola) tanımlar. ${VARIABLE_NAME} sözdizimi, bu değerlerin .env dosyasından alınacağını gösterir.
  • ports: - "5432:5432": Host makinesinin 5432 portunu, kapsayıcının 5432 portuna eşler. Böylece host makinesinden PostgreSQL’e erişebilirsiniz.
  • volumes:
    • pgdata:/var/lib/postgresql/data: Bu satır, PostgreSQL’in veri dizinini (/var/lib/postgresql/data) Docker’ın yönettiği pgdata adlı bir named volume’a bağlar. Bu, kapsayıcı silinse bile veritabanı verilerinizin kalıcı olarak saklanmasını sağlar.
    • ./init-scripts:/docker-entrypoint-initdb.d: Bu, yerel init-scripts dizinindeki tüm .sql, .sh veya .sql.gz dosyalarının PostgreSQL kapsayıcısı ilk başlatıldığında otomatik olarak çalıştırılmasını sağlar. Bu sayede veritabanı, tablo veya başlangıç verilerini otomatik olarak oluşturabilirsiniz.
  • healthcheck: Kapsayıcının sadece çalışır durumda olup olmadığını değil, aynı zamanda içindeki servisin (PostgreSQL) de sağlıklı bir şekilde hizmet verip vermediğini kontrol eder.
  • volumes: pgdata:: pgdata adında boş bir named volume tanımlar. Docker, bu volume’u otomatik olarak yönetir.

.env Dosyasının Hazırlanması

Veritabanı kimlik bilgilerinizi ve adını .env dosyasında saklamak, hassas bilgileri docker-compose.yml dosyasından ayırır ve güvenliği artırır. Ayrıca bu, farklı ortamlar için kolayca farklı konfigürasyonlar kullanmanıza olanak tanır.

.env dosyasını aşağıdaki gibi doldurun:


POSTGRES_DB=mydb
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword

Önemli: Üretim ortamlarında güçlü ve karmaşık parolalar kullanmaya özen gösterin!

Veritabanı Başlatma Scripti (init-scripts/init.sql)

PostgreSQL kapsayıcısı ilk kez başlatıldığında, /docker-entrypoint-initdb.d dizinindeki tüm .sql dosyalarını otomatik olarak çalıştırır. Bu özellik sayesinde veritabanınızda başlangıç tabloları oluşturabilir veya örnek veri ekleyebilirsiniz.

init-scripts/init.sql dosyasını aşağıdaki gibi düzenleyin:


CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL
);

INSERT INTO users (name, email) VALUES ('Ali Can', 'ali.can@example.com') ON CONFLICT (email) DO NOTHING;
INSERT INTO users (name, email) VALUES ('Ayşe Yılmaz', 'ayse.yilmaz@example.com') ON CONFLICT (email) DO NOTHING;

Bu script, eğer yoksa users adında bir tablo oluşturacak ve içine iki örnek kullanıcı kaydı ekleyecektir. ON CONFLICT DO NOTHING ifadesi, scriptin birden fazla kez çalıştırılması durumunda aynı veriyi tekrar eklemeyi engeller.

Servisi Başlatma

Tüm dosyalarımızı hazırladığımıza göre, şimdi Docker Compose ile PostgreSQL servisimizi başlatabiliriz. my-pg-app dizini içinde terminali açın ve aşağıdaki komutu çalıştırın:


docker compose up -d
  • docker compose up: docker-compose.yml dosyasında tanımlanan servisleri oluşturur ve başlatır.
  • -d (detached mode): Kapsayıcıları arka planda çalıştırır ve terminalinizi serbest bırakır.

Komutu çalıştırdıktan sonra Docker, PostgreSQL imajını indirip (eğer yerelde yoksa) kapsayıcıyı oluşturacak ve başlatacaktır. İlk başlatmada init.sql scripti de çalışacaktır.

Kurulumu Doğrulama

Servisin doğru bir şekilde çalıştığını doğrulamak için çeşitli kontroller yapabiliriz.

Kapsayıcının Durumunu Kontrol Etme


docker compose ps

Çıktı aşağıdaki gibi olmalı (durumun Up (healthy) olduğuna dikkat edin):


NAME              COMMAND                  SERVICE   STATUS           PORTS
my_postgres_db    "docker-entrypoint.s…"   db        running (healthy)   0.0.0.0:5432->5432/tcp

Kapsayıcı Loglarını Kontrol Etme


docker compose logs db

Bu komut, PostgreSQL kapsayıcısının loglarını gösterecektir. Loglarda database system is ready to accept connections gibi mesajları görmeniz, veritabanının başarıyla başlatıldığını gösterir. Ayrıca init.sql scriptinin başarıyla çalıştığına dair çıktılar da görebilirsiniz.

Veritabanına Bağlanma ve Verileri Kontrol Etme

Şimdi doğrudan veritabanı kapsayıcısının içine girip psql istemcisi ile bağlanarak verilerimizi kontrol edelim:


docker compose exec db psql -U myuser -d mydb
  • docker compose exec db: db servisi kapsayıcısının içinde bir komut çalıştırmamızı sağlar.
  • psql -U myuser -d mydb: myuser kullanıcısı ile mydb veritabanına bağlanır.

Bağlandıktan sonra aşağıdaki komutları çalıştırarak tabloları ve verileri listeleyebilirsiniz:


\dt

Çıktı:


                List of relations
 Schema |  Name   | Type  |  Owner
--------+---------+-------+---------
 public | users   | table | myuser
(1 row)


SELECT * FROM users;

Çıktı:


 id |    name     |        email
----+-------------+---------------------
  1 | Ali Can     | ali.can@example.com
  2 | Ayşe Yılmaz | ayse.yilmaz@example.com
(2 rows)

Verilerin başarıyla eklenmiş olduğunu gördüğünüze göre, \q komutuyla psql istemcisinden çıkış yapabilirsiniz.

Uygulamanızdan Bağlanma (Kısa Bilgi)

Eğer bir uygulama geliştiriyorsanız, uygulamanızı bu PostgreSQL veritabanına aşağıdaki bağlantı bilgileriyle bağlayabilirsiniz:

  • Host: localhost veya 127.0.0.1
  • Port: 5432
  • Database: mydb (veya .env dosyanızdaki POSTGRES_DB değeri)
  • User: myuser (veya .env dosyanızdaki POSTGRES_USER değeri)
  • Password: mypassword (veya .env dosyanızdaki POSTGRES_PASSWORD değeri)

Servisi Durdurma ve Kaldırma

PostgreSQL servisini durdurmak veya tamamen kaldırmak için aşağıdaki komutları kullanabilirsiniz.

Sadece Durdurma

Kapsayıcıyı durdurur ancak verilerini ve diğer kaynaklarını korur:


docker compose stop

Durdurma ve Kaldırma (Verileri Korumak İçin)

Kapsayıcıyı, ağları ve diğer tanımlı kaynakları kaldırır, ancak verilerin saklandığı pgdata volume’u korur:


docker compose down

Durdurma ve Tamamen Kaldırma (Veriler Dahil)

Kapsayıcıyı, ağları ve veri volume’unu (pgdata) da kaldırır. Bu komutu çalıştırdığınızda verileriniz kalıcı olarak silinecektir. Dikkatli kullanın!


docker compose down -v

Sonuç

Bu rehberde, Docker Compose kullanarak güvenilir, taşınabilir ve yönetim kolaylığı sağlayan bir PostgreSQL veritabanı ortamını nasıl kuracağımızı öğrendik. .env dosyası ile ortam değişkenlerini yönetmek, named volume’lar ile veri kalıcılığını sağlamak, init.sql ile başlangıç verilerini yapılandırmak ve sağlık kontrolleri eklemek, üretim ortamlarına yakın bir kurulum için temel ve kritik adımlardır. Artık kendi uygulamalarınız için bu yapıyı rahatlıkla kullanabilir ve geliştirme süreçlerinizi hızlandırabilirsiniz.

***

Emre Karabulut
📊 Bu yazı 7 kez okundu.