接口

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 也需要遵守该接口中函数的入参及返回值定义。

父类型:

prop state

prop state: ConnectionState

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

类型:ConnectionState

func createTransaction()

func createTransaction(): Transaction

功能:创建事务对象。

返回值:

异常:

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

func getMetaData()

func getMetaData(): 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 也需要遵守该接口中函数的入参及返回值定义。

父类型:

func connect()

func connect(): 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

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

如果否,则不建议使用连接池。比如 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 数组,打开数据源的选项。

返回值:

interface QueryResult

public interface QueryResult <: Resource {
    prop columnInfos: Array<ColumnInfo>
    func next(values: Array<SqlDbType>): Bool
}

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

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

父类型:

prop columnInfos

prop columnInfos: Array<ColumnInfo>

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

类型:Array<ColumnInfo>

func next(Array<SqlDbType>)

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

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

参数:

返回值:

  • Bool - 下一行存在数据则返回 true,否则返回 false

interface SqlDbType

public interface SqlDbType {
    prop name: String
}

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

要扩展用户定义的类型,请继承 SqlDbTypeSqlNullableDbType

说明:

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

  • 只有一个参数的构造函数,参数类型为 TT 为仓颉语言支持的类型)。
  • public 修饰的 value 属性,其类型必须上一条中使用的参数类型一致,其值为对应仓颉类型的值。
  • 如果数据类型允许 null 值,继承 SqlNullableDbTypenull 值时,value 字段的值为 Option<T>.None。

prop name

prop name: String

功能:获取类型名称。

类型:String

interface SqlNullableDbType

public interface SqlNullableDbType <: SqlDbType

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

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

父类型:

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
}

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

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

父类型:

prop parameterColumnInfos

prop parameterColumnInfos: Array<ColumnInfo>

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

类型:Array<ColumnInfo>

func query(Array<SqlDbType>)

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

功能:执行 sql 语句,得到查询结果。

参数:

  • params: Array<SqlDbType> - sql 数据类型的数据列表,用于替换 sql 语句中的 ? 占位符。

返回值:

异常:

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

func setOption(String, String)

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

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

参数:

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

func update(Array<SqlDbType>)

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

功能:执行 sql 语句,得到更新结果。

参数:

  • params: Array<SqlDbType> - sql 数据类型的数据列表,用于替换 sql 语句中的 ? 占位符。

返回值:

异常:

  • 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