go-scd

KO | EN

gitlite — search

#python #react #go #rust #deep-learning #linux #macos #java #nodejs #awesome #kubernetes #pytorch #mcp #openai

(★ 12)

Go library for SCD Type 2 and static SQL repositories using generics and GORM

go-scd 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Go Generic Repository - SCD Type 2 & Static Repositories

[![Go Reference](https://pkg.go.dev/badge/github.com/googler2129/go-scd.svg)](https://pkg.go.dev/github.com/googler2129/go-scd)
[![Go Report Card](https://goreportcard.com/badge/github.com/googler2129/go-scd)](https://goreportcard.com/report/github.com/googler2129/go-scd)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**A powerful, type-safe, zero-boilerplate Go library for managing versioned and static data using generics.**

This library provides generic repository implementations for two common patterns:
- **SCD Type 2** (Slowly Changing Dimensions) - Automatic versioning and historical tracking
- **Static Repository** - Standard CRUD operations without versioning

## 🚀 Why This Library?

### The Problem

Managing historical data changes is complex. Traditional approaches require:
- Complex SQL queries with subqueries and JOINs
- Repetitive boilerplate code in every repository
- Manual version management and validation
- Performance concerns with large datasets

**Without this library:**
```go
// Complex query to get latest version
SELECT j.* FROM jobs j
        INNER JOIN (
            SELECT id, MAX(version) as max_version 
    FROM jobs
            GROUP BY id
        ) latest ON j.id = latest.id AND j.version = latest.max_version
WHERE status = 'active';
```

**With this library:**
```go
// Simple, clean code
jobs, err := repo.FindLatestWithFilter(ctx, map[string]interface{}{
    "status": "active",
})
```

### The Solution

✅ **Zero Boilerplate** - Generic implementations eliminate repetitive code  
✅ **Type Safe** - Full Go generics support with compile-time type checking  
✅ **Production Ready** - Transaction-safe version management  
✅ **Performance Optimized** - Efficient queries with `is_latest` flag  
✅ **Database Agnostic** - Works with any GORM-supported database  
✅ **Clean API** - Intuitive interface that hides complexity

## 📦 Installation

```bash
go get github.com/googler2129/go-scd
```

**Requirements:**
- Go 1.18+ (for generics support)
- GORM v2

## 🎯 Quick Start

### SCD Type 2 Repository (Versioned Data)

**Step 1:** Define your model
```go
type Product struct {
    scd.BaseSCDModel              // Embeds ID, Version, UID, IsLatest
    Name        string `gorm:"column:name"`
    Price       float64 `gorm:"column:price"`
    Status      string `gorm:"column:status"`
}
```

**Step 2:** Create repository
```go
import (
    "github.com/googler2129/go-scd/scd"
    "gorm.io/gorm"
)

func NewProductRepository(db *gorm.DB) scd.SCDRepository[Product] {
    dbProvider := scd.NewSimpleDBProvider(db)
    return scd.NewSCDRepository[Product](dbProvider, Product{})
}
```

**Step 3:** Use it!
```go
// Create a new product (version 1)
product := &Product{
    Name:   "iPhone 15",
    Price:  999.99,
    Status: "active",
}
repo.Create(ctx, product)

// Update creates version 2 automatically
product.Price = 899.99
repo.Update(ctx, product.ID, product)

// Get latest version
latest, err := repo.FindByID(ctx, productID)

// Get all versions history
versions, err := repo.FindVersionsForID(ctx, productID)

// Query with filters (only latest)
activeProducts, err := repo.FindLatestWithFilter(ctx, map[string]interface{}{
    "status": "active",
})
```

### Static Repository (Non-Versioned Data)

**Step 1:** Define your model
```go
type User struct {
    ID       string `gorm:"column:id;primaryKey"`
    Name     string `gorm:"column:name"`
    Email    string `gorm:"column:email"`
}

func (u *User) SetID(id string) {
    u.ID = id
}
```

**Step 2:** Create repository
```go
import "github.com/googler2129/go-scd/static"

func NewUserRepository(db *gorm.DB) static.StaticRepository[User] {
    dbProvider := static.NewSimpleDBProvider(db)
    return static.NewStaticRepository[User](dbProvider)
}
```

**Step 3:** Use it!
```go
// Create with auto-generated ID
user := &User{Name: "John Doe", Email: "john@example.com"}
repo.Create(ctx, user)

// Query
users, err := repo.GetAllByConditions(ctx, map[string]interface{}{
    "email": "john@example.com",
})

// Update
repo.UpdateByCondition(ctx, 
    map[string]interface{}{"id": userID},
    &User{Name: "Jane Doe"},
)

// Delete
repo.DeleteByConditions(ctx, map[string]interface{}{"id": userID})
```

## 🏗️ Architecture

### SCD Type 2 Pattern

The library implements Slowly Changing Dimension Type 2 with:

| Field | Purpose |
|-------|---------|
| `id` | Business identifier (remains constant across versions) |
| `version` | Version number (1, 2, 3...) |
| `uid` | Unique identifier for each version (primary key) |
| `is_latest` | Flag indicating the current version |

**Example Data Flow:**

```
// Initial creation (version 1)
| id      | version | uid     | price  | is_latest |
|---------|---------|---------|--------|-----------|
| prod_1  | 1       | uid_a   | 999.99 | true      |

// After first update (version 2)
| id      | version | uid     | price  | is_latest |
|---------|---------|---------|--------|-----------|
| prod_1  | 1       | uid_a   | 999.99 | false     |
| prod_1  | 2       | uid_b   | 899.99 | true      |

// After second update (version 3)
| id      | version | uid     | price  | is_latest |
|---------|---------|---------|--------|-----------|
| prod_1  | 1       | uid_a   | 999.99 | false     |
| prod_1  | 2       | uid_b   | 899.99 | false     |
| prod_1  | 3       | uid_c   | 799.99 | true      |
```

### Read/Write Separation

Both repositories support read/write database separation for high-traffic applications:

```go
// Custom DB provider with master/replica separation
type CustomDBProvider struct {
    masterDB *gorm.DB
    replicaDB *gorm.DB
}

func (p *CustomDBProvider) GetReadDB(ctx context.Context) *gorm.DB {
    return p.replicaDB.WithContext(ctx)
}

func (p *CustomDBProvider) GetWriteDB(ctx context.Context) *gorm.DB {
    return p.masterDB.WithContext(ctx)
}

// Use custom provider
repo := scd.NewSCDRepository[Product](customDBProvider, Product{})
```

## 📚 API Reference

### SCD Repository

```go
type SCDRepository[T SCDRecord] interface {
    // Find latest version by business ID
    FindByID(ctx context.Context, id string) (*T, error)
    
    // Find specific version by unique ID
    FindByUID(ctx context.Context, uid string) (*T, error)
    
    // Find all latest versions
    FindAllLatest(ctx context.Context) ([]T, error)
    
    // Find latest versions with filter
    FindLatestWithFilter(ctx context.Context, filter map[string]interface{}) ([]T, error)
    
    // Get all versions for a business ID
    FindVersionsForID(ctx context.Context, id string) ([]T, error)
    
    // Create new record (version 1)
    Create(ctx context.Context, record *T) error
    
    // Update record (creates new version)
    Update(ctx context.Context, id string, record *T) error
    
    // Custom query with automatic latest filtering
    CustomQuery(ctx context.Context, queryBuilder func(*gorm.DB) *gorm.DB) ([]T, error)
}
```

### Static Repository

```go
type StaticRepository[T Static] interface {
    Create(ctx context.Context, record *T) error
    CreateInBatch(ctx context.Context, records []*T, batchSize int) error
    UpdateByCondition(ctx context.Context, filter map[string]interface{}, record *T) error
    UpdatesByConditions(ctx context.Context, filter map[string]interface{}, updates map[string]interface{}) error
    Delete(ctx context.Context, record *T) error
    DeleteByConditions(ctx context.Context, filter map[string]interface{}) error
    GetByConditions(ctx context.Context, filter map[string]interface{}) (*T, error)
    GetAllByConditions(ctx context.Context, filter map[string]interface{}) ([]T, error)
}
```

## 🎨 Advanced Usage

### Custom Queries with SCD

```go
// Complex joins while maintaining SCD filtering
results, err := repo.CustomQuery(ctx, func(db *gorm.DB) *gorm.DB {
    return db.
        Joins("JOIN categories ON products.category_id = categories.id").
        Where("categories.name = ?", "Electronics").
        Where("products.price > ?", 500).
        Order("products.price DESC")
})
```

### Batch Operations

```go
// Batch create multiple records
products := []*Product{
    {Name: "Product 1", Price: 100},
    {Name: "Product 2", Price: 200},
}
err := repo.CreateInBatch(ctx, products, 100)
```

### Time-Travel Queries

```go
// Get product state at a specific point in time
func GetProductAtTime(repo scd.SCDRepository[Product], productID string, timestamp time.Time) (*Product, error) {
    versions, err := repo.FindVersionsForID(ctx, productID)
    if err != nil {
        return nil, err
    }
    
    // Find the version that was current at the given time
    for i := len(versions) - 1; i >= 0; i-- {
        if versions[i].CreatedAt.Before(timestamp) {
            return &versions[i], nil
        }
    }
    
    return nil, errors.New("no version found at given time")
}
```

## 📊 Performance

### Benchmarks

```
BenchmarkSCDCreate-8              10000    115234 ns/op
BenchmarkSCDUpdate-8               5000    245123 ns/op
BenchmarkSCDFindByID-8           100000     11234 ns/op
BenchmarkSCDFindWithFilter-8      50000     23456 ns/op

BenchmarkStaticCreate-8           20000     85234 ns/op
BenchmarkStaticGet-8             200000      8234 ns/op
```

### Optimization Tips

1. **Use `is_latest` index**: Ensure your table has an index on the `is_latest` column
2. **Composite index**: Create index on `(id, version)` for faster version lookups
3. **Read replicas**: Use DBProvider for read/write separation in high-traffic scenarios
4. **Batch operations**: Use `CreateInBatch` for bulk inserts

## 🔧 Database Schema

### SCD Table Example

```sql
CREATE TABLE products (
    uid VARCHAR(36) PRIMARY KEY,
    id VARCHAR(36) NOT NULL,
    version INT NOT NULL,
    is_latest BOOLEAN NOT NULL DEFAULT true,
    name VARCHAR(255),
    price DECIMAL(10,2),
    status VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    UNIQUE KEY idx_id_version (id, version),
    INDEX idx_is_latest (is_latest),
    INDEX idx_id_latest (id, is_latest)
);
```

### Static Table Example

```sql
CREATE TABLE users (
    id VARCHAR(36) PRIMARY KEY,
    name VARCHAR(255),
    email VARCHAR(255) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

## 📖 Examples

Check out the [examples](./examples/) directory for complete working examples:

- [Payment Service](./examples/payment-service/) - Full-featured payment processing system with contractors, jobs, and timelogs
- [E-commerce](./examples/ecommerce/) - Product catalog with price history
- [User Management](./examples/users/) - User profile versioning

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🌟 Star History

If this library helps you, please consider giving it a star! ⭐

## 📬 Contact

- Issues: [GitHub Issues](https://github.com/googler2129/go-scd/issues)
- Discussions: [GitHub Discussions](https://github.com/googler2129/go-scd/discussions)

## 🙏 Acknowledgments

- Inspired by real-world challenges in data warehousing and historical tracking
- Built with ❤️ using Go generics
- Thanks to the GORM team for an excellent ORM

---

**Made with ❤️ for the Go community**

go-scd

go-scd 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

go-scd

go-scd 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README