# gsql

**Repository Path**: kingecg/gsql

## Basic Information

- **Project Name**: gsql
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GSQL

SQLite 兼容的数据库引擎，使用 Go 语言从零实现。

## 特性

- **VDBE (Virtual Database Engine)** - SQLite 风格的字节码执行引擎
- **完整 SQL 支持** - INSERT, SELECT, UPDATE, DELETE, CREATE TABLE, ALTER TABLE, CREATE INDEX, CREATE VIEW, CREATE TRIGGER 等
- **完整事务支持** - BEGIN, COMMIT, ROLLBACK, SAVEPOINT
- **约束 enforcement** - NOT NULL, PRIMARY KEY, UNIQUE, CHECK, DEFAULT, FOREIGN KEY, AUTOINCREMENT
- **持久化存储** - 内存模式和文件模式
- **B-Tree 存储引擎** - 自定义 B-Tree 实现，带 Pager 缓存和 WAL 支持
- **自定义 VFS** - 支持 OS 文件系统和内存文件系统

## 项目结构

```
pkg/sql/
├── api.go          # 数据库 API (Open, Exec, Query 等)
├── codegen/        # 代码生成器 (AST → VDBE 字节码)
├── parser/         # SQL 解析器 (递归下降 parser)
├── tokenize/       # 词法分析器
├── vdbe/           # 虚拟数据库引擎
│   ├── opcode.go   # 操作码定义 (140+ opcodes)
│   └── vdbe.go     # VDBE 执行器
├── schema/         # 数据库模式/目录
├── btree/          # B-Tree 存储引擎
├── pager/          # 页面管理器
├── vfs/            # 虚拟文件系统
└── wal/            # Write-Ahead Logging
```

## 快速开始

### 安装

```bash
go build ./cmd/gsql/
```

### 运行示例

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

### 使用 API

```go
package main

import (
    "fmt"
    "gsql/pkg/sql"
)

func main() {
    // 打开内存数据库
    db, _ := sql.Open(":memory:", nil)
    defer db.Close()

    // 创建表
    db.Exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")

    // 插入数据
    db.Exec("INSERT INTO users VALUES (1, 'Alice', 'alice@example.com')")
    db.Exec("INSERT INTO users VALUES (2, 'Bob', 'bob@example.com')")

    // 查询数据
    stmt, _ := db.Query("SELECT * FROM users")
    for {
        hasRow, _ := stmt.Step()
        if !hasRow {
            break
        }
        for i := 0; i < stmt.ColumnCount(); i++ {
            val, _ := stmt.Column(i)
            fmt.Print(val, " ")
        }
        fmt.Println()
    }
    stmt.Finalize()
}
```

## SQL 支持

### 支持的语句

| 语句 | 说明 |
|------|------|
| `CREATE TABLE` | 创建表（支持完整列约束） |
| `DROP TABLE` | 删除表 |
| `ALTER TABLE` | ADD/DROP/RENAME COLUMN, RENAME TO |
| `INSERT INTO ... VALUES` | 插入数据 |
| `INSERT INTO ... SELECT` | 插入查询结果 |
| `REPLACE INTO` | 替换插入 |
| `SELECT * FROM` | 查询数据 |
| `SELECT DISTINCT` | 去重查询 |
| `SELECT FOR UPDATE` | 加锁查询 |
| `UPDATE ... SET ... WHERE` | 更新数据 |
| `DELETE FROM ... WHERE` | 删除数据 |
| `CREATE INDEX` | 创建索引 |
| `CREATE VIEW` | 创建视图 |
| `DROP VIEW` | 删除视图 |
| `CREATE TRIGGER` | 创建触发器 |
| `DROP TRIGGER` | 删除触发器 |
| `BEGIN` | 开始事务 |
| `COMMIT` | 提交事务 |
| `ROLLBACK` | 回滚事务 |
| `ROLLBACK TO SAVEPOINT` | 回滚到保存点 |
| `RELEASE SAVEPOINT` | 释放保存点 |
| `UNION / UNION ALL` | 并集查询 |
| `INTERSECT / EXCEPT` | 交集/差集查询 |
| `WITH (CTE)` | 公共表表达式（支持递归） |
| `EXPLAIN` | 执行计划分析 |
| `PRAGMA` | 数据库 pragma |
| `ATTACH / DETACH DATABASE` | 附加数据库 |

### 支持的表达式和操作符

- 算术操作符: `+`, `-`, `*`, `/`
- 比较操作符: `=`, `!=`, `<`, `>`, `<=`, `>=`
- 逻辑操作符: `AND`, `OR`, `NOT`
- NULL检查: `IS NULL`, `IS NOT NULL`
- LIKE: 模式匹配（支持 `%` 和 `_` 通配符）
- IN: 值在列表中或子查询中
- BETWEEN: 值在范围内
- CASE/WHEN/THEN/ELSE/END 表达式

### 支持的数据类型

- `INTEGER` - 64位整数
- `REAL` / `FLOAT` / `DOUBLE` - 64位浮点数
- `TEXT` / `STRING` - 字符串
- `BLOB` - 二进制数据
- `NULL` - 空值
- `JSON` / `JSON1` - JSON 类型

### 标量函数

- `LENGTH(s)` - 返回字符串长度
- `SUBSTR(s, start[, len])` - 截取子字符串
- `ABS(n)` - 返回绝对值
- `ROUND(n[, decimals])` - 四舍五入
- `UPPER(s)` - 转换为大写
- `LOWER(s)` - 转换为小写
- `TYPEOF(v)` - 返回值类型
- `COALESCE(...)` - 返回第一个非NULL值
- `IFNULL(a, b)` - 如果a为NULL返回b
- `NULLIF(a, b)` - 如果a=b返回NULL否则返回a

### 聚合函数

- `COUNT(*)` / `COUNT(col)` - 计数
- `SUM(col)` - 求和
- `AVG(col)` - 平均值
- `MIN(col)` - 最小值
- `MAX(col)` - 最大值
- `GROUP_CONCAT(col[, sep])` - 分组连接
- `TOTAL(col)` - 总和（忽略NULL）

### 窗口函数

- `ROW_NUMBER()` - 行号
- `RANK()` / `DENSE_RANK()` - 排名
- `SUM(col)` / `AVG(col)` - 窗口聚合

### 存储模式

```go
// 内存模式 (数据不持久化)
db, _ := sql.Open(":memory:", nil)

// 文件模式 (数据持久化到文件)
db, _ := sql.Open("mydb.db", nil)

// WAL 模式
db.Exec("PRAGMA journal_mode=WAL")
```

## 架构

### VDBE 执行流程

```
SQL String → Tokenizer → Parser (AST) → CodeGen (VDBE bytecode) → VDBE Execution
                                                                          ↓
                                                                   BTree/Pager/WAL
```

### 持久化机制

- B-Tree 作为主存储引擎
- Pager 负责页面缓存和脏页跟踪
- WAL (Write-Ahead Logging) 支持
- VFS 抽象层支持多种文件系统

## 测试

```bash
# 运行所有测试
go test ./... -v -count=1

# 运行集成测试
go test ./tests/... -v

# 运行示例程序
go run ./cmd/gsql/main.go
```

## 开发状态

所有 6 个开发阶段已完成，41/41 任务全部通过 ✅

| 阶段 | 状态 | 描述 |
|------|------|------|
| Phase 1 | ✅ | VDBE 游标模型（拉取式迭代） |
| Phase 2 | ✅ | 存储引擎连接（BTree/Pager/WAL） |
| Phase 3 | ✅ | 事务支持（BEGIN/COMMIT/ROLLBACK/SAVEPOINT） |
| Phase 4 | ✅ | 约束 enforcement（NOT NULL/PK/UNIQUE/CHECK等） |
| Phase 5 | ✅ | SQL 功能完整性（VIEW/TRIGGER/CTE/WINDOW等） |
| Phase 6 | ✅ | VDBE Opcode 补全（索引/seek/filter等） |

### 里程碑

| 里程碑 | 状态 | 描述 |
|--------|------|------|
| M1 | ✅ | 可迭代引擎 |
| M2 | ✅ | 可持久化引擎 |
| M3 | ✅ | 可事务引擎 |
| M4 | ✅ | 约束引擎 |
| M5 | ✅ | 功能完整 |
| M6 | ✅ | **生产就绪** |

## 版本

当前版本: 2.0.0 - 生产就绪

## 许可

MIT License