XMySQL Server

https://github.com/zhukovaskychina/xmysql-server
Admin
XMySQL Server is a Go-based, MySQL-compatible database kernel project designed for single-machine...
Tokens:393,045
Snippets:3,962
Trust Score:6.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Replication Setup (Master)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/analysis/MISSING_FEATURES_LIST.md

Shows the basic SQL commands on the master server to configure replication, including setting the master host, user, and password, and starting the slave process. This is the foundation for high availability and read scaling.

```sql
-- 主库
CHANGE MASTER TO MASTER_HOST='master_host', MASTER_USER='repl', MASTER_PASSWORD='password';
START SLAVE;
```

--------------------------------

### Start XMySQL Server

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/client/CLIENT_README.md

Command to start the XMySQL server using a specified configuration file. Ensure you are in the project's root directory.

```bash
# 启动服务器 (在项目根目录)
go run main.go --configPath=conf/my.ini
```

--------------------------------

### Implement XMySQL Server Start Function in Go

Source: https://github.com/zhukovaskychina/xmysql-server/wiki/如何实现-MySQL-‐-第-02-篇：MySQL-架构全景图与分层设计

Provides the main `Start` function for the XMySQL Server, orchestrating the initialization of configuration, storage engine, query processor, network services, and background tasks before listening for connections.

```go
// XMySQL Server 主启动流程
func (s *XMySQLServer) Start() error {
    // 1. 初始化配置
    if err := s.initConfig(); err != nil {
        return fmt.Errorf("failed to init config: %v", err)
    }
    
    // 2. 初始化存储引擎
    if err := s.initStorageEngine(); err != nil {
        return fmt.Errorf("failed to init storage engine: %v", err)
    }
    
    // 3. 初始化查询处理器
    if err := s.initQueryProcessor(); err != nil {
        return fmt.Errorf("failed to init query processor: %v", err)
    }
    
    // 4. 初始化网络服务
    if err := s.initNetworkService(); err != nil {
        return fmt.Errorf("failed to init network service: %v", err)
    }
    
    // 5. 启动后台服务
    s.startBackgroundServices()
    
    // 6. 开始监听连接
    return s.listenAndServe()
}
```

--------------------------------

### Configure and Execute Incremental Defragmentation

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/storage-reports/STORAGE-003_TABLESPACE_DEFRAGMENTATION_REPORT.md

Sets up and initiates an incremental defragmentation process for a tablespace. This example demonstrates configuring the batch size and interval for incremental processing before starting the defragmentation.

```go
// 配置增量整理
config := &DefragmenterConfig{
    IncrementalBatchSize: 100,
    IncrementalInterval:  100 * time.Millisecond,
}
defragmenter := NewTablespaceDefragmenter(spaceManager, extentManager, bufferPool, config)

// 执行增量整理
err := defragmenter.Defragment(ctx, spaceID, DefragmentModeIncremental)
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/btree/BTREE_QUICKSTART_GUIDE.md

Download all necessary Go modules for the project.

```bash
go mod download
```

--------------------------------

### XMySQL Client Command Line Interface Example

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/client/CLIENT_README.md

An example of the XMySQL client's interactive command-line interface, showing a welcome message, connection details, and a sample SQL query execution with results.

```bash
欢迎使用 XMySQL 客户端!
连接到: 127.0.0.1:3308
用户: root
数据库: test

输入 'help' 查看帮助，输入 'quit' 或 'exit' 退出。

xmysql> SELECT * FROM users LIMIT 3;
+----+--------+------------------+
| id | name   | email            |
+----+--------+------------------+
| 1  | 张三   | zhang@example.com |
| 2  | 李四   | li@example.com    |
| 3  | 王五   | wang@example.com  |
+----+--------+------------------+
3 rows in set (0.001 sec)

xmysql> 

```

--------------------------------

### Package Comment Example in Go

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/CODING_STANDARDS.md

Every Go package must have a package comment explaining its purpose. The comment should start with `// Package [packagename] ...`.

```go
// Package types defines the core types and interfaces for the storage layer.
// It provides unified abstractions for pages, records, indexes, and other
// storage-related concepts.
package types
```

--------------------------------

### Create UnifiedExtent (Recommended)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p1-tasks/P1_1_BASEEXTENT_MIGRATION_REPORT.md

Example of creating a new UnifiedExtent instance. This is the recommended approach for new code.

```go
import "server/innodb/wrapper/extent"

// 创建Extent
ext := extent.NewUnifiedExtent(
    extentID,
    spaceID,
    startPage,
    extType,
    purpose,
)
```

--------------------------------

### Start XMySQL Server

Source: https://context7.com/zhukovaskychina/xmysql-server/llms.txt

Launches the XMySQL Server using a configuration file. Ensure the configuration file path is correctly specified.

```go
package main

import (
    "flag"
    "github.com/zhukovaskychina/xmysql-server/server/conf"
    "github.com/zhukovaskychina/xmysql-server/server/net"
    "github.com/zhukovaskychina/xmysql-server/logger"
)

func main() {
    var configPath string
    flag.StringVar(&configPath, "configPath", "", "配置文件路径")
    flag.Parse()

    args := &conf.CommandLineArgs{ConfigPath: configPath}
    config := conf.NewCfg().Load(args)

    logConfig := logger.LogConfig{
        ErrorLogPath: config.LogError,
        InfoLogPath:  config.LogInfos,
        LogLevel:     config.LogLevel,
    }
    logger.InitLogger(logConfig)

    mysqlServer := net.NewMySQLServer(config)
    mysqlServer.Start()
}
```

```bash
# 命令行启动
go run . -configPath=conf/my.ini

# 编译后启动
go build -o xmysql-server .
./xmysql-server -configPath=conf/my.ini

# 通过标准 MySQL 客户端连接（端口 33090）
mysql -h 127.0.0.1 -P 33090 -u root
```

--------------------------------

### Go: MySQL Query Processing with Tracing

Source: https://github.com/zhukovaskychina/xmysql-server/wiki/如何实现-MySQL-‐-第-04-篇：数据流向：从客户端请求到存储层的全链路解读

Demonstrates how to integrate request tracing into the query processing pipeline of a MySQL server. This example shows starting and finishing spans for parsing, optimization, execution, and response phases.

```go
// 使用示例
func (server *MySQLServer) ProcessQueryWithTracing(ctx context.Context, conn *Connection, querySQL string) error {
    traceID := generateTraceID()
    
    // 创建根 Span
    rootSpan := server.tracker.StartSpan(traceID, "query.process", nil)
    rootSpan.Tags["sql"] = querySQL
    rootSpan.Tags["connection_id"] = conn.ID
    defer server.tracker.FinishSpan(rootSpan)
    
    // 解析阶段
    parseSpan := server.tracker.StartSpan(traceID, "query.parse", rootSpan)
    ast, err := server.parseSQL(querySQL)
    server.tracker.FinishSpan(parseSpan)
    
    if err != nil {
        rootSpan.Tags["error"] = err.Error()
        return err
    }
    
    // 优化阶段
    optimizeSpan := server.tracker.StartSpan(traceID, "query.optimize", rootSpan)
    plan, err := server.optimizeQuery(ast)
    server.tracker.FinishSpan(optimizeSpan)
    
    if err != nil {
        rootSpan.Tags["error"] = err.Error()
        return err
    }
    
    // 执行阶段
    executeSpan := server.tracker.StartSpan(traceID, "query.execute", rootSpan)
    result, err := server.executeQuery(ctx, plan)
    executeSpan.Tags["rows_scanned"] = result.RowsScanned
    executeSpan.Tags["rows_returned"] = len(result.Rows)
    server.tracker.FinishSpan(executeSpan)
    
    if err != nil {
        rootSpan.Tags["error"] = err.Error()
        return err
    }
    
    // 响应阶段
    responseSpan := server.tracker.StartSpan(traceID, "query.response", rootSpan)
    err = server.sendResultSet(conn, result)
    server.tracker.FinishSpan(responseSpan)
    
    return err
}
```

--------------------------------

### Full Example of Advanced Protocol Handler Usage

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/ADVANCED_PROTOCOL_FEATURES.md

A comprehensive example showing the initialization, character set setting, connection attribute parsing, enabling compression, session tracking, and processing large packets with the AdvancedProtocolHandler.

```go
// 1. 初始化
handler := NewAdvancedProtocolHandler(nil) // 使用默认配置

// 2. 设置字符集
charsetMgr := handler.GetCharsetManager()
utf8mb4, _ := charsetMgr.GetCharsetByName("utf8mb4")

// 3. 解析连接属性
attrs, _, _ := ParseConnectionAttributes(authPacketData)
clientInfo := attrs.GetClientInfo()
fmt.Printf("客户端: %s\n", clientInfo.String())

// 4. 启用压缩（如果客户端支持）
if clientSupportsCompression {
    handler.EnableCompression()
}

// 5. 跟踪会话状态
sessionMgr := handler.GetSessionManager()
sessionMgr.SetSchema("mydb")
sessionMgr.SetSystemVariable("autocommit", "ON")

// 6. 处理大数据包
largeResult := generateLargeResultSet()
packets, _ := handler.ProcessPacket(largeResult, 1)
for _, packet := range packets {
    conn.Write(packet)
}

// 7. 在OK包中包含会话跟踪
trackData := sessionMgr.GetTrackingData()
okPacket := createOKPacket(affectedRows, lastInsertId)
if trackData != nil {
    okPacket = append(okPacket, trackData...)
}
conn.Write(okPacket)
```

--------------------------------

### Start Log Archiver

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/transaction-reports/log-optimization-summary.md

Configure and start the log archiver to manage log file archiving. Set maximum log size and file count, then start the archiving process. Ensure the archive directory is specified.

```go
// 创建日志归档器
archiver, err := NewLogArchiver("/data/redo", "/data/archive")
if err != nil {
    log.Fatal(err)
}

// 配置参数
archiver.SetMaxLogSize(100 * 1024 * 1024) // 100MB
archiver.SetMaxLogFiles(10)

// 启动归档
archiver.Start()
deferr archiver.Stop()
```

--------------------------------

### SQL Examples for Covering Index Optimization

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/development/IDX-008-INDEX-LOOKUP-IMPLEMENTATION.md

Illustrates how to leverage covering indexes in SQL queries. It shows examples where a query requires a back-to-table lookup because a needed column is not in the index, and conversely, examples where no lookup is needed because all required columns are covered by the index.

```sql
-- 表结构
CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(255),
    age INT,
    INDEX idx_name_email(name, email)
);

-- 查询1：需要回表
SELECT name, email, age FROM users WHERE name = 'Alice';
-- 原因：age列不在索引idx_name_email中

-- 查询2：不需要回表（覆盖索引）
SELECT name, email FROM users WHERE name = 'Alice';
-- 原因：name和email都在索引idx_name_email中

-- 查询3：不需要回表（覆盖索引+主键）
SELECT id, name, email FROM users WHERE name = 'Alice';
-- 原因：二级索引包含主键id，加上name和email都在索引中
```

--------------------------------

### Install Dependencies with Maven

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/jdbc_client/测试总结.md

Install project dependencies and build artifacts using Maven. Navigate to the jdbc_client directory before running.

```bash
cd jdbc_client
mvn clean install
```

--------------------------------

### Initialize Storage Engine DML Executor

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/storage/STORAGE_ENGINE_INTEGRATION.md

Example of creating a new instance of the StorageIntegratedDMLExecutor with necessary manager dependencies.

```go
// 创建存储引擎集成的DML执行器
executor := NewStorageIntegratedDMLExecutor(
    optimizerManager,
    bufferPoolManager,
    btreeManager,
    tableManager,
    txManager,
    indexManager,
    storageManager,
    tableStorageManager,
)
```

--------------------------------

### Test Compression Protocol with MySQL Client

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/ADVANCED_PROTOCOL_FEATURES.md

Command-line example to test the compression protocol by connecting to a MySQL server with the --compress flag.

```bash
# 测试压缩协议
mysql -h localhost -P 3306 -u root --compress
```

--------------------------------

### Migration Guide: Old vs. New Code for IPageWrapper (Go)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p0-tasks/P0_TASKS_COMPLETION_REPORT.md

Provides a migration guide showing how to update import paths and variable declarations when transitioning from the old PageWrapper interface to the new standard types.IPageWrapper, or when using the backward-compatible wrapper.IPageWrapper alias.

```go
// 旧代码:
import "github.com/zhukovaskychina/xmysql-server/server/innodb/storage/wrapper/page"

var p page.PageWrapper
```

```go
// 新代码:
import "github.com/zhukovaskychina/xmysql-server/server/innodb/storage/wrapper/types"

var p types.IPageWrapper
```

```go
// 兼容代码:
import "github.com/zhukovaskychina/xmysql-server/server/innodb/storage/wrapper"

var p wrapper.IPageWrapper  // 等同于 types.IPageWrapper
```

--------------------------------

### Monitor Index Performance and Consistency

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/storage/STORAGE_ENGINE_INTEGRATION.md

Code examples for monitoring index performance, checking index consistency, and optimizing indexes.

```go
// 监控索引性能
perfStats := executor.monitorIndexPerformance()

// 检查索引一致性
err := executor.checkIndexConsistency(tableID)

// 优化索引
err := executor.optimizeIndexes(tableID)
```

--------------------------------

### Launch XMySQL Client in GUI Mode

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/client/CLIENT_README.md

Start the XMySQL client with the graphical user interface enabled.

```bash
./xmysql-client --gui
```

--------------------------------

### Comment Patterns: Full Documentation Comments

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p3-tasks/P3_2_NAMING_CODING_STYLE_ANALYSIS.md

Examples of comprehensive documentation comments for functions and interfaces, including descriptions and purpose.

```go
// NewPageHeader creates a new PageHeader instance
func NewPageHeader(size uint32) *PageHeader { ... }

// IPageWrapper 统一的页面包装器接口
// 所有页面实现都应该实现此接口
// 这是 Storage 模块的核心接口，用于抽象不同类型的页面
type IPageWrapper interface { ... }
```

--------------------------------

### Test Connection Attributes with MySQL Client

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/ADVANCED_PROTOCOL_FEATURES.md

Command-line example to test connection attributes by connecting to a MySQL server with the --connect-attrs option.

```bash
# 测试连接属性
mysql -h localhost -P 3306 -u root --connect-attrs="app=myapp,version=1.0"
```

--------------------------------

### Method Definitions without 'Get' Prefix

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p3-tasks/P3_2_NAMING_CODING_STYLE_ANALYSIS.md

Examples of methods that do not use the 'Get' prefix, including boolean checks and data retrieval. These are less common and may indicate inconsistent naming.

```go
func (p *Page) IsDirty() bool
```

```go
func (p *Page) IsLeaf() bool
```

```go
func (p *Page) IsRoot() bool
```

```go
func (ph *PageHeader) Bytes() []byte  // 应该是GetBytes()
```

--------------------------------

### InnoDB Storage Manager Usage Example (Go)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/storage_architecture_doc.md

Demonstrates the basic usage of the StorageManager, including initialization with configuration, creating a user tablespace, accessing the SystemSpaceManager, and performing data dictionary operations.

```go
// 1. 初始化存储管理器
cfg := &conf.Cfg{
    DataDir: "/data/mysql",
    InnodbBufferPoolSize: 134217728, // 128MB
}
sm := manager.NewStorageManager(cfg)

// 2. 创建用户表空间
spaceID, err := sm.CreateTablespace("test_db/user_table")

// 3. 访问系统表空间
systemSpaceMgr := sm.GetSystemSpaceManager()
dictRootPage, err := systemSpaceMgr.LoadDictRootPage()

// 4. 数据字典操作
dictMgr := systemSpaceMgr.GetDictManager()
table, err := dictMgr.CreateTable("user_table", spaceID, columns)
```

--------------------------------

### Example: Create User and Insert into B+ Tree

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/MYSQL_USER_RECORD_FORMAT.md

Demonstrates the workflow of creating a default root user, generating its record in the standard InnoDB format, and inserting it into a B+ tree index.

```go
// Create user
user := createDefaultRootUser()

// Create table metadata
frmMeta := createMySQLUserTableMetadata()

// Create standard record
record := user.createMySQLUserRecord(frmMeta, 2)

// Insert into B+ tree index
primaryKey := []byte("root@localhost")
err := btreeManager.Insert(ctx, indexID, primaryKey, record.ToByte())
```

--------------------------------

### Exported Function/Method Comment Example in Go

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/CODING_STANDARDS.md

All exported functions and methods in Go must have comments. The comment should start with the function/method name, e.g., `// NewPageHeader creates...`.

```go
// NewPageHeader creates a new PageHeader instance with the given size.
// The size parameter specifies the total size of the page header in bytes.
// Returns a pointer to the newly created PageHeader.
func NewPageHeader(size uint32) *PageHeader {
    ...
}

// GetPageID returns the page ID (same as GetPageNo).
// The page ID uniquely identifies a page within a tablespace.
func (p *Page) GetPageID() uint32 {
    ...
}
```

--------------------------------

### Exported Type Comment Example in Go

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/CODING_STANDARDS.md

All exported types (structs, interfaces, etc.) in Go must have comments. The comment should start with the type name, e.g., `// IPageWrapper is...`.

```go
// IPageWrapper is the unified page wrapper interface.
// All page implementations should implement this interface.
// This is the core interface of the Storage module for abstracting
// different types of pages.
type IPageWrapper interface {
    ...
}

// PageManager manages all pages in the buffer pool.
// It provides methods for creating, reading, updating, and deleting pages.
type PageManager struct {
    mu    sync.RWMutex
    pages map[uint32]*Page
}
```

--------------------------------

### Basic Usage of Optimizer Components in Go

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/query-optimizer/query_optimizer_p0_implementation.md

Provides a Go code example demonstrating how to instantiate and use the Statistics Collector, Cost Estimator, and Index Pushdown Optimizer components.

```go
// 创建统计信息收集器
collector := plan.NewStatisticsCollector(nil)

// 创建代价估算器
estimator := plan.NewCostEstimator(collector, nil)

// 创建索引下推优化器
optimizer := plan.NewIndexPushdownOptimizer()

// 收集统计信息
tableStats, _ := collector.CollectTableStatistics(ctx, table)

// 进行索引优化
candidate, _ := optimizer.OptimizeIndexAccess(table, conditions, columns)

// 估算代价
cost, _ := estimator.EstimateIndexScanCost(table, index, selectivity, conditions)
```

--------------------------------

### Hardcoded Error Examples

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/protocol-reports/PROTO-005_ERROR_CODE_MAPPING_REPORT.md

These examples show instances of hardcoded MySQL error codes and SQL States that were identified as problematic.

```go
// server/protocol/mysql_protocol.go:146
errPacket := EncodeErrorPacket(1064, "42000", result.Error.Error())
```

```go
// server/protocol/encoder.go:80
return EncodeErrorPacket(1064, "42000", result.Error.Error()), nil
```

```go
// server/dispatcher/enhanced_message_handler.go:67
return &protocol.ErrorMessage{
    Code:  common.ER_UNKNOWN_ERROR,
    State: "42000",  // 硬编码的SQL State
    Message: fmt.Sprintf("Unknown message type: %d", msg.Type()),
}, nil
```

--------------------------------

### Run Integration Demo Program

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/query-optimizer/query_optimizer_integration_summary.md

Command to navigate to the integration demo directory and run the main program using Go. Demonstrates various integration features.

```bash
cd cmd/integration_demo
go run main.go
```

--------------------------------

### B+ Tree Split Locking Example

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/btree/BTREE_ARCHITECTURE_OVERVIEW.md

Provides a step-by-step example of the locking sequence during a B+ Tree node split operation.

```pseudocode
**示例: 分裂时的加锁顺序**
```
步骤1: 锁叶子节点 Lock(leafNode)
步骤2: 分裂叶子节点 (持有leafNode锁)
步骤3: 锁父节点 Lock(parent)
步骤4: 释放叶子节点锁 Unlock(leafNode)
步骤5: 更新父节点 (持有parent锁)
步骤6: 释放父节点锁 Unlock(parent)
```
```

--------------------------------

### Configure and Initialize Advanced Protocol Handler

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/ADVANCED_PROTOCOL_FEATURES.md

Demonstrates how to create and configure an AdvancedProtocolHandler with options like compression, session tracking, and default charset. It also shows how to access various component managers.

```go
// 创建配置
config := NewDefaultAdvancedProtocolConfig()
config.EnableCompression = true
config.EnableSessionTracking = true
config.DefaultCharset = "utf8mb4"

// 创建处理器
handler := NewAdvancedProtocolHandler(config)

// 使用各个组件
charsetMgr := handler.GetCharsetManager()
compressor := handler.GetCompressionHandler()
sessionMgr := handler.GetSessionManager()
splitter := handler.GetPacketSplitter()

// 处理包（自动压缩和分片）
packets, err := handler.ProcessPacket(largePayload, sequenceId)
```

--------------------------------

### Running the Query Optimizer Demo

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/query-optimizer/query_optimizer_p0_implementation.md

Shows the command to execute the query optimizer demonstration program.

```bash
go run cmd/query_optimizer_demo/main.go
```

--------------------------------

### Start Long Transaction Monitor

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/transaction-reports/TXN-004_LONG_TRANSACTION_DETECTION_REPORT.md

Starts the background goroutine for long transaction monitoring. It ensures that the monitor only runs once by checking the `monitorRunning` flag.

```go
func (tm *TransactionManager) StartLongTransactionMonitor() {
	tm.mu.Lock()
	defer tm.mu.Unlock()

	if tm.monitorRunning {
		return
	}

	tm.monitorRunning = true
	tm.monitorWg.Add(1)

	go tm.longTransactionMonitor()
}
```

--------------------------------

### IBD File Usage Example

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/IBD_README.md

Demonstrates the basic workflow for creating an IBD file, allocating a page, writing data, and synchronizing changes to disk.

```go
// 创建表空间
ibdFile := NewIBDFile("users", "mydb", 1, "/data", "users.ibd", 0)
ibdFile.CreateTable()

// 分配页面
pageNo, err := ibdFile.AllocatePage()
if err != nil {
    // 处理错误
}

// 写入数据
data := []byte{...}
ibdFile.WritePage(pageNo, data)

// 同步到磁盘
ibdFile.Sync()
```

--------------------------------

### GapRange Struct Example

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/mvcc-reports/LOCK_001_GAP_LOCK_FIX_REPORT.md

Example demonstrating how to instantiate a GapRange struct to represent the gap between keys 10 and 20 in a specific table and index.

```go
// 锁定 (10, 20) 之间的间隙
gapRange := &GapRange{
    LowerBound: 10,
    UpperBound: 20,
    TableID:    1,
    IndexID:    1,
}
```

--------------------------------

### Use Protocol Constants

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/PROTOCOL_ENCODER_REFACTORING.md

Demonstrates the usage of constants for creating column definitions, server statuses, and OK packets.

```go
// 字段类型
colDef := encoder.CreateColumnDefinition("age", protocol.MYSQL_TYPE_LONG, protocol.FLAG_NOT_NULL)

// 服务器状态
eofPacket := encoder.WriteEOFPacket(0, protocol.SERVER_STATUS_AUTOCOMMIT)

// OK 包
okPacket := encoder.WriteOKPacket(1, 0, protocol.SERVER_STATUS_AUTOCOMMIT, 0)
```

--------------------------------

### ReadContent Usage Examples in Go

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p2-tasks/P2_3_COMPLETION_REPORT.md

These Go examples demonstrate various use cases for the ReadContent method. They cover scenarios like calculating checksums, serializing data, and contrast with using GetContent for modifications.

```go
// 场景1：计算校验和（只读）
page.ReadContent(func(content []byte) {
    checksum := calculateChecksum(content)
})
```

```go
// 场景2：序列化（只读）
page.ReadContent(func(content []byte) {
    writer.Write(content)
})
```

```go
// 场景3：需要修改（使用GetContent）
content := page.GetContent()
content[0] = 0xFF
page.SetContent(content)
```

--------------------------------

### Test Full Initialization Flow

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/mysql_user_initialization_process.md

Sets up the storage manager, executes the full MySQL user data initialization process, and asserts that no errors occur. It also includes verification steps for the resulting user table structure and default users.

```go
func TestFullInitializationFlow(t *testing.T) {
    // 完整的初始化流程测试
    sm := setupStorageManager()
    err := sm.InitializeMySQLUserData()
    assert.NoError(t, err)
    
    // 验证结果
    verifyUserTableStructure(t, sm)
    verifyDefaultUsers(t, sm)
}
```

--------------------------------

### Client Usage of Prepared Statements in Go

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/development/NET-001-PREPARED-STATEMENT-SUMMARY.md

Demonstrates how to use prepared statements with the Go MySQL driver. This involves opening a database connection, preparing a statement, executing it with parameters, and processing the results.

```go
package main

import (
    "database/sql"
    "fmt"
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    // 连接数据库
    db, err := sql.Open("mysql", "root:password@tcp(127.0.0.1:3308)/test")
    if err != nil {
        panic(err)
    }
    defer db.Close()
    
    // 准备预处理语句
    stmt, err := db.Prepare("SELECT * FROM users WHERE id = ? AND name = ?")
    if err != nil {
        panic(err)
    }
    defer stmt.Close()
    
    // 执行查询（参数会通过二进制协议传输）
    rows, err := stmt.Query(1, "Alice")
    if err != nil {
        panic(err)
    }
    defer rows.Close()
    
    // 处理结果
    for rows.Next() {
        var id int
        var name string
        if err := rows.Scan(&id, &name); err != nil {
            panic(err)
        }
        fmt.Printf("ID: %d, Name: %s\n", id, name)
    }
    
    // 再次执行（复用执行计划）
    rows2, err := stmt.Query(2, "Bob")
    // ...
}
```

--------------------------------

### Start Background Threads for Flush and LRU Maintenance

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/storage-reports/STORAGE-001_FIX_SUMMARY.md

Starts background threads for flushing and LRU list maintenance. The flush thread uses a ticker based on the current flush interval, while the LRU thread runs periodically.

```go
func (bpm *BufferPoolManager) startBackgroundThreads() {
    // 创建刷新定时器
    bpm.flushTicker = time.NewTicker(bpm.currentFlushInterval)

    // 启动后台刷新线程
    go func() {
        for {
            select {
            case <-bpm.flushTicker.C:
                bpm.backgroundFlush()
            case <-bpm.stopChan:
                return
            }
        }
    }()

    // 启动 LRU 维护线程
    go func() {
        ticker := time.NewTicker(5 * time.Second)
        defer ticker.Stop()
        for {
            select {
            case <-ticker.C:
                bpm.maintainLRULists()
            case <-bpm.stopChan:
                return
            }
        }
    }()
}
```

--------------------------------

### System Initialization Flow

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/storage_architecture_doc.md

Outlines the steps involved in initializing the StorageManager and its sub-components, including the creation of the system tablespace, SystemSpaceManager, and DictionaryManager.

```text
1. StorageManager.NewStorageManager(cfg)
   ├── 创建 SpaceManager (管理所有表空间)
   ├── 创建 BufferPool (页面缓存)
   ├── 创建 PageManager (页面管理)
   ├── 创建 SegmentManager (段管理)
   └── 调用 initializeSystemTablespaces()
       ├── 创建系统表空间 ibdata1 (space_id=0)
       ├── 创建 SystemSpaceManager
       ├── 初始化数据字典根页面 (页面5)
       └── 创建 DictionaryManager

2. SystemSpaceManager 初始化
   ├── 加载/创建数据字典根页面
   ├── 创建系统表段 (SYS_TABLES, SYS_COLUMNS, SYS_INDEXES)
   └── 初始化 B+树索引结构
```

--------------------------------

### Example: Handling Go Errors (Old Way)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/protocol-reports/PROTO-005_ERROR_CODE_MAPPING_REPORT.md

This example shows the previous method for handling Go errors, which required manually specifying the error code, SQL state, and error message when creating an error packet. This was more verbose and prone to errors.

```go
// 旧方式
if err != nil {
    errPacket := EncodeErrorPacket(1064, "42000", err.Error())
    conn.Write(errPacket)
}
```

--------------------------------

### Implement Storage Engine Initialization in Go

Source: https://github.com/zhukovaskychina/xmysql-server/wiki/如何实现-MySQL-‐-第-02-篇：MySQL-架构全景图与分层设计

Details the `initStorageEngine` function, which initializes the storage manager, buffer pool, and transaction manager, then creates and registers the InnoDB engine with the server.

```go
func (s *XMySQLServer) initStorageEngine() error {
    // 创建存储管理器
    storageManager, err := storage.NewStorageManager(s.config.StorageConfig)
    if err != nil {
        return err
    }
    
    // 创建缓冲池
    bufferPool, err := buffer.NewBufferPool(s.config.BufferPoolConfig)
    if err != nil {
        return err
    }
    
    // 创建事务管理器
    transactionManager := transaction.NewTransactionManager(storageManager)
    
    // 创建InnoDB引擎
    innodbEngine := innodb.NewInnoDBEngine(
        storageManager,
        bufferPool,
        transactionManager,
    )
    
    // 注册存储引擎
    s.engineRegistry.Register("InnoDB", innodbEngine)
    s.defaultEngine = innodbEngine
    
    return nil
}
```

--------------------------------

### Initialize and Use Session Tracker

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/ADVANCED_PROTOCOL_FEATURES.md

Demonstrates how to initialize a `SessionTracker` to track changes in system variables, schema, and transaction states. The tracked data can be encoded for inclusion in OK packets.

```go
tracker := NewSessionTracker(true) // 启用跟踪

// 跟踪系统变量
tracker.TrackSystemVariable("autocommit", "ON")

// 跟踪数据库变更
tracker.TrackSchema("testdb")

// 跟踪事务状态
tracker.TrackTransactionState(TxStateActive)

// 获取编码数据
trackData := tracker.EncodeForOKPacket()
```

--------------------------------

### Example: Handling Go Errors (New Way)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/protocol-reports/PROTO-005_ERROR_CODE_MAPPING_REPORT.md

This example demonstrates the modern approach to handling Go errors. Instead of manually constructing error packets, `EncodeErrorFromGoError` is used to automatically generate the correct MySQL error packet, simplifying the error handling logic.

```go
// 新方式
if err != nil {
    errPacket := EncodeErrorFromGoError(err)
    conn.Write(errPacket)
}
```

--------------------------------

### Add Package-Level Documentation (doc.go)

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/PROTOCOL_PACKAGE_OPTIMIZATION.md

Provides package-level documentation for the 'protocol' package, including its main components, protocol specification links, and usage examples.

```go
// doc.go
/*
Package protocol 实现 MySQL 客户端/服务器协议

主要组件:
- MySQLProtocolEncoder: 消息编码器注册表
- MySQLResultSetEncoder: ResultSet 协议包编码器
- MySQLProtocolHandler: 协议处理器

协议规范:
- https://dev.mysql.com/doc/internals/en/client-server-protocol.html
- https://dev.mysql.com/doc/internals/en/text-protocol.html

使用示例:
    encoder := protocol.NewMySQLResultSetEncoder()
    data := &protocol.ResultSetData{
        Columns: []string{"id", "name"},
        Rows: [][]interface{}{{1, "Alice"}, {2, "Bob"}},
    }
    packets := encoder.SendResultSetPackets(data)
*/
package protocol
```

--------------------------------

### StorageManager Get Method Concurrency Consideration

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/DATABASE_AND_TABLE_MANAGER_ANALYSIS.md

This note discusses the concurrency implications of StorageManager's Get methods. Direct field access for GetTableManager() lacks locking, while GetSystemSpaceManager() uses RLock. Consider adding locks if runtime manager replacement is a future requirement or for style consistency.

```go
// Current implementation for GetTableManager() does not use locks.
// GetSystemSpaceManager() uses sm.mu.RLock().
// Consider adding RLock/Lock to Get/Set methods if runtime replacement is needed.
```

--------------------------------

### Current Package Structure

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p3-tasks/P3_2_NAMING_CODING_STYLE_ANALYSIS.md

Illustrates the existing directory structure for the server/innodb/storage module, highlighting potential organization issues.

```text
server/innodb/storage/
├── store/              # 底层存储格式
│   ├── pages/          # 页面格式
│   ├── extents/        # Extent格式
│   ├── segs/           # Segment格式
│   └── mvcc/           # MVCC实现（位置不当）
├── wrapper/            # 业务逻辑
│   ├── types/          # 类型定义
│   ├── page/           # 页面管理
│   ├── extent/         # Extent管理
│   ├── segment/        # Segment管理
│   ├── space/          # 表空间管理
│   ├── system/         # 系统页面
│   ├── mvcc/           # MVCC实现（重复）
│   └── blob/           # BLOB管理
└── io/                 # I/O操作
```

--------------------------------

### Getting Page Type from Header

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/PAGES_README.md

Retrieves the type of the page from its file header.

```go
// 获取页面类型
pageType := header.GetPageType()
```

--------------------------------

### Get DML Executor Statistics

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/storage/STORAGE_ENGINE_INTEGRATION.md

Retrieves the collected statistics from the DML executor instance.

```go
// 获取统计信息
stats := executor.GetStats()
```

--------------------------------

### Recommended Commenting for Interfaces and Functions

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p3-tasks/P3_2_NAMING_CODING_STYLE_ANALYSIS.md

Demonstrates best practices for documenting interfaces and functions, including detailed explanations, parameter, and return value descriptions.

```go
// IPageWrapper is the unified page wrapper interface.
// All page implementations should implement this interface.
// This is the core interface of the Storage module for abstracting different types of pages.
type IPageWrapper interface {
    // GetPageID returns the page ID (same as GetPageNo).
    GetPageID() uint32
    
    // GetSpaceID returns the tablespace ID.
    GetSpaceID() uint32
}

// NewPageHeader creates a new PageHeader instance with the given size.
// The size parameter specifies the total size of the page header in bytes.
// Returns a pointer to the newly created PageHeader.
func NewPageHeader(size uint32) *PageHeader {
    ...
}
```

--------------------------------

### INode Page Wrapper Usage Example

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/inode_README.md

Demonstrates how to create and use the INode page wrapper. This includes obtaining the underlying page, serializing the wrapper to bytes, and deserializing from bytes into a new INode instance.

```go
// 创建 INode 页面包装器
inode := NewInodePageWrapper(pageID, spaceID)

// 获取底层页面
inodePage := inode.GetInodePage()

// 序列化
data := inode.ToBytes()

// 反序列化
newInode := &INode{}
err := newInode.ParseFromBytes(data)
```

--------------------------------

### Getting BLOB Data

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/innodb/PAGES_README.md

Retrieves the BLOB data stored within a BLOB page.

```go
blobData := blobPage.GetBlobData()
```

--------------------------------

### Comment Patterns: No Comments

Source: https://github.com/zhukovaskychina/xmysql-server/blob/main/docs/reports/p3-tasks/P3_2_NAMING_CODING_STYLE_ANALYSIS.md

Code examples demonstrating functions and types without any accompanying comments.

```go
func (p *Page) GetSpaceID() uint32 { ... }

type PageHeader struct { ... }
```

--------------------------------

### Create MVCC Manager and Begin Transactions

Source: https://context7.com/zhukovaskychina/xmysql-server/llms.txt

Initializes an MVCC manager with configuration and demonstrates starting transactions, which automatically generate ReadView snapshots. Handles potential transaction limits.

```go
package main

import (
    "fmt"
    "time"
    "github.com/zhukovaskychina/xmysql-server/server/innodb/manager"
)

func main() {
    cfg := &manager.MVCCConfig{
        TxTimeout:         5 * time.Minute,
        MaxActiveTxs:      10000,
        SnapshotRetention: 30 * time.Minute,
    }

    mvccMgr := manager.NewMVCCManager(cfg)

    // 开启事务，自动生成 ReadView 快照
    txID, err := mvccMgr.BeginTransaction()
    if err != nil {
        // ErrTooManyTransactions: 活跃事务超出上限
        panic(err)
    }
    fmt.Printf("MVCC事务开始: txID=%d\n", txID)

    // 并发开启第二个事务（txID2 > txID1，ReadView 中 txID1 为活跃）
    txID2, _ := mvccMgr.BeginTransaction()
    fmt.Printf("并发事务: txID=%d\n", txID2)

    // txID2 修改数据 → txID1 的 ReadView 不可见（可重复读保证）

    // 提交第一个事务
    if err := mvccMgr.CommitTransaction(txID); err != nil {
        mvccMgr.RollbackTransaction(txID)
    }
    fmt.Printf("txID=%d 已提交\n", txID)

    // 回滚第二个事务
    mvccMgr.RollbackTransaction(txID2)
    fmt.Printf("txID=%d 已回滚\n", txID2)
}
```
Tokens:
Raw