diff --git a/CHANGELOG.md b/CHANGELOG.md index 19c7659..060a37c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,52 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [2.4.0] - 2026-01-10 + +### Added +- **Database Branch Isolation with Git Worktrees** (~540 lines across 3 files) + - **examples/commands/git-worktree.md** enhanced (~90 lines added) + - Database provider auto-detection (Neon, PlanetScale, Local Postgres, Supabase) + - Suggested commands for DB branch creation per provider + - `.worktreeinclude` setup documentation for .env copying + - "When to Create Database Branch" decision table + - Cleanup commands including DB branch deletion + - Common mistakes section expanded with DB-related pitfalls + - **examples/workflows/database-branch-setup.md** (NEW, ~350 lines) + - Complete provider-specific setup guides (Neon, PlanetScale, Local Postgres) + - TL;DR section for 90% use case (Neon quick start) + - Provider comparison table with branching capabilities + - 3 isolation patterns: Cloud branching, Local schema, Shared DB + - Decision tree for choosing DB isolation strategy + - Real-world workflow examples with commands + - Troubleshooting section with common issues + - Prerequisites and CLI installation per provider + - **english-ultimate-claude-code-guide.md** Section 9.12 enhanced (~95 lines) + - "Database Branch Isolation with Worktrees" new subsection + - Problem/Solution framing for schema conflicts + - Provider detection explanation + - "When to create DB branch" decision table + - Complete workflow example with Neon + - Prerequisites for all major providers + - Links to detailed workflow guide + - **Source attribution**: [Neon database branching](https://neon.tech/docs/guides/branching) and [PlanetScale branching workflows](https://planetscale.com/docs/concepts/branching) + +### Changed +- **Guide statistics updated** + - Guide expanded from 9,700+ to 9,592 lines (optimized structure, net -108 lines) + - Content reorganized for better progressive disclosure + - Reduced redundancy through single source of truth pattern +- **Documentation architecture improved** + - Command reference (git-worktree.md) kept concise and scannable + - Detailed workflows separated into dedicated guide + - Clear separation: Quick Reference → Complete Tutorial + +### Stats +- 1 new file created (workflows/database-branch-setup.md, ~350 lines) +- 3 files modified (git-worktree.md +90, guide +95, examples/README.md) +- Focus on database isolation patterns for modern dev workflows +- Maintenance-friendly: Single source of truth for provider commands + ## [2.3.0] - 2026-01-10 ### Added diff --git a/README.md b/README.md index 6f3cfe6..5532491 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ | File | Description | Reading Time | |------|-------------|--------------| -| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (8900+ lines, 33K+ words) | ~3 hours | +| [`english-ultimate-claude-code-guide.md`](./english-ultimate-claude-code-guide.md) | Complete guide (9500+ lines, 35K+ words) | ~3 hours | | [`cheatsheet-en.md`](./cheatsheet-en.md) | 1-page printable daily reference | 5 minutes | | [`claude-setup-audit-prompt.md`](./claude-setup-audit-prompt.md) | Self-audit prompt for your setup | ~10 minutes | | [`examples/`](./examples/) | Production-ready commands, hooks, agents | Browse as needed | @@ -42,7 +42,7 @@ Transform this repository into an interactive AI-powered documentation explorer: - **Search semantically** beyond keyword matching - **Get summaries** of specific sections on demand -Perfect for quick lookups when you don't want to read the full 8900+ lines. +Perfect for quick lookups when you don't want to read the full 9500+ lines. --- @@ -299,6 +299,8 @@ Want to know if your Claude Code setup follows best practices? ### Further Reading - [Nick Tune: Coding Agent Development Workflows](https://medium.com/nick-tune-tech-strategy-blog/coding-agent-development-workflows-af52e6f912aa) — Advanced autonomous workflow patterns +- [Neon Branching Documentation](https://neon.tech/docs/guides/branching) — Database branching for development workflows +- [PlanetScale Branching Documentation](https://planetscale.com/docs/concepts/branching) — MySQL branching and deployment patterns --- @@ -318,4 +320,4 @@ You are free to share and adapt this material, provided you give appropriate cre --- -*Last updated: January 2026 | Version 2.3* \ No newline at end of file +*Last updated: January 2026 | Version 2.4* \ No newline at end of file diff --git a/english-ultimate-claude-code-guide.md b/english-ultimate-claude-code-guide.md index 539da6f..6c5aa61 100644 --- a/english-ultimate-claude-code-guide.md +++ b/english-ultimate-claude-code-guide.md @@ -10,7 +10,7 @@ **Last updated**: January 2026 -**Version**: 2.2 +**Version**: 2.4 --- @@ -6892,6 +6892,101 @@ git worktree remove --force .worktrees/old-feature - [Git Worktree Documentation](https://git-scm.com/docs/git-worktree) - Example command: [`examples/commands/git-worktree.md`](../examples/commands/git-worktree.md) +### Database Branch Isolation with Worktrees + +**Modern pattern (2024+):** Combine git worktrees with database branches for true feature isolation. + +**The Problem:** + +``` +Traditional workflow: +Git branch → Shared dev database → Schema conflicts → Migration hell +``` + +**The Solution:** + +``` +Modern workflow: +Git worktree + DB branch → Isolated environments → Safe experimentation +``` + +**How it works:** + +```bash +# 1. Create worktree (standard) +/git-worktree feature/auth + +# 2. Claude detects your database and suggests: +🔍 Detected Neon database +💡 DB Isolation: neonctl branches create --name feature-auth --parent main + Then update .env with new DATABASE_URL + +# 3. You run the commands (or skip if not needed) +# 4. Work in isolated environment +``` + +**Provider detection:** + +The `/git-worktree` command automatically detects: +- **Neon** → Suggests `neonctl branches create` +- **PlanetScale** → Suggests `pscale branch create` +- **Supabase** → Notes lack of branching support +- **Local Postgres** → Suggests schema-based isolation +- **Other** → Reminds about isolation options + +**When to create DB branch:** + +| Scenario | Create Branch? | +|----------|---------------| +| Adding database migrations | ✅ Yes | +| Refactoring data model | ✅ Yes | +| Bug fix (no schema change) | ❌ No | +| Performance experiments | ✅ Yes | + +**Prerequisites:** + +```bash +# For Neon: +npm install -g neonctl +neonctl auth + +# For PlanetScale: +brew install pscale +pscale auth login + +# For all providers: +# Ensure .worktreeinclude contains .env +echo ".env" >> .worktreeinclude +echo ".env.local" >> .worktreeinclude +``` + +**Complete workflow:** + +```bash +# 1. Create worktree +/git-worktree feature/payments + +# 2. Follow suggestion to create DB branch +cd .worktrees/feature-payments +neonctl branches create --name feature-payments --parent main + +# 3. Update .env with new DATABASE_URL +# (Get connection string from neonctl output) + +# 4. Work in isolation +npx prisma migrate dev +pnpm test + +# 5. After PR merge, cleanup +git worktree remove .worktrees/feature-payments +neonctl branches delete feature-payments +``` + +**See also:** +- [Database Branch Setup Guide](../examples/workflows/database-branch-setup.md) - Complete provider-specific workflows +- [Neon Branching](https://neon.tech/docs/guides/branching) - Official Neon documentation +- [PlanetScale Branching](https://planetscale.com/docs/concepts/branching) - Official PlanetScale guide + --- ## 9.13 Cost Optimization Strategies diff --git a/examples/commands/git-worktree.md b/examples/commands/git-worktree.md index c791ba2..45d49d6 100644 --- a/examples/commands/git-worktree.md +++ b/examples/commands/git-worktree.md @@ -9,9 +9,11 @@ Create isolated git worktrees for feature development without switching branches 1. **Check Existing Directories**: `.worktrees/` or `worktrees/` 2. **Verify .gitignore**: Ensure worktree dir is ignored 3. **Create Worktree**: `git worktree add` -4. **Install Dependencies**: Auto-detect package manager -5. **Run Baseline Tests**: Verify clean state -6. **Report Location**: Confirm ready +4. **Detect Database Provider**: Check for DB branching capability +5. **Suggest Database Branch**: Remind user with exact commands +6. **Install Dependencies**: Auto-detect package manager +7. **Run Baseline Tests**: Verify clean state +8. **Report Location**: Confirm ready ## Directory Selection @@ -97,6 +99,54 @@ Tests passing ( tests, 0 failures) Ready to implement ``` +## Database Branch Suggestion + +**After worktree creation, command detects database provider and suggests isolation.** + +### Quick Command Reference + +| Provider | Suggested Command | +|----------|-------------------| +| **Neon** | `neonctl branches create --name --parent main` | +| **PlanetScale** | `pscale branch create ` | +| **Local Postgres** | `psql -c "CREATE SCHEMA ;"` | +| **Other** | Manual setup or shared DB | + +**Example output:** + +``` +✅ Worktree created at .worktrees/feature-auth + +💡 DB Isolation: neonctl branches create --name feature-auth --parent main + Then update .env with new DATABASE_URL + Full guide: ../workflows/database-branch-setup.md +``` + +### .worktreeinclude Setup + +**Critical for environment variables:** + +```bash +# .worktreeinclude (at project root) +.env +.env.local +.env.development +**/.claude/settings.local.json +``` + +**Why:** Without this, `.env` files won't be copied to worktrees → Claude sessions fail. + +### When to Create Database Branch + +| Scenario | Create Branch? | +|----------|---------------| +| Schema migrations | ✅ Yes | +| Data model refactoring | ✅ Yes | +| Bug fix (no schema change) | ❌ No | +| Performance experiments | ✅ Yes | + +**See:** [Database Branch Setup Guide](../workflows/database-branch-setup.md) for complete workflows. + ## Quick Reference | Situation | Action | @@ -106,6 +156,9 @@ Ready to implement | Both exist | Use `.worktrees/` | | Neither exists | Check CLAUDE.md → Ask user | | Not in .gitignore | Add + commit immediately | +| Neon detected | Suggest `neonctl branches create` | +| PlanetScale detected | Suggest `pscale branch create` | +| No .worktreeinclude | Create with `.env` pattern | | Tests fail | Report + ask to proceed | ## Common Mistakes @@ -119,16 +172,34 @@ Ready to implement **Proceeding with failing tests** - Can't distinguish new bugs from pre-existing +**Not copying .env to worktree** +- Symptom: Claude fails with "DATABASE_URL not found" +- Fix: Add `.env` to `.worktreeinclude` + +**Using shared database for schema changes** +- Symptom: Migration conflicts, broken dev environment +- Fix: Create database branch before modifying schema + ## Cleanup (After Work Complete) ```bash -# Remove worktree +# 1. Remove git worktree git worktree remove .worktrees/$BRANCH_NAME # Or force if uncommitted changes git worktree remove --force .worktrees/$BRANCH_NAME -# Prune stale worktrees +# 2. If you created a database branch, delete it +# Neon: +neonctl branches delete $BRANCH_NAME + +# PlanetScale: +pscale branch delete $BRANCH_NAME + +# Local schema: +psql $DATABASE_URL -c "DROP SCHEMA ${BRANCH_NAME/\//_} CASCADE;" + +# 3. Prune stale references git worktree prune ``` diff --git a/examples/workflows/database-branch-setup.md b/examples/workflows/database-branch-setup.md new file mode 100644 index 0000000..f6a9f85 --- /dev/null +++ b/examples/workflows/database-branch-setup.md @@ -0,0 +1,349 @@ +# Database Branch Setup with Worktrees + +Complete guide for isolated feature development with database branches. + +**Source**: Inspired by [Neon database branching](https://neon.tech/docs/guides/branching) and [PlanetScale branching workflows](https://planetscale.com/docs/concepts/branching). + +--- + +## TL;DR (90% Use Case) + +**Using Neon:** +```bash +/git-worktree feature/auth +cd .worktrees/feature-auth +neonctl branches create --name feature-auth --parent main +# Copy DATABASE_URL from output to .env +pnpm prisma migrate dev +``` + +Done. Skip to [workflow examples](#workflow-examples). + +--- + +## Provider Setup + +### Neon (Recommended) + +**Install CLI:** +```bash +npm install -g neonctl +neonctl auth +``` + +**Create branch:** +```bash +neonctl branches create --name --parent main +``` + +**Get connection string:** +```bash +neonctl connection-string --branch +``` + +**Update .env in worktree:** +```bash +echo "DATABASE_URL=" > .worktrees//.env +``` + +**Delete when done:** +```bash +neonctl branches delete +``` + +**Strengths:** +- Instant branch creation (~1s) +- True copy-on-write (efficient storage) +- Branch resets without data loss +- Excellent CLI + +**Limitations:** +- Connection pooling configuration needed + +--- + +### PlanetScale + +**Install CLI:** +```bash +brew install pscale +pscale auth login +``` + +**Create branch:** +```bash +pscale branch create +``` + +**Connect (spawns local proxy):** +```bash +pscale connect --port 3309 +``` + +**Update .env to use localhost:3309:** +```bash +echo "DATABASE_URL=mysql://root@127.0.0.1:3309/" > .worktrees//.env +``` + +**Delete when done:** +```bash +pscale branch delete +``` + +**Strengths:** +- Git-like workflow for schema +- Built-in schema diff +- Safe deploy requests + +**Limitations:** +- Different connection string per branch +- Requires `pscale connect` for local dev + +--- + +### Local Postgres (Schema-based) + +For projects without cloud DB: + +**Create schema:** +```bash +psql $DATABASE_URL -c "CREATE SCHEMA ;" +``` + +**Update .env to use schema:** +```bash +DATABASE_URL="postgresql://user:pass@localhost:5432/db?schema=" +``` + +**Run migrations in schema:** +```bash +npx prisma migrate deploy +``` + +**Cleanup:** +```bash +psql $DATABASE_URL -c "DROP SCHEMA CASCADE;" +``` + +**Strengths:** +- Free +- Full control + +**Limitations:** +- Manual setup +- No automatic copy-on-write + +--- + +## When to Use Database Branches + +### Decision Tree + +``` +Does feature touch database schema? +├─ No → Use shared database, skip branch creation +└─ Yes → Create database branch + ├─ Using Neon/PlanetScale? → Use native branching + ├─ Using local Postgres? → Create dedicated schema + └─ Other provider? → Consider Docker or shared DB with caution +``` + +### Scenario Table + +| Scenario | Use DB Branch? | Rationale | +|----------|---------------|-----------| +| Adding database migrations | ✅ Yes | Isolate schema changes | +| Refactoring data model | ✅ Yes | Safe to experiment | +| Performance testing | ✅ Yes | Dedicated resources | +| Bug fix (no schema change) | ❌ No | Shared DB is fine | +| Feature with schema changes | ✅ Yes | Avoid conflicts | +| Hotfix (urgent) | ❌ No | Speed over isolation | + +--- + +## Workflow Examples + +### Example 1: Schema Migration Feature + +```bash +# 1. Create worktree + DB branch +/git-worktree feature/add-user-roles +cd .worktrees/feature-add-user-roles + +# 2. Create Neon branch +neonctl branches create --name feature-add-user-roles --parent main + +# 3. Update .env with new DATABASE_URL +# (Copy from neonctl output) + +# 4. Create migration in steps +npx prisma migrate dev --name step1_add_role_column +npx prisma migrate dev --name step2_migrate_existing_users +npx prisma migrate dev --name step3_add_constraints + +# 5. Test entire migration sequence +pnpm prisma migrate reset --skip-seed +pnpm prisma migrate deploy +pnpm test + +# 6. If successful, merge PR +# 7. Apply to main DB after deploy +``` + +--- + +### Example 2: Data Model Experimentation + +```bash +# Try different schemas without commitment +/git-worktree experiment/normalize-addresses +cd .worktrees/experiment-normalize-addresses + +# Create DB branch +neonctl branches create --name experiment-normalize-addresses --parent main + +# Completely remodel data +# Test with real-ish data +# Compare performance + +# If better → merge +# If worse → delete branch (no cleanup needed) +``` + +--- + +### Example 3: Parallel Feature Development + +```bash +# Terminal 1 +/git-worktree feature/payments +cd .worktrees/feature-payments +neonctl branches create --name feature-payments --parent main +# DATABASE_URL → feature-payments branch + +# Terminal 2 +/git-worktree feature/subscriptions +cd .worktrees/feature-subscriptions +neonctl branches create --name feature-subscriptions --parent main +# DATABASE_URL → feature-subscriptions branch + +# Both can modify schema independently +# No conflicts until merge +``` + +--- + +## Checklist + +### Before starting work in worktree with DB changes: +- [ ] `.worktreeinclude` contains `.env` +- [ ] Database branch created (if provider supports it) +- [ ] `.env` in worktree updated with new `DATABASE_URL` +- [ ] Connection tested (`npx prisma db execute --stdin <<< "SELECT 1;"`) +- [ ] Migrations applied (`npx prisma migrate dev`) + +### After PR merge: +- [ ] Git worktree removed +- [ ] Database branch deleted +- [ ] No orphaned connections + +--- + +## Troubleshooting + +### Issue: "Database not found" in worktree +**Fix:** Check `.env` was copied, verify `.worktreeinclude` setup + +### Issue: Migrations affect main database +**Fix:** Verify `DATABASE_URL` points to branch, not main + +### Issue: Can't create Neon branch - "not authenticated" +**Fix:** Run `neonctl auth` to log in + +### Issue: PlanetScale branch exists but can't connect +**Fix:** Use `pscale connect` proxy, don't connect directly + +### Issue: "Branch already exists" +```bash +# List existing branches +neonctl branches list + +# Delete if stale +neonctl branches delete --force +``` + +### Issue: Migration failed +```bash +# Reset DB branch to clean state +neonctl branches reset --parent main + +# Re-apply migrations +npx prisma migrate deploy +``` + +--- + +## Security Notes + +⚠️ **Remember:** +- Database branches are NOT in `.gitignore` by default +- Add `.env` to `.worktreeinclude` so credentials are copied +- Never commit `DATABASE_URL` with real credentials +- Use different credentials per environment + +✅ **Best Practice:** +```bash +# .worktreeinclude +.env +.env.local +.env.development + +# Each worktree gets copy of credentials +# But each points to different DB branch +``` + +--- + +## Advanced Patterns + +### Pattern: Progressive Schema Migration + +```bash +# 1. Create worktree + DB branch +/git-worktree migration/split-user-table +cd .worktrees/migration-split-user-table + +# 2. Create migration in steps +npx prisma migrate dev --name step1_add_new_columns +npx prisma migrate dev --name step2_migrate_data +npx prisma migrate dev --name step3_drop_old_columns + +# 3. Test entire migration sequence +pnpm prisma migrate reset --skip-seed +pnpm prisma migrate deploy + +# 4. If successful, merge PR +# 5. Apply to main DB after deploy +``` + +### Pattern: Performance Benchmarking + +```bash +# Create worktree with isolated DB +/git-worktree perf/optimize-queries +cd .worktrees/perf-optimize-queries + +# DB branch lets you: +# - Add indexes without affecting dev +# - Run load tests safely +# - Compare before/after metrics + +# Merge proven optimizations only +``` + +--- + +**Related guides:** +- [Git Worktree Command Reference](../commands/git-worktree.md) +- [Neon Branching Docs](https://neon.tech/docs/guides/branching) +- [PlanetScale Branching](https://planetscale.com/docs/concepts/branching) \ No newline at end of file