---
alwaysApply: true
description: Database interaction rules and interface requirements
---

# Database Interface Rules

## STRICT Database Interface Usage

**ALL database interactions MUST be done through the database interface defined in [db.go](mdc:db.go).**

### NEVER Use Raw GORM Calls
- **DO NOT** call `db.DB().Where(...)` directly
- **DO NOT** call `db.DB().Save(...)` directly  
- **DO NOT** call `db.DB().First(...)` directly
- **DO NOT** call `db.DB().Create(...)` directly

### ALWAYS Use Interface Methods
Use the high-level methods defined in the DB interface:
- `GetCharacterByName(characterName string) (*Character, error)`
- `SaveCharacter(character *Character) error`
- `AutoMigrate(dst ...interface{}) error`

### Database Interface Location
The database interface is defined in [db.go](mdc:db.go) and provides:
- `DB() *gorm.DB` - Access to underlying GORM instance
- `Raw(sql string, args ...any) *gorm.DB` - For raw SQL when needed
- High-level methods for all database operations

### Why This Rule Exists
- **Abstraction**: Database operations are abstracted behind a clean interface
- **Testing**: Interface allows for easy mocking and testing
- **Consistency**: All database operations follow the same patterns
- **Maintainability**: Changes to database logic are centralized

### Cache Operations
For cache operations, use the database interface methods:
- Store cache entries through the interface
- Retrieve cache entries through the interface
- Never bypass the interface for any database operations

### Error Handling
- Always log database operations with appropriate context
- Include character names and operation details in log messages
- Handle errors gracefully and log them with context