Docker pgAdmin: Docker Compose ile PostgreSQL GUI Nasıl Kurulur

Oturumlar arasında geçiş yapmak, sözdizimini ezberlemek ve yıkıcı bir sorguya yazım hatası yapmadığınızı ummak bir süre sonra yorucu hale gelir. Görsel sorgu planı yoktur, şema tarayıcı yoktur ve bir veritabanını yedeklemenin kolay bir yolu yoktur. İş görür, ancak ideal olmaktan uzaktır.

pgAdmin 4, özel olarak PostgreSQL için geliştirilmiş tarayıcı tabanlı bir GUI ile bunu çözer. Docker’da çalıştırmak ise yerel kurulum gerektirmez. Yapmanız gereken tek şey konteyneri başlatmaktır.

Bu yazıda, PostgreSQL ve pgAdmin 4’ü Docker Compose ile nasıl kuracağınızı, iki konteyneri nasıl bağlayacağınızı ve pgAdmin’in Query Tool’u, şema tarayıcısı ve yedekleme özelliklerini nasıl kullanacağınızı göstereceğim.

Takip edebilmek için makinenizde Docker’ın kurulu ve çalışır durumda olması gerekir. Docker Compose’a yeniyseniz, çok konteynerli geliştirmeyi nasıl basitleştirdiğini anlattığımız rehberimizi okuyun.

pgAdmin 4 Nedir?

pgAdmin 4, PostgreSQL için açık kaynaklı, tarayıcı tabanlı bir yönetim ve geliştirme platformudur. Bir web tarayıcısı üzerinden erişirsiniz; kurmanız gereken masaüstü uygulaması yoktur. Veritabanlarını yönetmek, sorgular çalıştırmak, şemaları incelemek ve yedeklemeleri komut satırına dokunmadan GUI üzerinden yapmak için bir arayüz sunar.

Resmi Docker imajı, pgAdmin geliştirme ekibi tarafından bakımı yapılan dpage/pgadmin4’tür.

pgAdmin 4’ü Docker’da çalıştırmanın yerel kuruluma göre birkaç somut avantajı vardır. Birincisi taşınabilirliktir - tüm veritabanı ortamınız ekip arkadaşlarınızla paylaşabileceğiniz bir docker-compose.yml dosyasında yaşar. İkincisi sürüm çakışması yoktur - pgAdmin kendi konteynerinde, makinenizdeki diğer her şeyden tamamen yalıtılmış şekilde çalışır. İşiniz bittiğinde, docker compose down ile tertemiz silersiniz.

pgAdmin 4 vs. diğer PostgreSQL GUI’leri

Veritabanı yönetimi için GUI araçlarından bolca var. İşte pgAdmin 4’ün iki popüler alternatife kıyasla durumu.

pgAdmin 4 ve popüler alternatifler

DBeaver ve TablePlus iyi araçlardır, ancak hiçbirinin resmi bir Docker imajı yoktur. PostgreSQL örneğiniz zaten Docker’da çalışıyorsa, pgAdmin 4 harika bir uyum sağlar - docker-compose.yml dosyanıza yalnızca bir servis eklemeniz yeterlidir ve her şey aynı ağda birlikte çalışır.

Ortamı Docker Compose ile Kurma

PostgreSQL ve pgAdmin 4’ü birlikte en hızlı çalıştırmanın yolu tek bir docker-compose.yml dosyasıdır. Konuya yeniyseniz, Docker Compose Rehberi temelleri kapsar. Burada pgAdmin’e özgü yapılandırmaya odaklanacağım.

İşte kopyalayıp yapıştırabileceğiniz tam dosya:

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

depends_on alanı, Docker Compose’a pgadmin’dan önce postgres konteynerini başlatmasını söyler. Olmadan, pgAdmin PostgreSQL hazır olmadan başlatılabilir ve bağlanmada başarısız olabilir. Bu, PostgreSQL’in tamamen sağlıklı olmasını beklemez - yalnızca konteynerin başlamasını bekler. Yine de çoğu yarış durumunu önlemeye yeter.

pgAdmin 4 ortam değişkenleri

İki ortam değişkeni zorunludur:

• PGADMIN_DEFAULT_EMAIL - pgAdmin web arayüzüne giriş için kullanacağınız e-posta adresi
• PGADMIN_DEFAULT_PASSWORD - bu hesabın parolası

Üçüncüsü isteğe bağlıdır ama belirtmeniz iyi olur:

• PGADMIN_LISTEN_PORT - pgAdmin’in konteyner içinde dinlediği port. Varsayılanı 80’dir, ancak 5050 olarak ayarlamak port eşlemelerini düzenli tutar.

Bununla birlikte, kimlik bilgilerini Compose dosyasında sabitlemek kötü bir fikirdir, özellikle de dosya sürüm kontrolüne girerse. Bunları bir .env dosyasına taşıyın.

docker-compose.yml ile aynı dizinde bir .env dosyası oluşturun:

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

Ardından değişkenleri Compose dosyanızda referans verin:

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

Docker Compose komutu çalıştırıldığında .env dosyalarını otomatik olarak alır, bu yüzden ekstra yapılandırmaya gerek yoktur. Sadece .env dosyasını .gitignore’a eklemeyi unutmayın; kimlik bilgileriniz depoya girmez.

Volumeler ve veri kalıcılığı

/var/lib/pgadmin’a eşlenen volume, pgAdmin’in oturum verileri, kayıtlı sunucu bağlantıları ve yapılandırma gibi verileri sakladığı yerdir. Bunu compose dosyasından çıkarırsanız, konteyner her yeniden başlatıldığında hepsini kaybedersiniz.

Mevcut compose dosyasında, Docker’ın ana makinenizde yönettiği isimlendirilmiş bir volume bulunur. Veriler, konteyner yeniden başlatmalarında, yeniden oluşturmalarda ve imaj güncellemelerinde kalıcıdır - volume’ü docker volume rm ile açıkça silmediğiniz sürece.

Yığını Başlatma ve pgAdmin 4’e Erişim

docker-compose.yml hazır olduğunda, yığını başlatmak tek bir komuttur:

docker compose up -d

-d bayrağı her iki konteyneri ayrık modda çalıştırır - arka planda başlarlar ve terminaliniz boş kalır. Her iki konteynerin de çalıştığını doğrulamak için:

docker ps

postgres ve pgadmin için Up durumunu görmelisiniz.

Konteyner durumu

Bir şeyler ters görünüyorsa, pgAdmin günlüklerini kontrol edin:

docker logs pgadmin

Sağlıklı bir başlangıç şöyle görünür:

pgAdmin başlangıç günlükleri

Burada bir hata görürseniz, büyük olasılıkla şu üçünden biridir:

• Parola kimlik doğrulaması başarısız: .env dosyasında PGADMIN_DEFAULT_PASSWORD eksik ya da hatalı

• Port zaten ayrılmış: 5050 portunda başka bir şey çalışıyor; Compose dosyanızda ana makine portunu değiştirin

• Böyle bir dosya veya dizin yok: volume yolu yanlış ya da konteynerin oraya yazma izni yok

Her iki konteyner de ayaktayken ve günlükler temiz görünüyorsa, tarayıcınızı açın ve http://localhost:5050 adresine gidin:

pgAdmin giriş sayfası

PGADMIN_DEFAULT_EMAIL ve PGADMIN_DEFAULT_PASSWORD ile belirlediğiniz e-posta ve parola ile giriş yapın. pgAdmin panosuna ineceksiniz; PostgreSQL sunucunuzu kaydetmeye hazırsınız:

pgAdmin ana sayfası

pgAdmin 4’ü PostgreSQL Konteynerinize Bağlama

pgAdmin kenar çubuğunda, Servers - Register - Server’a sağ tıklayın. Doldurmanız gereken iki sekmeli bir diyalog açılır: General ve Connection.

General sekmesi

Sunucunuza anlamlı bir ad verin - local-dev-postgres gibi. Bu yalnızca pgAdmin içindeki bir etikettir, bu nedenle kurulumunuza uygun herhangi bir şeyi seçebilirsiniz.

Sunucu kaydı - General sekmesi

Connection sekmesi

Burada localhost kullanmayın. 

Bir Docker ağının içinde, localhost konteynerin kendisini ifade eder - ana makinenizi ya da PostgreSQL konteynerini değil. Docker’ın kendi dahili DNS’i vardır ve docker-compose.yml dosyanızda tanımlanan servis adlarını kullanarak konteyner adlarını çözümler. Dolayısıyla PostgreSQL servisinize postgres adını verdiyseniz, kullanmanız gereken ana makine adı budur.

Alanları şu şekilde doldurun:

• Host name/address: postgres (docker-compose.yml’deki servis adı)

• Port: 5432

• Maintenance database: Compose dosyanızdaki POSTGRES_DB değeri (ör. mydb)

• Kullanıcı adı: POSTGRES_USER değeri (ör. admin)

• Parola: POSTGRES_PASSWORD değeri

Save’e tıklayın. 

Sunucu kaydı - Connection sekmesi

Her şey doğruysa sunucu kenar çubuğunda görünecek ve genişleterek veritabanlarınızı görüntüleyebileceksiniz:

Başarılı sunucu kaydı

Bu, bağlandığınız anlamına gelir.

Query Tool’u Kullanma

Artık bağlandığınıza göre, pgAdmin 4’ün ve genel olarak Postgres’in temellerini göstereceğim.

Üst menüden Tools - Query Tool’a tıklayarak Query Tool’u açın. Arayüz üç panelden oluşur:

• Editor: SQL yazdığınız yer
• Data Output: sorguyu çalıştırdıktan sonra sonuçların göründüğü yer
• Messages: PostgreSQL’in durum mesajları, hatalar ve yürütme bilgilerini gönderdiği yer

Query tool

SQL yazma ve çalıştırma

Basit bir orders tablosu oluşturalım ve biraz veri ekleyelim. Her bloğu Oynat düğmesine basarak veya kısayol olan F5 ile çalıştırabilirsiniz.

Tabloyu oluşturmak için bunu çalıştırın:

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

Birkaç satır ekleyin:

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

Ve şimdi veriyi sorgulayın:

SELECT * FROM orders;

Veri sorgulama

Sonuçlar, Data Output panelinde tablo olarak görünür. Sütunları sıralayabilir, yeniden boyutlandırabilir ve satırları doğrudan ızgaradan kopyalayabilirsiniz.

Görsel sorgu planını okuma

Bir sorgu çalıştırırken arka planda neler olduğunu görmek için, SELECT ifadenizde EXPLAIN ANALYZE çalıştırın:

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Explain Analyze sonuçları

Data Output paneli ham çıktıyı gösterir. Ancak pgAdmin daha iyi bir seçenek sunar. Araç çubuğundaki Explain düğmesine tıklayın - pgAdmin sorgu planını etkileşimli bir grafik olarak oluşturur.

Grafik olarak sorgu planı

Bu sorgu için basit, ancak tabloları birleştiriyor ya da daha karmaşık veri toplamaları yapıyorsanız çok daha fazla bilgi elde edersiniz.

Bu önemlidir çünkü ham EXPLAIN çıktısını okumak yavaş ve hataya açıktır. Görsel plan, PostgreSQL’in büyük bir tabloda tam tablo taraması yaptığını ya da bir indeks varken kullanılmadığını bariz hale getirir.

Veritabanı Şemanızı Yönetme

pgAdmin’in kenar çubuğu size veritabanı yapınızın tam bir görünümünü sunar - ve GUI üzerinden değiştirmenize olanak tanır.

Kenar çubuğu ağacı şu şekildedir: Servers - sunucu adınız - Databases - veritabanınız - Schemas - public - Tables. Herhangi bir tabloyu genişletin; Columns, Indexes ve Constraints alt düğümler olarak listelenir. Ayrıntıları sağ panelde incelemek için herhangi birine tıklayın.

Tablo oluşturma ve değiştirme

Yeni bir tablo oluşturmak için şemanız altındaki Tables’a sağ tıklayın ve Create - Table’ı seçin. Birkaç sekmeli bir diyalog açılır.

Tablo oluşturma

General sekmesi tablo adını belirlediğiniz yerdir. Sütunlarınızı eklemek için Columns sekmesine geçin - her satırda sütun adı, veri türü, uzunluğu ve boş bırakılabilir olup olmadığı ayarlanır. Constraints sekmesi birincil anahtar, yabancı anahtar ve benzersiz kısıtları ele alır.

Mevcut bir tabloya indeks eklemek için kenar çubuğunda tabloyu genişletin, Indexes’e sağ tıklayın ve Create - Index’i seçin. İndekslenecek sütunları seçin ve indeks türünü belirleyin - btree varsayılandır ve çoğu durumda işe yarar.

İndeks oluşturma

Yedekleme ve geri yükleme

Bir veritabanını yedeklemek için Tools - Backup’a gidin. Bir format seçmeniz gerekir:

• Custom: sıkıştırılmış, ikili format; en esnek seçenektir ve çoğu durumda en iyi tercihtir çünkü içinden tekil tabloları geri yükleyebilirsiniz
• Plain: herhangi bir metin düzenleyicide açıp okuyabileceğiniz düz bir SQL betiği
• Tar: sıkıştırılmamış bir arşiv; daha az yaygındır ancak bazı geri yükleme iş akışları için faydalıdır

Bir format ve hedef yolu seçtikten sonra, pgAdmin arka planda pg_dump çalıştırır ve dosyayı yerel makinenize kaydeder.

Yedek oluşturma

Geri yüklemek için Tools - Restore’a gidin, yedek dosyanızı seçin ve hedef veritabanını belirtin.

Yedekten geri yükleme

Bunun neden kullanışlı olduğunu merak ediyorsanız, geliştirme veritabanınızda yıkıcı bir migrasyonu test ettiğinizi düşünün. Önce bir yedek alın, migrasyonu çalıştırın ve bir şeyler bozulursa, yedeği geri yükleyerek bilinen bir duruma dönün.

Docker’da pgAdmin 4 Çalıştırmak için En İyi Uygulamalar

pgAdmin 4’ü çalıştırmak bir şeydir. Ancak sorunsuz çalışmaya devam etmesini sağlamak için birkaç ekstra şeyi bilmeniz gerekir. İşte bazı pratik ipuçları.

Kimlik bilgilerini Compose dosyanızın dışında tutun

docker-compose.yml dosyanız sürüm kontrolüne girerse - ki genelde girer - sabitlenmiş parolalar da onunla birlikte gider. Kimlik bilgileri için bir .env dosyası kullanın ve .gitignore’a ekleyin. Üretim ortamlarında bir adım daha ileri gidip, hassas değerleri ortam değişkenleri yerine dosyalar olarak bağlayan Docker secrets kullanın.

pgAdmin portunu asla herkese açık şekilde yayınlamayın

Varsayılan olarak Docker portları 0.0.0.0’a bağlar; bu da herkese açık olanlar dahil tüm ağ arayüzleri demektir. Uzak bir sunucuda bu, pgAdmin örneğinizi internetten erişilebilir kılar. Bunun yerine açıkça 127.0.0.1’e bağlayın:

ports:
  - "127.0.0.1:5050:5050"

Bu, pgAdmin’i yalnızca sunucunun kendisinden erişilebilir kılar. Uzak erişime ihtiyacınız varsa bir SSH tüneli veya kimlik doğrulamalı bir ters proxy kullanın.

İmaj etiketlerinizi sabitleyin

dpage/pgadmin4:latest kullanmak, bir sonraki docker compose pull çalıştırıldığında yeni bir sürümü çeker. Bu yeni sürüm farklı davranabilir, yapılandırmanızı bozabilir ya da beklenmedik değişiklikler getirebilir. Her ekip arkadaşının tamamen aynı sürümü çalıştırması için dpage/pgadmin4:9.13 gibi belirli bir etiketi kullanın.

servers.json ile sunucu bağlantılarını önceden yükleyin

Tüm ekibiniz aynı Compose kurulumunu paylaşıyorsa, yığın kalktıktan sonra herkesin PostgreSQL sunucusunu tek tek kaydetmesini beklemeyin. pgAdmin, başlangıçta bağlantıları önceden dolduran bir servers.json dosyasını destekler. Bunu konteynere şu şekilde bağlayın:

volumes:
  - ./servers.json:/pgadmin4/servers.json

Minimal bir servers.json şöyle görünür:

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

Sunucu, pgAdmin başladığında görünecektir - manuel kurulum gerekmez.

Sonuç

Bu yazıda, pgAdmin 4’ü Docker’da sıfırdan kurmayı adım adım gösterdim. PostgreSQL ve pgAdmin 4’ü birlikte ayağa kaldıran bir Docker Compose dosyası yazdınız, iki konteyneri Docker’ın dahili DNS’ini kullanarak bağladınız ve pgAdmin’in çekirdek özelliklerini - Query Tool, şema tarayıcı ve yedekleme/geri yükleme iş akışını - kullandınız.

Buradaki temel ilke tekrarlanabilirliktir. 

Bir docker-compose.yml dosyası, bir servers.json ve bir .env dosyası, bir ekip arkadaşınıza tamamen yapılandırılmış bir veritabanı ortamı teslim etmek için yeterlidir. Bu, “benim makinemde çalışıyor” sorununu bir daha yaşamamanızı sağlar.

Docker ve konteynerleşme konusunda derinleşmek için Intermediate Docker kursumuza göz atın. Çok aşamalı derlemeler, ağ oluşturma ve Compose’a derin dalış hakkında faydalı ipuçlarıyla doludur.