# py-sqlx

**Repository Path**: MM-Q/py-sqlx

## Basic Information

- **Project Name**: py-sqlx
- **Description**: py-sqlx 是一个封装了 SQLAlchemy 的 Python 数据库工具库，旨在简化数据库操作并提供便捷的事务管理。它支持多种数据库（如 SQLite、MySQL 和 PostgreSQL），并提供了丰富的功能，包括 SQL 执行、脚本执行、事务管理、日志记录以及结果导出等。
- **Primary Language**: Python
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-26
- **Last Updated**: 2025-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SQLx: 一个简单强大的数据库操作工具库

## 项目简介
SQLx 是一个用于简化数据库操作的 Python 库，支持多种数据库（如 SQLite、MySQL、PostgreSQL）的连接和操作。它提供了自动事务管理和手动事务管理两种模式，同时封装了常用的数据库操作方法，如执行 SQL 语句、执行脚本文件、清空表数据等。此外，SQLx 还提供了日志记录功能，方便开发者调试和监控。

## 功能描述
- **自动事务管理**：通过 `Sqlx` 类，自动管理事务，确保操作的原子性。
- **手动事务管理**：通过 `SqlTx` 类，手动控制事务的提交和回滚。
- **数据库操作封装**：提供执行 SQL 语句、执行脚本文件、清空表数据等方法。
- **结果封装**：通过 `Result` 类封装查询结果，支持多种数据格式（如字典、JSON、CSV、Excel）的转换。
- **日志记录**：内置日志记录器，支持不同日志级别和颜色输出。
- **异常处理**：自定义异常类，方便开发者处理数据库错误和值类型错误。

## 安装步骤
1. 克隆项目代码：
   ```bash
   git clone https://gitee.com/MM-Q/sqlx.git
   ```
2. 进入项目目录：
   ```bash
   cd sqlx
   ```
3. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```

## 使用方法
### 示例 1：自动事务管理
```python
from sqlx import Sqlx

# 创建 Sqlx 实例
db = Sqlx("sqlite:///example.db")

# 执行 SQL 语句
result = db.exec_sql("SELECT * FROM users", is_return_data=True)

# 打印查询结果
print(result.result)
```

### 示例 2：手动事务管理
```python
from sqlx import SqlTx

# 创建 SqlTx 实例
db = SqlTx("sqlite:///example.db")

# 开始事务
db.begin()

try:
    # 执行 SQL 语句
    db.exec_sql("INSERT INTO users (name, age) VALUES (:name, :age)", params={"name": "Alice", "age": 30})
    # 提交事务
    db.commit()
except Exception as e:
    # 回滚事务
    db.rollback()
    print(f"Error: {e}")
```

### 示例 3：执行脚本文件
```python
from sqlx import Sqlx

# 创建 Sqlx 实例
db = Sqlx("sqlite:///example.db")

# 执行 SQL 脚本文件
result = db.exec_script("path/to/script.sql", batch_size=100)

# 打印受影响的行数
print(result.rowcount)
```

## 依赖关系
- Python 3.x
- SQLAlchemy
- openpyxl（用于 Excel 导出）
- sqlparse
- 其他依赖库（请参考 `requirements.txt` 文件）

## 贡献指南
欢迎提交 Pull Request，为项目贡献代码！请遵循以下规范：
1. 遵守 PEP 8 编码规范。
2. 提交代码前，请确保代码通过所有测试用例。
3. 提供详细的代码注释和文档说明。