goSqlite

[!NOTE] This README was generated by Claude Code, get the ZH version from here.

go-sqlite

Lightweight Go SQLite wrapper with read/write connection pool separation and chainable Query Builder.

Table of Contents

• Features
• Installation
• Usage
• API Reference
• License
• Author
• Stars

Features

• Read/Write Separation: Independent read and write connection pools optimized for high concurrency
• WAL Mode: Write-Ahead Logging enabled by default for improved write performance
• Chainable API: Fluent Query Builder syntax supporting SELECT, INSERT, UPDATE, DELETE
• Comprehensive Conditions: WHERE, OR WHERE, HAVING, OR HAVING and various condition combinations
• JOIN Support: INNER JOIN, LEFT JOIN for cross-table queries
• Aggregate Queries: GROUP BY, HAVING, COUNT and other aggregate operations
• Conflict Handling: INSERT OR IGNORE/REPLACE/ABORT/FAIL/ROLLBACK
• Batch Insert: InsertBatch for inserting multiple records in one operation
• Context Support: All operations support context.Context propagation
• Auto Checkpoint: Background WAL checkpoint execution to maintain database performance

Installation

go get github.com/pardnchiu/go-sqlite

Usage

Initialize Connection

import (
    goSqlite "github.com/pardnchiu/go-sqlite"
    "github.com/pardnchiu/go-sqlite/core"
)

conn, err := goSqlite.New(core.Config{
    Path:         "./data.db",
    MaxOpenConns: 50,  // Read connection pool limit
    MaxIdleConns: 25,  // Idle connection limit
    Lifetime:     120, // Connection lifetime in seconds
})
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

Create Table

err := conn.Write.Table("users").Create(
    core.Column{Name: "id", Type: "INTEGER", IsPrimary: true, AutoIncrease: true},
    core.Column{Name: "name", Type: "TEXT", IsNullable: false},
    core.Column{Name: "email", Type: "TEXT", IsUnique: true},
    core.Column{Name: "age", Type: "INTEGER", Default: 0},
)

INSERT

// Single insert
id, err := conn.Write.Table("users").Insert(map[string]any{
    "name":  "Alice",
    "email": "alice@example.com",
})

// With conflict handling
id, err := conn.Write.Table("users").
    Conflict(core.Replace).
    Insert(map[string]any{"name": "Bob"})

// Batch insert
affected, err := conn.Write.Table("users").InsertBatch([]map[string]any{
    {"name": "User1", "email": "u1@example.com"},
    {"name": "User2", "email": "u2@example.com"},
})

SELECT

// Select all
rows, err := conn.Read.Table("users").Get()

// With columns and conditions
rows, err := conn.Read.Table("users").
    Select("id", "name", "email").
    WhereEq("status", 1).
    WhereGt("age", 18).
    OrderBy("created_at", core.Desc).
    Limit(10).
    Get()

// Single row
row, err := conn.Read.Table("users").WhereEq("id", 1).First()

// Count
count, err := conn.Read.Table("users").WhereEq("status", 1).Count()

// Paginated query with total count
rows, err := conn.Read.Table("users").
    Total().
    Limit(20, 10). // offset=20, limit=10
    Get()

UPDATE

// Basic update
affected, err := conn.Write.Table("users").
    WhereEq("id", 1).
    Update(map[string]any{"name": "NewName"})

// Increment/Decrement
affected, err := conn.Write.Table("users").
    WhereEq("id", 1).
    Increase("login_count").
    Update()

affected, err := conn.Write.Table("users").
    WhereEq("id", 1).
    Decrease("credits", 10).
    Update()

// Toggle boolean
affected, err := conn.Write.Table("users").
    WhereEq("id", 1).
    Toggle("is_active").
    Update()

DELETE

// Conditional delete
affected, err := conn.Write.Table("users").
    WhereEq("status", 0).
    Delete()

// Full table delete requires force confirmation
affected, err := conn.Write.Table("users").Delete(true)

JOIN

rows, err := conn.Read.Table("orders").
    Select("orders.id", "users.name", "orders.amount").
    Join("users", "users.id = orders.user_id").
    WhereGt("orders.amount", 100).
    Get()

rows, err := conn.Read.Table("posts").
    LeftJoin("comments", "comments.post_id = posts.id").
    Get()

GROUP BY & HAVING

rows, err := conn.Read.Table("orders").
    Select("user_id", "SUM(amount) as total").
    GroupBy("user_id").
    HavingGt("total", 1000).
    Get()

Context Support

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

rows, err := conn.Read.Table("users").
    Context(ctx).
    WhereEq("status", 1).
    Get()

Raw SQL

// Query
rows, err := conn.Query("", "SELECT * FROM users WHERE id = ?", 1)

// Execute
result, err := conn.Exec("", "UPDATE users SET name = ? WHERE id = ?", "Bob", 1)

// Access underlying *sql.DB
db := conn.Read.Raw()

API Reference

Config

Connector

Builder - Chain Methods

Builder - Execute Methods

Conflict Modes

Column Definition

License

MIT License

Author

邱敬幃 Pardn Chiu

Stars

©️ 2026 邱敬幃 Pardn Chiu