docs: Add CLAUDE.md with codebase guidance

Create comprehensive documentation for future Claude Code instances working in this repository, including:
- Development commands for testing, building, and code quality
- Core architecture overview of the SQL query builder system
- Directory structure and component explanations
- Testing patterns and conventions
- Key dependencies and their purposes

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

engine/engine.go

@@ -1,6 +1,7 @@
 package engine
 
 import (
+	"context"
 	"database/sql"
 	"fmt"
 
@@ -8,15 +9,16 @@ import (
 
 	_ "github.com/denisenkom/go-mssqldb"
 	_ "github.com/go-sql-driver/mysql"
+	"github.com/mattn/go-sqlite3"
 	_ "github.com/mattn/go-sqlite3"
 
-	_ "git.fsdpf.net/go/db/v2/dialect/mysql"
-	_ "git.fsdpf.net/go/db/v2/dialect/postgres"
-	_ "git.fsdpf.net/go/db/v2/dialect/sqlite3"
-	_ "git.fsdpf.net/go/db/v2/dialect/sqlserver"
+	_ "git.fsdpf.net/go/db/dialect/mysql"
+	_ "git.fsdpf.net/go/db/dialect/postgres"
+	_ "git.fsdpf.net/go/db/dialect/sqlite3"
+	_ "git.fsdpf.net/go/db/dialect/sqlserver"
 
-	"git.fsdpf.net/go/db/v2"
-	"git.fsdpf.net/go/db/v2/internal/errors"
+	"git.fsdpf.net/go/db"
+	"git.fsdpf.net/go/db/internal/errors"
 )
 
 type Engine struct {
@@ -50,12 +52,31 @@ func (e Engine) Connection(name string) *db.Database {
 	return db.New(cfg.Driver, _db)
 }
 
-func (e Engine) MakeConnection(cfg DBConfig) *sql.DB {
+func (e Engine) MakeConnection(cfg DBConfig) (db *sql.DB) {
 	dsn := cfg.ToDSN()
 
 	switch cfg.Driver {
 	case "mysql":
 	case "sqlite3":
+		defer func() {
+			if r := recover(); r != nil {
+				panic(r)
+			}
+			if cfg.SQLite.Raw == nil {
+				return
+			}
+			conn, err := db.Conn(context.Background())
+			if err != nil {
+				panic(err)
+			}
+			err = conn.Raw(func(driverConn any) error {
+				sqliteConn := driverConn.(*sqlite3.SQLiteConn)
+				return cfg.SQLite.Raw(sqliteConn)
+			})
+			if err != nil {
+				panic(err)
+			}
+		}()
 	case "sqlserver":
 	case "postgres":
 		if url, err := pq.ParseURL(dsn); err == nil {
@@ -80,10 +101,18 @@ func (e Engine) MakeConnection(cfg DBConfig) *sql.DB {
 	return db
 }
 
-func Open(cfgs map[string]DBConfig) *Engine {
+func Open(cfgs map[string]DBConfig) Engine {
 	for n, cfg := range cfgs {
 		_engine.configs[n] = cfg
 	}
 
-	return _engine
+	return *_engine
+}
+
+func Mock(cfgs map[string]MockDBConfig) Engine {
+	for k, cfg := range cfgs {
+		_engine.dbs[k] = cfg.Mock
+		_engine.configs[k] = DBConfig{Driver: cfg.Driver}
+	}
+	return *_engine
 }

engine/engine_config.go

@@ -1,11 +1,19 @@
 package engine
 
 import (
+	"database/sql"
 	"fmt"
 	"net/url"
 	"time"
+
+	"github.com/mattn/go-sqlite3"
 )
 
+type MockDBConfig struct {
+	Driver string
+	Mock   *sql.DB
+}
+
 // DBConfig 数据库配置结构体
 type DBConfig struct {
 	Driver          string
@@ -48,6 +56,7 @@ type DBConfig struct {
 		Synchronous int
 		Cache       string
 		BusyTimeout int
+		Raw         func(*sqlite3.SQLiteConn) error
 	}
 
 	SQLServer struct {
@@ -379,6 +388,16 @@ func WithSQLiteFile(file string) Option {
 	}
 }
 
+// SQLite 注册函数
+func WithSQLiteRaw(raw func(*sqlite3.SQLiteConn) error) Option {
+	return func(c *DBConfig) {
+		if c.Driver != "sqlite3" {
+			panic("WithSQLiteRegFn is only valid for sqlite3 driver")
+		}
+		c.SQLite.Raw = raw
+	}
+}
+
 func WithSQLiteJournal(journal string) Option {
 	return func(c *DBConfig) {
 		if c.Driver != "sqlite3" {

engine/engine_config_test.go

@@ -4,7 +4,7 @@ import (
 	"testing"
 	"time"
 
-	"git.fsdpf.net/go/db/v2/engine"
+	"git.fsdpf.net/go/db/engine"
 )
 
 // TestMySQLConfig 测试 MySQL 驱动的配置