Hedef: Tek Komutla Veritabanı Ortamı
Yerel geliştirme ortamında PostgreSQL kurmak çoğu zaman “kuruldu mu, servis başladı mı, port çakıştı mı, kullanıcı yetkileri doğru mu?” gibi küçük ama zaman yiyen sorularla uzar. Üstelik ekip çalışmasında herkesin makinesinde aynı sürüm ve aynı ayarlarla çalışmak daha da zorlaşır. Bu yazıda, Docker Compose ile PostgreSQL’i ve yönetim aracı olarak pgAdmin’i birlikte çalıştıran, tekrar üretilebilir (reproducible) bir kurulum hazırlayacağız. Amaç: projeyi klonlayan herkesin tek komutla aynı veritabanına erişebilmesi.
Konu “ileri seviye” tarafına şu noktada yaklaşıyor: sadece konteyneri çalıştırmakla kalmayacağız; kalıcı veri (volume), başlangıç SQL dosyaları, servis bağımlılıkları ve güvenli sayılabilecek temel ayarlarla pratik bir şablon oluşturacağız. Bu yapı; Node.js, Python, Java, .NET gibi farklı backend’lerle rahatça kullanılabilir.
Ön Koşullar
Bilgisayarınızda Docker ve Docker Compose yüklü olmalı. Güncel Docker Desktop sürümlerinde Compose genellikle hazır gelir. Terminalde docker --version ve docker compose version komutlarıyla kontrol edebilirsiniz.
Proje Yapısını Hazırlama
Proje klasörünüzde aşağıdaki gibi bir yapı işinizi kolaylaştırır. Özellikle init dosyalarını ayrı klasörde tutmak, veritabanını ilk kurulumda otomatik hazırlamak için idealdir.
Önerilen dizinler:
- docker-compose.yml
- db/init/01-schema.sql
- db/init/02-seed.sql
docker-compose.yml Dosyası
Aşağıdaki Compose tanımı PostgreSQL (db) ve pgAdmin (pgadmin) servislerini ayağa kaldırır. PostgreSQL verisi named volume ile kalıcı hale gelir; pgAdmin ayarları da ayrı volume’da tutulur. Ayrıca PostgreSQL’e ilk kurulumda SQL çalıştırmak için ./db/init klasörünü otomatik mount ediyoruz.
docker-compose.yml içeriği:
version satırı artık zorunlu olmasa da okunabilirlik için ekleyebilirsiniz. Örnek YAML:
Not: Aşağıdaki blokları dosyanıza aynen yazın (girintiler YAML için kritiktir).
docker-compose.yml
services:
db:
image: postgres:16
container_name: local_postgres
restart: unless-stopped
environment:
POSTGRES_USER: appuser
POSTGRES_PASSWORD: apppass
POSTGRES_DB: appdb
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
- ./db/init:/docker-entrypoint-initdb.d:ro
healthcheck:
test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
interval: 5s
timeout: 3s
retries: 20
pgadmin:
image: dpage/pgadmin4:latest
container_name: local_pgadmin
restart: unless-stopped
environment:
PGADMIN_DEFAULT_EMAIL: [email protected]
PGADMIN_DEFAULT_PASSWORD: adminpass
ports:
- "5050:80"
volumes:
- pgadmin_data:/var/lib/pgadmin
depends_on:
db:
condition: service_healthy
volumes:
postgres_data:
pgadmin_data:
Başlangıç SQL Dosyaları (Opsiyonel ama Çok Faydalı)
PostgreSQL’in resmi imajı, ilk kez boş bir data dizini oluştururken /docker-entrypoint-initdb.d altındaki .sql dosyalarını otomatik çalıştırır. Bu sayede tablo şemasını ve örnek veriyi sürüm kontrolüne alabilirsiniz. Örnek iki dosya hazırlayalım:
db/init/01-schema.sql
CREATE TABLE IF NOT EXISTS users (
id SERIAL PRIMARY KEY,
email TEXT UNIQUE NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
db/init/02-seed.sql
INSERT INTO users (email) VALUES ('[email protected]')
ON CONFLICT DO NOTHING;
Buradaki önemli detay: init dosyaları sadece veritabanı ilk kez oluşturulurken devreye girer. Eğer volume zaten doluysa ve siz SQL’i değiştirdiyseniz, değişikliğin uygulanması için ya manuel migration çalıştırmanız ya da geliştirme ortamında ilgili volume’u temizleyip yeniden başlatmanız gerekir.
Servisleri Başlatma
Aynı klasörde terminal açın ve şu komutu çalıştırın:
docker compose up -d
Ardından konteynerlerin durumunu görmek için:
docker compose ps
pgAdmin ile Bağlantı Kurma
Tarayıcıdan http://localhost:5050 adresine gidin. Giriş için Compose dosyasındaki PGADMIN_DEFAULT_EMAIL ve PGADMIN_DEFAULT_PASSWORD değerlerini kullanın. Yeni bir server kaydı eklerken:
Host name/address: db
Port: 5432
Maintenance database: appdb
Username: appuser
Password: apppass
Burada “host” olarak db yazmamızın sebebi, Compose ağında servis isimlerinin DNS gibi çalışmasıdır. Yani pgAdmin konteyneri, PostgreSQL’e db:5432 üzerinden erişir.
Sık Karşılaşılan Sorunlar ve İpuçları
Port çakışması: Makinenizde 5432 zaten kullanılıyorsa, “5432:5432” satırını örneğin “5433:5432” yapın. Uygulamanızdan bağlanırken host portunu (5433) kullanırsınız.
Şifreleri dosyaya yazmak: Bu örnek geliştirme içindir. Ekip içinde daha güvenli kullanım için ortam değişkenlerini .env dosyasına taşıyıp Compose’dan çağırabilirsiniz.
Veriyi sıfırlama: Tamamen temiz kurulum için servisleri durdurup volume’ları silin: docker compose down -v. Sonra tekrar docker compose up -d dediğinizde init SQL dosyaları yeniden çalışır.
Sonuç
Docker Compose ile PostgreSQL + pgAdmin kurulumu, hem tek kişilik projelerde hem de ekip çalışmalarında standart bir geliştirme zemini sağlar. En büyük kazanım; “benim makinemde çalışıyor” problemini azaltmanız, versiyon uyumunu korumanız ve veritabanını birkaç komutla yönetebilmenizdir. Bu şablonu temel alıp Redis, MinIO, Kafka gibi servisleri de aynı Compose dosyasına ekleyerek daha kapsamlı bir yerel ortam kurabilirsiniz.
