br-pgsql 0.1.17

# AGENTS.md

**Generated:** 2025-02-06 | **Commit:** 52238c0 | **Branch:** main

## OVERVIEW

Rust library crate implementing PostgreSQL wire protocol v3 with SCRAM-SHA-256 auth. Synchronous API, connection pooling via global static `DB_POOL`.

## STRUCTURE

```
br-pgsql/
├── src/
│   ├── lib.rs       # API surface: Pgsql, connect, pools
│   ├── config.rs    # Config struct, defaults, URL assembly
│   ├── connect.rs   # TCP lifecycle, startup/auth, query/execute
│   ├── packet.rs    # Wire protocol pack/unpack (903 lines, largest)
│   ├── pools.rs     # ConnectionGuard, lazy pool, retry logic
│   └── format.rs    # OID→JsonValue type conversion
├── tests/index.rs   # Integration test (requires live PostgreSQL)
├── examples/        # index.rs uses tokio-postgres (not this crate!)
├── Cargo.toml
└── INSTALL.md       # Clippy/publish commands
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| Add PostgreSQL message type | `src/packet.rs` → `MessageType::form()` | Match on byte tag |
| Add field type conversion | `src/format.rs` → `FieldFormat::from_u16()` | Match (code, type_oid) |
| Change auth flow | `src/connect.rs` → `sasl_initial_response_message()` | SCRAM logic |
| Modify pool behavior | `src/pools.rs` → `get_connect()`, `release_conn()` | Global `DB_POOL` |
| Change defaults | `src/config.rs` → `Config::new()` | localhost:5432, postgres/111111 |

## COMMANDS

```bash
# Build
cargo build
cargo build --release

# Format
cargo fmt
cargo fmt --check

# Lint (from INSTALL.md)
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings -W clippy::pedantic

# Test (requires PostgreSQL at localhost:5432)
cargo test --test index init_db    # Single test
cargo test                          # Full suite

# Publish
cargo package --list
cargo publish --dry-run
```

## MODULE BOUNDARIES

| Module | Responsibility | DO NOT mix with |
|--------|----------------|-----------------|
| `packet.rs` | Wire protocol only | Network I/O |
| `connect.rs` | Socket lifecycle | Pool policy |
| `pools.rs` | Pool management | Protocol details |
| `format.rs` | Type conversion | Packet parsing |

## CONVENTIONS

- **Result type**: `Result<T, String>` throughout - preserve unless redesigning API
- **Imports**: `crate::...` first, then external, then `std`
- **Logging**: `log` macros only, no `println!` in library code
- **Numeric widths**: Explicit (`u16`, `u32`, `i32`) for protocol fields
- **JSON**: `json::JsonValue` for config and result rows

## ANTI-PATTERNS (THIS PROJECT)

- **DO NOT** expand `unsafe { String::from_utf8_unchecked }` usage - existing tech debt
- **DO NOT** add `.unwrap()` in new parse paths - use fallible conversions
- **DO NOT** introduce async in core crate - sync only, async in examples
- **DO NOT** hold mutex during socket operations - keep lock times short
- **DO NOT** change public API signatures without explicit request

## KNOWN SHARP EDGES

- `packet.rs` uses `unsafe` UTF-8 conversions extensively - narrow edits only
- `tests/index.rs` requires live PostgreSQL with default creds
- `examples/index.rs` demos `tokio-postgres`, not this crate (misleading)
- Global `DB_POOL` static - all `Pools` instances share same backing store
- Chinese comments throughout - preserve or translate consistently

## DEPENDENCIES

| Crate | Purpose |
|-------|---------|
| `json` | Config parsing, result rows |
| `hmac` + `sha2` + `base64` + `rand` | SCRAM-SHA-256 auth |
| `log` | Diagnostics |
| `tokio-postgres` (dev) | Reference in examples only |

## QUICK CHECKLIST

Before coding:
1. Identify target module boundary
2. Choose smallest validating test command
3. Check if change affects DB connection requirements

Before finishing:
1. `cargo fmt --check`
2. `cargo clippy --all-targets --all-features -- -D warnings`
3. Smallest relevant test, then broader if needed
4. Verify diff is focused and intentional