🚀 zpgxpool — Lightweight pgx pool interface + testing mocks

A compact helper library and mock utilities for working with PostgreSQL via pgx in Go. Ideal for projects that need:

• A small, test-friendly abstraction over pgx connection pool
• Ready-to-use mocks for unit tests (using gomock)
• Clear examples to run & learn from

📌 Short: fast to adopt, easy to test, and designed for clean unit testing patterns.

---

⚡ Quick links

• Full documentation: DOCUMENTATION.md
• Examples folder (runnable tests): examples/README.md
• Source: this repository root

---

📦 Why use zpgxpool?

• Replace direct pgx calls in business logic with interfaces to make unit testing trivial.
• Use generated mocks (gomock) to assert interactions, simulate errors, and test transaction flows without a real DB.
• Includes utilities to create fake rows (NewRows, NewRow) to simulate query results (including NULLs and CSV input).

---

🧭 Quick Start

1. Add repository as a module dependency (or vendor locally):

go get github.com/zihxs/zpgxpool

2. Use the PgxPool interface in your code:

var db zpgxpool.PgxPool = realPool // or injected mock in tests
row := db.QueryRow(ctx, "SELECT id FROM users WHERE id = $1", 1)

3. Run examples:

cd examples && go test ./...

See examples/README.md for details.

---

🧪 Unit testing patterns

• Create mock controller:

ctrl := gomock.NewController(t)
defer ctrl.Finish()
mockPool := zpgxpool.NewMockPgxPool(ctrl)

• Return mocked rows:

rows := zpgxpool.NewRows([]string{"id","name"}).AddRow(1,"John")
mockPool.EXPECT().Query(gomock.Any(), "SELECT ...").Return(rows.ToPgxRows(), nil)

• Test transaction behavior with MockTx:

mockTx := zpgxpool.NewMockTx(ctrl)
mockPool.EXPECT().Begin(gomock.Any()).Return(mockTx, nil)
mockTx.EXPECT().Exec(gomock.Any(), "INSERT ...", gomock.Any()).Return(pgconn.NewCommandTag("INSERT 0 1"), nil)
mockTx.EXPECT().Commit(gomock.Any()).Return(nil)

---

📂 Examples included (runnable)

• successful_query_test.go — multi-row query ✅
• successful_transaction_test.go — transaction commit ✅
• query_error_test.go — simulate query error ❌
• transaction_rollback_test.go — simulate rollback on error 🔁
• empty_query_results_test.go — no rows edge case ⚠️
• null_values_test.go — scan NULL values into pointers 🌫️
• single_row_result_test.go — QueryRow usage 1️⃣
• nested_transactions_test.go — nested transaction scenarios 🧵
• batch_operations_test.go — send batch and verify results 🔥

Run all examples:

cd examples && go test ./...

---

🛠️ Implementation notes (for contributors)

• Interfaces are defined in pgx_pool.go.
• Mocks are generated by gomock and included (pgx_pool_mock.go) to avoid requiring mock generation during CI.
• Row/Rows helpers defined in row.go and rows.go.

If you change interfaces, re-generate mocks with:

mockgen -destination=pgx_pool_mock.go -package=zpgxpool path/to/your/module PgxPool,Tx

---

🤝 Contribution & Code of Conduct

Contributions welcome — please open issues or pull requests. Follow repository coding and PR guidelines:

• Small iterative PRs
• Tests included for new features
• Update docs / examples when behavior changes

---

If this project helped you speed up DB testing, please:

• Star the repo ⭐
• Share an example of how you use it
• Open issues for missing features or improvements

Thanks — and happy testing! 🎉

---

• Keywords: pgx, postgres, golang, db pool, pgxpool, mocking, gomock, unit test, database testing, sql transactions.
• Ideal for: backend services, microservices, Open Source libraries using PostgreSQL and Go.
• Features: interface abstractions (PgxPool, Tx), mock generator output, utilities to build pgx.Rows and pgx.Row for tests, examples.