Membaca Data
dengan pgx

Pool yang sudah ada, sekarang dipakai membaca katalog

Di chapter sebelumnya kita sudah membuat pgxpool.Pool dan memverifikasinya dengan Ping. Sekarang pool itu mulai bekerja: membaca produk, varian, dan order dari PostgreSQL ke struct Go.

Di React atau Laravel, membaca data sering terasa seperti memanggil satu fungsi yang langsung mengembalikan object. Di Go dengan pgxpool, prosesnya lebih eksplisit dan punya tiga langkah yang jelas: kirim SQL, ambil baris, lalu Scan kolom ke field struct. Tidak ada lapisan sihir di tengah yang menebak relasi atau nama kolom untukmu.

Itu terasa lebih “manual”, tetapi justru di situ kekuatannya. Setiap query yang dieksekusi backend skincare terlihat apa adanya, bisa di-EXPLAIN, bisa di-index, dan bisa dites. Tidak ada query tersembunyi yang muncul karena kamu mengakses sebuah properti relasi tanpa sengaja.

PostgreSQL mendefinisikan SELECT sebagai perintah mengambil baris dari satu atau lebih tabel, dengan filter WHERE, urutan ORDER BY, dan batas LIMIT. Tiga klausa itulah yang akan kita pakai berulang kali untuk endpoint katalog, detail produk, dan riwayat order.

Tiga endpoint inilah target konkret chapter ini. Di akhir modul, repository product punya GetProductByID dan ListProducts, dan repository order punya GetOrderByID yang mengembalikan order beserta seluruh order_items-nya dalam satu struct bersarang, tanpa membombardir database dengan puluhan query kecil.

pgx bukan ORM, dan itu disengaja

pgx bukan ORM. Ia tidak menebak relasi, tidak otomatis meng-hydrate struct, dan tidak menyembunyikan SQL. Kamu menulis SQL, kamu menentukan mapping.

Buat developer yang datang dari Eloquent atau Prisma, ini perubahan cara berpikir yang paling besar di Roadmap 3. Di ORM, satu pemanggilan finder bisa diam-diam menjalankan beberapa query (satu untuk model utama, beberapa lagi untuk relasi yang diakses). Di pgx, satu pemanggilan Query adalah tepat satu round-trip ke database, dan kamu yang menentukan SQL-nya.

Ada tiga primitif pgx yang akan kita pakai sepanjang chapter. Memahami kapan memakai yang mana adalah separuh dari pekerjaan.

Satu resource, satu object

Gunakan pool.QueryRow(ctx, sql, args...) saat endpoint hanya butuh satu resource, misalnya detail produk dari ID.

QueryRow mengembalikan pgx.Row. Yang sering bikin kaget developer baru: error query tidak langsung keluar dari QueryRow, melainkan ditunda sampai Scan dipanggil. Jadi pola error handling-nya selalu berada di sebelah Scan, bukan di sebelah QueryRow.

internal/product/repository.goSalin
func (r *PostgresRepository) GetProductByID(ctx context.Context, id int64) (*Product, error) {
	const query = `
SELECT
	p.id,
	p.brand_id,
	p.slug,
	p.name,
	p.description,
	p.status,
	p.created_at,
	p.updated_at
FROM products p
WHERE p.id = $1
	AND p.deleted_at IS NULL
LIMIT 1
`

	var product Product
	err := r.pool.QueryRow(ctx, query, id).Scan(
		&product.ID,
		&product.BrandID,
		&product.Slug,
		&product.Name,
		&product.Description,
		&product.Status,
		&product.CreatedAt,
		&product.UpdatedAt,
	)
	if err != nil {
		return nil, err
	}

	return &product, nil
}

Perhatikan pemakaian placeholder $1. PostgreSQL dan pgx memakai placeholder posisi $1, $2, $3, bukan ? ala MySQL. Nilai id tidak pernah digabung ke string SQL; ia dikirim terpisah lewat argumen Query, sehingga aman dari SQL injection secara default.

Diagram berikut menunjukkan empat tahap yang terjadi saat satu detail produk dibaca, dari handler sampai database dan kembali lagi.

sequenceDiagram
  participant Handler as HTTP Handler
  participant Service as Product Service
  participant Repo as Product Repository
  participant DB as PostgreSQL
  Handler->>Service: GetProductByID(ctx, id)
  Service->>Repo: GetProductByID(ctx, id)
  Repo->>DB: QueryRow(ctx, SELECT ... WHERE id = $1, id)
  DB-->>Repo: satu row (atau ErrNoRows)
  Repo->>Repo: Scan kolom -> field Product
  Repo-->>Service: *Product atau error
  Service-->>Handler: hasil siap jadi response DTO

Gambar 1. QueryRow cocok untuk jalur detail produk karena hasilnya satu object, bukan list. Error baru terdeteksi saat Scan, bukan saat QueryRow.

ErrNoRows bukan kegagalan database

Saat query satu baris tidak menemukan data, pgx mengembalikan pgx.ErrNoRows dari Scan. Ini sinyal “tidak ada”, bukan sinyal “database rusak”.

Di Laravel, find mengembalikan null, sedangkan findOrFail melempar ModelNotFoundException yang otomatis jadi HTTP 404. Di Go tidak ada otomatisasi itu: kamu memutuskan sendiri bagaimana repository melaporkan “tidak ditemukan”, lalu service menerjemahkannya jadi error domain yang dipahami handler.

Ada dua pola yang sama-sama idiomatik. Pertama, repository mengembalikan (nil, nil) untuk “tidak ada”, lalu service mengubahnya jadi ErrProductNotFound. Kedua, repository langsung mengembalikan error domain. Kita pakai pola pertama agar repository tetap netral terhadap kebijakan HTTP.

internal/product/repository.goSalin
func (r *PostgresRepository) GetProductByID(ctx context.Context, id int64) (*Product, error) {
	var product Product
	err := r.pool.QueryRow(ctx, getProductByIDSQL, id).Scan(
		&product.ID,
		&product.BrandID,
		&product.Slug,
		&product.Name,
		&product.Description,
		&product.Status,
		&product.CreatedAt,
		&product.UpdatedAt,
	)
	if err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			return nil, nil // tidak ditemukan, bukan error database
		}
		return nil, fmt.Errorf("get product by id: %w", err)
	}

	return &product, nil
}

Service menerima (nil, nil) itu lalu memutuskan bahwa “produk tidak ada” adalah kondisi domain yang punya error sendiri. Handler nanti memetakan ErrProductNotFound ke HTTP 404 dengan kode product_not_found, persis seperti yang sudah dirancang di kontrak API Roadmap 2.

internal/product/service.goSalin
var ErrProductNotFound = errors.New("product not found")

type Service struct {
	repo Repository
}

func (s *Service) Detail(ctx context.Context, id int64) (*Product, error) {
	product, err := s.repo.GetProductByID(ctx, id)
	if err != nil {
		return nil, err
	}
	if product == nil {
		return nil, ErrProductNotFound
	}

	return product, nil
}

Lifecycle Rows yang wajib dijaga

Gunakan pool.Query(ctx, sql, args...) untuk daftar produk, riwayat order, review, dan hasil pencarian. Ia mengembalikan pgx.Rows yang punya lifecycle ketat.

Inilah bagian yang paling sering jadi sumber bug awal. pgx.Rows memegang sebuah koneksi dari pool selama belum ditutup. Selama Rows masih terbuka, koneksi itu tidak bisa dikembalikan dan dipakai query lain. Lupa menutupnya, dan saat traffic naik pool terasa “habis” padahal database baik-baik saja.

Pola amannya selalu sama: cek error dari Query dulu, baru defer rows.Close(). Urutan ini penting, karena kalau Query gagal, rows bisa nil dan defer pada nil aman, tetapi cek error duluan membuat alurnya jelas.

internal/product/repository.goSalin
func (r *PostgresRepository) listVariants(ctx context.Context, productID int64) ([]ProductVariant, error) {
	const query = `
SELECT
	pv.id,
	pv.product_id,
	pv.sku,
	pv.variant_name,
	pv.size_label,
	pv.shade,
	pv.price_rupiah,
	pv.compare_at_price_rupiah,
	pv.weight_grams,
	pv.is_active,
	pv.created_at,
	pv.updated_at
FROM product_variants pv
WHERE pv.product_id = $1
	AND pv.is_active = true
ORDER BY pv.price_rupiah ASC
`

	rows, err := r.pool.Query(ctx, query, productID)
	if err != nil {
		return nil, fmt.Errorf("query variants: %w", err)
	}
	defer rows.Close()

	variants := make([]ProductVariant, 0, 4)
	for rows.Next() {
		var v ProductVariant
		if err := rows.Scan(
			&v.ID,
			&v.ProductID,
			&v.SKU,
			&v.VariantName,
			&v.SizeLabel,
			&v.Shade,
			&v.PriceRupiah,
			&v.CompareAtPriceRupiah,
			&v.WeightGrams,
			&v.IsActive,
			&v.CreatedAt,
			&v.UpdatedAt,
		); err != nil {
			return nil, fmt.Errorf("scan variant: %w", err)
		}

		variants = append(variants, v)
	}

	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate variants: %w", err)
	}

	return variants, nil
}

Dua hal di sini wajib jadi refleks. Pertama, defer rows.Close() segera setelah error Query aman. Kedua, rows.Err() setelah loop selesai. Loop for rows.Next() berhenti baik karena baris habis maupun karena error di tengah jalan, dan keduanya membuat Next() mengembalikan false. Hanya rows.Err() yang bisa membedakan keduanya.

Flowchart berikut memperjelas alur loop, termasuk kenapa cek rows.Err() setelah loop adalah cabang yang mudah terlupa tetapi krusial.

flowchart TD
  START["pool.Query(ctx, sql, args)"] --> QERR{"err != nil?"}
  QERR -->|ya| FAIL["return error query"]
  QERR -->|tidak| DEFER["defer rows.Close()"]
  DEFER --> NEXT{"rows.Next() true?"}
  NEXT -->|ya| SCAN["rows.Scan(&dst...)"]
  SCAN --> SERR{"scan error?"}
  SERR -->|ya| FAIL2["return error scan"]
  SERR -->|tidak| APPEND["append ke slice"]
  APPEND --> NEXT
  NEXT -->|tidak| RERR{"rows.Err() != nil?"}
  RERR -->|ya| FAIL3["return error iterasi"]
  RERR -->|tidak| OK["return slice hasil"]

Gambar 2. Loop rows.Next punya tiga gerbang error: error dari Query, error per baris dari Scan, dan error iterasi dari rows.Err. Loop berhenti tanpa keluhan saat error iterasi, jadi rows.Err() adalah satu-satunya cara mengetahuinya.

Apa yang ditampung tiap field Scan

Scan hanya berhasil kalau tipe Go di sisi penerima cocok dengan tipe kolom PostgreSQL. Mengetahui pemetaan ini menghemat banyak waktu debugging.

pgx mengubah representasi biner PostgreSQL menjadi tipe Go yang masuk akal. Sebagian besar pemetaan intuitif (bigint jadi int64, text jadi string), tetapi beberapa punya kejutan, terutama kolom yang bisa NULL dan tipe khas PostgreSQL seperti array dan jsonb yang kita pakai di tabel products.

Untuk kolom array text[] seperti products.skin_types (berisi nilai seperti oily, dry, combination), pgx memetakannya langsung ke []string. Kamu tidak perlu mem-parsing string {oily,dry} secara manual; pgx yang menangani format array PostgreSQL.

internal/product/repository.go (membaca kolom array)Salin
func (r *PostgresRepository) getProductWithArrays(ctx context.Context, id int64) (*Product, error) {
	const query = `
SELECT
	p.id,
	p.slug,
	p.name,
	p.skin_types,
	p.concerns,
	p.status
FROM products p
WHERE p.id = $1 AND p.deleted_at IS NULL
`

	var product Product
	err := r.pool.QueryRow(ctx, query, id).Scan(
		&product.ID,
		&product.Slug,
		&product.Name,
		&product.SkinTypes, // []string menerima text[] langsung
		&product.Concerns,  // []string
		&product.Status,
	)
	if err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			return nil, nil
		}
		return nil, fmt.Errorf("get product with arrays: %w", err)
	}

	return &product, nil
}

Kolom yang boleh kosong butuh penampung yang tahu kosong

Scan NULL ke string atau int64 biasa akan error. Kolom yang bisa NULL butuh penampung yang bisa membedakan “nol” dari “tidak ada nilai”.

Ini perbedaan halus yang penting. Go tidak punya null di tipe nilai biasa: string zero value-nya "", int64 zero value-nya 0. Padahal di database, NULL berbeda dari "" dan dari 0. Kolom product_variants.size_label bisa NULL (varian tanpa label ukuran), dan compare_at_price_rupiah bisa NULL (produk tanpa harga coret).

Ada dua cara idiomatik menampung NULL. Pakai pointer Go (*string, *int64), di mana nil berarti NULL. Atau pakai wrapper pgtype (pgtype.Text, pgtype.Int8) yang membawa flag Valid bool.

Di proyek skincare kita memilih pointer untuk struct domain, karena pointer otomatis jadi null di JSON response, sejalan dengan tag seperti json:"size_label,omitempty".

internal/product/model.goSalin
package product

import "time"

type Product struct {
	ID          int64      `json:"id"`
	BrandID     int64      `json:"brand_id"`
	Slug        string     `json:"slug"`
	Name        string     `json:"name"`
	Description string     `json:"description"`
	SkinTypes   []string   `json:"skin_types"`
	Concerns    []string   `json:"concerns"`
	Status      string     `json:"status"` // draft, active, archived
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	DeletedAt   *time.Time `json:"deleted_at,omitempty"`
}

type ProductVariant struct {
	ID                   int64     `json:"id"`
	ProductID            int64     `json:"product_id"`
	SKU                  string    `json:"sku"`
	VariantName          string    `json:"variant_name"`
	SizeLabel            *string   `json:"size_label,omitempty"`        // text NULL
	Shade                *string   `json:"shade,omitempty"`             // text NULL
	PriceRupiah          int64     `json:"price"`                       // bigint NOT NULL
	CompareAtPriceRupiah *int64    `json:"compare_at_price,omitempty"`  // bigint NULL
	WeightGrams          *int      `json:"weight_grams,omitempty"`      // integer NULL
	IsActive             bool      `json:"is_active"`
	CreatedAt            time.Time `json:"created_at"`
	UpdatedAt            time.Time `json:"updated_at"`
}

Kalau suatu saat kamu lebih suka gaya pgtype (misalnya ingin field Valid eksplisit tanpa dereference pointer), pola Scan-nya seperti ini.

internal/product/repository.go (varian pgtype)Salin
import "github.com/jackc/pgx/v5/pgtype"

func (r *PostgresRepository) variantPrice(ctx context.Context, id int64) (int64, *int64, error) {
	var price int64
	var compareAt pgtype.Int8 // bigint nullable, punya Valid bool

	err := r.pool.QueryRow(ctx,
		`SELECT price_rupiah, compare_at_price_rupiah FROM product_variants WHERE id = $1`,
		id,
	).Scan(&price, &compareAt)
	if err != nil {
		return 0, nil, fmt.Errorf("variant price: %w", err)
	}

	if compareAt.Valid {
		v := compareAt.Int64
		return price, &v, nil
	}
	return price, nil, nil
}

pgx v5 memangkas boilerplate Scan

Menulis Scan positional untuk tiap struct itu eksplisit, tetapi melelahkan untuk struct lebar. pgx v5 punya helper generik yang memetakan baris ke struct by-name lewat tag db.

Sejak pgx v5, ada keluarga fungsi generik yang menggabungkan loop rows.Next + Scan + append menjadi satu pemanggilan. Yang paling sering dipakai adalah pgx.CollectRows (untuk slice) dan pgx.CollectOneRow (untuk satu baris), dikombinasikan dengan pgx.RowToStructByName[T] yang mencocokkan kolom ke field struct lewat tag db:"...".

internal/product/model.go (tambah tag db)Salin
type Product struct {
	ID          int64      `json:"id"          db:"id"`
	BrandID     int64      `json:"brand_id"    db:"brand_id"`
	Slug        string     `json:"slug"        db:"slug"`
	Name        string     `json:"name"        db:"name"`
	Description string     `json:"description" db:"description"`
	Status      string     `json:"status"      db:"status"`
	CreatedAt   time.Time  `json:"created_at"  db:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"  db:"updated_at"`
}

Dengan tag db terpasang, mapping jadi by-name. Urutan kolom SELECT tidak lagi harus sinkron dengan urutan field, asalkan nama kolom hasil query cocok dengan tag db.

internal/product/repository.go (gaya helper)Salin
func (r *PostgresRepository) ListProductsModern(ctx context.Context, limit, offset int32) ([]Product, error) {
	const query = `
SELECT
	p.id,
	p.brand_id,
	p.slug,
	p.name,
	p.description,
	p.status,
	p.created_at,
	p.updated_at
FROM products p
WHERE p.deleted_at IS NULL
	AND p.status = 'active'
ORDER BY p.created_at DESC
LIMIT $1 OFFSET $2
`

	rows, err := r.pool.Query(ctx, query, limit, offset)
	if err != nil {
		return nil, fmt.Errorf("list products: %w", err)
	}

	products, err := pgx.CollectRows(rows, pgx.RowToStructByName[Product])
	if err != nil {
		return nil, fmt.Errorf("collect products: %w", err)
	}

	return products, nil
}

Perhatikan: CollectRows menangani loop, Scan, rows.Err(), dan rows.Close() di dalamnya. Untuk satu baris, pgx.CollectOneRow mengembalikan pgx.ErrNoRows saat kosong, jadi penanganan not-found tetap sama persis.

internal/product/repository.go (satu baris dengan helper)Salin
func (r *PostgresRepository) GetProductByIDModern(ctx context.Context, id int64) (*Product, error) {
	rows, err := r.pool.Query(ctx, getProductByIDSQL, id)
	if err != nil {
		return nil, fmt.Errorf("query product: %w", err)
	}

	product, err := pgx.CollectOneRow(rows, pgx.RowToStructByName[Product])
	if err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			return nil, nil
		}
		return nil, fmt.Errorf("collect product: %w", err)
	}

	return &product, nil
}

Optional filter tanpa membuka celah injection

Katalog butuh filter opsional (slug, kategori) dan pagination. Tantangannya: menyusun SQL dinamis yang tetap memakai placeholder, bukan menggabung nilai user ke string.

Aturan emasnya: yang boleh disusun dinamis adalah potongan SQL tetap (menambah klausa AND c.slug = $N), sedangkan nilai user selalu masuk lewat args. PostgreSQL menerima parameter terpisah dari teks query, jadi nilai user tidak pernah jadi bagian SQL yang dieksekusi.

Karena katalog menampilkan harga mulai dari (starting price) sementara harga ada di tabel product_variants, query list menggabungkan products, brands, dan product_variants, lalu mengambil MIN(price_rupiah) per produk. Kategori dihubungkan lewat join table product_categories (relasi many-to-many).

query-list-products.sqlSalin
SELECT
	p.id,
	p.slug,
	p.name,
	p.description,
	b.name AS brand_name,
	COALESCE(MIN(pv.price_rupiah), 0)::bigint AS starting_price_rupiah,
	p.status,
	p.created_at,
	p.updated_at
FROM products p
JOIN brands b ON b.id = p.brand_id
JOIN product_categories pc ON pc.product_id = p.id
JOIN categories c ON c.id = pc.category_id
LEFT JOIN product_variants pv ON pv.product_id = p.id AND pv.is_active = true
WHERE p.deleted_at IS NULL
	AND p.status = 'active'
	AND c.slug = $1
GROUP BY
	p.id, p.slug, p.name, p.description, b.name, p.status, p.created_at, p.updated_at
ORDER BY p.created_at DESC
LIMIT $2 OFFSET $3;

Pagination di sini memakai LIMIT dan OFFSET, pasangan paling sederhana dan paling mudah dipahami. LIMIT $2 membatasi jumlah baris, OFFSET $3 melompati baris awal. Untuk halaman 1 dengan 20 item, LIMIT 20 OFFSET 0; halaman 2, LIMIT 20 OFFSET 20.

Untuk filter opsional, kita bangun query bertahap. Yang ditambah ke string hanya klausa dengan nomor placeholder; nilainya selalu masuk ke slice args.

internal/product/repository.go (filter dinamis aman)Salin
func buildListProductsQuery(filter ListProductsFilter) (string, []any) {
	var sql strings.Builder
	args := make([]any, 0, 4)

	sql.WriteString(productSelectSQL)
	sql.WriteString("\nWHERE p.deleted_at IS NULL\n\tAND p.status = 'active'\n")

	if filter.Slug != "" {
		args = append(args, filter.Slug)
		fmt.Fprintf(&sql, "\tAND p.slug = $%d\n", len(args))
	}

	if filter.CategorySlug != "" {
		args = append(args, filter.CategorySlug)
		fmt.Fprintf(&sql, "\tAND c.slug = $%d\n", len(args))
	}

	sql.WriteString(productGroupBySQL)
	sql.WriteString("ORDER BY p.created_at DESC\n")

	args = append(args, clampLimit(filter.Limit))
	fmt.Fprintf(&sql, "LIMIT $%d\n", len(args))

	args = append(args, clampOffset(filter.Offset))
	fmt.Fprintf(&sql, "OFFSET $%d\n", len(args))

	return sql.String(), args
}

Satu order, banyak item, tetap dua query saja

Order detail butuh data dari dua tabel: orders (satu baris) dan order_items (banyak baris). Pertanyaannya: bagaimana memuat keduanya tanpa terjebak N+1 query?

Masalah N+1 adalah jebakan klasik yang dibawa banyak orang dari ORM. Pola buruknya: ambil 1 order, lalu untuk setiap item jalankan 1 query terpisah mengambil detail produk. Untuk order berisi 30 item, itu 1 + 30 = 31 query. Untuk halaman riwayat berisi 20 order, ledakannya makin parah.

Pendekatan kita: ambil order dengan 1 QueryRow, lalu ambil semua item-nya dengan 1 Query yang difilter order_id. Dua query, berapa pun jumlah item. Karena order_items sudah menyimpan snapshot (product_name, sku, unit_price_rupiah), kita bahkan tidak perlu join ke products untuk menampilkan order. Snapshot itulah yang membuat invoice lama tidak berubah saat katalog diperbarui.

flowchart LR
  REQ["GET /v1/orders/{id}"] --> Q1["QueryRow orders WHERE id = $1"]
  Q1 --> ORD["Order (1 baris)"]
  ORD --> Q2["Query order_items WHERE order_id = $1"]
  Q2 --> ITEMS["[]OrderItem (N baris, 1 query)"]
  ITEMS --> NEST["Rakit Order.Items = items"]
  NEST --> RESP["Order bersarang -> JSON response"]

Gambar 3. Order detail dimuat dengan dua query saja: satu untuk order, satu untuk semua item-nya. Jumlah item tidak menambah jumlah query, jadi tidak ada N+1.

Struct order bersarang mengikuti skema kanonik: order_items membawa snapshot nama dan harga, unit_price_rupiah adalah harga beku saat checkout, dan line_total_rupiah adalah kolom generated yang kita baca apa adanya.

internal/order/model.goSalin
package order

import "time"

type Order struct {
	ID             int64       `json:"id"`
	UserID         int64       `json:"user_id"`
	OrderNumber    string      `json:"order_number"`
	Status         string      `json:"status"`         // pending, paid, processing, shipped, completed, cancelled, refunded
	PaymentStatus  string      `json:"payment_status"` // unpaid, pending, paid, failed, refunded
	Currency       string      `json:"currency"`
	SubtotalRupiah int64       `json:"subtotal"`
	DiscountRupiah int64       `json:"discount"`
	ShippingRupiah int64       `json:"shipping"`
	TotalRupiah    int64       `json:"total"`
	Items          []OrderItem `json:"items"`
	PlacedAt       time.Time   `json:"placed_at"`
	CreatedAt      time.Time   `json:"created_at"`
}

type OrderItem struct {
	ID                 int64  `json:"id"`
	OrderID            int64  `json:"order_id"`
	VariantID          int64  `json:"variant_id"`
	ProductName        string `json:"name"`          // snapshot saat checkout
	VariantName        string `json:"variant_name"`
	SKU                string `json:"sku"`           // snapshot saat checkout
	UnitPriceRupiah    int64  `json:"price"`         // snapshot saat checkout
	Quantity           int    `json:"quantity"`
	ItemDiscountRupiah int64  `json:"item_discount"`
	LineTotalRupiah    int64  `json:"subtotal"`      // kolom generated
}

Sekarang repository order. GetOrderByID memuat header order, lalu memanggil listOrderItems untuk seluruh item dalam satu query.

internal/order/repository.goSalin
package order

import (
	"context"
	"errors"
	"fmt"

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

type PostgresRepository struct {
	pool *pgxpool.Pool
}

func NewPostgresRepository(pool *pgxpool.Pool) *PostgresRepository {
	return &PostgresRepository{pool: pool}
}

func (r *PostgresRepository) GetOrderByID(ctx context.Context, id int64) (*Order, error) {
	const orderSQL = `
SELECT
	o.id,
	o.user_id,
	o.order_number,
	o.status,
	o.payment_status,
	o.currency,
	o.subtotal_rupiah,
	o.discount_rupiah,
	o.shipping_rupiah,
	o.total_rupiah,
	o.placed_at,
	o.created_at
FROM orders o
WHERE o.id = $1
`

	var ord Order
	err := r.pool.QueryRow(ctx, orderSQL, id).Scan(
		&ord.ID,
		&ord.UserID,
		&ord.OrderNumber,
		&ord.Status,
		&ord.PaymentStatus,
		&ord.Currency,
		&ord.SubtotalRupiah,
		&ord.DiscountRupiah,
		&ord.ShippingRupiah,
		&ord.TotalRupiah,
		&ord.PlacedAt,
		&ord.CreatedAt,
	)
	if err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			return nil, nil
		}
		return nil, fmt.Errorf("get order by id: %w", err)
	}

	items, err := r.listOrderItems(ctx, ord.ID)
	if err != nil {
		return nil, err
	}
	ord.Items = items

	return &ord, nil
}

func (r *PostgresRepository) listOrderItems(ctx context.Context, orderID int64) ([]OrderItem, error) {
	const itemsSQL = `
SELECT
	oi.id,
	oi.order_id,
	oi.variant_id,
	oi.product_name,
	oi.variant_name,
	oi.sku,
	oi.unit_price_rupiah,
	oi.quantity,
	oi.item_discount_rupiah,
	oi.line_total_rupiah
FROM order_items oi
WHERE oi.order_id = $1
ORDER BY oi.id ASC
`

	rows, err := r.pool.Query(ctx, itemsSQL, orderID)
	if err != nil {
		return nil, fmt.Errorf("query order items: %w", err)
	}
	defer rows.Close()

	items := make([]OrderItem, 0, 8)
	for rows.Next() {
		var it OrderItem
		if err := rows.Scan(
			&it.ID,
			&it.OrderID,
			&it.VariantID,
			&it.ProductName,
			&it.VariantName,
			&it.SKU,
			&it.UnitPriceRupiah,
			&it.Quantity,
			&it.ItemDiscountRupiah,
			&it.LineTotalRupiah,
		); err != nil {
			return nil, fmt.Errorf("scan order item: %w", err)
		}

		items = append(items, it)
	}

	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate order items: %w", err)
	}

	return items, nil
}

Kalau kamu perlu memuat banyak order sekaligus (misalnya riwayat 20 order beserta itemnya) tanpa N+1, polanya: ambil 20 order, kumpulkan semua id-nya, lalu satu query WHERE order_id = ANY($1) mengambil semua item dalam sekali jalan, baru kelompokkan item ke order-nya di Go.

internal/order/repository.go (memuat item banyak order tanpa N+1)Salin
func (r *PostgresRepository) itemsByOrderIDs(ctx context.Context, orderIDs []int64) (map[int64][]OrderItem, error) {
	const query = `
SELECT
	oi.order_id,
	oi.id,
	oi.product_name,
	oi.sku,
	oi.unit_price_rupiah,
	oi.quantity,
	oi.line_total_rupiah
FROM order_items oi
WHERE oi.order_id = ANY($1)
ORDER BY oi.order_id, oi.id
`

	rows, err := r.pool.Query(ctx, query, orderIDs)
	if err != nil {
		return nil, fmt.Errorf("query items by order ids: %w", err)
	}
	defer rows.Close()

	grouped := make(map[int64][]OrderItem, len(orderIDs))
	for rows.Next() {
		var it OrderItem
		if err := rows.Scan(
			&it.OrderID,
			&it.ID,
			&it.ProductName,
			&it.SKU,
			&it.UnitPriceRupiah,
			&it.Quantity,
			&it.LineTotalRupiah,
		); err != nil {
			return nil, fmt.Errorf("scan grouped item: %w", err)
		}

		grouped[it.OrderID] = append(grouped[it.OrderID], it)
	}

	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate grouped items: %w", err)
	}

	return grouped, nil
}

Semua potongan dirakit jadi satu file siap pakai

Sekarang kita satukan: model, SQL konstan, scan helper, builder filter, dan dua method publik menjadi satu repository produk yang siap dipakai service layer.

Kita pakai satu interface kecil rowScanner agar fungsi scanListItem bisa menerima baik pgx.Row (dari QueryRow) maupun pgx.Rows (dari Query), karena keduanya punya method Scan. Ini menghemat duplikasi antara jalur satu-baris dan banyak-baris.

internal/product/repository.goSalin
package product

import (
	"context"
	"errors"
	"fmt"
	"strings"

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

type Repository interface {
	GetProductByID(ctx context.Context, id int64) (*Product, error)
	ListProducts(ctx context.Context, filter ListProductsFilter) ([]ProductListItem, error)
}

type PostgresRepository struct {
	pool *pgxpool.Pool
}

func NewPostgresRepository(pool *pgxpool.Pool) *PostgresRepository {
	return &PostgresRepository{pool: pool}
}

type ListProductsFilter struct {
	Slug         string
	CategorySlug string
	Limit        int32
	Offset       int32
}

const productSelectSQL = `
SELECT
	p.id,
	p.slug,
	p.name,
	p.description,
	b.name AS brand_name,
	COALESCE(MIN(pv.price_rupiah), 0)::bigint AS starting_price_rupiah,
	p.status,
	p.created_at,
	p.updated_at
FROM products p
JOIN brands b ON b.id = p.brand_id
LEFT JOIN product_categories pc ON pc.product_id = p.id
LEFT JOIN categories c ON c.id = pc.category_id
LEFT JOIN product_variants pv ON pv.product_id = p.id AND pv.is_active = true
`

const productGroupBySQL = `
GROUP BY
	p.id, p.slug, p.name, p.description, b.name, p.status, p.created_at, p.updated_at
`

type rowScanner interface {
	Scan(dest ...any) error
}

// ProductListItem adalah bentuk baris katalog (produk + brand + harga mulai).
type ProductListItem struct {
	ID                  int64
	Slug                string
	Name                string
	Description         string
	BrandName           string
	StartingPriceRupiah int64
	Status              string
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

func scanListItem(row rowScanner) (ProductListItem, error) {
	var item ProductListItem
	err := row.Scan(
		&item.ID,
		&item.Slug,
		&item.Name,
		&item.Description,
		&item.BrandName,
		&item.StartingPriceRupiah,
		&item.Status,
		&item.CreatedAt,
		&item.UpdatedAt,
	)
	return item, err
}

func (r *PostgresRepository) GetProductByID(ctx context.Context, id int64) (*Product, error) {
	const query = `
SELECT
	p.id,
	p.brand_id,
	p.slug,
	p.name,
	p.description,
	p.skin_types,
	p.concerns,
	p.status,
	p.created_at,
	p.updated_at
FROM products p
WHERE p.id = $1
	AND p.deleted_at IS NULL
LIMIT 1
`

	var product Product
	err := r.pool.QueryRow(ctx, query, id).Scan(
		&product.ID,
		&product.BrandID,
		&product.Slug,
		&product.Name,
		&product.Description,
		&product.SkinTypes,
		&product.Concerns,
		&product.Status,
		&product.CreatedAt,
		&product.UpdatedAt,
	)
	if err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			return nil, nil
		}
		return nil, fmt.Errorf("get product by id: %w", err)
	}

	return &product, nil
}

func (r *PostgresRepository) ListProducts(ctx context.Context, filter ListProductsFilter) ([]ProductListItem, error) {
	query, args := buildListProductsQuery(filter)

	rows, err := r.pool.Query(ctx, query, args...)
	if err != nil {
		return nil, fmt.Errorf("list products: %w", err)
	}
	defer rows.Close()

	items := make([]ProductListItem, 0, int(clampLimit(filter.Limit)))
	for rows.Next() {
		item, err := scanListItem(rows)
		if err != nil {
			return nil, fmt.Errorf("scan product list item: %w", err)
		}

		items = append(items, item)
	}

	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate products: %w", err)
	}

	return items, nil
}

func buildListProductsQuery(filter ListProductsFilter) (string, []any) {
	var sql strings.Builder
	args := make([]any, 0, 4)

	sql.WriteString(productSelectSQL)
	sql.WriteString("WHERE p.deleted_at IS NULL\n\tAND p.status = 'active'\n")

	if filter.Slug != "" {
		args = append(args, filter.Slug)
		fmt.Fprintf(&sql, "\tAND p.slug = $%d\n", len(args))
	}

	if filter.CategorySlug != "" {
		args = append(args, filter.CategorySlug)
		fmt.Fprintf(&sql, "\tAND c.slug = $%d\n", len(args))
	}

	sql.WriteString(productGroupBySQL)
	sql.WriteString("ORDER BY p.created_at DESC\n")

	args = append(args, clampLimit(filter.Limit))
	fmt.Fprintf(&sql, "LIMIT $%d\n", len(args))

	args = append(args, clampOffset(filter.Offset))
	fmt.Fprintf(&sql, "OFFSET $%d\n", len(args))

	return sql.String(), args
}

func clampLimit(limit int32) int32 {
	switch {
	case limit <= 0:
		return 20
	case limit > 100:
		return 100
	default:
		return limit
	}
}

func clampOffset(offset int32) int32 {
	if offset < 0 {
		return 0
	}
	return offset
}

Sambungkan repository ke pool dari chapter sebelumnya

Latihan ini menyambungkan repository ke pgxpool.Pool yang sudah kamu buat di chapter koneksi pgx, lalu menjalankan query pertama dari sebuah command kecil.

cmd/api/main.goSalin
package main

import (
	"context"
	"log"
	"os"

	"github.com/kamu/skincare-backend/internal/database"
	"github.com/kamu/skincare-backend/internal/product"
)

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

	pool, err := database.NewPostgresPool(ctx, os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatalf("connect database: %v", err)
	}
	defer pool.Close()

	repo := product.NewPostgresRepository(pool)

	// Smoke test 1: detail produk by ID.
	p, err := repo.GetProductByID(ctx, 1)
	if err != nil {
		log.Fatalf("get product: %v", err)
	}
	if p == nil {
		log.Println("produk id=1 tidak ditemukan")
	} else {
		log.Printf("produk: %s (%s), status=%s", p.Name, p.Slug, p.Status)
	}

	// Smoke test 2: katalog dengan filter kategori dan pagination.
	items, err := repo.ListProducts(ctx, product.ListProductsFilter{
		CategorySlug: "serum",
		Limit:        10,
		Offset:       0,
	})
	if err != nil {
		log.Fatalf("list products: %v", err)
	}
	log.Printf("ditemukan %d produk di kategori serum", len(items))
	for _, it := range items {
		log.Printf("- %s | %s | mulai dari Rp%d", it.Name, it.BrandName, it.StartingPriceRupiah)
	}
}

TerminalSalin
export DATABASE_URL="postgres://postgres:postgres@localhost:5432/skincare?sslmode=disable"
go run ./cmd/api
go test ./...

Bug pgx awal jarang soal SQL rumit

Sebagian besar bug awal saat memakai pgx bukan di SQL yang kompleks, melainkan di lifecycle Rows, urutan mapping, dan penanganan NULL. Kenali polanya, dan kamu menghemat berjam-jam.

Sekarang backend skincare bisa membaca data dari PostgreSQL dengan pola repository yang eksplisit, aman, dan testable, dari detail produk sampai order bersarang.

Dengan modul ini, repository product punya GetProductByID untuk halaman detail dan ListProducts untuk katalog, sementara repository order punya GetOrderByID yang mengembalikan order beserta seluruh item-nya. Snapshot di order_items (product_name, sku, unit_price_rupiah) memastikan invoice lama tetap stabil walau katalog berubah.