Slim Connection for v1.0

.gitignore

@@ -10,3 +10,5 @@
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
+
+pqconn/test/postgres-data

CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Run tests for all modules**: `./test-workspace.sh` - This runs tests across all Go workspace modules (main, mssqlconn, mysqlconn, pqconn)
+- **Run tests for specific module**: `go test ./...` in the module directory
+- **Build all modules**: `go build ./...` 
+- **Get dependencies**: `go mod tidy` (run in each module directory as needed)
+
+## Go Workspace Structure
+
+This repository uses Go workspaces with multiple modules:
+- Main module: `github.com/domonda/go-sqldb` (root)
+- Database drivers: `./mssqlconn`, `./mysqlconn`, `./pqconn`
+- Command tools: `./cmd/sqldb-dump`
+- Examples: `./examples/user_demo`
+
+## Architecture Overview
+
+### Core Components
+
+- **Connection Interface**: Central abstraction for database connections and transactions (`connection.go`)
+- **DB Package**: Context-based connection management pattern (`db/` directory)
+- **Database Drivers**: Separate modules for PostgreSQL (`pqconn/`), MySQL (`mysqlconn/`), and SQL Server (`mssqlconn/`)
+- **Query Building**: Flexible query construction with struct mapping
+- **Transaction Management**: Nested transactions with savepoint support
+
+### Key Design Patterns
+
+1. **Context-Based Connection Storage**: Store connections/transactions in context for seamless function composition
+2. **Struct-to-SQL Mapping**: Automatic mapping between Go structs and database rows using reflection
+3. **Transaction Callbacks**: Execute transactions in callback functions that can be nested
+4. **Flexible Query Interface**: Support for both raw SQL and struct-based operations
+
+### Important Packages
+
+- `sqldb` (root): Core interfaces and types
+- `db/`: Context-based connection management and transaction utilities
+- `information/`: Database schema introspection
+- `_mockconn/`: Mock implementations for testing
+
+## Code Conventions
+
+### SQL Queries
+- Write SQL string literals with backticks and prefix with `/*sql*/` comment
+- Use numbered parameters (`$1`, `$2`) for PostgreSQL driver
+
+### Error Handling  
+- Use `github.com/domonda/go-errs` instead of standard `errors` package
+- Use `errs.New()` instead of `errors.New()`
+- Use `errs.Errorf()` instead of `fmt.Errorf()`
+
+### UUID Types
+- Use `github.com/domonda/go-types/uu` package for UUIDs
+- Single UUID: `uu.ID`
+- UUID slice: `uu.IDSlice` (not `[]uu.ID`)
+- Zero values: `uu.IDNil` for `uu.ID`, `uu.IDNull` for `uu.NullableID`, `nil` for `uu.IDSlice`
+
+### General Go Rules
+- Use `any` instead of `interface{}`
+- In HTTP handlers, use `http.Request.Context()` for context
+- Never return actual error strings as HTTP 500 responses - use abstract descriptions
+
+### Struct Field Mapping
+- Default tag: `db:"column_name"`
+- Primary key: `db:"id,pk"`
+- Ignore field: `db:"-"`
+
+## Testing
+- Mock connections available in `_mockconn/` package
+- PostgreSQL integration tests use Docker (see `pqconn/test/`)
+- Use `db.ContextWithNonConnectionForTest()` for testing without real database
+- Helper functions in `db/testhelper.go`
+
+## Common Usage Patterns
+
+### Transaction Management
+```go
+// Simple transaction
+err := db.Transaction(ctx, func(ctx context.Context) error {
+    // All db.Conn(ctx) calls use the transaction
+    return db.Conn(ctx).Exec(/*sql*/ `INSERT ...`)
+})
+
+// Serialized transaction (for high concurrency scenarios)
+err := db.SerializedTransaction(ctx, func(ctx context.Context) error { ... })
+
+// Transaction with savepoints (nested transactions)
+err := db.TransactionSavepoint(ctx, func(ctx context.Context) error { ... })
+```
+
+### Struct Operations
+```go
+// Insert with struct
+err := db.InsertStruct(ctx, "table_name", &structInstance)
+
+// Upsert (uses primary key fields)
+err := db.UpsertStruct(ctx, "table_name", &structInstance)
+
+// Query into struct
+user, err := db.QueryRowValue[User](ctx, /*sql*/ `SELECT * FROM users WHERE id = $1`, id)
+```

TODO.md

@@ -0,0 +1,78 @@
+# TODO - Unfinished Work in go-sqldb
+
+## Major TODOs from README.md
+
+- [ ] Test all pkg db functions
+- [ ] pkg information completion
+- [ ] Test pqconn with dockerized Postgres
+- [ ] Cache struct types (see commit 090e73d1d9db8534d2950dd7236d7ebe192cd512)
+- [ ] Std SQL driver for mocks
+- [ ] Smooth out listener for Postgres
+- [ ] SQLite integration https://github.com/zombiezen/go-sqlite
+- [ ] Bartch insert
+```go
+  func BatchInsert[T any](ctx context.Context, table string, items []T, 
+  batchSize int) error
+```
+
+## Code-Level TODOs and Missing Implementations
+
+### Performance Optimizations
+
+- [ ] **db/insert.go:203** - `InsertRowStructs` missing optimized batch insert (currently processes one-by-one in transaction)
+- [ ] **db/insert.go:76** - Commented code for RETURNING clause needs error wrapping
+- [ ] **pqconn/arrays.go:128** - Array element scanning needs type conversion improvement for different element types
+
+### Function Implementations
+
+- [ ] **db/insert.go:152** - Complete commented out `InsertStructStmt` function with TODO placeholder
+- [ ] **mssqlconn/queryformatter.go:11** - Allow spaces and other characters with backtick escaping
+
+### API Design Questions
+
+- [ ] **db/scanresult.go:3** - Consider moving ScanResult to RowScanner interface
+- [ ] **db/multirowscanner.go:15,97** - Resolve API design questions about single vs multi-column scanning
+- [ ] **db/reflectstruct.go:168** - Clean up Connection implementation detail
+
+## Missing Patterns
+
+### 1. Batch Operations
+- Current `InsertRowStructs` processes items individually in a transaction
+- Need optimized batch INSERT statements that combine multiple structs
+- Consider maxArgs parameter limitations
+
+### 2. RETURNING Clause Support
+- Commented implementation exists in insert.go:76
+- Need proper error wrapping for query execution
+- Should integrate with existing query building patterns
+
+### 3. Error Handling Standardization
+- Some query error wrapping is incomplete
+- Need consistent pattern across all database operations
+
+### 4. Type Conversion Enhancement
+- Array scanning needs improvement for different element types
+- String-to-type conversion challenges in pqconn/arrays.go:128
+
+## Key Areas for Completion
+
+### High Priority
+1. **Performance Optimization**: Implement batch insert operations
+2. **Testing**: Comprehensive test coverage for db package functions
+3. **Configuration**: Rethink and improve Config structure
+
+### Medium Priority
+4. **Database Support**: Complete SQLite integration
+5. **Error Handling**: Standardize query error wrapping patterns
+6. **API Consistency**: Resolve design questions in multirowscanner
+
+### Low Priority
+7. **Code Organization**: Move ScanResult and clean up implementation details
+8. **Features**: Enhanced array type support and RETURNING clause functionality
+
+## Implementation Notes
+
+- The UpsertStruct function (db/upsert.go:14) is marked "TODO" but appears fully implemented
+- Mock connection patterns are well established in _mockconn/ package
+- Go workspace structure supports multiple database drivers effectively
+- Context-based connection management pattern is consistently implemented

_mockconn/connection.go

@@ -0,0 +1,136 @@
+package mockconn
+
+/*
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"time"
+
+	"github.com/domonda/go-sqldb"
+)
+
+var DefaultArgFmt = "?"
+
+func New(ctx context.Context, queryWriter io.Writer, rowsProvider RowsProvider) sqldb.Connection {
+	return &connection{
+		ctx:              ctx,
+		queryWriter:      queryWriter,
+		listening:        newBoolMap(),
+		rowsProvider:     rowsProvider,
+		structFieldNamer: sqldb.DefaultStructFieldMapping,
+		argFmt:           DefaultArgFmt,
+	}
+}
+
+type connection struct {
+	ctx              context.Context
+	queryWriter      io.Writer
+	listening        *boolMap
+	rowsProvider     RowsProvider
+	structFieldNamer sqldb.StructFieldMapper
+	argFmt           string
+}
+
+
+
+func (conn *connection) Stats() sql.DBStats {
+	return sql.DBStats{}
+}
+
+func (conn *connection) Config() *sqldb.Config {
+	return &sqldb.Config{Driver: "mockconn", Host: "localhost", Database: "mock"}
+}
+
+func (conn *connection) Ping(time.Duration) error {
+	return nil
+}
+
+func (conn *connection) Exec(query string, args ...any) error {
+	if conn.queryWriter != nil {
+		fmt.Fprint(conn.queryWriter, query)
+	}
+	return nil
+}
+
+func (conn *connection) Query(query string, args ...any) sqldb.Rows {
+	if err := conn.ctx.Err(); err != nil {
+		return sqldb.RowsErr(err)
+	}
+	return conn.rowsProvider.Query(conn.structFieldNamer, query, args...)
+}
+
+// func (conn *connection) QueryRow(query string, args ...any) sqldb.RowScanner {
+// 	if conn.ctx.Err() != nil {
+// 		return sqldb.RowScannerWithError(conn.ctx.Err())
+// 	}
+// 	if conn.queryWriter != nil {
+// 		fmt.Fprint(conn.queryWriter, query)
+// 	}
+// 	if conn.rowsProvider == nil {
+// 		return sqldb.RowScannerWithError(nil)
+// 	}
+// 	return conn.rowsProvider.QueryRow(conn.structFieldNamer, query, args...)
+// }
+
+// func (conn *connection) QueryRows(query string, args ...any) sqldb.RowsScanner {
+// 	if conn.ctx.Err() != nil {
+// 		return sqldb.RowsScannerWithError(conn.ctx.Err())
+// 	}
+// 	if conn.queryWriter != nil {
+// 		fmt.Fprint(conn.queryWriter, query)
+// 	}
+// 	if conn.rowsProvider == nil {
+// 		return sqldb.RowsScannerWithError(nil)
+// 	}
+// 	return conn.rowsProvider.QueryRows(conn.structFieldNamer, query, args...)
+// }
+
+func (conn *connection) Transaction() (no uint64, opts *sql.TxOptions) {
+	return 0, nil
+}
+
+func (conn *connection) Begin(no uint64, opts *sql.TxOptions) (sqldb.Connection, error) {
+	if no == 0 {
+		return nil, errors.New("transaction number must not be zero")
+	}
+	if conn.queryWriter != nil {
+		fmt.Fprint(conn.queryWriter, "BEGIN")
+	}
+	return transaction{conn, opts, no}, nil
+}
+
+func (conn *connection) Commit() error {
+	return sqldb.ErrNotWithinTransaction
+}
+
+func (conn *connection) Rollback() error {
+	return sqldb.ErrNotWithinTransaction
+}
+
+func (conn *connection) ListenOnChannel(channel string, onNotify sqldb.OnNotifyFunc, onUnlisten sqldb.OnUnlistenFunc) (err error) {
+	conn.listening.Set(channel, true)
+	if conn.queryWriter != nil {
+		fmt.Fprint(conn.queryWriter, "LISTEN "+channel)
+	}
+	return nil
+}
+
+func (conn *connection) UnlistenChannel(channel string) (err error) {
+	conn.listening.Set(channel, false)
+	if conn.queryWriter != nil {
+		fmt.Fprint(conn.queryWriter, "UNLISTEN "+channel)
+	}
+	return nil
+}
+
+func (conn *connection) IsListeningOnChannel(channel string) bool {
+	return conn.listening.Get(channel)
+}
+
+func (conn *connection) Close() error {
+	return nil
+}
+*/