@sedatdemirAra

pgx v5 ile Postgres: tip güvenli veri erişimi

Go'da Postgres ile çalışırken ilk refleks genellikle bir ORM'e uzanmak oluyor. GORM, Ent gibi araçlar tanıdık geliyor; ama sorguların ürettiği SQL'i kontrol edemediğin, N+1 problemlerini geç fark ettiğin, migration sürprizleriyle karşılaştığın projeler hemen herkesin geçmişinde var. pgx v5 bu denklemi baştan kuruyor: doğrudan SQL yazıyorsun, ama Go'nun tip sisteminden ödün vermiyorsun.

pgx v5 neden farklı

pgx, jackc/pgx deposunda geliştirilen, database/sql arayüzünü destekleyen ama kendi native protokol katmanını kullanan bir Postgres sürücüsü. v5 (Ekim 2022'de yayınlanan major sürüm) birkaç tasarım kararıyla önceki sürümlerden ayrılıyor:

  • pgxpool.Pool artık varsayılan bağlantı yönetimi. pgx.Conn doğrudan kullanımı nadir senaryolara indi.
  • pgx.RowTo* ailesinden generic scan fonksiyonları eklendi. Go 1.18 generics desteği sayesinde reflection'a ihtiyaç kalmadı.
  • pgx.Batch API'si yeniden tasarlandı; tek bir round-trip ile birden fazla sorguyu pipeline olarak gönderebiliyorsun.
  • pgtype paketi tamamen yeniden yazıldı. Postgres'in jsonb, inet, tsrange gibi tiplerini Go tarafında temiz map'liyorsun.

Bağlantı havuzu kurulumu

pgx v5'te connection pool kurmak tek bir çağrı:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5/pgxpool"
)

func main() {
	ctx := context.Background()

	config, err := pgxpool.ParseConfig(os.Getenv("DATABASE_URL"))
	if err != nil {
		panic(err)
	}

	config.MaxConns = 20
	config.MinConns = 4

	pool, err := pgxpool.NewWithConfig(ctx, config)
	if err != nil {
		panic(err)
	}
	defer pool.Close()

	var greeting string
	err = pool.QueryRow(ctx, "SELECT 'merhaba pgx'").Scan(&greeting)
	if err != nil {
		panic(err)
	}
	fmt.Println(greeting)
}

pgxpool.ParseConfig fonksiyonu DATABASE_URL formatını (postgres://user:pass@host:5432/db?sslmode=disable) ayrıştırıyor. MaxConns ve MinConns pool davranışını belirliyor. Production'da MaxConnLifetime ve HealthCheckPeriod değerlerini de ayarlamak gerekiyor; varsayılanlar çoğu durumda yeterli olsa da uzun yaşayan bağlantılarda idle timeout'a dikkat etmekte fayda var.

Generic scan: RowToStructByName

pgx v5 öncesinde her sorgu sonucu için elle Scan(&field1, &field2, ...) yazmak gerekiyordu. Sütun sayısı arttıkça bu yaklaşım hata üretiyor. v5'in generic pgx.RowToStructByName fonksiyonu bu problemi çözüyor:

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/pgxpool"
)

type Article struct {
	ID        int64     `db:"id"`
	Title     string    `db:"title"`
	Body      string    `db:"body"`
	CreatedAt time.Time `db:"created_at"`
}

func GetArticles(ctx context.Context, pool *pgxpool.Pool) ([]Article, error) {
	rows, err := pool.Query(ctx,
		"SELECT id, title, body, created_at FROM articles ORDER BY created_at DESC LIMIT 20")
	if err != nil {
		return nil, err
	}

	articles, err := pgx.CollectRows(rows, pgx.RowToStructByName[Article])
	if err != nil {
		return nil, err
	}

	return articles, nil
}

pgx.CollectRows satırları iterate ediyor ve rows.Close() çağrısını kendi yapıyor. RowToStructByName struct tag'larıyla (db:"column_name") sütunları eşleştiriyor. Sütun adı ile struct field eşleşmezse çalışma zamanında hata dönüyor; bunu test aşamasında yakalamak kolay.

Tek satır okumak için pgx.CollectOneRow var:

func GetArticleByID(ctx context.Context, pool *pgxpool.Pool, id int64) (Article, error) {
	rows, err := pool.Query(ctx,
		"SELECT id, title, body, created_at FROM articles WHERE id = $1", id)
	if err != nil {
		return Article{}, err
	}

	return pgx.CollectOneRow(rows, pgx.RowToStructByName[Article])
}

Satır bulunamazsa pgx.ErrNoRows döner. Bu, database/sql paketindeki sql.ErrNoRows ile aynı semantiği taşıyor.

Batch: tek round-trip, birden fazla sorgu

Birden fazla bağımsız sorguyu ardışık göndermek network latency'sini katlar. pgx'in Batch API'si tüm sorguları tek bir TCP round-trip'te pipeline olarak gönderiyor. Postgres'in extended query protocol'ünü kullanarak bunu yapıyor.

func GetDashboardData(ctx context.Context, pool *pgxpool.Pool, userID int64) (int, int, error) {
	batch := &pgx.Batch{}

	batch.Queue("SELECT count(*) FROM articles WHERE author_id = $1", userID)
	batch.Queue("SELECT count(*) FROM comments WHERE user_id = $1", userID)

	br := pool.SendBatch(ctx, batch)
	defer br.Close()

	var articleCount int
	err := br.QueryRow().Scan(&articleCount)
	if err != nil {
		return 0, 0, err
	}

	var commentCount int
	err = br.QueryRow().Scan(&commentCount)
	if err != nil {
		return 0, 0, err
	}

	return articleCount, commentCount, nil
}

Burada dikkat edilecek nokta: br.QueryRow() çağrılarının sırası, batch.Queue sırasıyla birebir eşleşmeli. Sıra karışırsa yanlış sonuçlar okursun ve derleyici bunu yakalayamaz.

Batch içinde INSERT, UPDATE, DELETE de kullanılabilir. Hatta aynı batch içinde farklı tiplerde sorgular karıştırılabilir:

batch := &pgx.Batch{}
batch.Queue("INSERT INTO audit_log (action, user_id) VALUES ($1, $2)", "login", userID)
batch.Queue("UPDATE users SET last_login = now() WHERE id = $1", userID)

br := pool.SendBatch(ctx, batch)
defer br.Close()

_, err := br.Exec() // INSERT sonucu
if err != nil {
	return err
}
_, err = br.Exec() // UPDATE sonucu
return err

Transaction desenleri

pgx v5'te transaction yönetimi pool.BeginTx ile başlıyor. Ama daha temiz bir desen pgxpool.Pool'un BeginFunc metodu:

func TransferCredits(ctx context.Context, pool *pgxpool.Pool, fromID, toID int64, amount int) error {
	return pgx.BeginTxFunc(ctx, pool, pgx.TxOptions{}, func(tx pgx.Tx) error {
		var balance int
		err := tx.QueryRow(ctx,
			"SELECT balance FROM wallets WHERE user_id = $1 FOR UPDATE", fromID).Scan(&balance)
		if err != nil {
			return err
		}

		if balance < amount {
			return fmt.Errorf("yetersiz bakiye: %d < %d", balance, amount)
		}

		_, err = tx.Exec(ctx,
			"UPDATE wallets SET balance = balance - $1 WHERE user_id = $2", amount, fromID)
		if err != nil {
			return err
		}

		_, err = tx.Exec(ctx,
			"UPDATE wallets SET balance = balance + $1 WHERE user_id = $2", amount, toID)
		return err
	})
}

pgx.BeginTxFunc callback'ten nil dönerse commit, hata dönerse rollback yapıyor. defer tx.Rollback() yazmayı unutma riski yok. Bu desen, Go'nun error handling mekanizmasıyla doğal bir şekilde uyuşuyor.

FOR UPDATE ile satır seviyesinde kilit aldığıma dikkat et. Concurrent transfer senaryosunda bu olmadan race condition kaçınılmaz.

pgtype ile Postgres tiplerini kullanmak

pgx v5'in yeniden yazılan pgtype paketi, Go'nun standart tiplerinin kapsamadığı Postgres tiplerini destekliyor. jsonb bunların başında geliyor:

import "github.com/jackc/pgx/v5/pgtype"

type UserSettings struct {
	Theme    string `json:"theme"`
	Timezone string `json:"timezone"`
}

type User struct {
	ID       int64        `db:"id"`
	Name     string       `db:"name"`
	Settings UserSettings `db:"settings"`
}

pgx, Settings alanını otomatik olarak jsonb sütunundan deserialize ediyor. Struct json.Unmarshal ile uyumlu olduğu sürece ek bir kayıt gerekmez.

Nullable alanlar için pgtype.Text, pgtype.Int8 gibi tipler var:

type Profile struct {
	ID    int64       `db:"id"`
	Bio   pgtype.Text `db:"bio"`
	Age   pgtype.Int4 `db:"age"`
}

// Kullanım:
if profile.Bio.Valid {
	fmt.Println(profile.Bio.String)
}

Bu yaklaşım *string veya sql.NullString kullanmaktan daha tutarlı. pgtype tipleri Valid alanı ile null/not-null durumunu açıkça belirtiyor.

sqlc ile karşılaştırma

sqlc, SQL dosyalarından Go kodu üreten bir code generator. pgx v5 ile birlikte kullanılabiliyor (sqlc'nin emit_json_tags, sql_package: "pgx/v5" ayarlarıyla). İki aracı karşılaştırmak yerine, birlikte kullandığım ve ayrı kullandığım senaryoları paylaşayım.

sqlc iyi çalışıyor: CRUD ağırlıklı sorgular, sütun değişikliklerinin derleme zamanında yakalanması gereken projeler, büyük ekiplerde sorgu tutarlılığı. sqlc bir .sql dosyasından tip güvenli Go fonksiyonları üretiyor. Sorguyu değiştirdiğinde sqlc generate çalıştırıyorsun ve üretilen Go kodu güncelleniyor.

sqlc'nin sınırlarına geldiğim yerler: dinamik WHERE koşulları (filtreleme API'leri), CTE zincirlerinde ara sonuçları manipüle etme, Postgres'e özgü tiplerde (composite type, custom domain) sqlc'nin parser'ının henüz desteklemediği sözdizimi. Bu durumlarda doğrudan pgx ile elle sorgu yazıyorum.

Benim tercihim: projenin %80'inde sqlc ile üretilmiş kodu kullanıp, kalan %20 karmaşık sorguyu doğrudan pgx ile yazmak. İkisi aynı pgxpool.Pool üzerinde çalışıyor, çakışma yok.

Test stratejisi

pgx ile yazdığın data access katmanını test etmek için gerçek bir Postgres instance'ına ihtiyacın var. Mock'lamak anlamsız; SQL sorgusunun doğruluğunu ancak gerçek veritabanı doğrulayabilir.

testcontainers-go ile her test suite'inde taze bir Postgres container'ı ayağa kaldırmak yaygın bir desen:

package repo_test

import (
	"context"
	"testing"

	"github.com/jackc/pgx/v5/pgxpool"
	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/modules/postgres"
)

func setupTestDB(t *testing.T) *pgxpool.Pool {
	t.Helper()
	ctx := context.Background()

	ctr, err := postgres.Run(ctx, "postgres:16-alpine",
		postgres.WithDatabase("testdb"),
		postgres.WithUsername("test"),
		postgres.WithPassword("test"),
	)
	if err != nil {
		t.Fatal(err)
	}
	t.Cleanup(func() { ctr.Terminate(ctx) })

	connStr, err := ctr.ConnectionString(ctx, "sslmode=disable")
	if err != nil {
		t.Fatal(err)
	}

	pool, err := pgxpool.New(ctx, connStr)
	if err != nil {
		t.Fatal(err)
	}
	t.Cleanup(func() { pool.Close() })

	return pool
}

Her test fonksiyonu setupTestDB ile kendi pool'unu alıyor. Transaction içinde test çalıştırıp sonunda rollback yapmak da iyi bir alternatif; container başlatma süresi yerine her test için birkaç milisaniye ödüyorsun.

Performans notları

pgx v5'in native protokolü kullanması database/sql katmanını atlıyor. Bu, her sorgu için bir interface{} slice allocation'ı ve reflection tabanlı scan'i ortadan kaldırıyor. jackc/pgx deposundaki benchmark'lara göre native mod, database/sql uyumluluk moduna kıyasla tekil sorgu başına yaklaşık %15-25 daha az allocation üretiyor.

Prepared statement'lar da farklı çalışıyor. pgx varsayılan olarak her sorguyu otomatik prepare ediyor (Describe + Execute). Bağlantı başına bir statement cache tutuyor. Bu cache pgxpool.Config'de ConnConfig.DefaultQueryExecMode ile kontrol ediliyor. pgx.QueryExecModeSimpleProtocol ile prepare aşamasını atlayabilirsin, ama bu durumda parametre sanitization'ı Postgres tarafında değil istemci tarafında yapılıyor. Production'da varsayılan modu değiştirmek için iyi bir sebep olmalı.

Batch sorgular ise asıl performans farkını yaratan yer. Beş bağımsız sorguyu ardışık göndermek yerine batch ile göndermek, latency'yi 5x round-trip'ten 1x round-trip'e düşürüyor. Bu özellikle cloud ortamlarında, veritabanı ve uygulama arasında 1-2ms network gecikmesi olan durumlarda belirgin bir fark yaratıyor.

Ne zaman pgx, ne zaman ORM

pgx ile doğrudan çalışmak her proje için doğru tercih değil. Hızlı prototipleme yapıyorsan, SQL bilgisi sınırlı bir ekiple çalışıyorsan ya da migration yönetimini de aynı araçtan bekliyorsan Ent veya GORM daha pragmatik olabilir. Ama sorgu performansı üzerinde tam kontrol istiyorsan, Postgres'e özgü özellikleri (advisory lock, listen/notify, logical replication) kullanman gerekiyorsa ya da Go ile in-memory cache katmanı arasına ince bir data access layer koyuyorsan, pgx v5 doğru araç. SQL yazmaktan korkmamak tek ön koşul.