.datasource 文件 Schema¶

位置：/{软件名}.application/datasource/{数据源名}.datasource（单文件，非目录）　|　XML 根：dataSource　|　与技能对齐：generate-datasource-file 机制背景见 [[design/table-schema/overview]] §7.5。

1. 用途与落盘¶

数据源 = 软件连接哪个数据库。应用级扁平单文件，不落 module/ 下。表单动态表（TLK_/LOG_/PARM_）与平台运行表（T_DOCUMENT 等）落在**默认数据源**指向的库。

storage/workspace/{软件名}.application/datasource/{数据源名}.datasource

文件名 = <name> + .datasource；同软件 datasource/ 下不重名。脚本按名访问（queryByDSName(name,…)）用的就是 name（文件名去后缀），不是 id。

2. 属性表¶

属性	XML 形态	类型	默认	说明
`id`	根属性	string	须生成	`__` + 短 UUID
`name`	子元素	string	—	必填；脚本 `dsName` 用此名
`parentId` / `applicationid`	子元素	string	—	= 软件 id
`defaultDataSource`	子元素	bool	false	默认库须 true；同软件建议仅一个
`useType`	子元素	string	JDBC	`JDBC` / `JNDI`
`driverClass`	子元素	string		JDBC 驱动类
`url`	CDATA	string		JDBC URL；可含 `${ENV:default}` 占位
`username` / `password`	子元素/CDATA	string		可含占位
`dbType`	子元素	int	—	必填语义；见 §3
`poolsize` / `timeout`	子元素	string		如 `20` / `3600`
`jndiName`	子元素	string		useType=JNDI 时
`readonly`	子元素	bool	false	true=读写分离
`readonlyUseType`…`readonlyTimeout`、`readonlyJndiName`	子元素			只读侧一套（readonlyDbType 未开时常 0）

默认库解析：列软件下全部 DataSource → 优先 defaultDataSource=true → 都未标记取第一项（兼容旧包）。历史 .application 的 <datasourceId> 新写忽略。

3. dbType 与方言¶

值	库	值	库
1	Oracle	6	PostgreSQL
2	SQL Server	7	达梦 DM
3	DB2	8	KingBase
4	MySQL（最常见）	9	OceanBase
5	HSQL/H2	10	神通 Oscar

dbType 必须与真实库一致——决定动态表 DDL（Mysql*/Oracle*/…Builder）、DAO 与分页方言。URL/账号可写 ${DB_HOST:localhost} 式环境变量占位。

4. XML 骨架（JDBC MySQL 默认库）¶

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataSource id="__dsLeaveOAmain001">
  <name>main</name>
  <parentId>__a1b2c3d4e5f6g7h8i9j</parentId>
  <applicationid>__a1b2c3d4e5f6g7h8i9j</applicationid>
  <defaultDataSource>true</defaultDataSource>
  <useType>JDBC</useType>
  <driverClass>com.mysql.jdbc.Driver</driverClass>
  <url><![CDATA[jdbc:mysql://localhost:3307/obpm_leave?useUnicode=true&characterEncoding=utf8&useSSL=false]]></url>
  <username>root</username>
  <password><![CDATA[password]]></password>
  <dbType>4</dbType>
  <poolsize>20</poolsize>
  <timeout>3600</timeout>
  <readonly>false</readonly>
  <readonlyUseType>JDBC</readonlyUseType>
  <readonlyDbType>0</readonlyDbType>
</dataSource>

JNDI：useType=JNDI + jndiName，驱动/URL 可省。读写分离：readonly=true + 只读侧完整一套。

5. 默认库初始化（手工落盘后）¶

不走设计器 save 时，默认库落盘后须向 workspace/.sync/ 投递 *.init_default_datasource（内容 = .datasource 逻辑 URI 一行），平台真实建连 + 初始化 T_XXXX 静态表；成功归档 .sync/.done/、失败 .sync/.failed/。非默认附加数据源不投递。细节见 [[design/table-schema/overview]] §7.5。

无可用默认库时：软件激活不初始化 RT 表、表单动态表同步跳过、前台文档读写失败。

6. 相关¶

资源	文档
所属软件	[[application-file]]
动态表机制	`design/table-schema/overview.md`
生成操作指南	`agent-skills-usage/skills/generate-datasource-file/SKILL.md`（含全库驱动/URL 表、init_default_datasource.py）