« 驱动程序安装 SQL 客户端应用程序 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›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 Driver是否在已安装驱动程序的列表中来验证驱动程序是否已正确安装。

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

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

2. 配置 DSN

编辑

下一步是配置 DSN。您可以选择以下在管理器应用程序的前三个选项卡上映射的选项

  • 用户 DSN

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

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

  • 系统 DSN

    与用户 DSN 类似，不同之处在于在此选项卡下配置的连接对系统上配置的所有用户都可用。

  • 文件 DSN

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

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

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

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

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

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

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

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

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

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

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

2.2 连接参数
编辑

此选项卡允许配置以下项

  • 名称

    这是 DSN 将被引用的名称。

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

    示例：localhost

  • 描述

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

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

  • 云 ID

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

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

  • 主机名

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

    示例：::1

  • 端口

    Elasticsearch 监听的端口。

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

  • 用户名，密码

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

在保存 DSN 之前，至少必须提供名称和主机名字段。

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

2.3 加密参数
编辑

可以选择以下 SSL 选项之一

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

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

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

  • 启用。未验证证书。

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

    这是当前的默认设置。

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

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

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

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

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

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

  • 启用。已验证证书标识链。

    此设置与前一个设置等效，但多了一个针对证书吊销的检查。这提供了最强的安全选项，是生产部署的建议设置。

  • 证书文件

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

    驱动程序仅在尝试连接之前读取文件内容。有关如何检查所提供参数的有效性的信息，请参阅稍后的 2.7 测试连接 部分。

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

    如果使用文件浏览器查找证书（通过按浏览…​按钮），则默认情况下只会考虑扩展名为 .pem 和 .der 的文件。如果您的文件以不同的扩展名结尾，请从下拉列表中选择所有文件 (*.*)

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

2.4 代理参数
编辑

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

  • 类型

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

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

  • 端口

    代理正在侦听连接的 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 日志记录参数
编辑

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

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

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

  • 启用日志记录？

    勾选此项将启用驱动程序的日志记录。启用此选项时，日志目录也是强制性的（请参阅下一个选项）。但是，如果提供了指定的日志目录，即使禁用了日志记录，该目录也会保存在 DSN 中。

  • 日志目录

    在此处指定要将日志文件写入哪个目录。

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

  • 日志级别

    配置日志的详细程度。

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

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

调试日志记录可能会很快导致创建许多非常大的文件，并产生显著的处理开销。仅在指示时启用，并且最好仅在提取少量数据时启用。

2.7 测试连接
编辑

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

连接测试dsn editor conntest

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

请参阅替代日志配置部分，以了解配置日志的另一种方法。

3. DSN 可用

编辑

一切就绪后，按“*保存*”按钮会将配置存储到选定的目标位置（注册表或文件）。

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

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

已添加连接administrator system added

替代日志配置

编辑

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

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

环境变量的定义需要按如下方式进行：

  • 名称：*ESODBC_LOG_DIR*

  • 值：[路径](?[级别])，其中

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

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

日志环境变量env var log

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

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

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