feat: improve documentation, tests, and examples

This commit significantly enhances the go-pglock package with comprehensive
documentation, improved test coverage, and practical examples for common
distributed locking patterns.

Documentation improvements:
- Rewrite README.md with 10 detailed examples covering real-world use cases
  including leader election, task processing, resource pools, and migrations
- Add QUICKREF.md with concise API reference, patterns, and troubleshooting
- Add examples/README.md with detailed guide for running example programs
- Enhance all Go doc strings in lock.go following best practices with
  comprehensive descriptions of behavior, parameters, and edge cases
- Add package-level documentation explaining PostgreSQL advisory locks

Test improvements:
- Add 12 comprehensive test cases covering:
  * Basic lock acquisition and release
  * Lock stacking behavior (multiple acquisitions)
  * Context cancellation and timeout handling
  * Concurrent lock attempts with race detection
  * Blocking vs non-blocking behavior
  * Lock cleanup via Close()
  * Error cases and edge conditions
- Improve test helpers with t.Helper(), require assertions, and better error messages
- Add proper test skipping when DATABASE_URL is not set
- All tests pass with race detector enabled

Example programs:
- Add 5 complete, runnable example programs demonstrating:
  * basic/ - Simple lock acquire/release pattern
  * workers/ - Concurrent workers coordinating access
  * leader-election/ - Cluster leadership election
  * timeout/ - Context timeout and cancellation
  * task-processing/ - Distributed task coordination
- All examples compile successfully and include proper error handling

Development tooling:
- Add docker-compose.yml for easy PostgreSQL test database setup
- Enhance Makefile with test-race, test-coverage, docker-up, docker-down,
  and test-local targets for improved developer experience

The documentation now provides clear guidance from basic usage to advanced
patterns, with 10 real-world examples, troubleshooting guides, and best
practices. Test coverage includes comprehensive scenarios with proper
concurrency testing and edge case handling.

Author: allisson

Makefile

@@ -8,8 +8,29 @@ lint:
 test:
 	go test -covermode=count -coverprofile=count.out -v ./...
 
+test-race:
+	go test -race -covermode=atomic -coverprofile=count.out -v ./...
+
+test-coverage:
+	go test -covermode=count -coverprofile=count.out -v ./...
+	go tool cover -html=count.out -o coverage.html
+	@echo "Coverage report generated: coverage.html"
+
+docker-up:
+	docker-compose up -d
+	@echo "Waiting for PostgreSQL to be ready..."
+	@sleep 3
+
+docker-down:
+	docker-compose down -v
+
+test-local: docker-up
+	@echo "Running tests with local PostgreSQL..."
+	@DATABASE_URL='postgres://test:test@localhost:5432/pglock?sslmode=disable' go test -v ./...
+	@$(MAKE) docker-down
+
 mock:
 	@rm -rf mocks
 	mockery --name Locker
 
-.PHONY: lint test mock
+.PHONY: lint test test-race test-coverage docker-up docker-down test-local mock

QUICKREF.md

@@ -0,0 +1,232 @@
+# go-pglock Quick Reference
+
+## Installation
+
+```bash
+go get github.com/allisson/go-pglock/v3
+```
+
+## Basic Usage
+
+```go
+import "github.com/allisson/go-pglock/v3"
+
+// Connect to database
+db, _ := sql.Open("postgres", "postgres://user:pass@host/db?sslmode=disable")
+
+// Create lock
+ctx := context.Background()
+lock, err := pglock.NewLock(ctx, lockID, db)
+defer lock.Close()
+
+// Acquire lock (non-blocking)
+acquired, err := lock.Lock(ctx)
+
+// Wait for lock (blocking)
+err := lock.WaitAndLock(ctx)
+
+// Release lock
+err := lock.Unlock(ctx)
+```
+
+## API Quick Reference
+
+| Method | Behavior | Returns | Use Case |
+|--------|----------|---------|----------|
+| `NewLock(ctx, id, db)` | Create lock instance | `Lock, error` | Initialize lock |
+| `Lock(ctx)` | Try acquire (non-blocking) | `bool, error` | Skip if busy |
+| `WaitAndLock(ctx)` | Wait for lock (blocking) | `error` | Must execute |
+| `Unlock(ctx)` | Release one lock level | `error` | After work |
+| `Close()` | Release all & cleanup | `error` | Shutdown |
+
+## Common Patterns
+
+### Pattern: Try Lock
+
+```go
+acquired, _ := lock.Lock(ctx)
+if !acquired {
+    return // Skip work
+}
+defer lock.Unlock(ctx)
+// Do work
+```
+
+### Pattern: Wait for Lock
+
+```go
+if err := lock.WaitAndLock(ctx); err != nil {
+    return err
+}
+defer lock.Unlock(ctx)
+// Do work
+```
+
+### Pattern: Lock with Timeout
+
+```go
+ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+defer cancel()
+
+if err := lock.WaitAndLock(ctx); err != nil {
+    return err // Timeout or other error
+}
+defer lock.Unlock(context.Background())
+// Do work
+```
+
+### Pattern: Unique Lock per Resource
+
+```go
+import "hash/fnv"
+
+func lockIDFromString(s string) int64 {
+    h := fnv.New64a()
+    h.Write([]byte(s))
+    return int64(h.Sum64())
+}
+
+lockID := lockIDFromString("user-" + userID)
+```
+
+## Lock Behavior
+
+### Blocking vs Non-blocking
+
+| Method | Blocks? | Use When |
+|--------|---------|----------|
+| `Lock()` | No | Can skip if locked |
+| `WaitAndLock()` | Yes | Must execute eventually |
+
+### Lock Stacking
+
+Locks **stack** within the same session:
+
+```go
+lock.Lock(ctx)    // Acquired (count: 1)
+lock.Lock(ctx)    // Acquired (count: 2)
+lock.Unlock(ctx)  // Released (count: 1) - still locked!
+lock.Unlock(ctx)  // Released (count: 0) - now free
+```
+
+### Lock Release
+
+Locks are released when:
+- ✅ `Unlock()` called (decrements count)
+- ✅ `Close()` called (releases all)
+- ✅ Connection closes
+- ✅ Database session ends
+
+## Error Handling
+
+```go
+acquired, err := lock.Lock(ctx)
+if err != nil {
+    // Database or connection error
+}
+if !acquired {
+    // Lock held by another process
+}
+```
+
+```go
+err := lock.WaitAndLock(ctx)
+if errors.Is(err, context.DeadlineExceeded) {
+    // Timeout occurred
+}
+if errors.Is(err, context.Canceled) {
+    // Context was cancelled
+}
+```
+
+## Best Practices
+
+### ✅ DO
+
+- Always `defer lock.Close()`
+- Use context with timeouts for `WaitAndLock()`
+- Match lock and unlock calls (stacking)
+- Use deterministic lock IDs
+- Check `acquired` return value
+
+### ❌ DON'T
+
+- Don't use random lock IDs
+- Don't forget to unlock
+- Don't acquire in inconsistent order (deadlock)
+- Don't share Lock instances across goroutines
+- Don't rely on lock after `Close()`
+
+## Testing
+
+```bash
+# Start PostgreSQL
+docker-compose up -d
+
+# Run tests
+make test-local
+
+# With race detector
+make test-race
+```
+
+## Use Cases at a Glance
+
+| Use Case | Pattern | Lock Type |
+|----------|---------|-----------|
+| Scheduled jobs | Try Lock | Non-blocking |
+| Database migrations | Wait + Timeout | Blocking |
+| Leader election | Try Lock | Non-blocking |
+| Task processing | Try Lock | Non-blocking |
+| Resource pools | Try each slot | Non-blocking |
+| Critical sections | Wait Lock | Blocking |
+
+## Connection Management
+
+```go
+// Configure pool for locks
+db.SetMaxOpenConns(50)  // Each lock uses one connection
+db.SetMaxIdleConns(10)
+db.SetConnMaxLifetime(time.Hour)
+```
+
+## Lock ID Strategies
+
+### Strategy 1: Sequential IDs
+
+```go
+const (
+    LockIDMigration = 1
+    LockIDBackup    = 2
+    LockIDCleanup   = 3
+)
+```
+
+### Strategy 2: Hash-based
+
+```go
+lockID := hashToInt64("resource-name")
+```
+
+### Strategy 3: Composite
+
+```go
+lockID := (resourceType << 32) | resourceID
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Lock never released | Add `defer lock.Close()` |
+| Too many connections | Reduce pool size or close locks |
+| Deadlocks | Acquire locks in consistent order |
+| Timeouts | Increase timeout or investigate blocking |
+| Tests skip | Set `DATABASE_URL` environment variable |
+
+## Resources
+
+- [Full Documentation](README.md)
+- [Examples](examples/)
+- [API Reference](https://pkg.go.dev/github.com/allisson/go-pglock/v3)
+- [PostgreSQL Advisory Locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)