Menulis Data dengan pgx
INSERT, UPDATE, DELETE yang Eksplisit

Di backend e-commerce, write query adalah titik perubahan fakta bisnis.

Write query bukan sekadar menyimpan data, melainkan mengubah fakta bisnis: isi cart, jumlah stok varian, harga jual, status order, dan visibilitas produk di katalog.

Di chapter sebelumnya repository hanya membaca: SELECT produk, Scan ke struct, balas ke handler. Sekarang kita masuk sisi yang lebih berbahaya. Sebuah SELECT yang salah hanya menampilkan data yang keliru, tetapi sebuah UPDATE yang salah bisa menjual stok yang tidak ada, atau menghapus produk yang masih dirujuk ribuan invoice.

Di Laravel, kamu mungkin terbiasa menulis $product->update([...]), $cart->items()->create([...]), atau soft delete lewat trait SoftDeletes yang terasa otomatis. Di Go dengan pgx, kita menulis SQL secara langsung supaya kontrak ke database terlihat jelas: kolom mana yang berubah, kondisi mana yang wajib terpenuhi sebelum baris boleh berubah, dan apa yang dikembalikan PostgreSQL setelahnya.

Dalam proyek online shop skincare, write query dipakai untuk skenario nyata berikut. Endpoint-nya sudah kita rancang di capstone Roadmap 2, sekarang kita beri storage sungguhan.

PostgreSQL menyediakan klausa RETURNING untuk mengambil nilai dari baris yang baru dibuat atau diubah, termasuk id yang dibangkitkan database dan created_at yang dihitung now(). Di sisi Go, pgxpool.Pool (yang dibuat di chapter koneksi) menyediakan Exec untuk query yang tidak mengembalikan row dan QueryRow untuk query yang mengembalikan satu row. Dua method itu adalah seluruh fondasi chapter ini.

Pilih method berdasarkan apakah SQL mengembalikan baris atau tidak.

Aturan praktisnya cuma satu kalimat: pakai Exec ketika tidak butuh baris balik, pakai QueryRow ketika SQL memakai RETURNING.

pool.Exec(ctx, sql, args...) menjalankan SQL dan mengembalikan sebuah pgconn.CommandTag. Dari CommandTag kita bisa membaca berapa baris yang benar-benar terdampak lewat RowsAffected(). Ini pilihan tepat untuk UPDATE dan DELETE yang hasilnya cukup “berhasil atau tidak”.

internal/inventory/repository.goSalin
commandTag, err := r.pool.Exec(ctx, `
	UPDATE inventories
	SET quantity_available = quantity_available - $2,
	    updated_at = now()
	WHERE variant_id = $1
	  AND quantity_available >= $2
`, variantID, qty)
if err != nil {
	return fmt.Errorf("decrease stock: %w", err)
}

if commandTag.RowsAffected() == 0 {
	return ErrInsufficientStock
}

pool.QueryRow(ctx, sql, args...) menjalankan SQL yang diharapkan menghasilkan maksimal satu baris, lalu mengembalikan sebuah pgx.Row. Satu hal yang sering mengejutkan pendatang dari ORM: error dari query muncul saat Scan, bukan saat QueryRow dipanggil. QueryRow sendiri tidak pernah mengembalikan error.

internal/cart/repository.goSalin
var item CartItem
err := r.pool.QueryRow(ctx, `
	INSERT INTO cart_items (cart_id, variant_id, quantity)
	VALUES ($1, $2, $3)
	RETURNING id, created_at, updated_at
`, cartID, variantID, qty).Scan(&item.ID, &item.CreatedAt, &item.UpdatedAt)
if err != nil {
	return nil, fmt.Errorf("create cart item: %w", err)
}

Database yang membuat ID, Go yang menerima hasilnya dalam satu round trip.

Saat membuat baris baru, biarkan PostgreSQL membangkitkan id dan created_at, lalu ambil nilainya dengan RETURNING. Go tidak perlu menebak ID berikutnya.

Tabel cart_items di skema kanonik memakai id bigint GENERATED ALWAYS AS IDENTITY (pengganti modern untuk serial), plus timestamp ber-default now(). Aplikasi cukup mengirim data yang ia tahu (cart, varian, quantity), dan biarkan database mengisi sisanya.

migrations/000004_create_cart.up.sqlSalin
CREATE TABLE cart_items (
    id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    cart_id     bigint  NOT NULL REFERENCES carts(id) ON DELETE CASCADE,
    variant_id  bigint  NOT NULL REFERENCES product_variants(id) ON DELETE RESTRICT,
    quantity    integer NOT NULL CHECK (quantity > 0),
    created_at  timestamptz NOT NULL DEFAULT now(),
    updated_at  timestamptz NOT NULL DEFAULT now(),
    UNIQUE (cart_id, variant_id)
);

Method repository-nya menerima context.Context sebagai parameter pertama (idiom Go), memetakan input ke $1, $2, $3, dan membaca kembali kolom yang dibuat database. Perhatikan: cart_items sengaja tidak menyimpan harga, karena harga dibaca segar saat checkout, bukan saat barang masuk cart.

internal/cart/repository.goSalin
package cart

import (
	"context"
	"fmt"
	"time"

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

type Repository struct {
	pool *pgxpool.Pool
}

func NewRepository(pool *pgxpool.Pool) *Repository {
	return &Repository{pool: pool}
}

type CreateItemInput struct {
	CartID    int64
	VariantID int64
	Quantity  int
}

func (r *Repository) CreateItem(ctx context.Context, in CreateItemInput) (*CartItem, error) {
	const q = `
		INSERT INTO cart_items (cart_id, variant_id, quantity)
		VALUES ($1, $2, $3)
		RETURNING id, cart_id, variant_id, quantity, created_at, updated_at
	`

	var item CartItem
	err := r.pool.QueryRow(ctx, q, in.CartID, in.VariantID, in.Quantity).Scan(
		&item.ID,
		&item.CartID,
		&item.VariantID,
		&item.Quantity,
		&item.CreatedAt,
		&item.UpdatedAt,
	)
	if err != nil {
		return nil, fmt.Errorf("create cart item: %w", err)
	}

	return &item, nil
}

type CartItem struct {
	ID        int64     `json:"id"`
	CartID    int64     `json:"cart_id"`
	VariantID int64     `json:"variant_id"`
	Quantity  int       `json:"quantity"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Alur mentalnya satu round trip: insert dan pembacaan hasil terjadi dalam satu perjalanan query, bukan insert dulu lalu SELECT lagi.

sequenceDiagram
  participant H as Handler (chi)
  participant S as Service
  participant R as Repository (pgx)
  participant DB as PostgreSQL
  H->>S: AddItem(ctx, userID, req)
  S->>R: CreateItem(ctx, input)
  R->>DB: INSERT cart_items ... RETURNING id, created_at
  DB-->>R: baris baru (id, timestamps)
  R-->>S: *CartItem terisi penuh
  S-->>H: 201 Created

Gambar 1. INSERT ... RETURNING menggabungkan write dan pembacaan hasil dalam satu round trip, menghemat satu query dibanding pola insert-lalu-select.

PostgreSQL bisa mengembalikan nilai baru dari baris yang diubah.

Untuk operasi update yang perlu memberi tahu client kapan data berubah, gabungkan SET updated_at = now() dengan RETURNING updated_at.

created_at dan updated_at memang punya DEFAULT now(), tetapi default hanya bekerja saat baris dibuat. Untuk UPDATE, PostgreSQL tidak otomatis menyentuh updated_at. Kamu harus menuliskannya sendiri di klausa SET, atau memasang trigger database. Lupa langkah ini adalah salah satu bug paling halus saat pindah dari Eloquent, yang mengisi updated_at di balik layar.

Harga varian disimpan di tabel product_variants dengan kolom price_rupiah bigint. Method update harga mengubah nilai, menyentuh updated_at, lalu mengembalikan timestamp resmi ke service supaya API bisa membalas waktu yang dihasilkan database, bukan jam browser.

internal/product/repository.goSalin
func (r *Repository) UpdateVariantPrice(ctx context.Context, variantID int64, priceRupiah int64) (time.Time, error) {
	const q = `
		UPDATE product_variants
		SET price_rupiah = $2,
		    updated_at   = now()
		WHERE id = $1
		  AND is_active = true
		RETURNING updated_at
	`

	var updatedAt time.Time
	err := r.pool.QueryRow(ctx, q, variantID, priceRupiah).Scan(&updatedAt)
	if errors.Is(err, pgx.ErrNoRows) {
		return time.Time{}, ErrVariantNotFound
	}
	if err != nil {
		return time.Time{}, fmt.Errorf("update variant price: %w", err)
	}

	return updatedAt, nil
}

Perhatikan pola errors.Is(err, pgx.ErrNoRows). Ketika UPDATE ... RETURNING tidak menyentuh satu baris pun (varian tidak ada atau sudah non-aktif), RETURNING tidak menghasilkan baris, dan Scan mengembalikan pgx.ErrNoRows. Itulah cara QueryRow memberi tahu kita bahwa “tidak ada yang berubah”. Repository menerjemahkannya menjadi error domain ErrVariantNotFound agar handler bisa membalas 404.

SQL sukses dieksekusi belum tentu ada baris yang berubah.

RowsAffected() adalah pagar pengaman yang membedakan dua hal yang sering dikira sama: query berhasil dieksekusi, dan data benar-benar berubah.

Contoh paling penting adalah update stok. Query bisa valid secara sintaks, koneksi database sehat, dan tetap nol baris berubah karena stok kurang atau varian tidak ditemukan. Untuk backend e-commerce, eksekusi tanpa error itu bukan sukses bisnis. Inilah jembatan langsung dari kontrak HTTP yang kita rancang di Roadmap 2: nol baris berubah biasanya berarti 404 (resource tidak ada) atau 409 (kondisi bisnis tidak terpenuhi), bukan 200.

flowchart TD
  A["pool.Exec(ctx, UPDATE ...)"] --> B{"err != nil?"}
  B -->|ya| C["500 internal_error<br/>(bungkus dengan %w)"]
  B -->|tidak| D{"RowsAffected() == 0?"}
  D -->|ya| E["404 / 409<br/>kembalikan error domain"]
  D -->|tidak| F["200 / 204<br/>perubahan tersimpan"]

Gambar 2. Dua cabang keputusan setelah Exec: error teknis menuju 500, sedangkan nol baris berubah menuju 404 atau 409 tergantung konteks bisnis.

internal/inventory/repository.goSalin
var ErrInsufficientStock = errors.New("insufficient stock")
var ErrInventoryNotFound = errors.New("inventory not found")

func (r *Repository) DecreaseAvailable(ctx context.Context, variantID int64, qty int) error {
	const q = `
		UPDATE inventories
		SET quantity_available = quantity_available - $2,
		    updated_at = now()
		WHERE variant_id = $1
		  AND quantity_available >= $2
	`

	tag, err := r.pool.Exec(ctx, q, variantID, qty)
	if err != nil {
		return fmt.Errorf("decrease available: %w", err)
	}

	if tag.RowsAffected() == 0 {
		// Bisa karena stok kurang, bisa karena variant_id tidak ada.
		// Bedakan dengan satu SELECT cek keberadaan bila perlu pesan akurat.
		return ErrInsufficientStock
	}

	return nil
}

Tidak semua penghapusan boleh benar-benar menghapus baris.

Untuk katalog e-commerce, soft delete sering lebih aman daripada DELETE FROM products, karena riwayat order tetap membutuhkan produk untuk tetap ada.

Bedakan dua operasi. Hard delete (DELETE) menghapus baris secara fisik, cocok untuk data yang benar-benar boleh hilang (misalnya membersihkan satu cart_items saat user menekan tombol hapus). Soft delete menandai baris sebagai terhapus lewat kolom deleted_at tanpa menghilangkannya, cocok untuk data yang masih dirujuk histori (produk yang pernah dibeli).

flowchart TD
  A["Admin menekan hapus produk"] --> B{"Produk pernah masuk order_items?"}
  B -->|ya / biasanya ya| C["Soft delete:<br/>UPDATE products SET deleted_at = now()"]
  B -->|tidak pernah & memang sampah| D["Hard delete:<br/>DELETE FROM products WHERE id = $1"]
  C --> E["Listing memfilter deleted_at IS NULL"]
  C --> F["order_items lama tetap menyimpan snapshot nama, sku, harga"]
  D --> G["Baris hilang permanen, tidak bisa dipulihkan"]

Gambar 3. Pohon keputusan soft delete vs hard delete. Untuk produk yang punya jejak transaksi, soft delete menyembunyikannya dari katalog tanpa merusak invoice lama.

Soft delete produk hanya menyentuh deleted_at dan updated_at. Karena ini operasi tanpa data balik, Exec plus RowsAffected() sudah pas: nol baris berubah berarti produk sudah terhapus sebelumnya atau memang tidak ada, dan kita balas 404.

internal/product/repository.goSalin
func (r *Repository) SoftDelete(ctx context.Context, productID int64) error {
	const q = `
		UPDATE products
		SET deleted_at = now(),
		    updated_at = now()
		WHERE id = $1
		  AND deleted_at IS NULL
	`

	tag, err := r.pool.Exec(ctx, q, productID)
	if err != nil {
		return fmt.Errorf("soft delete product: %w", err)
	}

	if tag.RowsAffected() == 0 {
		return ErrProductNotFound
	}

	return nil
}

Untuk cart item, hard delete justru tepat. Item cart tidak punya nilai histori; ketika user menghapusnya, ia memang harus hilang. Di sini kita pakai DELETE, dan RowsAffected() membedakan “item dihapus” dari “item tidak ada / bukan milik cart ini”.

internal/cart/repository.goSalin
func (r *Repository) DeleteItem(ctx context.Context, cartID, itemID int64) error {
	const q = `DELETE FROM cart_items WHERE id = $1 AND cart_id = $2`

	tag, err := r.pool.Exec(ctx, q, itemID, cartID)
	if err != nil {
		return fmt.Errorf("delete cart item: %w", err)
	}

	if tag.RowsAffected() == 0 {
		return ErrItemNotFound
	}

	return nil
}

Tambah baru kalau belum ada, jumlahkan kalau sudah ada, dalam satu statement.

Saat customer menambahkan varian yang sudah ada di cart, kita tidak ingin baris duplikat. Kita ingin quantity bertambah. PostgreSQL menyelesaikan ini dengan satu statement INSERT ... ON CONFLICT.

Tabel cart_items punya UNIQUE (cart_id, variant_id). Tanpa upsert, kamu harus SELECT dulu untuk cek apakah item ada, lalu memilih INSERT atau UPDATE. Pola “cek lalu tulis” itu rawan race condition: dua request paralel bisa sama-sama lolos SELECT lalu sama-sama INSERT, dan salah satu gagal karena melanggar unique constraint. ON CONFLICT menutup celah itu karena cek dan tulis terjadi atomik di database.

internal/cart/repository.goSalin
func (r *Repository) UpsertItem(ctx context.Context, in CreateItemInput) (*CartItem, error) {
	const q = `
		INSERT INTO cart_items (cart_id, variant_id, quantity)
		VALUES ($1, $2, $3)
		ON CONFLICT (cart_id, variant_id) DO UPDATE
		SET quantity   = cart_items.quantity + EXCLUDED.quantity,
		    updated_at = now()
		RETURNING id, cart_id, variant_id, quantity, created_at, updated_at
	`

	var item CartItem
	err := r.pool.QueryRow(ctx, q, in.CartID, in.VariantID, in.Quantity).Scan(
		&item.ID,
		&item.CartID,
		&item.VariantID,
		&item.Quantity,
		&item.CreatedAt,
		&item.UpdatedAt,
	)
	if err != nil {
		return nil, fmt.Errorf("upsert cart item: %w", err)
	}

	return &item, nil
}

Dua kata kunci penting di sini. EXCLUDED adalah baris yang tadinya hendak di-INSERT (nilai dari VALUES), jadi EXCLUDED.quantity adalah quantity yang baru dikirim customer. cart_items.quantity adalah nilai yang sudah ada di baris. Jadi cart_items.quantity + EXCLUDED.quantity artinya “jumlah lama ditambah jumlah baru”. Kalau kamu ingin perilaku “ganti, bukan jumlahkan”, cukup tulis SET quantity = EXCLUDED.quantity.

flowchart LR
  A["INSERT cart_items<br/>(cart_id, variant_id, qty)"] --> B{"(cart_id, variant_id)<br/>sudah ada?"}
  B -->|tidak| C["INSERT baris baru<br/>quantity = qty"]
  B -->|ya, konflik| D["DO UPDATE<br/>quantity = lama + EXCLUDED.quantity"]
  C --> E["RETURNING baris final"]
  D --> E

Gambar 4. Satu upsert menggantikan pola “SELECT lalu pilih INSERT atau UPDATE”, sekaligus aman dari race condition karena cek unique terjadi atomik di database.

Ubah hanya field yang dikirim, biarkan sisanya apa adanya.

Endpoint PATCH mengubah sebagian field. Tantangannya: SQL harus mengubah kolom yang dikirim saja, tanpa menimpa kolom lain dengan nilai kosong.

Di Roadmap 2 kita memakai pointer (*string, *int64) di DTO patch agar nil berarti “tidak dikirim”. Sekarang pertanyaannya: bagaimana menerjemahkan itu ke SQL? Ada dua pendekatan bersih, dan keduanya layak kamu kuasai.

Pendekatan A: COALESCE dengan argumen nullable

Trik COALESCE($n, kolom) berarti “pakai $n kalau bukan NULL, kalau NULL pakai nilai kolom yang sekarang”. Kita kirim pointer Go langsung sebagai argumen: pgx memetakan pointer nil menjadi SQL NULL, dan pointer berisi nilai menjadi nilainya. Satu query melayani semua kombinasi field.

internal/product/repository.goSalin
type PatchProductInput struct {
	Name        *string
	Slug        *string
	Description *string
	Status      *string // draft, active, archived
}

func (r *Repository) PatchProduct(ctx context.Context, id int64, in PatchProductInput) (time.Time, error) {
	const q = `
		UPDATE products
		SET name        = COALESCE($2, name),
		    slug        = COALESCE($3, slug),
		    description = COALESCE($4, description),
		    status      = COALESCE($5, status),
		    updated_at  = now()
		WHERE id = $1
		  AND deleted_at IS NULL
		RETURNING updated_at
	`

	var updatedAt time.Time
	err := r.pool.QueryRow(ctx, q, id, in.Name, in.Slug, in.Description, in.Status).Scan(&updatedAt)
	if errors.Is(err, pgx.ErrNoRows) {
		return time.Time{}, ErrProductNotFound
	}
	if err != nil {
		return time.Time{}, fmt.Errorf("patch product: %w", err)
	}

	return updatedAt, nil
}

Pendekatan B: dynamic SET (query builder kecil)

Saat kamu butuh kontrol penuh (termasuk set ke NULL secara sengaja, atau menghindari menulis kolom yang tidak berubah sama sekali), bangun klausa SET secara dinamis dari field yang benar-benar dikirim. Kuncinya: nama kolom berasal dari kode kita sendiri (bukan input user), sedangkan nilai tetap lewat placeholder $n. Itu menjaga keamanan dari SQL injection.

internal/product/repository.goSalin
func (r *Repository) PatchProductDynamic(ctx context.Context, id int64, in PatchProductInput) (time.Time, error) {
	set := make([]string, 0, 5)
	args := make([]any, 0, 6)
	args = append(args, id) // $1 selalu id

	if in.Name != nil {
		args = append(args, *in.Name)
		set = append(set, fmt.Sprintf("name = $%d", len(args)))
	}
	if in.Slug != nil {
		args = append(args, *in.Slug)
		set = append(set, fmt.Sprintf("slug = $%d", len(args)))
	}
	if in.Status != nil {
		args = append(args, *in.Status)
		set = append(set, fmt.Sprintf("status = $%d", len(args)))
	}
	if len(set) == 0 {
		return time.Time{}, ErrNothingToUpdate // tidak ada field dikirim
	}
	set = append(set, "updated_at = now()")

	q := fmt.Sprintf(`
		UPDATE products
		SET %s
		WHERE id = $1 AND deleted_at IS NULL
		RETURNING updated_at
	`, strings.Join(set, ", "))

	var updatedAt time.Time
	err := r.pool.QueryRow(ctx, q, args...).Scan(&updatedAt)
	if errors.Is(err, pgx.ErrNoRows) {
		return time.Time{}, ErrProductNotFound
	}
	if err != nil {
		return time.Time{}, fmt.Errorf("patch product dynamic: %w", err)
	}

	return updatedAt, nil
}

Mencegah dua admin saling menimpa tanpa mengunci baris.

Bayangkan dua admin membuka editor produk yang sama, lalu menyimpan. Tanpa pengaman, simpanan kedua menimpa diam-diam simpanan pertama. Optimistic locking memakai kolom version untuk mendeteksi tabrakan itu.

Ide optimistic concurrency: setiap baris punya kolom version integer. Saat membaca, client menerima versi saat ini. Saat menulis, UPDATE hanya berhasil kalau versi di database masih sama dengan versi yang dibaca tadi, dan setiap update menaikkan version. Kalau ada yang menyalip lebih dulu, versi sudah berubah, WHERE tidak cocok, RowsAffected() jadi nol, dan kita tahu terjadi konflik.

migrations/000009_add_version.up.sqlSalin
ALTER TABLE products
    ADD COLUMN version integer NOT NULL DEFAULT 1;

internal/product/repository.goSalin
var ErrVersionConflict = errors.New("version conflict")

func (r *Repository) UpdateProductOptimistic(ctx context.Context, id int64, expectedVersion int, name string) (int, error) {
	const q = `
		UPDATE products
		SET name       = $3,
		    version    = version + 1,
		    updated_at = now()
		WHERE id = $1
		  AND version = $2
		  AND deleted_at IS NULL
		RETURNING version
	`

	var newVersion int
	err := r.pool.QueryRow(ctx, q, id, expectedVersion, name).Scan(&newVersion)
	if errors.Is(err, pgx.ErrNoRows) {
		// Baris ada tapi versi tidak cocok (atau produk sudah terhapus).
		return 0, ErrVersionConflict
	}
	if err != nil {
		return 0, fmt.Errorf("optimistic update: %w", err)
	}

	return newVersion, nil
}

sequenceDiagram
  participant A as Admin A
  participant B as Admin B
  participant DB as PostgreSQL (version=5)
  A->>DB: GET produk (version=5)
  B->>DB: GET produk (version=5)
  A->>DB: UPDATE ... WHERE version=5
  DB-->>A: OK, version naik ke 6
  B->>DB: UPDATE ... WHERE version=5
  DB-->>B: 0 rows (version sudah 6)
  Note over B: ErrVersionConflict -> 409, minta refresh & ulang

Gambar 5. Optimistic locking. Admin B yang menyalip kalah karena versinya basi; handler membalas 409 dan meminta client memuat ulang data terbaru sebelum menyimpan ulang.

Menyisipkan banyak baris sekaligus tanpa loop satu-satu.

Saat checkout, satu order bisa berisi banyak order_items. Menyisipkannya satu per satu lewat loop berarti puluhan round trip. PostgreSQL dan pgx punya cara lebih cepat.

Ada tiga cara menyisipkan banyak baris, dari yang paling sederhana ke yang paling cepat. Untuk jumlah order item yang realistis (beberapa sampai puluhan baris per order), Batch adalah titik manis: cepat, fleksibel, dan tetap mendukung RETURNING.

Cara 1: multi-row VALUES (jumlah baris kecil dan tetap)

Satu INSERT dengan banyak baris di klausa VALUES. Sederhana, tetapi placeholder-nya ikut bertambah, jadi cocok untuk jumlah baris yang tidak terlalu besar.

contoh multi-row insertSalin
INSERT INTO order_items (order_id, variant_id, product_name, variant_name, sku, unit_price_rupiah, quantity)
VALUES
    ($1, $2, $3, $4, $5, $6, $7),
    ($1, $8, $9, $10, $11, $12, $13)
RETURNING id, line_total_rupiah;

Cara 2: pgx.Batch (banyak statement, satu perjalanan)

pgx.Batch mengantre banyak query lalu mengirimnya dalam satu round trip dengan SendBatch. Tiap item bisa berbeda dan tetap bisa RETURNING. Inilah cara yang akan kita pakai untuk order items.

internal/order/repository.goSalin
type NewOrderItem struct {
	VariantID       int64
	ProductName     string
	VariantName     string
	SKU             string
	UnitPriceRupiah int64
	Quantity        int
}

func (r *Repository) InsertOrderItems(ctx context.Context, orderID int64, items []NewOrderItem) ([]int64, error) {
	batch := &pgx.Batch{}
	const q = `
		INSERT INTO order_items
			(order_id, variant_id, product_name, variant_name, sku, unit_price_rupiah, quantity)
		VALUES ($1, $2, $3, $4, $5, $6, $7)
		RETURNING id
	`
	for _, it := range items {
		batch.Queue(q, orderID, it.VariantID, it.ProductName, it.VariantName, it.SKU, it.UnitPriceRupiah, it.Quantity)
	}

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

	ids := make([]int64, 0, len(items))
	for range items {
		var id int64
		if err := br.QueryRow().Scan(&id); err != nil {
			return nil, fmt.Errorf("insert order item: %w", err)
		}
		ids = append(ids, id)
	}

	return ids, nil
}

Urutan penting di Batch: kamu memanggil QueryRow (atau Exec) di BatchResults sebanyak statement yang di-Queue, dalam urutan yang sama. defer br.Close() wajib agar koneksi dikembalikan ke pool dan error tertunda ikut terbaca.

Cara 3: CopyFrom (ribuan baris, paling cepat)

Untuk impor masif (misalnya seed katalog ribuan varian, bukan order biasa), CopyFrom memakai protokol COPY PostgreSQL yang jauh lebih cepat dari INSERT beruntun. Trade-off-nya: ia tidak mendukung RETURNING dan tidak menjalankan trigger BEFORE INSERT tertentu, jadi pakai saat kamu memang butuh kecepatan curah.

internal/product/repository.goSalin
func (r *Repository) BulkInsertVariants(ctx context.Context, rows [][]any) (int64, error) {
	n, err := r.pool.CopyFrom(
		ctx,
		pgx.Identifier{"product_variants"},
		[]string{"product_id", "sku", "variant_name", "price_rupiah", "is_active"},
		pgx.CopyFromRows(rows),
	)
	if err != nil {
		return 0, fmt.Errorf("bulk insert variants: %w", err)
	}
	return n, nil
}

Satu file yang menggabungkan pola write utama secara realistis.

Bagian ini menyatukan Exec, QueryRow, RETURNING, timestamp, soft delete, upsert, dan affected rows ke dalam repository produk yang idiomatik.

Struktur folder tetap mengikuti modular monolith dari roadmap sebelumnya: tiap domain punya package sendiri di internal/<domain>, dengan repository.go memegang SQL mentah.

internal/product/repository.goSalin
package product

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

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

var (
	ErrProductNotFound = errors.New("product not found")
	ErrVariantNotFound = errors.New("variant not found")
	ErrNothingToUpdate = errors.New("no fields to update")
	ErrVersionConflict = errors.New("version conflict")
)

type Repository struct {
	pool *pgxpool.Pool
}

func NewRepository(pool *pgxpool.Pool) *Repository {
	return &Repository{pool: pool}
}

type CreateProductInput struct {
	BrandID     int64
	Slug        string
	Name        string
	Description string
	Status      string // draft, active, archived
}

// Create menyisipkan produk baru dan mengembalikan id serta created_at dari database.
func (r *Repository) Create(ctx context.Context, in CreateProductInput) (int64, time.Time, error) {
	const q = `
		INSERT INTO products (brand_id, slug, name, description, status)
		VALUES ($1, $2, $3, $4, $5)
		RETURNING id, created_at
	`

	var (
		id        int64
		createdAt time.Time
	)
	err := r.pool.QueryRow(ctx, q, in.BrandID, in.Slug, in.Name, in.Description, in.Status).
		Scan(&id, &createdAt)
	if err != nil {
		return 0, time.Time{}, fmt.Errorf("create product: %w", err)
	}

	return id, createdAt, nil
}

type PatchProductInput struct {
	Name        *string
	Slug        *string
	Description *string
	Status      *string
}

// Patch mengubah hanya field yang dikirim, lalu mengembalikan updated_at resmi.
func (r *Repository) Patch(ctx context.Context, id int64, in PatchProductInput) (time.Time, error) {
	set := make([]string, 0, 4)
	args := make([]any, 0, 6)
	args = append(args, id) // $1 = id

	if in.Name != nil {
		args = append(args, *in.Name)
		set = append(set, fmt.Sprintf("name = $%d", len(args)))
	}
	if in.Slug != nil {
		args = append(args, *in.Slug)
		set = append(set, fmt.Sprintf("slug = $%d", len(args)))
	}
	if in.Description != nil {
		args = append(args, *in.Description)
		set = append(set, fmt.Sprintf("description = $%d", len(args)))
	}
	if in.Status != nil {
		args = append(args, *in.Status)
		set = append(set, fmt.Sprintf("status = $%d", len(args)))
	}
	if len(set) == 0 {
		return time.Time{}, ErrNothingToUpdate
	}
	set = append(set, "updated_at = now()")

	q := fmt.Sprintf(`
		UPDATE products
		SET %s
		WHERE id = $1 AND deleted_at IS NULL
		RETURNING updated_at
	`, strings.Join(set, ", "))

	var updatedAt time.Time
	err := r.pool.QueryRow(ctx, q, args...).Scan(&updatedAt)
	if errors.Is(err, pgx.ErrNoRows) {
		return time.Time{}, ErrProductNotFound
	}
	if err != nil {
		return time.Time{}, fmt.Errorf("patch product: %w", err)
	}

	return updatedAt, nil
}

// SoftDelete menandai produk terhapus tanpa menghapus baris.
func (r *Repository) SoftDelete(ctx context.Context, id int64) error {
	const q = `
		UPDATE products
		SET deleted_at = now(),
		    updated_at = now()
		WHERE id = $1 AND deleted_at IS NULL
	`

	tag, err := r.pool.Exec(ctx, q, id)
	if err != nil {
		return fmt.Errorf("soft delete product: %w", err)
	}
	if tag.RowsAffected() == 0 {
		return ErrProductNotFound
	}

	return nil
}

// UpdateVariantPrice mengubah harga varian dan mengembalikan timestamp resmi.
func (r *Repository) UpdateVariantPrice(ctx context.Context, variantID, priceRupiah int64) (time.Time, error) {
	const q = `
		UPDATE product_variants
		SET price_rupiah = $2,
		    updated_at   = now()
		WHERE id = $1 AND is_active = true
		RETURNING updated_at
	`

	var updatedAt time.Time
	err := r.pool.QueryRow(ctx, q, variantID, priceRupiah).Scan(&updatedAt)
	if errors.Is(err, pgx.ErrNoRows) {
		return time.Time{}, ErrVariantNotFound
	}
	if err != nil {
		return time.Time{}, fmt.Errorf("update variant price: %w", err)
	}

	return updatedAt, nil
}

Latihan kecil untuk merasakan write flow end-to-end.

Latihan ini membuat kamu mempraktikkan empat pola inti: insert returning, upsert, update kondisional dengan guardrail, dan soft delete, langsung di skema kanonik.

Jalankan beberapa write langsung di psql dulu agar paham efeknya sebelum membungkusnya di Go. Perhatikan RETURNING mengembalikan nilai yang dihitung database.

psqlSalin
-- 1) Insert cart item, minta id dan timestamp balik.
INSERT INTO cart_items (cart_id, variant_id, quantity)
VALUES (1, 101, 2)
RETURNING id, created_at, updated_at;

-- 2) Upsert: tambah varian yang sama, quantity menjumlah.
INSERT INTO cart_items (cart_id, variant_id, quantity)
VALUES (1, 101, 3)
ON CONFLICT (cart_id, variant_id) DO UPDATE
SET quantity = cart_items.quantity + EXCLUDED.quantity,
    updated_at = now()
RETURNING id, quantity;          -- quantity sekarang 5

-- 3) Kurangi stok dengan guardrail, lihat berapa baris terdampak.
UPDATE inventories
SET quantity_available = quantity_available - 2,
    updated_at = now()
WHERE variant_id = 101
  AND quantity_available >= 2
RETURNING variant_id, quantity_available, updated_at;

-- 4) Soft delete produk, hanya kalau belum terhapus.
UPDATE products
SET deleted_at = now(), updated_at = now()
WHERE id = 10 AND deleted_at IS NULL;

Lalu jalankan dari Go lewat test integrasi atau handler, dan cek hasilnya.

TerminalSalin
go test ./internal/...
psql "$DATABASE_URL" -c "SELECT id, quantity, updated_at FROM cart_items WHERE cart_id = 1 AND variant_id = 101;"
psql "$DATABASE_URL" -c "SELECT variant_id, quantity_available FROM inventories WHERE variant_id = 101;"

Sebagian bug write datang dari asumsi framework yang terbawa ke Go.

pgx memberi kontrol tinggi, dan kontrol itu datang bersama tanggung jawab yang dulu ditangani diam-diam oleh framework.

Sekarang repository proyek skincare bisa menulis data ke PostgreSQL dengan pola yang eksplisit, aman dari race, dan mudah diuji.

Dalam proyek online shop skincare, pola chapter ini langsung dipakai untuk menambah cart item (upsert), mengubah harga dan status produk (partial update), menjaga stok dari oversell (guardrail RowsAffected), menyembunyikan produk dari katalog (soft delete), dan menyisipkan order items saat checkout (batch). Yang belum: semua write checkout itu harus terjadi bersama atau batal bersama.

Itulah jembatan ke chapter berikutnya. CreateOrder lengkap menyentuh orders, order_items, inventories, dan carts sekaligus, jadi tidak boleh setengah jadi. Chapter Transaksi membungkus seluruh rangkaian write ini dalam satu pool.Begin, tx.Commit, dan defer tx.Rollback, lengkap dengan isolation level dan penanganan serialization failure.