接口

interface ColumnInfo


public interface ColumnInfo {
    prop displaySize: Int64
    prop length: Int64
    prop name: String
    prop nullable: Bool
    prop scale: Int64
    prop typeName: String
}

功能：执行 Select/Query 语句返回结果的列信息。

prop displaySize


prop displaySize: Int64

功能：获取列值的最大显示长度，如果无限制，则应该返回 Int64.Max （仍然受数据库的限制）。

类型：Int64

prop length


prop length: Int64

功能：获取列值大小。

说明：

对于数值数据，表示最大精度。

对于字符数据，表示以字符为单位的长度。

对于日期时间数据类型，表示字符串表示形式的最大字符长度。

对于二进制数据，表示以字节为单位的长度。

对于 RowID 数据类型，表示以字节为单位的长度。

对于列大小不适用的数据类型，返回 0。

类型：Int64

prop name


prop name: String

功能：列名或者别名。

类型：String

prop nullable


prop nullable: Bool

功能：表示列值是否允许数据库 Null 值。

类型：Bool

prop scale


prop scale: Int64

功能：获取列值的小数长度，如果无小数部分，返回 0。

类型：Int64

prop typeName


prop typeName: String

功能：获取列类型名称，如果在仓颉中有对应数据类型的定义，返回对应类型的 toString 函数的返回值；如果在仓颉中无对应数据类型的定义，由数据库驱动定义。

类型：String

interface Connection


public interface Connection <: Resource {
    prop state: ConnectionState
    func createTransaction(): Transaction
    func getMetaData(): Map<String, String>
    func prepareStatement(sql: String): Statement
}

功能：数据库连接接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型：

Resource

prop state


prop state: ConnectionState

功能：描述与数据源连接的当前状态。

类型：ConnectionState

func createTransaction()


func createTransaction(): Transaction

功能：创建事务对象。

返回值：

Transaction - 事务对象。

异常：

SqlException - 当已经处于事务状态，不支持并行事务时，抛出异常。

func getMetaData()


func getMetaData(): Map<String, String>

功能：返回连接到的数据源元数据。

返回值：

Map < String, String > - 数据源元数据。

func prepareStatement(String)


func prepareStatement(sql: String): Statement

功能：通过传入的 sql 语句，返回一个预执行的 Statement 对象实例。

参数：

sql: String - 预执行的 sql 语句，sql 语句的参数只支持 ? 符号占位符。

返回值：

Statement - 一个可以执行 sql 语句的实例对象。

异常：

SqlException - 当 sql 语句包含不认识的字符时，抛出异常。

interface Datasource


public interface Datasource <: Resource {
    func connect(): Connection
    func setOption(key: String, value: String): Unit
}

功能：数据源接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型：

Resource

func connect()


func connect(): Connection

功能：返回一个可用的连接。

返回值：

Connection - 数据库连接实例。

func setOption(String, String)


func setOption(key: String, value: String): Unit

功能：设置连接选项。

参数：

key: String - 连接选项名称。
value: String - 连接选项的值。

interface Driver


public interface Driver {
    prop name: String
    prop preferredPooling: Bool
    prop version: String
    func open(connectionString: String, opts: Array<(String, String)>): Datasource
}

功能：数据库驱动接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop name


prop name: String

功能：驱动名称。

类型：String

prop preferredPooling


prop preferredPooling: Bool

功能：指示驱动程序是否与连接池亲和。

当该属性为 false 时，不建议使用连接池进行管理。例如，对于某些数据库驱动（如 SQLite），连接池化的收益不明显，因此不建议使用连接池。

类型：Bool

prop version


prop version: String

功能：驱动版本。

类型：String

func open(String, Array<(String, String)>)


func open(connectionString: String, opts: Array<(String, String)>): Datasource

功能：通过 connectionString 和选项打开数据源。

参数：

connectionString: String - 数据库连接字符串。
opts: Array<(String, String)> - key，value 的 tuple 数组，打开数据源的选项。

返回值：

Datasource - 数据源实例。

interface QueryResult


public interface QueryResult <: Resource {
    prop columnInfos: Array<ColumnInfo>
    func next(values: Array<SqlDbType>): Bool
    func next(): Bool
    func get<T>(index: Int): T
    func getOrNull<T>(index: Int): ?T
}

功能：执行 Select 语句产生的结果接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型：

Resource

prop columnInfos


prop columnInfos: Array<ColumnInfo>

功能：返回结果集的列信息，比如列名，列类型，列长度，是否允许数据库 Null 值等。

类型：Array<ColumnInfo>

func get<T>(Int)


func get<T>(index: Int): T

功能：从结果集的当前行检索指定列的值。

返回值：

T - T 类型的实例。

func getOrNull<T>(Int)


func getOrNull<T>(index: Int): ?T

功能：从结果集的当前行检索指定列的值，数据库列允许 SQL NULL。

返回值：

?T - T 类型的实例，如果为空，返回None。

异常：

SqlException - 索引超出列范围，或者行数据未准备好时，抛出异常。

func next()


func next(): Bool

功能：向后移动一行，必须先调用一次 next() 才能移动到第一行，第二次调用移动到第二行，依此类推。当返回 true 时，驱动会在 values 中填入行数据；当返回 false 时结束，且不会修改 values 的内容。

返回值：

Bool - 下一行存在数据则返回 true，否则返回 false。

func next(Array<SqlDbType>) ^(deprecated)


func next(values: Array<SqlDbType>): Bool

功能：向后移动一行，必须先调用一次 next 才能移动到第一行，第二次调用移动到第二行，依此类推。当返回 true 时，驱动会在 values 中填入行数据；当返回 false 时结束，且不会修改 values 的内容。

注意：

未来版本即将废弃不再使用，可使用 next() 替代。

参数：

values: Array<SqlDbType ^(deprecated)> - sql 数据类型的数据列表。

返回值：

Bool - 下一行存在数据则返回 true，否则返回 false。

interface SqlDbType ^(deprecated)


public interface SqlDbType {
    prop name: String
}

功能：所有 sql 数据类型的父类。

注意：

未来版本即将废弃不再使用。

要扩展用户定义的类型，请继承 SqlDbType ^(deprecated) 或 SqlNullableDbType ^(deprecated)。

说明：

SqlDbType ^(deprecated) 接口所有实现类型都必须具有公共 value 属性。每种 sql 数据类型实现类，同时满足以下条件：

只有一个参数的构造函数，参数类型为 T（T 为仓颉语言支持的类型）。

public 修饰的 value 属性，其类型必须上一条中使用的参数类型一致，其值为对应仓颉类型的值。

如果数据类型允许 null 值，继承 SqlNullableDbType ^(deprecated)，null 值时，value 字段的值为 Option<T>.None。

prop name


prop name: String

功能：获取类型名称。

类型：String

interface SqlNullableDbType ^(deprecated)


public interface SqlNullableDbType <: SqlDbType

功能：允许 null 值的 sql 数据类型父类。

注意：

未来版本即将废弃不再使用。

如果为 null 值，value 属性值为 Option.None。

父类型：

SqlDbType ^(deprecated)

interface Statement


public interface Statement <: Resource {
    prop parameterColumnInfos: Array<ColumnInfo>
    func query(params: Array<SqlDbType>): QueryResult
    func setOption(key: String, value: String): Unit
    func update(params: Array<SqlDbType>): UpdateResult
    func set<T>(index: Int, value: T): Unit
    func setNull(index: Int): Unit
    func update(): UpdateResult
    func query(): QueryResult
}

功能：sql 语句预执行接口。

Statement 绑定了一个 Connection ，继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

父类型：

Resource

prop parameterColumnInfos


prop parameterColumnInfos: Array<ColumnInfo>

功能：预执行 sql 语句中，占位参数的列信息，比如列名，列类型，列长度，是否允许数据库 Null 值等。

类型：Array<ColumnInfo>

func query()


func query(): QueryResult

功能：执行 sql 语句，得到查询结果。

返回值：

QueryResult - 查询结果。

异常：

SqlException - 当执行过程中发生了异常情况，比如网络中断，服务器超时，参数个数不正确时，抛出异常。

func query(Array<SqlDbType>) ^(deprecated)


func query(params: Array<SqlDbType>): QueryResult

功能：执行 sql 语句，得到查询结果。

注意：

未来版本即将废弃不再使用，可使用 query() 替代。

参数：

params: Array<SqlDbType ^(deprecated)> - sql 数据类型的数据列表，用于替换 sql 语句中的 ? 占位符。

返回值：

QueryResult - 查询结果。

异常：

SqlException - 当执行过程中发生了异常情况，比如网络中断，服务器超时，参数个数不正确时，抛出异常。

func set<T>(Int, T)


func set<T>(index: Int, value: T): Unit

功能：设置 sql 参数，将仓颉的数据类型转成数据库的数据类型。

参数：

index: Int - 参数所在序列。
value: T - 参数值。

func setNull(Int)


func setNull(index: Int): Unit

功能：将指定位置处的语句参数设置为 SQL NULL。

参数：

index: Int - 参数所在序列。

func setOption(String, String)


func setOption(key: String, value: String): Unit

功能：设置预执行 sql 语句选项。

参数：

key: String - 连接选项名称。
value: String - 连接选项的值。

func update(Array<SqlDbType>) ^(deprecated)


func update(params: Array<SqlDbType>): UpdateResult

功能：执行 sql 语句，得到更新结果。

注意：

未来版本即将废弃不再使用，可使用 update() 替代。

参数：

params: Array<SqlDbType ^(deprecated)> - sql 数据类型的数据列表，用于替换 sql 语句中的 ? 占位符。

返回值：

UpdateResult - 更新结果。

异常：

SqlException - 当执行过程中发生了异常情况，比如网络中断、服务器超时，参数个数不正确时，抛出异常。

func update()


func update(): UpdateResult

功能：执行 sql 语句，得到更新结果。

返回值：

UpdateResult - 更新结果。

异常：

SqlException - 当执行过程中发生了异常情况，比如网络中断，服务器超时，参数个数不正确时，抛出异常。

interface Transaction


public interface Transaction {
    mut prop accessMode: TransactionAccessMode
    mut prop deferrableMode: TransactionDeferrableMode
    mut prop isoLevel: TransactionIsoLevel
    func begin(): Unit
    func commit(): Unit
    func release(savePointName: String): Unit
    func rollback(): Unit
    func rollback(savePointName: String): Unit
    func save(savePointName: String): Unit
}

功能：定义数据库事务的核心行为。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop accessMode


mut prop accessMode: TransactionAccessMode

功能：获取数据库事务访问模式。

类型：TransactionAccessMode

prop deferrableMode


mut prop deferrableMode: TransactionDeferrableMode

功能：获取数据库事务延迟模式。

类型：TransactionDeferrableMode

prop isoLevel


mut prop isoLevel: TransactionIsoLevel

功能：获取数据库事务隔离级别。

类型：TransactionIsoLevel

func begin()


func begin(): Unit

功能：开始数据库事务。

异常：

SqlException - 当提交事务时服务器端发生错误，以及当事务已提交或回滚或连接已断开时，抛出异常。

func commit()


func commit(): Unit

功能：提交数据库事务。

异常：

SqlException - 当提交事务时服务器端发生错误，以及当事务已提交或回滚或连接已断开时，抛出异常。

func release(String)


func release(savePointName: String): Unit

功能：销毁先前在当前事务中定义的保存点。这允许系统在事务结束之前回收一些资源。

参数：

savePointName: String - 保存点名称。

异常：

SqlException - 当提交事务时服务器端发生错误，以及当事务已提交或回滚或连接已断开时，抛出异常。

func rollback()


func rollback(): Unit

功能：从挂起状态回滚事务。

异常：

SqlException - 当提交事务时服务器端发生错误，以及当事务已提交或回滚或连接已断开时，抛出异常。

func rollback(String)


func rollback(savePointName: String): Unit

功能：回滚事务至指定保存点名称。

参数：

savePointName: String - 保存点名称。

异常：

SqlException - 当提交事务时服务器端发生错误，以及当事务已提交或回滚或连接已断开时，抛出异常。

func save(String)


func save(savePointName: String): Unit

功能：在事务中创建一个指定名称的保存点，可用于回滚此保存点之后的事务。

参数：

savePointName: String - 保存点名称。

异常：

SqlException - 当提交事务时服务器端发生错误，以及当事务已提交或回滚或连接已断开时，抛出异常。

interface UpdateResult


public interface UpdateResult {
    prop lastInsertId: Int64
    prop rowCount: Int64
}

功能：执行 Insert、Update、Delete 语句产生的结果接口。

继承该接口的 class、interface、struct 也需要遵守该接口中函数的入参及返回值定义。

prop lastInsertId


prop lastInsertId: Int64

功能：执行 Insert 语句自动生成的最后 row ID ，如果不支持则 row ID 为 0。

类型：Int64

prop rowCount


prop rowCount: Int64

功能：执行 Insert、Update、Delete 语句影响的行数。

类型：Int64

仓颉编程语言标准库 API（0.60.5）