OracleNIO

非阻塞、事件驱动的 Swift 客户端，用于 Oracle 数据库，构建于 SwiftNIO 之上。

它就像 PostgresNIO，但是是为 Oracle 数据库编写的。

• 一个 OracleConnection，允许您连接到 Oracle 数据库服务器、进行身份验证、查询和检索结果
• 支持背压的 async/await 接口
• Swift 原始类型与 Oracle wire 格式之间的自动转换
• 与 Swift 服务器生态系统集成，包括使用 swift-log。
• 旨在在所有受支持的平台上高效运行（已在 Linux 和 Darwin 系统上测试）
• 在可用时支持 Network.framework（例如，在 Apple 平台上）
• 一个由 DRCP (数据库驻留连接池) 支持的 OracleClient 连接池（如果可用）

Oracle 数据库 12.1 或更高版本。

• 带有服务名称的用户名和密码
• 带有 sid 的用户名和密码
• 带有服务名称的 Oracle 云基础设施 (OCI) 身份和访问管理 (IAM) 基于令牌的身份验证
• 带有服务名称的开放授权 (OAuth 2.0) 基于令牌的身份验证
• 带有 sid 的开放授权 (OAuth 2.0) 基于令牌的身份验证

请注意，所有基于令牌的身份验证方法目前都未经测试，因为我 (@lovetodream) 没有基础设施来测试它。欢迎贡献！

所有连接都可以使用 OracleConnection.Configuration.TLS 进行 TLS 加密。

查看 OracleNIO API 文档，详细了解所有类、结构体、协议等。

将 OracleNIO 作为依赖项添加到您的 Package.swift

    dependencies: [
        .package(url: "https://github.com/lovetodream/oracle-nio.git", from: "1.0.0-alpha"),
        ...
    ]

将 OracleNIO 添加到您想要使用它的目标中

    targets: [
        .target(name: "MyFancyTarget", dependencies: [
            .product(name: "OracleNIO", package: "oracle-nio"),
        ])
    ]

要创建连接，首先创建一个连接配置对象

import OracleNIO

let config = OracleConnection.Configuration(
    host: "127.0.0.1", 
    port: 1521,
    service: .serviceName("my_service"), // or .sid("sid")
    username: "my_username",
    password: "my_password"
)

要创建连接，我们需要一个 Logger，用于记录连接后台事件。

import Logging

let logger = Logger(label: "oracle-logger")

现在我们可以将它们放在一起

import OracleNIO
import Logging

let logger = Logger(label: "oracle-logger")

let config = OracleConnection.Configuration(
    host: "127.0.0.1", 
    port: 1521,
    service: .serviceName("my_service"),
    username: "my_username",
    password: "my_password"
)

let connection = try await OracleConnection.connect(
  configuration: config,
  id: 1,
  logger: logger
)

// Close your connection once done
try await connection.close()

一旦建立连接，就可以将语句发送到服务器。这非常简单

let rows = try await connection.execute("SELECT id, username, birthday FROM users", logger: logger)

execute(_:options:logger:file:line:) 可以运行 Query、DML、DDL 甚至 PlSQL。

该语句将返回一个 OracleRowSequence，它是 OracleRow 的 AsyncSequence。这些行可以逐个迭代

for try await row in rows {
  // do something with the row
}

但是，在大多数情况下，将行的字段请求为一组 Swift 类型要容易得多

for try await (id, username, birthday) in rows.decode((Int, String, Date).self) {
  // do something with the datatypes.
}

类型必须实现 OracleDecodable 协议才能从行中解码。OracleNIO 为大多数 Swift 内置类型以及 Foundation 提供的一些类型提供了默认实现

• Bool
• Bytes、ByteBuffer、Data
• Date
• UInt8、Int8、UInt16、Int16、UInt32、Int32、UInt64、Int64、UInt、Int
• Float、Double
• String
• UUID

OracleNIO 也提供了一些更特定于 Oracle 的类型。

• Cursor
• IntervalDS
• OracleNumber
• OracleVectorBinary、OracleVectorInt8、OracleVectorFloat32、OracleVectorFloat64
• OracleJSON
• RowID

也支持将参数化查询发送到数据库（以最酷的方式）

let id = 1
let username = "fancyuser"
let birthday = Date()
try await connection.execute("""
  INSERT INTO users (id, username, birthday) VALUES (\(id), \(username), \(birthday))
  """, 
  logger: logger
)

虽然乍一看这看起来像是 SQL 注入 😱 的经典案例，但 OracleNIO 的 API 确保了这种用法是安全的。execute(_:options:logger:file:line:) 方法的第一个参数不是普通的 String，而是 OracleStatement，它实现了 Swift 的 ExpressibleByStringInterpolation 协议。OracleNIO 使用提供的字符串的字面部分作为 SQL 语句，并将每个插值替换为参数绑定。只有实现 OracleEncodable 协议的值才能以这种方式进行插值。与 OracleDecodable 一样，OracleNIO 为大多数常见类型提供了默认实现。

某些查询不会从服务器接收任何行（最常见的是 INSERT、UPDATE 和 DELETE 查询，更不用说大多数 DDL 查询）。为了支持这一点，execute(_:options:logger:file:line:) 方法被标记为 @discardableResult，这样如果未使用返回值，编译器就不会发出警告。

SemVer 更改记录在 发布页面 上的每个版本中。

Oracle NIO 是 Swift on Server Working Group 生态系统的一部分 - 目前被推荐为 沙箱成熟度。

在给定平台上，任何给定的 Oracle NIO 版本都将至少支持最新版本的 Swift 以及发布时之前的 1 个版本。

主要版本发布将围绕官方 Swift 版本发布进行安排，从 Swift 版本发布起不超过 3 个月。

主要版本发布将不再支持任何早于最后 2 个 Swift 版本的 Swift 版本。

此策略旨在平衡对尽可能多的向后兼容性的渴望，同时也能利用新的 Swift 功能来实现最佳的 API 设计。

Apache 2.0

版权所有 (c) 2023-至今，Timo Zacherl (@lovetodream)

本项目包含由与本项目无关的其他人编写的代码。所有版权声明均由他们保留。有关完整列表及其声明的权利，请参阅 NOTICE.txt

Oracle 是 Oracle Corporation 的注册商标。对其商标的任何使用均符合已建立的 商标指南，并不暗示与他们的任何关联或认可，所有权利均由他们保留。

Swift 是 Apple, Inc 的注册商标。对其商标的任何使用均不暗示与他们的任何关联或认可，所有权利均由他们保留。