xdb

xdb

A multi-database connection wrapper library built on GORM, supporting MySQL, PostgreSQL, SQLite, SQL Server, and ClickHouse.

Installation

go get github.com/sk-pkg/xdb

Quick Start

Single Database Connection

package main

import (
    "log"

    "github.com/sk-pkg/xdb"
    "gorm.io/gorm"
)

type Product struct {
    gorm.Model
    Code  string
    Price uint
}

func main() {
    // Create database connection using DBConfig (recommended)
    db, err := xdb.New(xdb.WithDBConfig(xdb.DBConfig{
        Driver:   xdb.MySQL,
        Host:     "127.0.0.1",
        Port:     3306,
        User:     "root",
        Password: "secret",
        DBName:   "mydb",
    }))
    if err != nil {
        log.Fatal("failed to connect database:", err)
    }

    // Auto migrate schema
    db.AutoMigrate(&Product{})

    // Create
    db.Create(&Product{Code: "D42", Price: 100})

    // Read
    var product Product
    db.First(&product, 1)
    db.First(&product, "code = ?", "D42")

    // Update
    db.Model(&product).Update("Price", 200)

    // Delete
    db.Delete(&product, 1)
}

Multiple Database Connections

package main

import (
    "log"

    "github.com/sk-pkg/xdb"
)

func main() {
    // Create multiple database connections
    dbs, err := xdb.NewMulti(
        []xdb.Option{
            xdb.WithHost("127.0.0.1"),
            xdb.WithPort(3306),
            xdb.WithUser("root"),
            xdb.WithPassword("secret"),
            xdb.WithDBName("master_db"),
        },
        []xdb.Option{
            xdb.WithHost("127.0.0.1"),
            xdb.WithPort(3307),
            xdb.WithUser("root"),
            xdb.WithPassword("secret"),
            xdb.WithDBName("slave_db"),
        },
    )
    if err != nil {
        log.Fatal("failed to connect database:", err)
    }
    defer xdb.CloseAll(dbs)

    // Use specific database (key is dbName)
    masterDB := dbs["master_db"]
    slaveDB := dbs["slave_db"]

    // Perform operations...
    _ = masterDB
    _ = slaveDB
}

Supported Databases

PostgreSQL Example

db, err := xdb.New(
    xdb.WithDriver(xdb.PostgreSQL),
    xdb.WithHost("localhost"),
    xdb.WithPort(5432),
    xdb.WithUser("postgres"),
    xdb.WithPassword("secret"),
    xdb.WithDBName("mydb"),
    xdb.WithSSLMode("disable"),
    xdb.WithTimezone("Asia/Shanghai"),
)

SQLite Example

db, err := xdb.New(
    xdb.WithDriver(xdb.SQLite),
    xdb.WithHost("./data.db"), // File path
)

Configuration Options

Using DBConfig (Recommended)

WithDBConfig allows you to set all options at once using a struct:

db, err := xdb.New(xdb.WithDBConfig(xdb.DBConfig{
    Driver:          xdb.MySQL,
    Host:            "127.0.0.1",
    Port:            3306,
    User:            "root",
    Password:        "secret",
    DBName:          "mydb",
    Charset:         "utf8mb4",
    MaxIdleConns:    10,
    MaxOpenConns:    100,
    ConnMaxLifetime: 3 * time.Hour,
}))

Connection Options

Driver-Specific Options

Connection Pool Options

GORM Configuration

db, err := xdb.New(
    xdb.WithHost("localhost"),
    xdb.WithDBName("mydb"),
    xdb.WithGormConfig(gorm.Config{
        SkipDefaultTransaction: true,
        Logger: customLogger,
    }),
)

Logging

xdb provides a GORM logger adapter that integrates with sk-pkg/logger.

Creating a Logger

import (
    "github.com/sk-pkg/logger"
    "github.com/sk-pkg/xdb"
    "gorm.io/gorm"
)

// Initialize logger manager
manager, err := logger.New()
if err != nil {
    log.Fatal(err)
}

// Create database logger
dbLogger := xdb.NewLog(manager,
    xdb.WithLevel("info"),
    xdb.WithSlowThreshold(200 * time.Millisecond),
    xdb.WithIgnoreRecordNotFoundError(true),
)

// Use with database
db, err := xdb.New(
    xdb.WithHost("localhost"),
    xdb.WithDBName("mydb"),
    xdb.WithGormConfig(gorm.Config{
        Logger: dbLogger,
    }),
)

Logger Options

Context Tracing

// Add trace_id to context
ctx := context.WithValue(context.Background(), "trace_id", "123456")
db = db.WithContext(ctx)

// Subsequent queries will include trace_id in logs
db.First(&product, 1)

Utility Functions

Health Check

db, err := xdb.New(...)
if err != nil {
    log.Fatal(err)
}

// Check if connection is healthy
if err := xdb.Ping(db); err != nil {
    log.Fatal("database connection failed:", err)
}

Closing Connections

// Close single connection
if err := xdb.Close(db); err != nil {
    log.Error("failed to close connection:", err)
}

// Close multiple connections
if err := xdb.CloseAll(dbs); err != nil {
    log.Error("failed to close connections:", err)
}

Connection Pool Stats

stats, err := xdb.Stats(db)
if err != nil {
    log.Error(err)
}

fmt.Printf("Open connections: %d\n", stats.OpenConnections)
fmt.Printf("In use: %d\n", stats.InUse)
fmt.Printf("Idle: %d\n", stats.Idle)

Notes

1. Set appropriate log levels in production to avoid excessive logging
2. Configure slow query threshold based on your application requirements
3. Using WithIgnoreRecordNotFoundError(true) reduces unnecessary error logs
4. SQLite does not support connection pool settings

Documentation

• GORM Documentation
• 中文文档

License

MIT