« 驱动安装 SQL 客户端应用程序 »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›SQL ›SQL ODBC

配置

编辑

配置编辑

驱动安装完成后，为了使应用程序能够通过 ODBC 连接到 Elasticsearch，必须向驱动提供一组配置参数。根据应用程序的不同，通常有三种提供这些参数的方法

  • 通过连接字符串；
  • 使用用户 DSN 或系统 DSN；
  • 通过文件 DSN。

DSN (数据源名称) 是 ODBC 驱动连接到数据库所需的一组参数的通用名称。

我们将这些参数称为连接参数或DSN（尽管其中一些参数配置了驱动程序功能的其他方面；例如日志记录、缓冲区大小……）。

使用 DSN 是执行驱动程序配置最广泛使用、最简单和最安全的方法。另一方面，构建连接字符串是最粗糙的方法，因此是最不常见的方法。

我们将只关注 DSN 的使用。

1. 启动 ODBC 数据源管理器编辑

对于 DSN 管理，ODBC 提供了ODBC 数据源管理器应用程序，该应用程序已安装在所有最新的桌面 Windows 操作系统上。

  • Odbcad32.exe 文件的 32 位版本位于 %systemdrive%\Windows\SysWoW64 文件夹中。
  • Odbcad32.exe 文件的 64 位版本位于 %systemdrive%\Windows\System32 文件夹中。

要启动它，请打开搜索菜单 - Win + S - 然后键入“ODBC 数据源 (64 位)”或“ODBC 数据源 (32 位)”，然后按Enter

启动 ODBC 数据源管理器启动管理员

启动后，您可以通过单击 ODBC 数据源管理器的驱动程序选项卡并检查Elasticsearch 驱动程序是否出现在已安装驱动程序列表中来验证驱动程序是否已正确安装。

您还应该看到已安装驱动程序的版本号。

驱动程序选项卡管理员驱动程序

2. 配置 DSN编辑

下一步是配置 DSN。您可以选择以下选项，这些选项映射到管理员应用程序的前三个选项卡

  • 用户 DSN

    在此选项卡下配置的连接仅对当前登录的用户可用。每个 DSN 都由一个选择的任意名称（通常是主机或集群名称）引用。

    构成 DSN 的实际参数集通过驱动程序存储在系统注册表中。因此，用户以后只需要向应用程序提供 DSN 名称即可连接到配置的 Elasticsearch 实例。

  • 系统 DSN

    与用户 DSN 类似，只是在此选项卡下配置的连接将对系统上配置的所有用户可用。

  • 文件 DSN

    此选项卡包含允许将一组连接参数写入文件而不是注册表的功能。

    然后可以在多个系统之间共享此文件，用户需要指定该文件的路径，以便应用程序连接到配置的 Elasticsearch 实例。

所有上述步骤的配置步骤都类似。以下是配置系统 DSN 的示例。

2.1 启动 Elasticsearch SQL ODBC 驱动程序 DSN 编辑器编辑

单击系统 DSN选项卡，然后单击添加…按钮

添加新的 DSN管理员系统添加

将打开一个新窗口，列出所有可用的已安装驱动程序。单击Elasticsearch 驱动程序以突出显示它，然后单击完成按钮

启动 DSN 编辑器管理员启动编辑器

此操作将关闭先前打开的第二个窗口，并打开一个新的窗口，即 Elasticsearch SQL ODBC 驱动程序的 DSN 编辑器

Elasticsearch SQL ODBC 驱动程序 DSN 编辑器dsn 编辑器基本

这个新窗口有三个选项卡，每个选项卡负责一组配置参数，如下所示。

2.2 连接参数编辑

此选项卡允许配置以下项目

  • 名称

    这是 DSN 将被引用的名称。

    此字段可用的字符仅限于注册表键允许的字符集。

    示例：localhost

  • 描述

    此字段允许任意文本；通常用于关于配置连接的简短说明。

    示例：到本地 [::1]:9200 的明文连接。

  • 云 ID

    云 ID 是一个字符串，它简化了连接到 Elastic 的云 Elasticsearch 服务时的配置；它是在每个 Elasticsearch 集群的云控制台中获得的，并对该集群的连接参数进行编码。

    当此字段被配置时，主机名、端口和安全设置也会被配置，并且它们各自的输入被禁用。

  • 主机名

    此字段需要驱动程序将连接到的 Elasticsearch 实例的可解析 DNS 名称或 IP 地址。

    示例：::1

  • 端口

    Elasticsearch 监听的端口。

    如果留空，将使用默认的 9200 端口号。

  • 用户名、密码

    如果启用了安全性，则这些字段需要包含访问用户的凭据。

至少，必须配置名称和主机名字段，然后才能保存 DSN。

默认情况下启用连接加密。如果连接到没有加密的 Elasticsearch 节点，则需要更改此设置。

2.3 密码学参数编辑

可以选择以下 SSL 选项之一

  • 禁用。所有通信未加密。

    驱动程序和 Elasticsearch 实例之间的通信通过明文连接执行。

    此设置可能会将访问凭据暴露给拦截网络流量的第三方，因此不建议使用。

  • 启用。证书未验证。

    连接加密已启用，但未验证服务器的证书。

    这目前是默认设置。

    此设置允许第三方轻松地充当中间人，从而拦截所有通信。

  • 启用。证书已验证；主机名未验证。

    连接加密已启用，驱动程序会验证服务器的证书是否有效，但它不会验证证书是否在它应该运行的服务器上运行。

    此设置允许拥有服务器证书的第三方充当中间人，从而拦截所有通信。

  • 启用。证书已验证；主机名已验证。

    连接加密已启用，驱动程序会验证证书是否有效，以及它是否部署在证书应该运行的服务器上。

  • 启用。证书身份链已验证。

    此设置等同于上一个设置，但对证书的吊销进行了额外的检查。这提供了最强的安全选项，是生产部署的推荐设置。

  • 证书文件

    如果服务器使用不在 PKI 中的证书，例如使用自签名证书，您可以配置指向 X.509 证书文件的路径，该文件将由驱动程序用于验证服务器提供的证书。

    驱动程序只会在尝试连接之前读取文件的内容。请参阅2.7 测试连接部分，了解如何检查所提供参数的有效性。

    证书文件不能捆绑或受密码保护，因为驱动程序不会提示输入密码。

    如果使用文件浏览器来定位证书 - 通过按浏览…按钮 - 默认情况下，只有扩展名为.pem和.der的文件会被考虑。如果您的文件以不同的扩展名结尾，请从下拉菜单中选择所有文件 (*.*)

    证书文件浏览器dsn 编辑器安全证书

2.4 代理参数编辑

如果连接到 Elasticsearch 节点需要通过代理，则需要配置以下参数

  • 类型

    连接到代理主机时要使用哪种协议。这也规定了您要通过代理连接到的 Elasticsearch 节点需要在2.2 连接参数下如何指定

    • HTTP、SOCKS4A、SOCKS5H：接受 IP 地址或主机名；代理将解析 DNS 名称；
    • SOCKS4、SOCKS5：Elasticsearch 节点位置需要以 IP 地址的形式提供；

  • 端口

    代理监听连接的 TCP 端口。

  • 用户名

    用于对代理进行身份验证的凭据的用户部分。

  • 密码

    代理凭据的密码部分。

代理参数dsn 编辑器代理

2.5 连接参数编辑

可以通过以下参数进一步调整连接配置。

  • 请求超时 (秒)

    服务器请求的最大时间（以秒为单位）。这可以被更大的语句级超时设置覆盖。值 0 表示没有超时。

  • 最大页面大小（行）

    Elasticsearch SQL 服务器应为一页发送给驱动程序的最大行数。这对应于 SQL 搜索 API 的 fetch_size 参数。值 0 表示服务器默认值。

  • 最大页面长度（MB）

    答案可以增长到的最大大小（以兆字节为单位），在被驱动程序拒绝为过大之前。这是关于一页的 HTTP 答案主体，而不是查询可能生成的累积数据量。

  • Varchar 限制

    字符串列的最大宽度。如果此设置大于零，驱动程序将宣传所有字符串类型列具有等于此值的字符长度，并将任何更长的字符串截断为它。字符串类型是文本字段（TEXT、KEYWORD 等）和一些特殊字段（IP、GEO 等）。请注意，在截断之前不会对值进行任何解释，如果限制设置得太低，可能会导致无效值。对于那些不支持与 Elasticsearch 字段一样大的列长度的应用程序来说，这是必需的。

  • 浮点数格式

    控制浮点数在驱动程序将其转换为字符串时将如何打印。此参数的可能值

    • scientific: 指数表示法（例如：1.23E01）；
    • default: 默认表示法（例如：12.3）；
    • auto: 驱动程序将根据要打印的值选择上述方法之一。请注意，小数位数取决于要打印的值的精度（或 ODBC 比例），并且随 Elasticsearch SQL 支持的不同浮点类型而变化。当应用程序从驱动程序获取值为数字，然后随后自行进行转换时，此设置无效。

  • 数据编码

    此值控制对 REST 内容进行编码的数据格式。可能的值是

    • CBOR: 使用简洁二进制对象表示格式。鉴于其更紧凑的格式，这是首选编码。
    • JSON: 使用 JavaScript 对象表示法格式。此格式更冗长，但更容易阅读，尤其是在故障排除时很有用。

  • 数据压缩

    此设置控制是否以及何时压缩 REST 内容（以上述格式之一进行编码）。可能的值是

    • on: 启用压缩；
    • off: 禁用压缩；
    • auto: 启用压缩，除了数据通过安全连接流动的情况；因为在这种情况下，加密层使用自己的数据压缩，并且启用额外的压缩可能会带来安全隐患，因此应将设置保持为该值。

  • 遵循 HTTP 重定向

    驱动程序是否应遵循对服务器的请求的 HTTP 重定向？

  • 使用本地时区

    此设置控制

    • 查询将执行的上下文中的时区（尤其与处理时间戳组件的函数相关）；

    • 从服务器接收/发送到服务器的时间戳。

      如果禁用，将应用 UTC 时区；否则，将应用本地机器的设置时区。

  • 自动转义 PVA

    模式值参数使用 _ 和 % 作为特殊字符来构建模式匹配值。但是，某些应用程序将这些字符用作常规字符，这会导致 Elasticsearch SQL 返回比应用程序预期的更多数据。通过自动转义，驱动程序将检查参数，如果应用程序尚未完成，将转义这些特殊字符。

  • 多值字段宽松

    此设置控制服务器在查询多值字段时的行为。如果设置了此设置并且服务器遇到此类字段，它将从集合中选择一个值 - 没有任何关于该值的保证，但通常是自然升序中的第一个 - 并将其作为该列的值返回。如果未设置，服务器将返回错误。这对应于 SQL 搜索 API 的 field_multi_value_leniency 参数。

  • 包含冻结索引

    如果此参数为 true，服务器将在查询执行中包含冻结索引。这对应于 Elasticsearch SQL 的请求参数 index_include_frozen

  • 早期查询执行

    如果设置了此配置，驱动程序将在应用程序提交语句以进行准备（即早期）时立即执行语句 - 这在功能上等同于直接执行。这只有在查询缺少参数时才会发生。早期执行对于那些在实际执行查询之前检查结果的应用程序很有用。Elasticsearch SQL 缺少准备 API，因此早期执行对于与这些应用程序的互操作性是必需的。

连接参数dsn editor misc

2.6 日志记录参数edit

出于故障排除目的，Elasticsearch SQL ODBC 驱动程序提供记录应用程序进行的 API 调用的功能；这在管理员应用程序中启用

启用应用程序 ODBC API 日志记录administrator tracing

但是，这只会将应用程序对驱动程序管理器进行的 ODBC API 调用记录到驱动程序管理器中，而不会将驱动程序管理器对驱动程序本身进行的调用记录到驱动程序本身中。要启用对驱动程序接收的调用的日志记录，以及内部驱动程序处理事件的日志记录，您可以在编辑器的日志记录选项卡上启用驱动程序的日志记录

  • 启用日志记录？

    选中此项将启用驱动程序的日志记录。启用此选项时，日志记录目录也是必需的（请参阅下一个选项）。但是，即使日志记录被禁用，指定的日志记录目录也会保存在 DSN 中。

  • 日志目录

    这里用于指定要将日志文件写入哪个目录。

    驱动程序将为那些生成日志记录消息的连接创建每个连接一个日志文件。

  • 日志级别

    配置日志的详细程度。

    启用驱动程序日志记录dsn editor logging

    启用身份验证后，密码将从日志中删除。

调试日志记录会导致快速创建许多非常大的文件并产生大量的处理开销。只有在指示的情况下才启用，最好是在获取少量数据时才启用。

2.7 测试连接edit

配置完主机名、端口（如果与隐式默认值不同）和 SSL 选项后，您可以通过按下测试连接按钮来测试提供的参数是否正确。这将指示驱动程序连接到 Elasticsearch 实例并执行简单的 SQL 测试查询。（因此，这将需要一个运行的 Elasticsearch 实例，并且启用了 SQL 插件。）

连接测试dsn editor conntest

进行连接测试时，将考虑所有配置的参数，包括日志记录配置。这将允许及早检测潜在的文件/目录访问权限冲突。

有关配置日志记录的另一种方法，请参阅替代日志记录配置部分。

3. DSN 可用edit

一切就绪后，按下保存按钮将配置存储到所选的目标（注册表或文件）中。

在保存 DSN 配置之前，将验证提供的文件/目录路径在当前系统上是否有效。但是，DSN 编辑器不会以任何方式验证配置的主机名：端口的有效性或可达性。有关详尽检查，请参阅2.7 测试连接。

如果一切正确，新创建的 DSN 的名称将被列为可用

连接已添加administrator system added

替代日志记录配置edit

由于 ODBC API 的规范，驱动程序只会在调用连接 API（例如SQLConnect或SQLDriverConnect）时才接收配置的 DSN 参数（包括日志记录参数）。但是，驱动程序管理器将在尝试建立连接之前始终对驱动程序进行一组 API 调用。要捕获这些调用，需要以另一种方式传递日志记录配置参数。Elasticsearch SQL ODBC 驱动程序将为此目的使用环境变量。

配置环境变量是特定于操作系统的，本指南中没有详细介绍。变量应该是在系统范围内配置还是在用户范围内配置，取决于 ODBC 启用应用程序的运行方式，以及日志记录是否应该只影响当前用户还是影响所有用户。

环境变量的定义需要按如下方式完成

  • 名称：ESODBC_LOG_DIR

  • 值： [path](?[level])，其中

    [path] 是将日志文件写入的目录的路径；

    [level] 是可选的，可以取以下值之一：debug、info、warn、error；如果未提供，则假定为debug。

日志记录环境变量env var log

通过环境变量启用日志记录时，驱动程序将创建每个进程一个日志文件。

两种配置日志记录的方法可以共存，并且都可以使用相同的目标日志记录目录。但是，一条日志记录消息只会记录一次，连接日志记录优先于环境变量日志记录。

« 驱动安装 SQL 客户端应用程序 »