2.1.8.database
2.1.8.database
database 包提供仓颉访问数据库的接口，当前仅支持 SQL/CLI 接口。
注意：当前 database 包本身没有对外接口，因此无法被引入。使用 SQL/CLI 接口时需引入 database.sql 包。
sql 包
介绍
sql 包提供了 SQL/CLI 的通用接口，配合数据库驱动 Driver 完成对数据库的各项操作。
数据类型对应表
Sql 数据类型和仓颉数据类型对应表。
| SQL | CDBC/Cangjie | SqlDataType | 说明 |
|---|---|---|---|
CHAR | String | SqlChar | |
VARCHAR | String | SqlVarchar | |
CLOB | io.InputStream | SqlClob | |
BINARY | Array<Byte> | SqlBinary | |
VARBINARY | Array<Byte> | SqlVarBinary | |
BLOB | io.InputStream | SqlBlob | |
NUMERIC | / | / | 仓颉无对应原生类型, 用户可使用 SqlBinary 扩展 |
DECIMAL | / | / | 仓颉无对应原生类型, 用户可使用 SqlBinary 扩展 |
BOOLEAN | Bool | SqlBool | |
TINYINT | Int8 | SqlByte | |
SMALLINT | Int16 | SqlSmallInt | |
INTEGER | Int32 | SqlInteger | |
BIGINT | Int64 | SqlBigInt | |
REAL | Float32 | SqlReal | |
DOUBLE | Float64 | SqlDouble | |
DATE | time.DateTime | SqlDate | YEAR, MONTH, and DAY |
TIME | time.DateTime | SqlTime | HOUR, MINUTE, and SECOND 不包含 TIME ZONE |
TIMETZ | time.DateTime | SqlTimeTz | HOUR, MINUTE, and SECOND 包含 TIME ZONE |
TIMESTAMP | time.DateTime | SqlTimestamp | YEAR, MONTH, DAY, HOUR, MINUTE, SECOND and TIME ZONE |
INTERVAL | time.Duration | SqlInterval | year-month interval or a day-time interval |
主要接口
interface Driver
public interface Driver {
prop name: String
prop version: String
prop preferredPooling: Bool
func open(connectionString: String, opts: Array<(String, String)>): Datasource
}
接口 Driver，数据库驱动接口，继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
prop name
prop name: String
功能：驱动名称
prop version
prop version: String
功能：驱动版本
prop preferredPooling
prop preferredPooling: Bool
功能：指示驱动程序是否与连接池亲和。
如果否，则不建议使用连接池。
比如 sqlite 驱动连接池化的收益不明显，不建议使用连接池。
func open
func open(connectionString: String, opts: Array<(String, String)>): Datasource
功能：通过 connectionString 和选项打开数据源。
参数：
- connectionString：数据库连接字符串
- opts：key,value 的 tuple 数组，打开数据源的选项
返回值：数据源实例
interface Datasource
public interface Datasource <: Resource {
func setOption(key: String, value: String): Unit
func connect(): Connection
}
接口 Datasource，数据源接口，继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
func setOption
func setOption(key: String, value: String): Unit
功能：设置连接选项。
参数：
- key：连接选项名称
- value：连接选项的值
func connect
func connect(): Connection
功能：返回一个可用的连接。
返回值：数据库连接实例
interface Connection
public interface Connection <: Resource {
prop state: ConnectionState
func getMetaData(): Map<String, String>
func prepareStatement(sql: String): Statement
func createTransaction(): Transaction
}
接口 Connection ，数据库连接接口，继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
prop state
prop state: ConnectionState
功能：描述与数据源连接的当前状态
func getMetaData
func getMetaData(): Map<String, String>
功能：返回连接到的数据源元数据。
返回值：数据源元数据
func prepareStatement
func prepareStatement(sql: String): Statement
功能：通过传入的 sql 语句，返回一个预执行的 Statement 对象实例。
参数：
- sql：预执行的 sql 语句，sql 语句的参数只支持 ? 符号占位符
返回值：一个可以执行 sql 语句的实例对象
异常：
- SqlException：语法错误， sql 语句包含不认识的字符
func createTransaction
func createTransaction(): Transaction
功能：创建事务对象。
返回值：事务对象
异常：
- SqlException：已经处于事务状态，不支持并行事务。
interface Statement
public interface Statement <: Resource {
prop parameterColumnInfos: Array<ColumnInfo>
func setOption(key: String, value: String): Unit
func update(params: Array<SqlDbType>): UpdateResult
func query(params: Array<SqlDbType>): QueryResult
}
接口 Statement ，sql 语句预执行接口，它绑定了一个 Connection , 继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
prop parameterColumnInfos
prop parameterColumnInfos: Array<ColumnInfo>
功能：预执行 sql 语句中，占位参数的列信息，比如列名，列类型，列长度，是否允许数据库 Null 值等
func setOption
func setOption(key: String, value: String): Unit
功能：设置预执行 sql 语句选项。
参数：
- key：连接选项名称
- value：连接选项的值
func update
func update(params: Array<SqlDbType>): UpdateResult
功能：执行 sql 语句，得到更新结果。
参数：
- params：sql 数据类型的数据列表，用于替换 sql 语句中的 ？占位符
返回值：更新结果。
异常：
- SqlException：执行过程中发生了异常，比如网络中断，服务器超时，参数个数不正确
func query
func query(params: Array<SqlDbType>): QueryResult
功能：执行 sql 语句，得到查询结果。
参数：
- params：sql 数据类型的数据列表，用于替换 sql 语句中的 ？占位符
返回值：查询结果。
异常：
- SqlException：执行过程中发生了异常，比如网络中断，服务器超时，参数个数不正确
interface UpdateResult
public interface UpdateResult {
prop rowCount: Int64
prop lastInsertId: Int64
}
接口 UpdateResult，它是执行 Insert、Update、Delete 语句产生的结果接口。继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
prop rowCount
prop rowCount: Int64
功能：执行 Insert, Update, Delete 语句影响的行数
prop lastInsertId
prop lastInsertId: Int64
功能：执行 Insert 语句自动生成的最后 row ID ，如果不支持则为 0
interface ColumnInfo
public interface ColumnInfo {
prop name: String
prop typeName: String
prop displaySize: Int64
prop length: Int64
prop scale: Int64
prop nullable: Bool
}
接口 ColumnInfo，它一般是执行 Select/Query 语句返回结果的列信息，通过这个信息，可以支持数据库服务侧扩展的数据类型值解析
prop name
prop name: String
功能：列名或者别名
prop typeName
prop typeName: String
功能：获取列类型名称，如果在 SqlDataType 中定义，返回 SqlDataType.toString(), 如果未在 SqlDataType 中定义，由数据库驱动定义
prop displaySize
prop displaySize: Int64
功能：获取列值的最大显示长度，如果无限制，则应该返回 Int64.Max （仍然受数据库的限制）
prop length
prop length: Int64
功能：获取列值大小。
- 对于数值数据，这是最大精度。
- 对于字符数据，这是以字符为单位的长度。
- 对于日期时间数据类型，这是字符串表示形式的最大字符长度。
- 对于二进制数据，这是以字节为单位的长度。
- 对于 RowID 数据类型，这是以字节为单位的长度。
- 对于列大小不适用的数据类型，返回 0。
prop scale
prop scale: Int64
功能：获取列值的小数长度，如果无小数部分，返回 0。
prop nullable
prop nullable: Bool
功能：列值是否允许数据库 Null 值
interface QueryResult
public interface QueryResult <: Resource {
prop columnInfos: Array<ColumnInfo>
func next(values: Array<SqlDbType>): Bool
}
接口 QueryResult，它是执行 Select 语句产生的结果接口。继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
prop columnInfos
prop columnInfos: Array<ColumnInfo>
功能：返回结果集的列信息，比如列名，列类型，列长度，是否允许数据库 Null 值等
func next
func next(values: Array<SqlDbType>): Bool
功能：向后移动一行，必须先调用一次 next 才能移动到第一行，第二次调用移动到第二行，依此类推。当返回 true 时，驱动会在 values 中填入行数据；当返回 false 时结束，且不会修改 values 的内容。
参数：
- params：
返回值：存在下一行则返回 true，否则返回 false
interface Transaction
public interface Transaction {
mut prop isoLevel: TransactionIsoLevel
mut prop accessMode: TransactionAccessMode
mut prop deferrableMode: TransactionDeferrableMode
func begin(): Unit
func commit(): Unit
func rollback(): Unit
func save(savePointName: String): Unit
func rollback(savePointName: String): Unit
func release(savePointName: String): Unit
}
接口 Transaction，定义数据库事务的核心行为。继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。
prop isoLevel
mut prop isoLevel: TransactionIsoLevel
功能：获取数据库事务隔离级别。
prop accessMode
mut prop accessMode: TransactionAccessMode
功能：获取数据库事务访问模式。
prop deferrableMode
mut prop deferrableMode: TransactionDeferrableMode
功能：获取数据库事务延迟模式。
func begin
func begin(): Unit
功能：开始数据库事务。
异常：
- SqlException：提交事务时服务器端发生错误。
- SqlException：事务已提交或回滚或连接已断开。
func commit
func commit(): Unit
功能：提交数据库事务。
异常：
- SqlException：提交事务时服务器端发生错误。
- SqlException：事务已提交或回滚或连接已断开。
func rollback
func rollback(): Unit
功能：从挂起状态回滚事务。
异常：
- SqlException：回滚事务时服务器端发生错误。
- SqlException：事务已提交或回滚或连接已断开。
func save
func save(savePointName: String): Unit
功能：在事务中创建一个指定名称的保存点，可用于回滚此保存点之后的事务。
参数：
- savePointName：保存点名称
异常：
- SqlException：提交事务时服务器端发生错误。
- SqlException：事务已提交或回滚或连接已断开。
func rollback
func rollback(savePointName: String): Unit
功能：回滚事务至指定保存点名称。
参数：
- savePointName：保存点名称
异常：
- SqlException：提交事务时服务器端发生错误。
- SqlException：事务已提交或回滚或连接已断开。
func release
func release(savePointName: String): Unit
功能：销毁先前在当前事务中定义的保存点。这允许系统在事务结束之前回收一些资源。
参数：
- savePointName：保存点名称
异常：
- SqlException：提交事务时服务器端发生错误。
- SqlException：事务已提交或回滚或连接已断开。
enum ConnectionState
public enum ConnectionState <: Equatable<ConnectionState> {
| Broken
| Closed
| Connecting
| Connected
}
枚举 ConnectionState ，描述与数据源连接的当前状态
Broken
| Broken
功能：表示与数据源的连接已中断。只有在 Connected 之后才可能发生这种情况。
Closed
| Closed
功能：表示连接对象已关闭
Connecting
| Connecting
功能：表示连接对象正在与数据源连接
Connected
| Connected
功能：表示连接对象已与数据源连接上
operator func ==
public operator func ==(rhs: ConnectionState): Bool
功能：判断数据源连接状态是否相同。
参数：
- rhs：数据源连接状态
返回值：传入数据源连接状态与当前状态相同则返回 true ，否则返回 false
operator func !=
public operator func !=(rhs: ConnectionState): Bool
功能：判断数据源连接状态是否不同。
参数：
- rhs：数据源连接状态
返回值：传入数据源连接状态与当前状态相同则返回 false ，否则返回 true
enum TransactionIsoLevel
public enum TransactionIsoLevel <: ToString & Hashable & Equatable<TransactionIsoLevel> {
| Unspecified
| ReadCommitted
| ReadUncommitted
| RepeatableRead
| Snapshot
| Serializable
| Linearizable
| Chaos
}
事务隔离定义了数据库系统中，一个事务中操作的结果在何时以何种方式对其他并发事务操作可见。
Unspecified
Unspecified
功能：未指定的事务隔离级别，其行为取决于特定的数据库服务器。
ReadCommitted
ReadCommitted
功能：表示事务等待，直到其他事务写锁定的行被解锁；这将防止它读取任何“脏”数据。
ReadUncommitted
ReadUncommitted
功能：表示事务之间不隔离。
RepeatableRead
RepeatableRead
功能：表示事务等待，直到其他事务写锁定的行被解锁；这将防止它读取任何“脏”数据。
Snapshot
Snapshot
功能：表示快照隔离通过使用行版本控制避免了大多数锁定和阻止。
Serializable
Serializable
功能：表示事务等待，直到其他事务写锁定的行被解锁；这将防止它读取任何“脏”数据。
Linearizable
Linearizable
功能：表示当您查看单个对象（即 db 行或 nosql 记录）上的操作子集时，线性化是相关的。
Chaos
Chaos
功能：表示无法覆盖来自高度隔离事务的挂起更改。
func toString
public func toString(): String
功能：返回事务隔离级别的字符串表示。
返回值：事务隔离级别的字符串
func hashCode
public func hashCode(): Int64
功能：获取事务隔离级别的哈希值。
返回值：事务隔离级别的哈希值
operator func ==
public operator func == (rhs: TransactionIsoLevel): Bool
功能：判断两个 TransactionIsoLevel 是否相等。
参数：
- that：传入
TransactionIsoLevel
返回值：如果相等，则返回 true；否则，返回 false
operator func !=
public operator func != (rhs: TransactionIsoLevel): Bool
功能：判断两个 TransactionIsoLevel 是否不相等。
参数：
- that：传入
TransactionIsoLevel
返回值：如果不相等，则返回 true；否则，返回 false
enum TransactionAccessMode
public enum TransactionAccessMode <: ToString & Hashable & Equatable<TransactionAccessMode> {
| Unspecified
| ReadWrite
| ReadOnly
}
事务读写模式
Unspecified
Unspecified
功能：未指定的事务读写模式，其行为取决于特定的数据库服务器。
ReadWrite
ReadWrite
功能：表示读 + 写模式
ReadOnly
ReadOnly
功能：表示只读模式
func toString
public func toString(): String
功能：返回事务读写模式的字符串表示。
返回值：事务读写模式的字符串
func hashCode
public func hashCode(): Int64
功能：获取事务读写模式的哈希值。
返回值：事务读写模式的哈希值
operator func ==
public operator func == (rhs: TransactionAccessMode): Bool
功能：判断两个 TransactionAccessMode 是否相等。
参数：
- that：传入
TransactionAccessMode
返回值：如果相等，则返回 true；否则，返回 false
operator func !=
public operator func != (rhs: TransactionAccessMode): Bool
功能：判断两个 TransactionAccessMode 是否不相等。
参数：
- that：传入
TransactionAccessMode
返回值：如果不相等，则返回 true；否则，返回 false
enum TransactionDeferrableMode
public enum TransactionDeferrableMode <: ToString & Hashable & Equatable<TransactionDeferrableMode> {
| Unspecified
| Deferrable
| NotDeferrable
}
事务的延迟模式
Unspecified
Unspecified
功能：未指定的事务延迟模式，其行为取决于特定的数据库服务器。
Deferrable
Deferrable
功能：延迟事务是指在前滚阶段结束时未提交的事务，并且遇到了阻止其回滚的错误。因为事务无法回滚，所以它被推迟。
NotDeferrable
NotDeferrable
功能：表示不可延迟
func toString
public func toString(): String
功能：返回事务延迟模式的字符串表示。
返回值：事务延迟模式的字符串
func hashCode
public func hashCode(): Int64
功能：获取事务延迟模式的哈希值。
返回值：事务延迟模式的哈希值
operator func ==
public operator func == (rhs: TransactionDeferrableMode): Bool
功能：判断两个 TransactionDeferrableMode 是否相等。
参数：
- that：传入
TransactionDeferrableMode
返回值：如果相等，则返回 true；否则，返回 false
operator func !=
public operator func != (rhs: TransactionDeferrableMode): Bool
功能：判断两个 TransactionDeferrableMode 是否不相等。
参数：
- that：传入
TransactionDeferrableMode
返回值：如果不相等，则返回 true；否则，返回 false
class DriverManager
public class DriverManager
类 DriverManager ，支持运行时根据驱动名获取数据库驱动实例
func register
public static func register(driverName: String, driver: Driver): Unit
功能：按名称注册数据库驱动。如果名称重复，会抛出 SqlException。本方法并发安全。
参数：
- driverName：驱动名称
- driver：驱动实例
异常：
- SqlException：driverName 已经注册
func deregister
public static func deregister(driverName: String): Unit
功能：按名称去注册数据库驱动（如果存在）。本函数并发安全。
参数：
- driverName：驱动名称
func getDriver
public static func getDriver(driverName: String): Option<Driver>
功能：按名称获取已注册的数据库驱动，如果不存在返回 None。本函数并发安全。
参数：
- driverName：驱动名称
返回值：若驱动存在返回 Option 包装的驱动实例，否则返回 None
func drivers
public static func drivers(): Array<String>
功能：返回已注册数据库驱动名称的列表(已排序)。本方法并发安全。
返回值：数据库驱动名称的列表
class PooledDatasource
public class PooledDatasource <: Datasource {
public init(datasource: Datasource)
}
数据库连接池类，提供数据库连接池能力，以下是连接池属性。
init
public init(datasource: Datasource)
功能：构造函数，入参必须为 Datasource 对象。
prop idleTimeout
public mut prop idleTimeout: Duration
功能：允许连接在池中闲置的最长时间，超过这个时间的空闲连接可能会被回收。
prop maxLifeTime
public mut prop maxLifeTime: Duration
功能：自连接创建以来的持续时间，在该持续时间之后，连接将自动关闭。
prop connectionTimeout
public mut prop connectionTimeout: Duration
功能：从池中获取连接的超时时间，超时后抛出 TimeoutException。
prop keepaliveTime
public mut prop keepaliveTime: Duration
功能：检查空闲连接健康状况的间隔时间，防止它被数据库或网络基础设施超时。
prop maxSize
public mut prop maxSize: Int32
功能：连接池最大连接数量，负数表示无限制。
prop maxIdleSize
public mut prop maxIdleSize: Int32
功能：最大空闲连接数量，超过这个数量的空闲连接会被关闭，负数表示无限制。
func setOption
public func setOption(key: String, value: String): Unit
功能：设置数据库驱动连接选项（公钥在 SqlOption 中预定义）。
func connect
public func connect(): Connection
功能：获取一个连接。
func isClosed
public func isClosed(): Bool
功能：判断连接是否关闭。
func close
public func close(): Unit
功能：关闭连接池中的所有连接并阻止其它连接请求调用该方法会阻塞至所有连接关闭并归还到连接池。
class SqlException
public open class SqlException <: Exception {
public init()
public init(message: String)
public init(message: String, sqlState: String, errorCode: Int64)
}
类 SqlException，继承了 Exception 用于处理 SQL 相关的异常。
init
public init()
功能：无参构造函数。
init
public init(message: String)
参数：
- message：预定义消息
init
public init(message: String, sqlState: String, errorCode: Int64)
参数：
- message: 预定义消息
- sqlState: 长度为五个字符的字符串，是数据库系统返回的最后执行的 SQL 语句状态。
- errorCode: 数据库供应商返回的整数错误代码。
prop sqlState
public prop sqlState: String
功能：长度为五个字符的字符串，是数据库系统返回的最后执行的 SQL 语句状态。
prop errorCode
public prop errorCode: Int64
功能：数据库供应商返回的整数错误代码。
prop message
public override prop message: String
功能：获取异常信息字符串。
class SqlOption
public class SqlOption {
public static let URL = "url"
public static let Host = "host"
public static let Username = "username"
public static let Password = "password"
public static let Driver = "driver"
public static let Database = "database"
public static let Encoding = "encoding"
public static let ConnectionTimeout = "connection_timeout"
public static let UpdateTimeout = "update_timeout"
public static let QueryTimeout = "query_timeout"
public static let FetchRows = "fetch_rows"
public static let SSLMode = "ssl.mode"
public static let SSLModePreferred = "ssl.mode.preferred"
public static let SSLModeDisabled = "ssl.mode.disabled"
public static let SSLModeRequired = "ssl.mode.required"
public static let SSLModeVerifyCA = "ssl.mode.verify_ca"
public static let SSLModeVerifyFull = "ssl.mode.verify_full"
public static let SSLCA = "ssl.ca"
public static let SSLCert = "ssl.cert"
public static let SSLKey = "ssl.key"
public static let SSLKeyPassword = "ssl.key.password"
public static let SSLSni = "ssl.sni"
public static let Tls12Ciphersuites = "tls1.2.ciphersuites"
public static let Tls13Ciphersuites = "tls1.3.ciphersuites"
public static let TlsVersion = "tls.version"
}
预定义的 SQL 选项名称和值。如果需要扩展，请不要与这些名称和值冲突。
URL
public static let URL = "url"
功能：获取 URL 数据库连接字符串
Host
public static let Host = "host"
功能：获取 Host 数据库服务器主机名或者 IP 地址
Username
public static let Username = "username"
功能：获取 Username 连接数据库的用户名
Password
public static let Password = "password"
功能：获取 Password 连接数据库的密码
Driver
public static let Driver = "driver"
功能：获取 Driver 数据库驱动名称，比如 postgres, opengauss
Database
public static let Database = "database"
功能：获取 Database 数据库名称
Encoding
public static let Encoding = "encoding"
功能：获取 Encoding 数据库字符集编码类型
ConnectionTimeout
public static let ConnectionTimeout = "connection_timeout"
功能：获取 ConnectionTimeout connect 操作的超时时间，单位 ms
UpdateTimeout
public static let UpdateTimeout = "update_timeout"
功能：获取 UpdateTimeout update 操作的超时时间，单位 ms
QueryTimeout
public static let QueryTimeout = "query_timeout"
功能：获取 QueryTimeout query 操作的超时时间，单位 ms
FetchRows
public static let FetchRows = "fetch_rows"
功能：获取 FetchRows 指定需要获取额外行时从数据库中提取的行数
SSLMode
public static let SSLMode = "ssl.mode"
功能：获取 SSLMode 传输层加密模式 key
SSLModePreferred
public static let SSLModePreferred = "ssl.mode.preferred"
功能：SSLModePreferred 如果服务器支持加密连接，则建立加密连接; 如果无法建立加密连接，则回退到未加密连接，这是 SSLMode 的默认值
SSLModeDisabled
public static let SSLModeDisabled = "ssl.mode.disabled"
功能：SSLModeDisabled 建立未加密的连接
SSLModeRequired
public static let SSLModeRequired = "ssl.mode.required"
功能：SSLModeRequired 如果服务器支持加密连接，则建立加密连接。如果无法建立加密连接，则连接失败。
SSLModeVerifyCA
public static let SSLModeVerifyCA = "ssl.mode.verify_ca"
功能：SSLModeVerifyCA 和 SSLModeRequired 类似，但是增加了校验服务器证书，如果校验失败，则连接失败。
SSLModeVerifyFull
public static let SSLModeVerifyFull = "ssl.mode.verify_full"
功能：SSLModeVerifyFull 和 SSLModeVerifyCA 类似，但通过对照服务器发送给客户端的证书中的标识检查客户端用于连接到服务器的主机名来执行主机名身份验证。
SSLCA
public static let SSLCA = "ssl.ca"
功能：SSLCA 证书颁发机构（ CA ）证书文件的路径名
SSLCert
public static let SSLCert = "ssl.cert"
功能：SSLCert 客户端 SSL 公钥证书文件的路径名
SSLKey
public static let SSLKey = "ssl.key"
功能：SSLKey 客户端 SSL 私钥文件的路径名
SSLKeyPassword
public static let SSLKeyPassword = "ssl.key.password"
功能：SSLKeyPassword 客户端 SSL 私钥文件的密码
SSLSni
public static let SSLSni = "ssl.sni"
功能：SSLSni 客户端通过该标识在握手过程开始时试图连接到哪个主机名
Tls12Ciphersuites
public static let Tls12Ciphersuites = "tls1.2.ciphersuites"
功能：Tls12Ciphersuites 此选项指定客户端允许使用 TLSv1.2 及以下的加密连接使用哪些密码套件。 值为冒号分隔的字符串，比如 “TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256:TLS_DHE_RSA_WITH_AES_128_CBC_SHA”
Tls13Ciphersuites
public static let Tls13Ciphersuites = "tls1.3.ciphersuites"
功能：Tls13Ciphersuites 此选项指定客户端允许使用 TLSv1.3 的加密连接使用哪些密码套件。 值为冒号分隔的字符串，比如 “TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256”
TlsVersion
public static let TlsVersion = "tls.version"
功能：TlsVersion 支持的 TLS 版本号，值为逗号分隔的字符串，比如 “TLSv1.2,TLSv1.3”
interface SqlDbType
public interface SqlDbType {
prop name: String
}
SqlDbType 接口和 SqlNullableDbType 接口是所有 Sql 数据类型的基类。要扩展用户定义的类型，请继承 SqlDbType 或 SqlNullableDbType。
每种 Sql 数据类型实现类，同时满足以下条件：
- 只有一个参数的构造函数，参数类型为
T（T为仓颉语言支持的类型） public修饰的value属性，其类型必须上一条中使用的参数类型一致，其值为对应仓颉类型的值- 如果数据类型允许
null值，继承SqlNullableDbType，null值时，value字段的值为Option<T>.None
SqlDbType 接口所有实现类型都必须具有公共 value 属性。
prop name
prop name: String
功能：获取类型名称
interface SqlNullableDbType
public interface SqlNullableDbType <: SqlDbType
允许 null 值的类型基类，如果为 null 值，value 属性值为 Option.None
class SqlChar
public class SqlChar <: SqlDbType {
public init(v: String)
}
定长字符串，对应仓颉 String 类型
init
public init(v: String)
prop value
public mut prop value: String
prop name
public prop name: String
功能：类型名称 SqlChar
class SqlNullableChar
public class SqlNullableChar <: SqlNullableDbType {
public init(v: ?String)
}
定长字符串，对应仓颉 String 类型，可为数据库 Null 值
init
public init(v: ?String)
prop value
public mut prop value: ?String
prop name
public prop name: String
功能：类型名称 SqlNullableChar
class SqlVarchar
public class SqlVarchar <: SqlDbType {
public init(v: String)
}
变长字符串，对应仓颉 String 类型
init
public init(v: String)
prop value
public mut prop value: String
prop name
public prop name: String
功能：类型名称 SqlVarchar
class SqlNullableVarchar
public class SqlNullableVarchar <: SqlNullableDbType {
public init(v: ?String)
}
变长字符串，对应仓颉 String 类型，可为数据库 Null 值
init
public init(v: ?String)
prop value
public mut prop value: ?String
prop name
public prop name: String
功能：类型名称 SqlNullableVarchar
class SqlBinary
public class SqlBinary <: SqlDbType {
public init(v: Array<Byte>)
}
定长二进制字符串，对应仓颉 Array<Byte> 类型
init
public init(v: Array<Byte>)
prop value
public mut prop value: Array<Byte>
prop name
public prop name: String
功能：类型名称 SqlBinary
class SqlNullableBinary
public class SqlNullableBinary <: SqlNullableDbType {
public init(v: ?Array<Byte>)
}
定长二进制字符串，对应仓颉 Array<Byte> 类型，可为数据库 Null 值
init
public init(v: ?Array<Byte>)
prop value
public mut prop value: ?Array<Byte>
prop name
public prop name: String
功能：类型名称 SqlNullableBinary
class SqlVarBinary
public class SqlVarBinary <: SqlDbType {
public init(v: Array<Byte>)
}
变长二进制字符串，对应仓颉 Array<Byte> 类型
init
public init(v: Array<Byte>)
prop value
public mut prop value: Array<Byte>
prop name
public prop name: String
功能：类型名称 SqlVarBinary
class SqlNullableVarBinary
public class SqlNullableVarBinary <: SqlNullableDbType {
public init(v: ?Array<Byte>)
}
变长二进制字符串，对应仓颉 Array<Byte> 类型，可为数据库 Null 值
init
public init(v: ?Array<Byte>)
prop value
public mut prop value: ?Array<Byte>
prop name
public prop name: String
功能：类型名称 SqlNullableVarBinary
class SqlClob
public class SqlClob <: SqlDbType {
public init(v: InputStream)
}
变长超大字符串(CHAR LARGE OBJECT)，对应仓颉 InputStream 类型
init
public init(v: InputStream)
prop value
public mut prop value: InputStream
prop name
public prop name: String
功能：类型名称 SqlClob
class SqlNullableClob
public class SqlNullableClob <: SqlNullableDbType {
public init(v: ?InputStream)
}
变长超大字符串(CHAR LARGE OBJECT)，对应仓颉 InputStream 类型，可为数据库 Null 值
init
public init(v: ?InputStream)
prop value
public mut prop value: ?InputStream
prop name
public prop name: String
功能：类型名称 SqlNullableClob
class SqlBlob
public class SqlBlob <: SqlDbType {
public init(v: InputStream)
}
变长超大二进制字符串(BINARY LARGE OBJECT)，对应仓颉 InputStream 类型
init
public init(v: InputStream)
prop value
public mut prop value: InputStream
prop name
public prop name: String
功能：类型名称 SqlBlob
class SqlNullableBlob
public class SqlNullableBlob <: SqlNullableDbType {
public init(v: ?InputStream)
}
变长超大二进制字符串(BINARY LARGE OBJECT)，对应仓颉 InputStream 类型，可为数据库 Null 值
init
public init(v: ?InputStream)
prop value
public mut prop value: ?InputStream
prop name
public prop name: String
功能：类型名称 SqlNullableBlob
class SqlBool
public class SqlBool <: SqlDbType {
public init(v: Bool)
}
布尔类型，对应仓颉 Bool 类型
init
public init(v: Bool)
prop value
public mut prop value: Bool
prop name
public prop name: String
功能：类型名称 SqlBool
class SqlNullableBool
public class SqlNullableBool <: SqlNullableDbType {
public init(v: ?Bool)
}
布尔类型，对应仓颉 Bool 类型，可为数据库 Null 值
init
public init(v: ?Bool)
prop value
public mut prop value: ?Bool
prop name
public prop name: String
功能：类型名称 SqlNullableBool
class SqlByte
public class SqlByte <: SqlDbType {
public init(v: Int8)
}
字节，对应仓颉 Int8 类型
init
public init(v: Int8)
prop value
public mut prop value: Int8
prop name
public prop name: String
功能：类型名称 SqlByte
class SqlNullableByte
public class SqlNullableByte <: SqlNullableDbType {
public init(v: ?Int8)
}
字节，对应仓颉 Int8 类型，可为数据库 Null 值
init
public init(v: ?Int8)
prop value
public mut prop value: ?Int8
prop name
public prop name: String
功能：类型名称 SqlNullableByte
class SqlSmallInt
public class SqlSmallInt <: SqlDbType {
public init(v: Int16)
}
小整数，对应仓颉 Int16 类型
init
public init(v: Int16)
prop value
public mut prop value: Int16
prop name
public prop name: String
功能：类型名称 SqlSmallInt
class SqlNullableSmallInt
public class SqlNullableSmallInt <: SqlNullableDbType {
public init(v: ?Int16)
}
小整数，对应仓颉 Int16 类型，可为数据库 Null 值
init
public init(v: ?Int16)
prop value
public mut prop value: ?Int16
prop name
public prop name: String
功能：类型名称 SqlNullableSmallInt
class SqlInteger
public class SqlInteger <: SqlDbType {
public init(v: Int32)
}
中整数，对应仓颉 Int32 类型
init
public init(v: Int32)
prop value
public mut prop value: Int32
prop name
public prop name: String
功能：类型名称 SqlInteger
class SqlNullableInteger
public class SqlNullableInteger <: SqlNullableDbType {
public init(v: ?Int32)
}
中整数，对应仓颉 Int32 类型，可为数据库 Null 值
init
public init(v: ?Int32)
prop value
public mut prop value: ?Int32
prop name
public prop name: String
功能：类型名称 SqlNullableInteger
class SqlBigInt
public class SqlBigInt <: SqlDbType {
public init(v: Int64)
}
大整数，对应仓颉 Int64 类型
init
public init(v: Int64)
prop value
public mut prop value: Int64
prop name
public prop name: String
功能：类型名称 SqlBigInt
class SqlNullableBigInt
public class SqlNullableBigInt <: SqlNullableDbType {
public init(v: ?Int64)
}
大整数，对应仓颉 Int64 类型，可为数据库 Null 值
init
public init(v: ?Int64)
prop value
public mut prop value: ?Int64
prop name
public prop name: String
功能：类型名称 SqlNullableBigInt
class SqlReal
public class SqlReal <: SqlDbType {
public init(v: Float32)
}
浮点数，对应仓颉 Float32 类型
init
public init(v: Float32)
prop value
public mut prop value: Float32
prop name
public prop name: String
功能：类型名称 SqlReal
class SqlNullableReal
public class SqlNullableReal <: SqlNullableDbType {
public init(v: ?Float32)
}
浮点数，对应仓颉 Float32 类型，可为数据库 Null 值
init
public init(v: ?Float32)
prop value
public mut prop value: ?Float32
prop name
public prop name: String
功能：类型名称 SqlNullableReal
class SqlDouble
public class SqlDouble <: SqlDbType {
public init(v: Float64)
}
双精度数，对应仓颉 Float64 类型，可为数据库 Null 值
init
public init(v: Float64)
prop value
public mut prop value: Float64
prop name
public prop name: String
功能：类型名称 SqlDouble
class SqlNullableDouble
public class SqlNullableDouble <: SqlNullableDbType {
public init(v: ?Float64)
}
双精度数，对应仓颉 Float64 类型，可为数据库 Null 值
init
public init(v: ?Float64)
prop value
public mut prop value: ?Float64
prop name
public prop name: String
功能：类型名称 SqlNullableDouble
class SqlDate
public class SqlDate <: SqlDbType {
public init(v: DateTime)
}
日期，仅年月日有效，对应仓颉 DateTime 类型
init
public init(v: DateTime)
prop value
public mut prop value: DateTime
prop name
public prop name: String
功能：类型名称 SqlDate
class SqlNullableDate
public class SqlNullableDate <: SqlNullableDbType {
public init(v: ?DateTime)
}
日期，仅年月日有效，对应仓颉 DateTime 类型，可为数据库 Null 值
init
public init(v: ?DateTime)
prop value
public mut prop value: ?DateTime
prop name
public prop name: String
功能：类型名称 SqlNullableDate
class SqlTime
public class SqlTime <: SqlDbType {
public init(v: DateTime)
}
时间，仅时分秒毫秒有效，对应仓颉 DateTime 类型
init
public init(v: DateTime)
prop value
public mut prop value: DateTime
prop name
public prop name: String
功能：类型名称 SqlTime
class SqlNullableTime
public class SqlNullableTime <: SqlNullableDbType {
public init(v: ?DateTime)
}
时间，仅时分秒毫秒有效，对应仓颉 DateTime 类型，可为数据库 Null 值
init
public init(v: ?DateTime)
prop value
public mut prop value: ?DateTime
prop name
public prop name: String
功能：类型名称 SqlNullableTime
class SqlTimeTz
public class SqlTimeTz <: SqlDbType {
public init(v: DateTime)
}
带时区的时间，仅时分秒毫秒时区有效，对应仓颉 DateTime 类型
init
public init(v: DateTime)
prop value
public mut prop value: DateTime
prop name
public prop name: String
功能：类型名称 SqlTimeTz
class SqlNullableTimeTz
public class SqlNullableTimeTz <: SqlNullableDbType {
public init(v: ?DateTime)
}
带时区的时间，仅时分秒毫秒时区有效，对应仓颉 DateTime 类型，可为数据库 Null 值
init
public init(v: ?DateTime)
prop value
public mut prop value: ?DateTime
prop name
public prop name: String
功能：类型名称 SqlNullableTimeTz
class SqlTimestamp
public class SqlTimestamp <: SqlDbType {
public init(v: DateTime)
}
时间戳，对应仓颉 DateTime 类型
init
public init(v: DateTime)
prop value
public mut prop value: DateTime
prop name
public prop name: String
功能：类型名称 SqlTimestamp
class SqlNullableTimestamp
public class SqlNullableTimestamp <: SqlNullableDbType {
public init(v: ?DateTime)
}
时间戳，对应仓颉 DateTime 类型，可为数据库 Null 值
init
public init(v: ?DateTime)
prop value
public mut prop value: ?DateTime
prop name
public prop name: String
功能：类型名称 SqlNullableTimestamp
class SqlInterval
public class SqlInterval <: SqlDbType {
public init(v: Duration)
}
时间间隔，对应仓颉 Duration 类型
init
public init(v: Duration)
prop value
public mut prop value: Duration
prop name
public prop name: String
功能：类型名称 SqlInterval
class SqlNullableInterval
public class SqlNullableInterval <: SqlNullableDbType {
public init(v: ?Duration)
}
时间间隔，对应仓颉 Duration 类型，可为数据库 Null 值
init
public init(v: ?Duration)
prop value
public mut prop value: ?Duration
prop name
public prop name: String
功能：类型名称 SqlNullableInterval
class SqlDecimal
public class SqlDecimal <: SqlDbType {
public init(v: Decimal)
}
时间间隔，对应仓颉 Decimal 类型
init
public init(v: Decimal)
prop value
public mut prop value: Decimal
prop name
public prop name: String
功能：类型名称 SqlDecimal
class SqlNullableDecimal
public class SqlNullableDecimal <: SqlNullableDbType {
public init(v: ?Decimal)
}
时间间隔，对应仓颉 Decimal 类型，可为数据库 Null 值
init
public init(v: ?Decimal)
prop value
public mut prop value: ?Decimal
prop name
public prop name: String
功能：类型名称 SqlNullableDecimal
示例
获取数据库连接
下面是获取数据库连接示例：
func test_opengauss() {
let drv = DriverManager.getDriver("opengauss") ?? return
let opts = [
("cachePrepStmts", "true"),
("prepStmtCacheSize", "250"),
("prepStmtCacheSqlLimit", "2048")
]
let ds = drv.open("opengauss://testuser:testpwd@localhost:5432/testdb", opts)
ds.setOption(SqlOption.SSLMode, SqlOption.SSLModeVerifyCA)
ds.setOption(SqlOption.SSLCA, "ca.crt")
ds.setOption(SqlOption.SSLCert, "server.crt")
ds.setOption(SqlOption.SSLKey, "server.key")
ds.setOption(SqlOption.SSLKeyPassword, "key_password")
ds.setOption(SqlOption.TlsVersion, "TLSv1.2,TLSv1.3")
let conn = ds.connect()
}
执行数据库定义语句
下面是删除表，创建表的示例：
var stmt = conn.prepareStatement("DROP TABLE IF EXISTS test")
var ur = stmt.update()
println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
stmt.close()
stmt = conn.prepareStatement("CREATE TABLE test(id SERIAL PRIMARY KEY, name VARCHAR(20) NOT NULL, age INT)")
ur = stmt.update()
println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
stmt.close()
执行数据库操作语句
插入数据
var stmt = conn.prepareStatement("INSERT INTO test VALUES(?, ?)")
var name = SqlVarchar("li lei")
var age = SqlNullableInteger(12)
var ur = stmt.update(name, age)
println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
name.value = "han meimei"
age.value = 13
ur = stmt.update(name, age)
println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
stmt.close()
如果需要在插入数据后返回插入的 id 值，可以参考如下方式：
let sql = "INSERT INTO test (name, age) VALUES (?,?) RETURNING id, name"
try (stmt = cn.prepareStatement(sql)) {
var name = SqlVarchar("li hua")
var age = SqlNullableInteger(12)
let qr = stmt.query(name, age)
let id = SqlInteger(0)
while (qr.next(id, name)) {
println("id = ${id.value}, name=${name.value}")
}
} catch (e: Exception) {
logger.error(e.message)
e.printStackTrace()
}
查询数据
var stmt = conn.prepareStatement("select * from test where name = ?")
var name = SqlNullableVarchar("li lei")
let id = SqlInteger(0)
let qr = stmt.query(name)
var age = SqlNullableInteger(0)
while (qr.next(id, name, age)) {
println("id = ${id.value}, name = ${name.value}, age=${age.value}")
}
stmt.close()
更新数据
var stmt = conn.prepareStatement("update test set age = ? where name = ?")
var age = SqlNullableInteger(15)
var name = SqlNullableVarchar("li lei")
var ur = stmt.update(age, name)
println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
stmt.close()
删除数据
var stmt = conn.prepareStatement("delete from test where name = ?")
var name = SqlNullableVarchar("li lei")
var ur = stmt.update(name)
println("Update Result: ${ur.rowCount} ${ur.lastInsertId}")
stmt.close()
执行事务控制语句
普通数据库事务
func test_transaction() {
let SQL_INSERT = "INSERT INTO EMPLOYEE (NAME, SALARY, CREATED_DATE) VALUES (?, ?, ?)"
let SQL_UPDATE = "UPDATE EMPLOYEE SET SALARY=? WHERE NAME=?"
let drv = DriverManager.getDriver("opengauss").getOrThrow()
let db = drv.open("opengauss://localhost:5432/testdb")
try(cn = db.connect()) {
let psInsert = cn.prepareStatement(SQL_INSERT)
let psUpdate = cn.prepareStatement(SQL_UPDATE)
let tx = cn.createTransaction()
try {
psInsert.update(SqlChar("mkyong"), SqlBinary(Array<Byte>([10])), SqlTime(DateTime.now()))
psInsert.update(SqlChar("kungfu"), SqlBinary(Array<Byte>([20])), SqlTime(DateTime.now()))
psInsert.update(SqlVarchar("mkyong"), SqlBinary(Array<Byte>([1, 2, 3, 4, 5])))
tx.commit()
} catch (e1: SqlException) {
e1.printStackTrace()
try {
tx.rollback()
} catch (e2: SqlException) {
e2.printStackTrace()
}
}
} catch (e: SqlException) {
e.printStackTrace()
}
}
事务保存点
如果数据库事务支持保存点，可以参考如下样例：
func test_savepoint() {
let SQL_INSERT = "INSERT INTO EMPLOYEE (NAME, SALARY, CREATED_DATE) VALUES (?, ?, ?)"
let SQL_UPDATE = "UPDATE EMPLOYEE SET SALARY=? WHERE NAME=?"
let drv = DriverManager.getDriver("opengauss").getOrThrow()
let db = drv.open("opengauss://localhost:5432/testdb")
try(cn = db.connect()) {
let psInsert = cn.prepareStatement(SQL_INSERT)
let psUpdate = cn.prepareStatement(SQL_UPDATE)
let tx = cn.createTransaction()
try {
tx.save("save1")
psInsert.update([SqlChar("mkyong"), SqlBinary(Array<Byte>([10])), SqlTime(DateTime.now())])
tx.save("save2")
psInsert.update([SqlChar("kungfu"), SqlBinary(Array<Byte>([20])), SqlTime(DateTime.now())])
tx.save("save3")
psInsert.update([SqlVarchar("mkyong"), SqlBinary(Array<Byte>([1, 2, 3, 4, 5]))])
tx.rollback("save2")
tx.commit()
} catch (e1: SqlException) {
e1.printStackTrace()
try {
tx.rollback()
} catch (e2: SqlException) {
e2.printStackTrace()
}
}
} catch (e: SqlException) {
e.printStackTrace()
}
}
实现数据库驱动查询功能参考
对于数据库驱动提供者，此处给出实现查询功能的样例代码：
public class Rows <: QueryResult {
public func next(values: Array<SqlDbType>): Bool {
for (idx in 0..values.size) {
match (values[idx]) {
case v: SqlBigInt => v.value = 100
case v: SqlVarchar => v.value = "foo"
case v: SqlNullableTimestamp => v.value = None
case v: MySqlExtXmlType => v.value = "<element></element>"
case _ => ()
}
}
return false
}
}