Repository: vitessio/vitess

Stars: 20919

CLAUDE.md Copy Chapter

:handshake: Our Partnership Copy Chapter

We're building this together. You're not just executing tasks - you're helping design and implement the best possible solution. This means:

- Challenge my suggestions when something feels wrong
- Ask me to explain my reasoning
- Propose alternative approaches
- Take time to think through problems

Quality is non-negotiable. We'd rather spend an hour designing than 3 hours fixing a rushed implementation.

:thought_balloon: Before We Code Copy Chapter

Always discuss first:
- What problem are we solving?
- What's the ideal solution?
- What tests would prove it works?
- Are we making the codebase better?

Strict Task Adherence Copy Chapter

Only do exactly what I ask for - nothing more, nothing less.

- Do NOT proactively update documentation unless explicitly requested
- Do NOT add explanatory comments unless asked
- Do NOT make "improvements" or "clean up" code beyond the specific task
- Do NOT add features, optimizations, or enhancements I didn't mention
- If there is something you think should be done, suggest it, but don't do it until asked to

Red flags that indicate you're going beyond the task:
- "Let me also..."
- "While I'm at it..."
- "I should also update..."
- "Let me improve..."
- "I'll also clean up..."

If the task is complete, STOP. Don't look for more work to do.

:test_tube: Test-Driven Development Copy Chapter

TDD isn't optional - it's how we ensure quality:

The TDD Cycle Copy Section

Example TDD Session Copy Section

// Step 1: Write the test first
func TestConnectionBilateralCleanup(t *testing.T) {
    // Define what success looks like
    client, server := testutils.CreateConnectedTCPPair()
    
    // Test the behavior we want
    client.Close()
    
    // Both sides should be closed
    assert.Eventually(t, func() bool {
        return isConnectionClosed(server)
    })
}
// Step 2: See it fail (confirms we're testing the right thing)
// Step 3: Implement the feature
// Step 4: See it pass
// Step 5: Refactor for clarity

To make sure tests are easy to read, we use github.com/stretchr/testify/assert and github.com/stretchr/testify/require for assertions:
- Use require (not assert) when the test cannot continue after a failure (e.g., require.NoError after setup that must succeed)
- Use assert.Eventually instead of manual time.Sleep() and timeouts
- Use t.Context() instead of context.Background() — it integrates with test cancellation
- Use t.Cleanup() for test teardown
- Use assert.ErrorContains / require.ErrorContains to check error messages
- Use the _test.go suffix for mocks and test helpers that are only used by the current package's tests; if helpers or mocks need to be imported by other packages' tests or fuzz harnesses, put them in a normal reusable package such as testlib or testutil
- CI timeouts must be generous (30s+) — GitHub Actions runners can be resource-starved with multi-second pauses; sub-second timeouts cause flakiness with no recourse but retry

:rotating_light: Error Handling Excellence Copy Chapter

Error handling is not an afterthought - it's core to reliable software.

Go Error Patterns Copy Section

// YES - Clear error context with vterrors
func ProcessUser(id string) (*User, error) {
    if id == "" {
        return nil, vterrors.Errorf(vtrpcpb.Code_FAILED_PRECONDITION, "user ID cannot be empty")
    }
    user, err := db.GetUser(id)
    if err != nil {
        return nil, vterrors.Wrapf(err, "failed to get user %s", id)
    }
    return user, nil
}
// NO - Swallowing errors
func ProcessUser(id string) *User {
    user, _ := db.GetUser(id)  // What if this fails?
    return user
}

Error Handling Principles Copy Section

Failure-Path Safety Copy Section

Testing Error Paths Copy Section

func TestProcessUser_InvalidID(t *testing.T) {
    _, err := ProcessUser("")
    assert.ErrorContains(t, err, "cannot be empty")
}
func TestProcessUser_DatabaseError(t *testing.T) {
    mockDB.EXPECT().GetUser("123").Return(nil, errors.New("db connection failed"))
    
    _, err := ProcessUser("123")
    assert.ErrorContains(t, err, "failed to get user")
}

:triangular_ruler: Design Principles Copy Chapter

1. Simple is Better Than Clever Copy Section

// YES - Clear and obvious
if user.NeedsMigration() {
    return migrate(user)
}
// NO - Clever but unclear
return user.NeedsMigration() && migrate(user) || user

2. Explicit is Better Than Implicit Copy Section

3. Conditions Must Be as Specific as the Intent Copy Section

4. Zero-Value / Default Behavior Safety Copy Section

5. Performance with Clarity Copy Section

6. Fail Fast and Clearly Copy Section

7. Interfaces Define What You Need, Not What You Provide Copy Section

#### Protobufs
- Never directly edit files under go/vt/proto/ - they are generated from proto/*.proto protobuf definitions
- After modifying proto/*.proto files, run make proto to regenerate
- Avoid storing timestamps or time durations as integers; use vttime.Time for timestamps and vttime.Duration (or google.protobuf.Duration, as appropriate) for durations instead
- Avoid storing tablet aliases as a string: use topodata.TabletAlias

#### SQL Parser
- Never directly edit these generated files in go/vt/sqlparser/: sql.go, ast_clone.go, ast_copy_on_rewrite.go, ast_equals.go, ast_format_fast.go, ast_path.go, ast_rewrite.go, ast_visit.go, cached_size.go
- After modifying source files (e.g., sql.y, AST definitions), run make codegen to regenerate
- Field order in AST structs matters — generated walkers visit fields in declaration order, so reordering fields changes semantic-analysis walk order and can break scope setup

Command-Line Flags Copy Section

// Use structured logging (slog-style) for new code
log.Info("Starting payment processing",
    slog.String("user_id", userID),
    slog.String("action", "process_payment"),
    slog.Float64("amount", amount),
)
// Add strategic debug points
func processPayment(amount float64) error {
    if amount <= 0 {
        return vterrors.Errorf(vtrpcpb.Code_INVALID_ARGUMENT, "invalid amount: %f", amount)
    }
    // More processing...
    log.Info("Payment validation passed")
    return nil
}

// Step 1: Add characterization tests
func TestLegacyProcessor_ExistingBehavior(t *testing.T) {
    processor := &LegacyProcessor{}
    
    // Document current behavior, even if it seems wrong
    result := processor.Process("input")
    assert.Equal(t, "weird_legacy_output", result)
}
// Step 2: Refactor with tests passing
func (p *LegacyProcessor) Process(input string) string {
    // Improved implementation that maintains the same behavior
    return processWithNewLogic(input)
}
// Step 3: Now we can safely change the behavior
func TestProcessor_ImprovedBehavior(t *testing.T) {
    processor := &Processor{}
    
    result := processor.Process("input")
    assert.Equal(t, "expected_output", result)
}

CRITICAL: Git commands are ONLY for reading state - NEVER for modifying it.
- NEVER use git commands that modify the filesystem unless explicitly told to commit
- You may read git state: git status, git log, git diff, git branch --show-current
- You may NOT: git commit, git add, git reset, git checkout, git restore, git rebase, git push, etc.
- ONLY commit when explicitly asked to commit
- Always sign git commits with the git commit --signoff flag
- When asked to commit, do it once and stop
- Only I can modify git state unless you've been given explicit permission to commit

Once a PR is created, NEVER amend commits or rewrite history.
- Always create new commits after PR is created
- No git commit --amend after pushing to a PR branch
- No git rebase that rewrites commits in the PR
- No force pushes to PR branches
- This keeps the PR history clean and reviewable

When asked to write a PR description:
1. Use gh CLI - Always use gh pr edit <number> to update PRs
2. Update both body and title - Use --body and --title flags
3. Be informal, humble, and short - Keep it conversational and to the point
4. Credit appropriately - If Claude Code wrote most of it, mention that
5. Example format:


## What's this?
   [Brief explanation of the feature/fix]
   ## How it works
   [Key implementation details]
   ## Usage
   [Code examples if relevant]
   ---
   _Most of this was written by Claude Code - I just provided direction._

:memo: Code Review Mindset Copy Chapter

When reviewing code (yours or mine), ask:
- Is this the simplest solution?
- Will this make sense in 6 months?
- Are edge cases handled?
- Is it well tested?
- Does it improve the codebase?

:dart: Common Patterns Copy Chapter

Feature Implementation Copy Section

You: "Let's add feature X"
Me: "Sounds good! What's the API going to look like? What are the main use cases?"
[Discussion of design]
Me: "Let me write some tests to clarify the behavior we want"
[TDD implementation]
Me: "Here's what I've got. What do you think?"

You: "We have a bug where X happens"
Me: "Let's write a test that reproduces it first"
[Test that fails]
Me: "Great, now we know exactly what we're fixing"
[Fix implementation]

You: "This seems slow"
Me: "Let's benchmark it first to get a baseline"
[Benchmark results]
Me: "Now let's optimize without breaking functionality"
[Optimization with tests passing]

Before considering any work "done":
- [ ] Tests pass and cover the feature
- [ ] Code is clean and readable
- [ ] Golang code passes the gofumpt formatter
- [ ] Golang code passes the goimports -local "vitess.io/vitess" -w ...` formatter
- [ ] Edge cases are handled
- [ ] Performance is acceptable
- [ ] Documentation is updated if needed
- [ ] We're both happy with it

Remember: We're crafting software, not just making it work. Every line of code is an opportunity to make the system better.

README.md Copy Chapter


Vitess

Vitess is a cloud-native horizontally-scalable distributed database system that is built around MySQL.
Vitess can achieve unlimited scaling through generalized sharding.

Vitess allows application code and database queries to remain agnostic to the distribution of data onto
multiple database servers. With Vitess, you can even split and merge shards as your needs
grow, with an atomic cutover step that takes only a few seconds.

Vitess was a core component of YouTube's database infrastructure
from 2011, and grew to encompass tens of thousands of MySQL nodes.
Starting in 2015, Vitess was adopted by many other large companies, including Slack, Square (now Block), and JD.com.

For more about Vitess, please visit vitess.io.

Community Copy Chapter

Vitess has a growing community.

If you are interested in contributing or participating in our monthly community meetings, please visit the Community page on our website.

We also maintain a roadmap on our website.

Follow our blog for low-frequency updates like new features and releases.

Reporting a Problem, Issue, or Bug Copy Chapter

To report a problem, create a GitHub issue.

For topics that are better discussed live, please join the Vitess Slack workspace.
You may post any questions on the #general channel or join some of the special-interest channels.

Security Copy Chapter

Reporting Security Vulnerabilities Copy Section

To report a security vulnerability, please email vitess-maintainers.

See Security for a full outline of the security process.

Security Audit Copy Section

A third party security audit was performed by ADA Logics. Read the full report.

License Copy Chapter

Unless otherwise noted, the Vitess source files are distributed
under the Apache Version 2.0 license found in the LICENSE file.