# littledata

**Repository Path**: srgnet/littledata

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LittleData 🗄️

> **A PostgreSQL-inspired relational database engine written in pure Python**

LittleData 是一个参照 PostgreSQL 内核架构设计、用纯 Python 实现的迷你关系数据库引擎，适合学习数据库原理、教学演示和嵌入式轻量级应用。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://python.org)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](littledata.py)

---

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| **存储引擎** | 8 KB 固定页面，PageHeader + ItemPointer + TupleHeader（与 PG Heap 对齐） |
| **缓冲池** | LRU 替换策略，支持 pin/unpin，脏页追踪与刷盘 |
| **B+ 树索引** | 支持主键、唯一索引、普通索引，支持范围扫描 |
| **WAL 预写日志** | 顺序追加写，CRC32 校验，支持崩溃恢复与 Checkpoint |
| **MVCC** | 快照隔离级别，xmin/xmax 版本链，事务可见性判断 |
| **SQL 解析器** | 手写递归下降解析器，零依赖 |
| **类型系统** | INTEGER、BIGINT、FLOAT、TEXT、BOOLEAN、TIMESTAMP、JSONB |
| **系统目录** | JSON 原子持久化（tmp + rename），支持多库多 schema |
| **交互式 CLI** | 类 psql 的命令行客户端，支持 `\d`、`\l`、`\timing` 等元命令 |

---

## 📁 项目结构

```
littledata/
├── littledata.py            # 交互式 CLI 客户端（类似 psql）
├── src/
│   ├── database.py          # 数据库主入口，整合所有子系统
│   ├── storage/
│   │   ├── page.py          # 8 KB 页面：PageHeader + ItemPointer + Tuple
│   │   ├── buffer_pool.py   # LRU 缓冲池（类似 PG shared_buffers）
│   │   └── types.py         # 类型系统 + 元组序列化/反序列化
│   ├── index/
│   │   └── btree.py         # B+ 树索引实现
│   ├── catalog/
│   │   └── catalog.py       # 系统目录：数据库/表/索引元数据管理
│   ├── transaction/
│   │   └── wal.py           # WAL 预写日志 + MVCC 事务管理器
│   ├── parser/
│   │   ├── lexer.py         # SQL 词法分析器（Lexer）
│   │   ├── ast_nodes.py     # AST 节点定义
│   │   └── parser.py        # 递归下降 SQL 解析器
│   └── executor/
│       └── executor.py      # 查询执行器（HeapScan + 投影 + 聚合 + JOIN）
├── tests/
│   └── test_demo.py         # 功能演示测试（37 项测试）
└── data/                    # 数据目录（运行时自动创建）
```

---

## 🚀 快速开始

### 环境要求

- Python **3.8+**
- 无需任何第三方依赖，标准库即可运行

### 安装

```bash
git clone https://gitee.com/srgnet/littledata.git
cd littledata
```

### 启动交互式 CLI

```bash
# 启动（数据保存到 ./data 目录）
python littledata.py

# 指定自定义数据目录
python littledata.py --data-dir /path/to/mydb

# 执行单条 SQL 后退出
python littledata.py -c "SELECT * FROM users"

# 查看版本
python littledata.py --version
```

---

## 💻 SQL 用法示例

### DDL — 建库建表

```sql
-- 创建数据库（切换后在当前 DB 操作）
CREATE DATABASE myapp;

-- 建表，支持 PRIMARY KEY、NOT NULL、DEFAULT
CREATE TABLE users (
    id      INTEGER PRIMARY KEY,
    name    TEXT    NOT NULL,
    email   TEXT,
    age     INTEGER,
    score   FLOAT   DEFAULT 0.0,
    active  BOOLEAN DEFAULT TRUE
);

-- 创建普通索引
CREATE INDEX idx_age ON users (age);

-- 创建唯一索引
CREATE UNIQUE INDEX idx_email ON users (email);

-- 删除表（IF EXISTS 防止报错）
DROP TABLE IF EXISTS users;

-- 查看元信息
SHOW TABLES;
SHOW DATABASES;
SHOW INDEXES;
```

### DML — 增删改查

```sql
-- 插入（按列名）
INSERT INTO users (id, name, email, age, score, active)
VALUES (1, 'Alice', 'alice@example.com', 30, 9.5, TRUE);

-- 插入（位置顺序）
INSERT INTO users VALUES (2, 'Bob', NULL, 25, 8.0, TRUE);
INSERT INTO users VALUES (3, 'Carol', 'carol@x.com', 17, 7.5, FALSE);

-- 全表查询
SELECT * FROM users;

-- 条件查询
SELECT name, age FROM users WHERE age > 20;
SELECT * FROM users WHERE name LIKE 'A%';
SELECT * FROM users WHERE email IS NULL;
SELECT * FROM users WHERE id IN (1, 2, 3);
SELECT * FROM users WHERE age BETWEEN 20 AND 30;

-- 排序 + 分页
SELECT name, score FROM users ORDER BY score DESC LIMIT 10 OFFSET 0;

-- 更新
UPDATE users SET score = 9.9 WHERE name = 'Alice';
UPDATE users SET active = FALSE WHERE age < 18;

-- 删除
DELETE FROM users WHERE age < 18;
```

### 聚合与分组

```sql
-- 聚合函数
SELECT COUNT(*), AVG(score), MAX(age), MIN(age), SUM(score) FROM users;

-- GROUP BY
SELECT active, COUNT(*) AS cnt FROM users GROUP BY active;

-- HAVING 过滤分组
CREATE TABLE orders (
    id      INTEGER PRIMARY KEY,
    user_id INTEGER,
    amount  FLOAT,
    status  TEXT
);

INSERT INTO orders VALUES (1, 1, 100.0, 'paid');
INSERT INTO orders VALUES (2, 1, 200.0, 'paid');
INSERT INTO orders VALUES (3, 2,  50.0, 'pending');

SELECT user_id, SUM(amount) AS total
FROM orders
GROUP BY user_id
HAVING SUM(amount) > 100;
```

### 事务

```sql
-- 开始事务
BEGIN;

-- 插入临时数据
INSERT INTO users VALUES (100, 'Temp', NULL, 0, 0.0, TRUE);

-- 回滚（数据不会保留）
ROLLBACK;

-- 正式事务提交
BEGIN;
UPDATE users SET score = 10.0 WHERE id = 1;
COMMIT;
```

### 执行计划与维护

```sql
-- 查看查询执行计划
EXPLAIN SELECT * FROM users WHERE age > 20;

-- 回收已删除行的空间
VACUUM users;
```

---

## 🐍 Python API 用法

```python
from src.database import LittleData

# 使用 with 语句，自动 close（刷盘 + checkpoint）
with LittleData("./mydata") as db:

    # ── DDL ────────────────────────────────
    db.execute("""
        CREATE TABLE products (
            id      INTEGER PRIMARY KEY,
            name    TEXT    NOT NULL,
            price   FLOAT,
            stock   INTEGER DEFAULT 0
        )
    """)
    db.execute("CREATE INDEX idx_price ON products (price)")

    # ── 插入 ───────────────────────────────
    db.execute("INSERT INTO products VALUES (1, 'Laptop',  999.99, 50)")
    db.execute("INSERT INTO products VALUES (2, 'Mouse',    29.99, 200)")
    db.execute("INSERT INTO products VALUES (3, 'Keyboard', 79.99, 100)")

    # ── 查询 ───────────────────────────────
    result = db.execute("SELECT * FROM products WHERE price < 100")
    print("columns:", result["columns"])   # ['id', 'name', 'price', 'stock']
    for row in result["rows"]:
        print(row)                         # [2, 'Mouse', 29.99, 200]

    # ── 聚合 ───────────────────────────────
    r = db.execute("SELECT COUNT(*), AVG(price) FROM products")
    print(r["rows"])                       # [[3, 369.99]]

    # ── 事务 API ───────────────────────────
    txn = db.begin()
    db.execute("UPDATE products SET stock = stock - 1 WHERE id = 1", txn)
    db.commit(txn)                         # 也可 db.rollback(txn)

    # ── 统计信息 ───────────────────────────
    import json
    print(json.dumps(db.stats(), indent=2))

    # ── 批量执行多条 SQL ────────────────────
    results = db.execute_many("""
        INSERT INTO products VALUES (4, 'Monitor', 299.99, 30);
        INSERT INTO products VALUES (5, 'Webcam',   49.99, 80);
        SELECT COUNT(*) FROM products;
    """)
    for r in results:
        print(r["message"], r["rows"])
```

### 返回值结构

`db.execute()` 返回一个字典：

| 键 | 类型 | 说明 |
|----|------|------|
| `columns` | `List[str]` | 列名列表 |
| `rows` | `List[list]` | 数据行（SELECT 时有值） |
| `rowcount` | `int` | 影响/返回的行数 |
| `message` | `str` | 状态消息，如 `INSERT 0 1`、`ERROR: ...` |

---

## 🖥️ CLI 元命令速查

| 命令 | 说明 |
|------|------|
| `\d` | 列出当前库所有表 |
| `\d <table>` | 描述表结构（列名、类型、约束、索引） |
| `\l` | 列出所有数据库 |
| `\timing` | 开关查询计时（毫秒） |
| `\stats` | 显示缓冲池、事务、目录统计 |
| `\clear` | 清屏 |
| `\help` | 显示帮助 |
| `\q` / `\quit` | 退出 |

---

## 🔬 运行测试

```bash
# 在 littledata 根目录下运行
python tests/test_demo.py
```

测试覆盖：DDL 建表、DML 增删改查、聚合函数、GROUP BY/HAVING、事务回滚/提交、索引创建/使用、EXPLAIN、VACUUM、多数据库，共 **37 项测试**。

---

## 📐 架构对照（PostgreSQL vs LittleData）

| 概念 | PostgreSQL | LittleData |
|------|-----------|------------|
| 页面大小 | 8192 B | 8192 B |
| 页面头 | `PageHeaderData` | `PageHeader` |
| 行指针 | `ItemId` | `ItemPointer` |
| 元组头 | `HeapTupleHeaderData` | `TupleHeader` |
| 缓冲池 | `shared_buffers` (LRU) | `BufferPool` (LRU) |
| WAL | `pg_wal/` | `pg_wal/wal.log` (CRC32) |
| 事务 | `TransactionId` + MVCC | `TransactionManager` + snapshot |
| 系统目录 | `pg_catalog`（关系表） | `catalog.json`（JSON 原子写） |
| 索引 | B-tree / Hash / GiST | B+ 树 |
| 客户端 | `psql` | `littledata.py` |

---

## 🗺️ 数据类型

| SQL 类型 | Python 类型 | 说明 |
|----------|------------|------|
| `INTEGER` | `int` | 32 位整数 |
| `BIGINT` | `int` | 64 位整数 |
| `FLOAT` | `float` | 双精度浮点 |
| `TEXT` | `str` | 变长字符串 |
| `BOOLEAN` | `bool` | `TRUE` / `FALSE` |
| `TIMESTAMP` | `str` | ISO 8601 时间字符串 |
| `JSONB` | `dict/list` | JSON 对象（存储为文本） |

---

## 📦 数据目录结构

数据目录（默认 `./data`）在首次运行时自动创建：

```
data/
├── catalog.json         # 系统目录（库/表/索引元信息）
├── pg_wal/
│   └── wal.log          # 预写日志（WAL）
└── <table_name>.heap    # 每张表的 Heap 文件（8KB 页面）
```

---

## 🤝 贡献
阿城
欢迎捐赠
![输入图片说明](tests/c29eb795b61df0d9364676dc6d3688cf.jpg)

欢迎 Issues 和 Pull Requests！

1. Fork 本仓库
2. 创建 feature 分支：`git checkout -b feature/my-feature`
3. 提交代码：`git commit -m 'Add some feature'`
4. 推送：`git push origin feature/my-feature`
5. 提交 PR

---

## 📄 License

[MIT](LICENSE) © 2026 srgnet