更新日期：2024年09月11日
意事项
由于GBase 产品特性，在使用EntityFramework 实体框架时会遇到相应的
问题，例如不支持主外键、不支持自增列等，在实际使用时需要规避这些问题。
GBase 8a 程序员手册ADO.NET 篇
- 112 -
南大通用数据技术股份有限公司
11 处理连接异常及常用错误代码
当.NET 应用程序连接到服务器时，服务器的状态是不可预知的。因此为应
用程序增加一个错误处理是很重要的。当捕获到错误后，应用程序可根据错误
代码判断错误等级及采取必要的处理。
例如：
当连接出现错误时，
GBaseConnection 类将抛出一个GBaseException
对象，该对象有两个相关的属性用来处理错误：
Message：描述当前错误的消息
Number：GBase 错误号
处理错误时，可根据错误号处理应用程序的响应。两个最常见的连接错误
号如下：
1042：不能连接到服务器
1045：无效用户名和/或密码
连接字符串是应用通过GBase ADO.NET 传递到GBase 数据源时设置的初始
化信息。其格式是使用分号分隔的键/值参数对列表，关键字不区分大小写，并
将忽略键/值对之间的空格。
下面是一个具体的连接字符串的例子。
Server=127.0.0.1;Port=5258;Database=test; User
Id=gbase;Password=1111;Pooling=false
此连接串连接到GBase
Server 的test 数据库，
Server 的地址是127.0.0.1，
端口号为默认值5258，验证信息中的用户名是gbase，密码是1111，并且不启
用连接池。关于更详细的连接串的参数含义，请参考下面介绍的连接参数表。
在使用了GBase ADO.NET 中继承了 .NET Framework 用于处理连接字符串
的“字符串生成器类”后，字符串生成器会将连接串中的关键字转换成类的属
性并公开。这将有助于在运行时创建有效的连接字符串，并在创建连接前检查
字符串合法性。
在GBase ADO.NET 中可以使用的连接参数如下表。
GBase 8a 程序员手册ADO.NET 篇
- 8 -
南大通用数据技术股份有限公司
表5-1 连接参数表
关键字
默认值
描 述
User Id, Username,
Uid, User name,
user, userID
连接GBaseServer 的用户名。
pwd, Password
连接GBaseServer 的密码。
Host, Server, Data
Source,
DataSource,
Address, Addr,
Network Address
localhost
GBase 服务器的主机名。
Initial Catalog,
Database
缺省数据库。
Port
5258
连接端口。
Protocol,Connecti
on Protocol
socket
指明连接到GBase
Server 时使用的通讯协
议。对于socket 连接时可以使用“socket
或 tcp”做为参数值。
compress,Use
Compression
false
是否启用在GBase
ADO.NET 与 GBase 数据
库之间的传输数据压缩。
Allow Batch,
AllowBatch
true
当设置为true 时，
可以在一个command 执
行时指定多条SQL 语句，
语句之间使用
“;”
分隔。
Old Syntax,
OldSyntax,
UseOldSyntax, Use
Old Syntax
false
设置为true 时，所有代码中使用‘@’符
号做为参数标记，如：GBaseCommand
cmd
=
new GBaseCommand("INSERT INTO Test
(id) VALUES (@id)", c)。这个选项不建
议使用。
Connect Timeout,
Connection
Timeout,
ConnectionTimeout
15
连接GBase
Server 的超时时间。连接时超
过给定的时间后，程序会抛出异常。
GBase 8a 程序员手册ADO.NET 篇
南大通用数据技术股份有限公司
- 9 -
关键字
默认值
描 述
Default Command
Timeout, command
timeout,
DefaultCommandTim
eout
30
向GBase
Server 发出SQL 命令后，等待服
务器返回的超时时间。
Persist Security
Info,
PersistSecurityIn
fo
false
当设置为false 或no 时，安全敏感信息，
如：密码，在连接打开后，连接对象属性
中不可见。
可以设置的值有 true 和false，
yes 和no。
Allow Zero
Datetime,
AllowZeroDateTime
false
如果设置为true，将返回针对date 和
datetime 列的含有非法值的
GBaseDateTime 对象。如果设置为false，
将抛出异常。
Convert Zero
Datetime,
ConvertZeroDateTi
me
false
如果设置为 true, 则会将对象的非法值
转换为合法值，如：0000-00-00 转换成
0100-01-01。
Procedure Cache
Size, procedure
cache,
procedurecache,
ProcedureCacheSiz
e
25
设置存储过程缓存个数，接口默认将存储
最近使用的25 个存储过程的metadata
（输
入/输出数据类型）
。若要禁用缓存，请设
置此参数为0。
Respect Binary
Flags,
RespectBinaryFlag
s
true
默认时，执行查询“SELECT
CONCAT('hello,world', 1)”后的列值将
转换为byte[]类型。设置为 false 时，则
将列值转换为string 类型。
functions return
string,
FunctionsReturnSt
ring
false
设置为true 时，
所有的服务器函数执行后
的结果都转换为string 类型。
GBase 8a 程序员手册ADO.NET 篇
- 10 -
南大通用数据技术股份有限公司
关键字
默认值
描 述
Treat Tiny As
Boolean,
TreatTinyAsBoolea
n,
true
设置为false 时，则TINYINT(1)将被处理
为INT。
CharSet, Character
Set, CharacterSet
表明用于发送给服务器的所有查询中的字
符集编码，返回的结果集同样也使用此字
符集。
Treat Blobs As
UTF8,
TreatBlobsAsUTF8
False
二进制blob 被处理为UTF8
BlobAsUTF8Include
Pattern
null
模式匹配的列被处理为UTF8
BlobAsUTF8Exclude
Pattern
null
模式不匹配的列被处理为UTF8
Logging
false
开启日志功能，开启日志时需要在应用中
的App.config 中定义如下内容，
如果应用
中不包含App.config，则需要手动新建同
名文件。
…
注：上述其中 value="verbose" 含义为开启全部日志，
GBase 8a 程序员手册ADO.NET 篇
南大通用数据技术股份有限公司
- 11 -
关键字
默认值
描 述
可选值可以是字符串，也可为数值，如下列表中定义：
a) Off[0] ：不开启;
b) Error[1] ：仅限错误信息;
c) Warning[2] ：警告消息和错误信息;
d) Info[3] ：提示信息、警告消息和错误信息;
e) Verbose[4] ：详细消息、提示性消息、警告消息和
错误信息。
Ignore Prepare,
IgnorePrepare
true
是否忽略Prepare 调用。开启此参数时，
如果在程序中定义了预处理语句，如：
insert into tb values(@a)，则在每次执
行相同语句时，如：insert into
values(188)，
只需将数据188 发送给服务
器。不开启参数时，每次执行都需要将完
整的语句发送给服务器。因此当需要执行
批量操作时开启此参数可以大量减少网络
流量，提高执行效率。
Use Procedure
Bodies,
procedure bodies,
UseProcedureBodie
s
true
设置为true 时，当执行存储过程时，参数
的添加顺序不需要与存储过程体定义的参
数顺序一致。为false 时，顺序需保持一
致。
Allow User
Variables,
AllowUserVariable
s
false
是否在执行的SQL 语句中允许存在用户变
量，设置为true 时，可以在语句中包含用
户变量，如：SET @a='test';SELECT @a;。
Auto Enlist,
AutoEnlist
true
当使用分布式事务时，该关键字指示
GBase.Data.GBaseClient 是否检测事务
上下文并自动在分布式事务范围中登记连
接。如果 AutoEnlist=true，连接将自动
在事务范围（TransactionScope）中登记。
如果 AutoEnlist=false，
连接不会自动登
GBase 8a 程序员手册ADO.NET 篇
- 12 -
南大通用数据技术股份有限公司
关键字
默认值
描 述
记
。
登
记
后
使
用
TransactionScope.Complete() 方法可将
该分布式事务提交，使用
TransactionScope.Dispose() 方法则回
滚。
Interactive
Session,
interactive
false
设置为true 时，定义为交互式客户端；为
false 时，
定义为非交互式客户端。
交互式
客户端为与Server 通讯频繁的一类连接，
非交互式客户端为通讯不频繁的连接。
Keep Alive,
Keepalive
0
对于TCP 连接，如果该连接空闲时间（与
Server 没有任何数据交互）超过定义的
Connection Timeout 时间，TCP 协议会自
动发出探测数据包（keepalive）检测与服
务器是否能够正常通讯。此参数为第一个
包发出前的等待时间。
默认值0 为不发送。
MultipleActiveRes
ultSets,
Multiple Active
ResultSets
false
支持多活动结果集，设置为true 时，同一
个连接中可以支持多个活动结果集的使
用；设置为false 时，同一个连接中只支
持一个活动结果集。
集群高可用功能参数
注：Failover, GClusterID, IpList 参数仅用于8a 集群的高可用功能使用，
包括连接池。
Failover, fail
over
false
设置true 时，开启集群高可用功能
GClusterID,
gcluster id
集群ID，可以为有效的数字字母组合。必
须以a-z 任意字符开头的字符串，
gclusterId 组成可以包含a-z、
0-9 所有字
符长度为最大为20。
GBase 8a 程序员手册ADO.NET 篇
南大通用数据技术股份有限公司
- 13 -
关键字
默认值
描 述
当failover=true 且IpList 参数不为空
时，设置该参数，8a 集群接口的负载均衡
开启（负载策略为轮询）
。在同一应用程序
中，gclusterId 可由程序开发人员自行决
定，全工程唯一即可。
注：当设置gclusteId 时，集群高可用功
能自动转换为集群负载均衡。
IpList, ip list
IP 地址列表。列表中的参数以“,”分隔，
中间不能含有空格。
例如：现有集群中有三个节点：
1) 192.168.0.2
2) 192.168.0.3
3) 192.168.0.4
当创建数据库连接时，如果当前节点
（192.168.0.2）不可用，我们希望把连接
请求转移到集群中任意一个可用的节点上
时可以使用下面的参数组合：
Server=192.168.0.2;User
Id=usr;Password=pwd;Failover=true;Ip
List=192.168.0.3,192.168.0.4
负载均衡连接池参数
pooling
true
默认时，则开启连接池功能，
GBaseConnection 对象将从连接池中获
取。可设置的值为true 和false，yes 和
no。
min pool size, min 3
最小空闲连接数。连接池中允许的最小空
GBase 8a 程序员手册ADO.NET 篇
- 14 -
南大通用数据技术股份有限公司
关键字
默认值
描 述
idle size,
MinimumPoolSize,
Minimum Pool Size
闲连接数量。
此值为集群最小空闲连接数，
如：集群有3 个节点，每个节点的最小空
闲连接数为1 个。
max pool size,max
idle size,
MaximumPoolSize,
Maximum Pool Size
3
最大空闲连接数。连接池中允许的最大空
闲连接数量。
此值为集群最大空闲连接数，
如：集群有3 个节点，每个节点的最大空
闲连接数为1 个。
checkout timeout,
CheckoutTimeout
0
当连接池中空闲连接用尽后，客户端等待
获取新连接的时间，
超时后将抛出异常,如
设为0 则无限期等待。单位秒。
initial pool size,
InitialPoolSize
3
初始化连接池时缓存连接的数量，取值应
在min Idle size 与max Idle size 之间。
此值为集群初始化缓存连接数，如：集群
有3 个节点，每个节点的初始化缓存连接
数为1 个。
max active size,
Maximum Active
Size,
MaximumActiveSize
2000
最大活动连接数，允许从连接池中借出连
接的最大数量。
max idle lifetime,
Maximum Idle
LifeTime,
MaximumIdleLifeTi
me
28800(8
hrs)
空闲连接存活时间。
该连接在连接池中多长时间没有被借用，
则将其关闭，默认与GBase
Server 中允许
连接存活的最大超时时间一致。单位秒。
max inuse
lifetime, Maximum
inuse LifeTime,
MaximumInUseLifeT
ime
0
已用连接存活时间。
连接池借出的连接多长时间后不归还，则
认为该连接出现问题，连接池会将其强制
关闭。当为0 时则为无限长时间。单位秒。
test on borrow,
TestOnBorrow
false
获取连接前是否检查有效性。是指从空闲
连接队列中获取到连接后检查是否能够与
GBase 8a 程序员手册ADO.NET 篇
南大通用数据技术股份有限公司
- 15 -
关键字
默认值
描 述
GBase 集群正常交互。
可设置的值有：
true
和 false。
提示：当设置此参数后，会在每次从连接
池中获取连接后，进行检查。此操作会有
性能上的损失，但可以保证获取到的连接
时可用的。
test on return,
TestOnReturn
false
返回连接时是否检查有效性。是指将连接
对象返回到空闲队列前检查是否能够与
GBase 集群正常交互。
可设置的值有：
true
和 false。
提示：当设置此参数后，当连接返回到连
接池中前，进行检查。此操作会有性能上
的损失，但可以保证归还到连接池中的连
接是可用的。
test while idle,
TestWhileIdle
true
是否检查连接的有效性，包括：
1) 检查空闲的连接和借出的连接是否过
期，过期条件为max
idle
lifetime 和max
inuse lifetime 约束。
2) 空闲连接是否能够与Server 正常交互。
3) 动态补充空闲连接数量。
可设置的值有：true 和 false。
invalid idle test
period,
invalididletestpe
riod
60
空闲连接检测周期。每隔多长时间检查所
有连接池中的空闲连接。单位秒。
supply idle
period,
supplyidleperiod
60
维护空闲连接周期。每隔多长时间维护连
接池中的连接，维护功能包括：补充缺少
的空闲连接和删除多余空闲连接。补充条
件为可用节点的当前空闲连接数小于最小
空闲连接数。删除条件为当前空闲连接数
大于最大空闲连接数。维护功能随负载均
GBase 8a 程序员手册ADO.NET 篇
- 16 -
南大通用数据技术股份有限公司
关键字
默认值
描 述
衡连接池开启而开启。单位秒。
LoadBalanceStrate
gy,
load balance
strategy, LBS
polling
客户端负载策略，连接池把请求分配给节
点的策略。可选值为：
1) polling ：轮询策略。
2) mncp ：节点当前连接最小者优先。
connection reset,
ConnectionReset
false
设置为true 时，
表明连接从池中获取后是
否状态重置。
可设置的值为：
true 和false。