database 包

database 包提供仓颉访问数据库的接口，当前仅支持 SQL/CLI 接口。

注意：当前 database 包本身没有对外接口，因此无法被引入。使用 SQL/CLI 接口时需引入 database.sql 包。

sql 包

介绍

sql 包提供了 SQL/CLI 的通用接口，配合数据库驱动 Driver 完成对数据库的各项操作。

数据类型对应表

Sql 数据类型和仓颉数据类型对应表。

主要接口

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()))

            // error, test rollback SQLException: No value specified for parameter 3.
            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 {
            // 创建保存点 1
            tx.save("save1")
            psInsert.update([SqlChar("mkyong"), SqlBinary(Array<Byte>([10])), SqlTime(DateTime.now())])

            // 创建保存点 2
            tx.save("save2")
            psInsert.update([SqlChar("kungfu"), SqlBinary(Array<Byte>([20])), SqlTime(DateTime.now())])

            // 创建保存点 3
            tx.save("save3")
            psInsert.update([SqlVarchar("mkyong"), SqlBinary(Array<Byte>([1, 2, 3, 4, 5]))])

            // 回滚到保存点 2
            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
    }
}