# TTSQL

**Repository Path**: ttzhanshen/ttsql

## Basic Information

- **Project Name**: TTSQL
- **Description**: ttsql
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TTSQL 1.0 关系型数据库系统

TTSQL 是面向可直接实现的单机事务型关系数据库核心规范（TTSQL 1.0 Technical Specification）的纯 Rust 完整实现。

## 🌟 核心特性与架构

- **存储引擎 (ttsql-vfs, page, buffer)**：
  - 固定 16 KiB Slotted Page 布局，页头 64 字节，内置 CRC32C 单 bit flip 校验。
  - 数据文件 `.ttd`：Page 0 Superblock、Page 1/2 Meta A/B 双副本（generation + checksum 崩溃原子切换）。
  - Buffer Pool Manager：支持页置换、脏页追踪与严格的 **WAL-before-data** 不变量保障。
- **持久化与崩溃恢复 (ttsql-wal)**：
  - 64 MiB 分段 WAL 日志文件 (`0000000000000001.ttw`)，40 字节紧凑对齐记录头。
  - Redo-oriented 幂等恢复：未提交事务崩溃时自动置为 ABORTED，已提交事务数据无损恢复。
- **MVCC 与并发控制 (ttsql-tx, lock, heap)**：
  - 32 字节 `HeapTupleHeader`（`xmin`, `xmax`, `cid`, `infomask`），支持 Snapshot 隔离级别与多版本可见性判定。
  - 2PL 锁管理器与基于 Wait-for Graph 的死锁检测（抛出 `TT4006`）。
- **B+Tree 索引 (ttsql-btree)**：
  - 内部节点与叶子节点统一 Slotted 布局，支持 Mem-comparable 二进制字节序编码与 50% 节点分裂。
- **SQL 引擎 (ttsql-parser, planner, optimizer, executor)**：
  - 词法解析、递归下降语法树生成、Catalog 绑定与基于规则的优化器。
  - Volcano 模型物理执行器（RowBatch 流水线处理）。
- **Native 网络协议 (ttsql-protocol, server, cli)**：
  - TTP/1 协议（端口 8432），包含 8 字节握手 Preface 与 16 字节帧头。
  - 交互式 CLI 工具与诊断命令。

---

## 📁 模块布局

```
ttsql/
├── Cargo.toml
├── crates/
│   ├── ttsql-common/        # 常量定义、ID 类型、Little/Big-Endian Codec、CRC32C
│   ├── ttsql-error/         # TTdddd 错误码、SQLSTATE、ErrorPayload 编解码
│   ├── ttsql-types/         # SQL 类型系统、Value 物理表示、Mem-comparable Binary Key 编码
│   ├── ttsql-vfs/           # .ttd / .ttw / .ttc VFS 抽象、Superblock / Meta 双副本
│   ├── ttsql-page/          # 64-byte PageHeader、16KiB Slotted Page 布局
│   ├── ttsql-buffer/        # Buffer Pool Manager、LRU 驱逐、WAL-before-data 检查
│   ├── ttsql-wal/           # 64MB Segments、40-byte Record Header、WAL 追加与刷盘
│   ├── ttsql-tx/            # MVCC 事务管理器、快照生成 (CSN/TxId)、可见性方程
│   ├── ttsql-lock/          # 2PL 锁管理器、Wait-for Graph 死锁检测
│   ├── ttsql-heap/          # Heap 表空间、32-byte HeapTupleHeader、Payload Codec
│   ├── ttsql-btree/         # B+Tree 索引节点、查找、插入、Split、Unique 约束
│   ├── ttsql-catalog/       # 系统元数据字典表 (sys_tables, sys_columns, sys_indexes)
│   ├── ttsql-sql-ast/       # SQL 抽象语法树
│   ├── ttsql-parser/        # 词法分析器与递归下降解析器
│   ├── ttsql-planner/       # 语义分析 (Binder)、Logical Plan
│   ├── ttsql-optimizer/     # 基于规则的优化器 (常量折叠)
│   ├── ttsql-executor/      # Volcano 物理执行器 (SeqScan, Filter, Project, Sort, Limit, DML)
│   ├── ttsql-protocol/      # TTP/1 协议帧编解码与 Typed Value 传输
│   ├── ttsql-server/        # TCP 网络服务、会话与生命周期
│   ├── ttsql-cli/           # 命令行客户端 (ttsql server, ttsql sql, ttsql page inspect)
│   └── ttsql-testkit/       # Golden Fixtures 与端到端集成测试
```

---

## 🚀 快速开始

### 1. 编译与测试
```bash
# 运行全部单元测试与 Golden Fixtures 测试
cargo test

# 编译发布版本 CLI
cargo build --release
```

### 2. 初始化与启动服务
```bash
# 初始化数据目录
./target/release/ttsql init ./data

# 启动 TTSQL 服务端 (监听 8432 端口)
./target/release/ttsql server start --data-dir ./data --native-port 8432
```

### 3. 命令行执行 SQL
```bash
# 执行建表与插入
./target/release/ttsql sql -p 8432 -e "CREATE TABLE users (id BIGINT PRIMARY KEY, name VARCHAR(64), age INT);"
./target/release/ttsql sql -p 8432 -e "INSERT INTO users (id, name, age) VALUES (1, 'Alice', 30), (2, 'Bob', 25);"

# 查询数据
./target/release/ttsql sql -p 8432 -e "SELECT id, name, age FROM users WHERE age > 20 ORDER BY age DESC;"
```

### 4. 存储页面诊断
```bash
# 检查 Page 0 (Superblock) 或 Page 3 (Heap Data Page)
./target/release/ttsql page inspect --data-dir ./data --page 3
```