README
¶
Bun Provider Example
This example demonstrates the Bun provider for the Go Persistence API (GPA), showcasing advanced SQL operations, query building, and Bun's powerful ORM capabilities.
Features Demonstrated
Core SQL Operations
- Schema Migration: Automatic table creation and schema management
- Advanced Queries: Complex SQL with joins, subqueries, and window functions
- Relationship Mapping: Foreign key relationships and eager loading
- Index Management: Creating and optimizing database indexes
- Batch Operations: Efficient bulk operations for better performance
Bun-Specific Features
- Query Builder: Fluent, type-safe query construction
- Struct Mapping: Automatic mapping between Go structs and database tables
- Relation Loading: Efficient loading of related data
- Raw SQL Support: Direct SQL execution when needed
- Hook System: Before/after operation hooks
- Debug Mode: Query logging and performance monitoring
Advanced Patterns
- Window Functions: Advanced analytics with SQL window functions
- Aggregation: Complex aggregation queries and analytics
- Transaction Management: ACID transactions with rollback support
- Performance Optimization: Efficient queries and batch operations
- Schema Introspection: Runtime schema information and metadata
Prerequisites
- Go 1.18+
- SQLite3 (included with Go)
Optional for other databases:
- PostgreSQL 12+
- MySQL 8.0+
- SQL Server 2019+
Quick Start
# Navigate to this directory
cd examples/gpabun
# Install dependencies
go mod tidy
# Run the example
go run main.go
Database Configuration
The example uses SQLite by default for simplicity:
config := gpa.Config{
Driver: "sqlite",
Database: "bun_example.db",
Options: map[string]interface{}{
"bun": map[string]interface{}{
"debug": true,
"log_slow_query": true,
"slow_query_time": "100ms",
},
},
}
Other Database Examples
PostgreSQL
config := gpa.Config{
Driver: "postgres",
Host: "localhost",
Port: 5432,
Username: "user",
Password: "password",
Database: "gpa_bun_example",
SSL: gpa.SSLConfig{
Enabled: true,
Mode: "require",
},
Options: map[string]interface{}{
"bun": map[string]interface{}{
"debug": true,
"max_open_conns": 25,
"max_idle_conns": 25,
},
},
}
MySQL
config := gpa.Config{
Driver: "mysql",
Host: "localhost",
Port: 3306,
Username: "user",
Password: "password",
Database: "gpa_bun_example",
Options: map[string]interface{}{
"bun": map[string]interface{}{
"debug": true,
"parse_time": true,
},
},
}
Code Structure
Entity Definitions
type User struct {
ID int64 `bun:"id,pk,autoincrement"`
Name string `bun:"name,notnull"`
Email string `bun:"email,unique,notnull"`
Age int `bun:"age,notnull"`
IsActive bool `bun:"is_active,default:true"`
Salary *float64 `bun:"salary,nullzero"` // Nullable field
CreatedAt time.Time `bun:"created_at,default:current_timestamp"`
UpdatedAt time.Time `bun:"updated_at,default:current_timestamp"`
Profile *Profile `bun:"rel:has-one,join:id=user_id"`
Posts []*Post `bun:"rel:has-many,join:id=user_id"`
}
Repository Operations
// Type-safe provider creation
provider, err := gpabun.NewTypeSafeProvider[User](config)
repo := provider.Repository()
// Basic CRUD operations
err := repo.Create(ctx, &user)
user, err := repo.FindByID(ctx, 1)
err := repo.Update(ctx, &user)
err := repo.Delete(ctx, 1)
SQL-Specific Operations
if sqlRepo, ok := repo.(gpa.SQLRepository[User]); ok {
// Raw SQL queries
users, err := sqlRepo.FindBySQL(ctx,
`SELECT u.*, p.bio FROM users u
LEFT JOIN profiles p ON u.id = p.user_id
WHERE u.age > ? AND u.is_active = ?`,
[]interface{}{25, true})
// Execute raw SQL commands
result, err := sqlRepo.ExecSQL(ctx,
"UPDATE users SET updated_at = ? WHERE id = ?",
time.Now(), userID)
// Create indexes
err := sqlRepo.CreateIndex(ctx, []string{"email"}, true)
// Load rel
users, err := sqlRepo.FindWithRelations(ctx, []string{"Profile", "Posts"})
}
Migration Operations
if migratableRepo, ok := repo.(gpa.MigratableRepository[User]); ok {
// Auto-migrate schema
err := migratableRepo.MigrateTable(ctx)
// Get migration status
status, err := migratableRepo.GetMigrationStatus(ctx)
// Get table information
tableInfo, err := migratableRepo.GetTableInfo(ctx)
}
Key Concepts
Bun Tags
Bun uses struct tags to control database mapping:
type User struct {
ID int64 `bun:"id,pk,autoincrement"` // Primary key with auto-increment
Name string `bun:"name,notnull"` // Not null constraint
Email string `bun:"email,unique,notnull"` // Unique constraint
Age int `bun:"age,notnull"` // Not null
IsActive bool `bun:"is_active,default:true"` // Default value
Salary *float64 `bun:"salary,nullzero"` // Nullable field
CreatedAt time.Time `bun:"created_at,default:current_timestamp"`
Profile *Profile `bun:"rel:has-one,join:id=user_id"` // One-to-one relationship
Posts []*Post `bun:"rel:has-many,join:id=user_id"` // One-to-many relationship
}
Type Safety
All operations are type-safe at compile time:
// This won't compile if User doesn't match the repository type
var user User
err := repo.Create(ctx, &user)
Query Building
Fluent query interface with type safety:
users, err := repo.Query(ctx,
gpa.Where("age", gpa.OpGreaterThan, 18),
gpa.Where("is_active", gpa.OpEqual, true),
gpa.WhereNotNull("salary"),
gpa.OrderBy("name", gpa.OrderAsc),
gpa.Limit(10),
gpa.Offset(20),
)
Error Handling
Structured errors with Bun-specific context:
if gpa.IsErrorType(err, gpa.ErrorTypeNotFound) {
// Handle record not found
}
if gpa.IsErrorType(err, gpa.ErrorTypeConstraintViolation) {
// Handle unique constraint violation
}
Transactions
Automatic transaction management:
err := repo.Transaction(ctx, func(tx gpa.Transaction[User]) error {
if err := tx.Create(ctx, &user1); err != nil {
return err // Automatic rollback
}
if err := tx.Update(ctx, &user2); err != nil {
return err // Automatic rollback
}
return nil // Commit
})
Advanced Features
Complex Queries
// Subquery example
topPosters, err := sqlRepo.FindBySQL(ctx, `
SELECT u.* FROM users u
WHERE u.id IN (
SELECT p.user_id
FROM posts p
WHERE p.published = ?
GROUP BY p.user_id
HAVING COUNT(*) >= ?
)
ORDER BY u.name
`, []interface{}{true, 2})
Window Functions
// Ranking with window functions
rankedUsers, err := sqlRepo.FindBySQL(ctx, `
SELECT
name,
age,
salary,
ROW_NUMBER() OVER (ORDER BY age DESC) as age_rank,
RANK() OVER (ORDER BY COALESCE(salary, 0) DESC) as salary_rank
FROM users
WHERE is_active = ?
ORDER BY age_rank
`, []interface{}{true})
Aggregation
// Complex aggregation
stats, err := sqlRepo.FindBySQL(ctx, `
SELECT
COUNT(*) as total_users,
COUNT(CASE WHEN is_active THEN 1 END) as active_users,
AVG(age) as avg_age,
AVG(CASE WHEN salary IS NOT NULL THEN salary END) as avg_salary
FROM users
`, []interface{}{})
Relationship Loading
// Load users with profiles and posts
users, err := sqlRepo.FindWithRelations(ctx,
[]string{"Profile", "Posts"},
gpa.Where("is_active", gpa.OpEqual, true))
// Access related data
for _, user := range users {
fmt.Printf("User: %s\n", user.Name)
if user.Profile != nil {
fmt.Printf(" Bio: %s\n", user.Profile.Bio)
}
fmt.Printf(" Posts: %d\n", len(user.Posts))
}
Performance Tips
- Use Indexes: Create indexes on frequently queried columns
- Batch Operations: Use
CreateBatch()for multiple inserts - Limit Results: Use
Limit()andOffset()for pagination - Select Specific Fields: Use raw SQL to select only needed columns
- Optimize Relationships: Use
FindWithRelations()to avoid N+1 queries
Testing
The example includes comprehensive testing scenarios:
- Schema migration and rollback
- Complex query patterns
- Transaction handling
- Error conditions
- Performance benchmarks
Common Patterns
Repository Pattern
type UserService struct {
repo gpa.Repository[User]
}
func (s *UserService) GetActiveUsers(ctx context.Context) ([]*User, error) {
return s.repo.Query(ctx,
gpa.Where("is_active", gpa.OpEqual, true),
gpa.OrderBy("created_at", gpa.OrderDesc),
)
}
Service Layer
func (s *UserService) CreateUserWithProfile(ctx context.Context, user *User, profile *Profile) error {
return s.repo.Transaction(ctx, func(tx gpa.Transaction[User]) error {
if err := tx.Create(ctx, user); err != nil {
return err
}
profile.UserID = user.ID
return s.profileRepo.Create(ctx, profile)
})
}
Query Builder Pattern
func (s *UserService) SearchUsers(ctx context.Context, filters UserFilters) ([]*User, error) {
conditions := []gpa.QueryOption{}
if filters.MinAge > 0 {
conditions = append(conditions, gpa.Where("age", gpa.OpGreaterThanOrEqual, filters.MinAge))
}
if filters.IsActive != nil {
conditions = append(conditions, gpa.Where("is_active", gpa.OpEqual, *filters.IsActive))
}
if filters.Name != "" {
conditions = append(conditions, gpa.WhereLike("name", filters.Name+"%"))
}
conditions = append(conditions, gpa.OrderBy("name", gpa.OrderAsc))
return s.repo.Query(ctx, conditions...)
}
Troubleshooting
Common Issues
- Migration Errors: Check database permissions and schema conflicts
- Constraint Violations: Handle unique constraints and foreign key errors
- Performance Issues: Add indexes and optimize queries
- Connection Issues: Verify database connection settings
Debug Tips
- Enable Debug Mode: Set
debug: truein Bun options - Log Slow Queries: Use
log_slow_queryandslow_query_timeoptions - Check Query Plans: Use
EXPLAIN QUERY PLANfor SQLite - Monitor Connections: Watch connection pool usage
Performance Debugging
// Enable query logging
config := gpa.Config{
Driver: "sqlite",
Database: "app.db",
Options: map[string]interface{}{
"bun": map[string]interface{}{
"debug": true,
"log_slow_query": true,
"slow_query_time": "100ms",
},
},
}
Environment Variables
# Database configuration
export DB_DRIVER="postgres"
export DB_HOST="localhost"
export DB_PORT="5432"
export DB_USER="user"
export DB_PASSWORD="password"
export DB_NAME="gpa_bun_example"
# SSL configuration
export DB_SSL_MODE="require"
# Connection pooling
export DB_MAX_OPEN_CONNS="25"
export DB_MAX_IDLE_CONNS="25"
export DB_CONN_MAX_LIFETIME="5m"
Production Considerations
- Connection Pooling: Configure appropriate pool sizes
- Migration Strategy: Use versioned migrations in production
- Error Handling: Implement proper error logging and monitoring
- Performance Monitoring: Track query performance and optimize
- Security: Use parameterized queries and validate inputs
Next Steps
- Explore other providers: MongoDB, Redis, GORM
- Review the main documentation for architecture details
- Check the test files for additional usage patterns
- Consider implementing custom query builders for complex use cases
- Explore Bun's advanced features like hooks and plugins
Documentation
¶
There is no documentation for this package.
Click to show internal directories.
Click to hide internal directories.