# Thinkphp Xugudb Adapter

> ThinkPHP PHP 框架适配虚谷数据库(XuguDB)的完整指南。当用户需要将基于 ThinkPHP 的 PHP 项目配置或适配到虚谷数据库时使用此技能，包括驱动安装、方言包配置、数据库配置、模型定义、CRUD 操作、事务处理等。适用于从 MySQL/PostgreSQL 迁移或新建虚谷数据库项目。

- **Type:** Skill
- **Install:** `agentstack add skill-kourou25-xugudb-dev-skills-thinkphp-xugudb-adapter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kourou25](https://agentstack.voostack.com/s/kourou25)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [kourou25](https://github.com/kourou25)
- **Source:** https://github.com/kourou25/xugudb-dev-skills/tree/master/skills/xugudb-ecosystem/adapters/thinkphp-xugudb-adapter

## Install

```sh
agentstack add skill-kourou25-xugudb-dev-skills-thinkphp-xugudb-adapter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ThinkPHP 虚谷数据库适配指南

## 概述

本技能提供 ThinkPHP 适配虚谷数据库(XuguDB)的完整流程。ThinkPHP 是一个面向对象，简易、快速的轻量级 PHP 开发框架，通过虚谷数据库专用的方言包，可以无缝集成 ThinkPHP 框架的各种功能，包括数据库操作、模型定义、查询构建等。

## 适配流程

在开始适配前，按以下顺序检查和修改：

```
1. 依赖安装 → 2. 连接配置 → 3. 模型定义 → 4. 数据库迁移 → 5. CRUD 操作 → 6. 事务处理 → 7. 性能优化 → 8. 测试验证
```

## 第一步：安装依赖

### 安装 ThinkPHP

```bash
# 创建 ThinkPHP 项目
composer create-project topthink/think tp

# 或者使用 ThinkPHP 6
composer create-project topthink/think tp6
```

### 安装虚谷数据库驱动

1. **下载方言包** - 从虚谷数据库官方下载 ThinkPHP 方言压缩包
2. **解压方言包** - 解压压缩包获取方言文件
3. **放置方言文件** - 将方言文件放置到 ThinkPHP 项目的相应目录中：
   - 将 `builder` 文件夹下的 `Xugusql.php` 文件复制到 `vendor/topthink/think-orm/src/db/builder` 目录下
   - 将 `connector` 文件夹下的 `Xugusql.php` 文件复制到 `vendor/topthink/think-orm/src/db/connector` 目录下

### 验证驱动安装

```php
 'success', 'message' => 'Database connection established']);
        } catch (\Exception $e) {
            return json(['status' => 'error', 'message' => $e->getMessage()]);
        }
    }
}
```

## 第二步：配置连接

### 环境变量配置

在项目根目录创建 `.env` 文件配置数据库连接参数：

```ini
[APP]
DEBUG = true

[DATABASE]
TYPE = xugusql
HOSTNAME = 127.0.0.1
DATABASE = SYSTEM
USERNAME = SYSDBA
PASSWORD = SYSDBA
HOSTPORT = 5138
CHARSET = utf8
DEBUG = true
PREFIX = 
```

### 数据库配置文件

修改 `config/database.php` 配置文件：

```php
 'xugusql',
    
    // 自定义时间查询规则
    'time_query_rule' => [],
    
    // 自动写入时间戳字段
    'auto_timestamp' => false,
    
    // 时间字段取出后的默认时间格式
    'datetime_format' => false,
    
    // 数据库连接配置信息
    'connections' => [
        'xugusql' => [
            // 数据库类型
            'type' => 'xugusql',
            // 服务器地址
            'hostname' => env('database.hostname', '127.0.0.1'),
            // 数据库名
            'database' => env('database.database', 'SYSTEM'),
            // 用户名
            'username' => env('database.username', 'SYSDBA'),
            // 密码
            'password' => env('database.password', 'SYSDBA'),
            // 端口
            'hostport' => env('database.hostport', '5138'),
            // 数据库连接参数
            'params' => [],
            // 数据库编码默认采用utf8
            'charset' => env('database.charset', 'utf8'),
            // 数据库表前缀
            'prefix' => env('database.prefix', ''),
            // 数据库部署方式:0 集中式(单一服务器),1 分布式(主从服务器)
            'deploy' => 0,
            // 数据库读写是否分离 主从式有效
            'rw_separate' => false,
            // 读写分离后 主服务器数量
            'master_num' => 1,
            // 指定从服务器序号
            'slave_no' => '',
            // 是否严格检查字段是否存在
            'fields_strict' => true,
            // 是否需要断线重连
            'break_reconnect' => false,
            // 监听SQL
            'trigger_sql' => env('app_debug', true),
            // 开启字段缓存
            'fields_cache' => false,
        ],
    ],
];
```

### 连接参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| type | 数据库类型 | xugusql |
| hostname | 服务器地址 | 127.0.0.1 |
| database | 数据库名 | SYSTEM |
| username | 用户名 | SYSDBA |
| password | 密码 | - |
| hostport | 端口号 | 5138 |
| charset | 字符集 | utf8 |
| prefix | 表前缀 | - |
| deploy | 部署方式 | 0 |
| rw_separate | 读写分离 | false |
| master_num | 主服务器数量 | 1 |
| fields_strict | 严格字段检查 | true |
| break_reconnect | 断线重连 | false |
| trigger_sql | 监听SQL | true |
| fields_cache | 字段缓存 | false |

## 第三步：定义模型

### 基本模型定义

创建 `app/model/User.php` 文件：

```php
 'int',
        'username' => 'string',
        'email' => 'string',
        'age' => 'int',
        'status' => 'string',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
        'deleted_at' => 'datetime',
    ];
    
    // 类型转换
    protected $type = [
        'id' => 'integer',
        'age' => 'integer',
        'created_at' => 'datetime',
        'updated_at' => 'datetime',
    ];
}
```

### 字段类型说明

| 字段类型 | 说明 | 示例 |
|----------|------|------|
| int | 整数 | `'id' => 'int'` |
| integer | 整数 | `'id' => 'integer'` |
| float | 浮点数 | `'price' => 'float'` |
| boolean | 布尔值 | `'status' => 'boolean'` |
| string | 字符串 | `'name' => 'string'` |
| text | 文本 | `'content' => 'text'` |
| date | 日期 | `'birthday' => 'date'` |
| datetime | 日期时间 | `'created_at' => 'datetime'` |
| timestamp | 时间戳 | `'updated_at' => 'timestamp'` |
| json | JSON | `'meta' => 'json'` |

### 关联关系

创建 `app/model/Article.php` 文件：

```php
belongsTo(User::class, 'user_id');
    }
    
    public function tags()
    {
        return $this->belongsToMany(Tag::class, 'article_tags', 'tag_id', 'article_id');
    }
}
```

创建 `app/model/Tag.php` 文件：

```php
belongsToMany(Article::class, 'article_tags', 'article_id', 'tag_id');
    }
}
```

## 第四步：数据库迁移

### 创建迁移文件

```bash
# 创建迁移文件
php think migrate:create create_users_table
php think migrate:create create_articles_table
php think migrate:create create_tags_table
```

### 迁移文件示例

创建 `database/migrations/20240101000000_create_users_table.php` 文件：

```php
table('users', ['engine' => 'InnoDB']);
        $table->addColumn('username', 'string', ['limit' => 50, 'comment' => '用户名'])
              ->addColumn('email', 'string', ['limit' => 100, 'comment' => '邮箱'])
              ->addColumn('age', 'integer', ['default' => 0, 'comment' => '年龄'])
              ->addColumn('status', 'string', ['limit' => 20, 'default' => 'active', 'comment' => '状态'])
              ->addColumn('created_at', 'datetime', ['comment' => '创建时间'])
              ->addColumn('updated_at', 'datetime', ['comment' => '更新时间'])
              ->addColumn('deleted_at', 'datetime', ['null' => true, 'comment' => '删除时间'])
              ->addIndex(['username'], ['unique' => true])
              ->addIndex(['email'], ['unique' => true])
              ->addIndex(['status'])
              ->create();
    }
}
```

### 执行迁移

```bash
# 执行所有迁移
php think migrate:run

# 回滚迁移
php think migrate:rollback

# 回滚所有迁移
php think migrate:rollback -t 0
```

## 第五步：CRUD 操作

### 创建记录

```php
username = 'john';
        $user->email = 'john@example.com';
        $user->age = 25;
        $user->save();
        
        return json(['status' => 'success', 'data' => $user]);
    }
    
    // 批量创建
    public function batchCreate()
    {
        $users = [
            ['username' => 'user1', 'email' => 'user1@example.com', 'age' => 20],
            ['username' => 'user2', 'email' => 'user2@example.com', 'age' => 25],
            ['username' => 'user3', 'email' => 'user3@example.com', 'age' => 30],
        ];
        
        $result = User::insertAll($users);
        
        return json(['status' => 'success', 'data' => $result]);
    }
}
```

### 查询记录

```php
 'success', 'data' => $users]);
    }
    
    // 查询单个记录
    public function read($id)
    {
        $user = User::find($id);
        if ($user) {
            return json(['status' => 'success', 'data' => $user]);
        } else {
            return json(['status' => 'error', 'message' => 'User not found']);
        }
    }
    
    // 条件查询
    public function search()
    {
        $users = User::where('age', '>', 18)
                     ->where('status', 'active')
                     ->order('created_at', 'desc')
                     ->limit(10)
                     ->select();
        
        return json(['status' => 'success', 'data' => $users]);
    }
    
    // 复杂查询
    public function complexSearch()
    {
        $users = User::where('username', 'like', '%keyword%')
                     ->whereOr('email', 'like', '%keyword%')
                     ->field('id,username,email,age')
                     ->with(['articles'])
                     ->select();
        
        return json(['status' => 'success', 'data' => $users]);
    }
}
```

### 更新记录

```php
 'error', 'message' => 'User not found']);
        }
        
        $user->age = 30;
        $user->save();
        
        return json(['status' => 'success', 'data' => $user]);
    }
    
    // 批量更新
    public function batchUpdate()
    {
        $result = User::where('age', 'update(['status' => 'inactive']);
        
        return json(['status' => 'success', 'data' => $result]);
    }
}
```

### 删除记录

```php
 'error', 'message' => 'User not found']);
        }
        
        $user->delete();
        
        return json(['status' => 'success', 'message' => 'User deleted']);
    }
    
    // 批量删除（软删除）
    public function batchDelete()
    {
        $result = User::where('status', 'inactive')->delete();
        
        return json(['status' => 'success', 'data' => $result]);
    }
    
    // 物理删除
    public function forceDelete($id)
    {
        $user = User::withTrashed()->find($id);
        if (!$user) {
            return json(['status' => 'error', 'message' => 'User not found']);
        }
        
        $user->force()->delete();
        
        return json(['status' => 'success', 'message' => 'User permanently deleted']);
    }
}
```

## 第六步：高级功能

### 事务处理

```php
where('id', 1)
                ->dec('balance', 100)
                ->update();
            
            // 向接收方加款
            Db::table('users')
                ->where('id', 2)
                ->inc('balance', 100)
                ->update();
            
            // 提交事务
            Db::commit();
            
            return json(['status' => 'success', 'message' => 'Transfer successful']);
        } catch (\Exception $e) {
            // 回滚事务
            Db::rollback();
            
            return json(['status' => 'error', 'message' => $e->getMessage()]);
        }
    }
}
```

### 原生 SQL

```php
 ?', [18]);
        
        return json(['status' => 'success', 'data' => $users]);
    }
    
    // 执行原生 SQL 更新
    public function execute()
    {
        $result = Db::execute('UPDATE users SET age = ? WHERE id = ?', [30, 1]);
        
        return json(['status' => 'success', 'data' => $result]);
    }
}
```

### 查询构建器

```php
where('age', '>', 18)
                    ->where('status', 'active')
                    ->field('id,username,email,age')
                    ->order('age', 'desc')
                    ->limit(10)
                    ->select();
        
        return json(['status' => 'success', 'data' => $users]);
    }
    
    // 聚合查询
    public function aggregate()
    {
        $count = Db::table('users')->where('age', '>', 18)->count();
        $max = Db::table('users')->max('age');
        $min = Db::table('users')->min('age');
        $avg = Db::table('users')->avg('age');
        $sum = Db::table('users')->sum('age');
        
        return json([
            'status' => 'success',
            'data' => [
                'count' => $count,
                'max' => $max,
                'min' => $min,
                'avg' => $avg,
                'sum' => $sum,
            ]
        ]);
    }
}
```

## 第七步：性能优化

### 批量操作

```php
 "user{$i}",
                'email' => "user{$i}@example.com",
                'age' => 20 + ($i % 50),
                'status' => 'active',
                'created_at' => date('Y-m-d H:i:s'),
                'updated_at' => date('Y-m-d H:i:s'),
            ];
        }
        
        // 分批插入，每批 100 条
        $batchSize = 100;
        for ($i = 0; $i  'success', 'message' => 'Bulk insert completed']);
    }
}
```

### 查询优化

```php
index('idx_username')
                     ->select();
        
        return json(['status' => 'success', 'data' => $users]);
    }
    
    // 使用特定字段
    public function useFields()
    {
        $users = User::field('id,username,email')
                     ->select();
        
        return json(['status' => 'success', 'data' => $users]);
    }
    
    // 使用关联查询优化
    public function useWith()
    {
        $users = User::with(['articles' => function ($query) {
                        $query->field('id,title,user_id')->limit(5);
                    }])
                    ->limit(10)
                    ->select();
        
        return json(['status' => 'success', 'data' => $users]);
    }
}
```

## 第八步：测试验证

### 运行测试

```bash
# 运行所有测试
php think test

# 运行特定测试
php think test --filter UserController
```

### 验证数据库连接

```php
 'success', 'message' => 'Database connection established']);
        } catch (\Exception $e) {
            return json(['status' => 'error', 'message' => $e->getMessage()]);
        }
    }
    
    // 验证表结构
    public function testTableStructure()
    {
        try {
            $tableInfo = Db::query('DESCRIBE users');
            return json(['status' => 'success', 'data' => $tableInfo]);
        } catch (\Exception $e) {
            return json(['status' => 'error', 'message' => $e->getMessage()]);
        }
    }
}
```

## 常见问题排查

### 1. 数据库配置未定义

**现象：** `数据库配置未定义:XXX`

**解决：** 检查 `.env` 文件和 `config/database.php` 文件中的配置项是否正确

### 2. 驱动不支持

**现象：** `DRIVER [THINK] NOT SUPPORTED`

**解决：** 确保已安装模板引擎依赖，并使用小写的 `think` 作为模板引擎

### 3. 路由修改未生效

**现象：** 路由修改后未生效

**解决：** 执行命令 `php think clear:route` 清理缓存

### 4. 控制器方法冲突

**现象：** 一直跳转控制器的 INDEX 方法

**解决：** 检查路由列表中是否存在冲突定义，如 `Route::get('user', 'User/index')`，需要检查并删除

### 5. 连接失败

**现象：** 无法连接到虚谷数据库

**解决：**
- 检查 `.env` 文件中的连接参数是否正确
- 确保虚谷数据库服务已启动
- 检查网络连接和防火墙设置
- 验证用户名和密码是否正确

### 6. 迁移失败

**现象：** 数据库迁移失败

**解决：**
- 检查迁移文件中的 SQL 语法是否正确
- 检查数据库权限
- 检查表名是否已存在
- 尝试回滚迁移后重新执行

### 7. 性能问题

**现象：** 查询响应缓慢

**解决：**
- 创建合适的索引
- 使用 `field` 限制查询字段
- 使用 `with` 优化关联查询
- 使用分页查询
- 配置连接池参数

## 参考文档

详细的配置和使用说明请参考：
- [ThinkPHP 配置详解](references/thinkphp-configuration.md)
- [ThinkPHP 官方文档](https://doc.thinkphp.cn/)
- [虚谷数据库 ThinkPHP 适配文档](https://docs.xugudb.com/content/ecosystem/orm/php/thinkphp)
- [虚谷数据库 PHP 驱动文档](https://help.xugudb.com/content/development/php/setup)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kourou25](https://github.com/kourou25)
- **Source:** [kourou25/xugudb-dev-skills](https://github.com/kourou25/xugudb-dev-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kourou25-xugudb-dev-skills-thinkphp-xugudb-adapter
- Seller: https://agentstack.voostack.com/s/kourou25
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.