客户端库

• 1: 客户端驱动程序和服务器版本兼容性
• 2: 客户端驱动程序
• 2.1: 安装和配置客户端驱动程序
• 2.1.1: Windows 客户端驱动程序安装程序
• 2.1.1.1: 系统先决条件
• 2.1.1.1.1: .NET Framework
• 2.1.1.1.2: Microsoft visual studio
• 2.1.1.1.3: Microsoft SQL server
• 2.1.1.2: 适用于 Windows 的 Visual Studio 插件
• 2.1.1.2.1: Visual Studio 限制
• 2.1.1.3: 卸载、修改或修复客户端驱动程序和工具
• 2.1.2: FIPS 客户端驱动程序
• 2.1.2.1: 为 JDBC 安装 FIPS 客户端驱动程序
• 2.1.2.2: 为 ODBC 和 vsql 安装 FIPS 客户端驱动程序
• 2.1.3: JDBC 客户端驱动程序
• 2.1.3.1: 安装 JDBC 客户端驱动程序
• 2.1.3.2: 修改 Java CLASSPATH
• 2.1.4: ODBC 客户端驱动程序
• 2.1.4.1: 安装 ODBC 客户端驱动程序
• 2.1.4.2: 升级和降级 ODBC
• 2.1.4.3: 卸载 ODBC
• 2.1.4.4: 创建 ODBC 数据源名称 (DSN)
• 2.1.4.4.1: 为 Linux 创建 ODBC DSN
• 2.1.4.4.1.1: 使用 isql 测试 ODBC DSN
• 2.1.4.4.2: 为 Windows 客户端创建 ODBC DSN
• 2.1.4.4.2.1: 设置 ODBC DSN
• 2.1.4.4.2.2: ODBC DSN 的密码加密
• 2.1.4.4.2.3: 使用 Excel 测试 ODBC DSN
• 2.1.4.4.3: 为 macOS 客户端创建 ODBC DSN
• 2.1.4.4.3.1: 使用 iodbctest 测试 ODBC DSN
• 2.1.4.4.4: ODBC DSN 连接属性
• 2.1.4.4.5: 设置 DSN 连接属性
• 2.1.4.5: ODBC 驱动程序设置
• 2.1.4.6: 配置 ODBC 日志
• 2.1.5: Python 客户端驱动程序
• 2.1.5.1: 安装 Python 客户端驱动程序
• 2.1.6: Node.js 客户端驱动程序
• 2.1.7: OLE DB 客户端驱动程序
• 2.1.7.1: 安装 OLE DB 客户端驱动程序
• 2.1.7.1.1: OLE DB 连接属性
• 2.1.7.1.2: 配置 OLE DB 日志
• 2.1.7.2: 适用于 Windows 的 Microsoft Connectivity Pack
• 2.1.7.2.1: Microsoft 组件
• 2.1.7.2.1.1: Microsoft 组件配置
• 2.1.7.2.1.2: BIDS 和 SSDT-BI
• 2.1.7.2.1.3: SQL Server Analysis Services (SSAS) 支持
• 2.1.7.2.1.4: SQL Server Integration Services (SSIS) 支持
• 2.1.7.2.1.5: SQL Server Reporting Services (SSRS) 支持
• 2.1.7.2.2: 兼容性问题和限制
• 2.1.7.2.2.1: BIDS 和 SSDT-BI 限制
• 2.1.7.2.2.2: SSAS 限制
• 2.1.7.2.2.3: SSIS 数据类型限制
• 2.1.7.2.2.4: SSRS 限制
• 2.1.8: ADO.NET 客户端驱动程序
• 2.1.8.1: 安装 ADO.NET 客户端驱动程序
• 2.2: 升级客户端驱动程序
• 2.3: 设置客户端连接标记
• 2.4: 使用旧版驱动程序
• 3: 访问 Vertica
• 3.1: C/C++
• 3.1.1: ODBC 体系结构
• 3.1.2: ODBC 功能支持
• 3.1.3: Vertica 和 ODBC 数据类型转换
• 3.1.4: ODBC 头文件
• 3.1.5: 连接到数据库
• 3.1.6: 负载均衡
• 3.1.7: 连接故障转移
• 3.1.8: 提示 Windows 用户提供缺少的连接属性
• 3.1.9: 提示 Windows 用户提供密码
• 3.1.10: 设置 ODBC 会话的区域设置和编码
• 3.1.11: AUTOCOMMIT 事务和 ODBC 事务
• 3.1.12: 检索数据
• 3.1.13: 加载数据
• 3.1.13.1: 使用单行插入
• 3.1.13.2: 使用预定义的语句
• 3.1.13.3: 使用批量插入
• 3.1.13.3.1: 跟踪加载状态 (ODBC)
• 3.1.13.3.2: 批量加载过程中的错误处理
• 3.1.13.4: 使用 COPY 语句
• 3.1.13.5: 使用 COPY LOCAL 从客户端进行流式数据传输
• 3.2: C#
• 3.2.1: ADO.NET 数据类型
• 3.2.2: 设置 ADO.NET 会话的区域设置
• 3.2.3: 连接到数据库
• 3.2.3.1: 使用 TLS：在 Windows 中安装证书
• 3.2.3.2: 打开和关闭数据库连接 (ADO.NET)
• 3.2.3.3: ADO.NET 连接属性
• 3.2.3.4: ADO.NET 中的负载均衡
• 3.2.3.5: ADO.NET 连接故障转移
• 3.2.4: 使用 ADO.NET 查询数据库
• 3.2.4.1: 插入数据 (ADO.NET)
• 3.2.4.1.1: 使用参数
• 3.2.4.1.2: 创建和回退事务
• 3.2.4.1.2.1: 设置事务隔离级别
• 3.2.4.2: 读取数据 (ADO.Net)
• 3.2.4.3: 通过 ADO.Net 加载数据
• 3.2.4.3.1: 使用 Vertica 数据适配器
• 3.2.4.3.2: 使用批量插入和预定义的语句
• 3.2.4.3.3: 通过 ADO.NET 进行流式数据传输
• 3.2.4.3.3.1: 通过 VerticaCopyStream 从客户端进行流式传输
• 3.2.4.3.3.2: 将复制功能与 ADO.NET 配合使用
• 3.2.5: 取消 ADO.NET 查询
• 3.2.6: 处理消息
• 3.2.7: 获取表元数据
• 3.3: Java
• 3.3.1: JDBC 功能支持
• 3.3.2: 创建和配置连接
• 3.3.2.1: JDBC 连接属性
• 3.3.2.2: 设置和获取连接属性值
• 3.3.2.3: 为 JDBC 客户端配置 TLS
• 3.3.2.4: 设置和返回客户端连接标记
• 3.3.2.5: 设置 JDBC 会话的区域设置
• 3.3.2.6: 更改事务隔离级别
• 3.3.2.7: JDBC 连接池
• 3.3.2.8: JDBC 中的负载均衡
• 3.3.2.9: JDBC 连接故障转移
• 3.3.3: JDBC 数据类型
• 3.3.3.1: VerticaTypes 类
• 3.3.3.2: 数值数据别名转换
• 3.3.3.3: 将时间间隔与 JDBC 配合使用
• 3.3.3.4: UUID 值
• 3.3.3.5: JDBC 中的复杂类型
• 3.3.3.6: JDBC 中的日期类型
• 3.3.4: 通过 JDBC 执行查询
• 3.3.5: 取消 JDBC 查询
• 3.3.6: 通过 JDBC 加载数据
• 3.3.6.1: 使用单行插入
• 3.3.6.2: 使用 JDBC 预定义的语句批量插入
• 3.3.6.2.1: 批量加载过程中的错误处理
• 3.3.6.2.2: 确定已接受和已拒绝行 (JDBC)
• 3.3.6.2.3: 在服务器中回退批量加载
• 3.3.6.3: 使用 COPY 语句进行批量加载
• 3.3.6.4: 通过 JDBC 进行流式数据传输
• 3.3.6.4.1: 使用 VerticaCopyStream
• 3.3.6.4.2: 将 COPY LOCAL 与 JDBC 配合使用
• 3.3.7: 处理错误
• 3.3.7.1: SQLState 和 Java 异常类的映射
• 3.3.8: 将 JDBC 查询直接路由到单个节点
• 3.3.8.1: 创建与可路由查询 API 一起使用的表和投影
• 3.3.8.2: 为可路由查询创建连接
• 3.3.8.3: 使用 VerticaRoutableExecutor 类为可路由查询定义查询
• 3.3.8.4: 使用 VGet 类为可路由查询定义查询
• 3.3.8.5: 可路由查询性能和故障排除
• 3.3.8.6: 使用 VHash 对数据进行预分段
• 3.4: JavaScript
• 3.5: Perl
• 3.5.1: 配置 Perl 开发环境
• 3.5.2: 使用 Perl 连接到 Vertica
• 3.5.2.1: 在 Perl 中设置 ODBC 连接参数
• 3.5.2.2: 设置 Perl DBI 连接属性
• 3.5.2.3: 不使用 DSN 从 Perl 进行连接
• 3.5.3: 使用 Perl 执行语句
• 3.5.4: 使用 Perl 批量加载数据
• 3.5.5: 在 Perl 中使用 COPY LOCAL 加载数据
• 3.5.6: 使用 Perl 执行查询
• 3.5.7: Perl 数据类型和 Vertica 数据类型之间的转换
• 3.5.8: Perl Unicode 支持
• 3.6: Python
• 3.6.1: 在 Linux 中配置 ODBC 运行时环境，请执行下列操作：
• 3.6.2: 使用 pyodbc 查询数据库
• 3.7: PHP
• 3.7.1: 配置 PHP 开发环境
• 3.7.2: PHP Unicode 支持
• 3.7.3: 使用 PHP 查询数据库
• 4: 管理客户端和 Vertica 之间的查询执行
• 4.1: ResultBufferSize
• 4.2: 多重活动结果集 (MARS)

1 - 客户端驱动程序和服务器版本兼容性

Vertica 服务器与客户端驱动程序之间的向后兼容性可双向工作；Vertica 服务器与所有先前版本的客户端驱动程序兼容，所有新的客户端驱动程序都与大多数版本的 Vertica 服务器兼容。这种兼容性使您无需立即升级客户端软件即可升级 Vertica 服务器，并且可以将新客户端软件与旧版本的 Vertica 一起使用。但有时，新服务器版本中的个别功能可能在旧版驱动程序中不可用。

2 - 客户端驱动程序

必须安装 Vertica 客户端驱动程序才能从客户端应用程序访问 Vertica。驱动程序将创建并维护与数据库的连接，而且为应用程序提供用于访问数据的 API。客户端驱动程序支持使用 JDBC、ODBC 和 ADO.NET 的连接。

客户端驱动程序标准

客户端驱动程序支持以下标准：

• ODBC 驱动程序符合 ODBC 3.5.1 规范。

• JDBC 驱动程序符合 JDK 5 规范。

• ADO.NET 驱动程序符合 .NET framework 3.0 规范。

2.1 - 安装和配置客户端驱动程序

通过安装适当的客户端驱动程序，您可以使用各种编程语言和工具访问 Vertica 数据库。下表列出了每种访问方法所需的客户端驱动程序：

2.1.1 - Windows 客户端驱动程序安装程序

Vertica 客户端驱动程序和工具安装程序中包含所有可用的 Windows 客户端驱动程序。这会在满足先决条件的系统上安装以下组件。个别组件在使用前可能需要额外配置，因此请导航至下方链接的页面以获取更多信息：

• ODBC

• JDBC

• OLE DB

• vsql

• ADO.NET

• 适用于 Windows 的 Microsoft Connectivity Pack
• 适用于 Windows 的 Visual Studio 插件

2.1.1.1 - 系统先决条件

适用于 Windows 的 Vertica 客户端驱动程序和工具要求系统满足基本的先决条件。该包还要求安装特定的 Microsoft 组件以实现完全集成。

有关所有先决条件的列表，请参阅支持的平台文档中的客户端驱动程序支持。

完全更新系统

在安装 Vertica 驱动程序包之前，请确认系统已使用所有 Windows 更新和修补程序进行了完全更新。有关如何运行 Windows 更新的说明，请参阅您的 Windows 版本的文档。Vertica 客户端库和 vsql 可执行文件安装依赖于 Windows Service Pack 的更新的 Windows 库。确保解决阻止安装 Windows 更新的任何问题。

如果您的系统不是完全最新，您可能会在启动 vsql 时收到有关缺少库（例如 api-ms-win-crt-runtime-l1-1-0.dll）的错误消息。

2.1.1.1.1 - .NET Framework

.NET Framework 未捆绑到适用于 Windows 的 Vertica 客户端驱动程序和工具中。但是，在安装期间，如果在系统上检测不到 Microsoft .NET 3.5 SP1，则 Web 安装程序会启动。然后，您可以下载该框架。此外，如果操作系统版本包含 .NET 3.5 SP1，但未打开此功能，则安装程序会打开此功能。

如果已安装 Visual Studio 2010 或 2012，则您的系统已包含 Microsoft .NET Framework 4.0 或 4.5。您还需要安装 Microsoft .NET 3.5 SP1，才能使用 Vertica 客户端驱动程序和工具来实现 Windows 集成功能。

可以使用以下链接直接从 Microsoft 下载相应的 .NET Framework 版本：

• 对于 .NET Framework 3.5 SP1：

  http://www.microsoft.com/en-us/download/details.aspx?id=22

• 对于 .NET Framework 4.0：

  http://www.microsoft.com/en-us/download/details.aspx?id=17851

• 对于 .NET Framework 4.5：

  http://www.microsoft.com/en-us/download/details.aspx?id=17851

2.1.1.1.2 - Microsoft visual studio

适用于 Windows 安装程序的 Vertica 客户端驱动程序和工具提供一个 Visual Studio 插件，通过该插件，您可以使用 Vertica 作为 Visual Studio 2008、Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015 的 Visual Studio 数据源。该插件的连接属性与 ADO.NET 连接属性 相同。

安装该插件之后，您可以使用该插件从 Visual Studio 中访问 Vertica 数据库。如果尚未安装 SDK，请下载特定于您的 Visual Studio 版本的 SDK。

• Microsoft Visual Studio 2008 SDK

• Microsoft Visual Studio 2008 SP1 SDK

• Microsoft Visual Studio 2010 SDK

• Microsoft Visual Studio 2010 SP1 SDK

• Microsoft Visual Studio 2012 SDK

• Microsoft Visual Studio 2013 SDK

如果开始安装时缺少 Microsoft Visual Studio SDK，将打开一个对话框进行安装。您可以选择忽略此对话框。

配置 BIDS 集成或 SSDT-BI 集成

适用于 Windows 安装程序的 Vertica 客户端驱动程序和工具提供 BIDS (Visual Studio 2008) 集成或 SSDT-BI（Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015）集成。若要使用 BIDS 或 SSDT-BI，请遵循以下过程：

1. 安装适用于 Visual Studio 的 BIDS 或 SSDT-BI 开发工具加载项。

2. 验证 SQL Server 是安装在同一台还是不同计算机上。

3. 验证是否已激活适用于 IDS 或 SSDT-BI 的 SQL Server 共享功能。

然后，您可以使用 BIDS 或 SSDT-BI 开发程序包，还可以使用 SQL Server 的 SSIS、SSAS 和 SSRS 功能创建项目。若要使用这些功能，您必须通过 Vertica ADO.NET 驱动程序（适用于 SSIS 和 SSRS）或 OLE DB 驱动程序（适用于 SSAS）连接到 Vertica。

有关详细信息，请参阅Microsoft 组件。

2.1.1.1.3 - Microsoft SQL server

使用 SQL Server 2012、SQL Server 2014 或 SQL Server 2016。适用于 Windows 安装程序的 Vertica 客户端驱动程序和工具支持以下功能：

• SQL Server 2012、SQL Server 2014 和 SQL Server 2016：

  • SQL Server Integration Services (SSIS)

  • SQL Server Reporting Services (SSRS)

  • SQL Server Analysis Services (SSAS)

• 使用 Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 和 Visual Studio 2015 的 SQL Server — SQL Server Data Tools - Business Intelligence (SSDT-BI)

  注意

  对于 SQL Server 2012，您可以使用 SQL Server 2012 或 SQL Server 2012 SP1。

若要使用增强的 Vertica .NET 支持，您必须先安装 SQL Server。然后，您可以安装适用于 Windows 的客户端驱动程序和工具。必须在 SQL Server 上安装以下组件：

2.1.1.2 - 适用于 Windows 的 Visual Studio 插件

适用于 Windows 的 Visual Studio 插件作为适用于 Windows 的客户端驱动程序和工具的一部分安装。

有关 Visual Studio 插件如何与先前已安装在系统上的 Microsoft 组件集成的信息，请参阅 Microsoft 组件。

2.1.1.2.1 - Visual Studio 限制

Visual Studio 2012 可能需要 Update 3

在下列情况下，您可能需要安装用于 Visual Studio 2012 的 Update 3：

• 启动 Server Explorer 以查看和使用 Vertica 服务器，但 Vertica 数据源不可见。

• 创建 SSAS 多维数据集，连接到 Vertica，并找到空的表列表或表无法正常工作。

对于其他受 Vertica 支持版本的 Visual Studio，此问题不会出现。

结果查看器限制为 655 列

Visual Studio 结果查看器无法执行包含超过 655 列的查询。如果表包含超过 655 列，请选择特定列（总数最多为 655），而不应选择所有列。

手动刷新 Visual Studio 的设置

安装 Visual Studio 插件后，如果 Vertica 未作为数据提供程序列出，请手动刷新。

若要执行此操作，请运行 devenv.exe/setup，您可以在 Visual Studio 的安装文件夹中找到该文件。

SQL 窗格问题

• ALTER TABLE 或 CREATE TABLE

  您使用 Visual Studio 2008、Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015，并在 SQL 窗格中发出 ALTER TABLE 或 CREATE TABLE 语句。但显示一条消息，指明该语句不受支持。若要解决该错误，请单击继续，查询将会执行。

• 带有分号的查询

  您使用 Visual Studio 2008、Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015，并在 SQL 窗格中执行 SQL 查询。如果在查询中包含分号 (;)，该查询将会执行，但您无法编辑返回的结果。若要避免此问题，请在 SQL 窗格中输入不带分号的相同查询。

• 引用布尔值

  您使用 Visual Studio 2008、Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 或 Visual Studio 2015 连接到 Vertica 数据库，并在 SQL 窗格中执行 SQL 查询。当尝试将值插入布尔列而不在值两端加上引号时，SQL 语句的后续执行将返回错误。要解决此问题，请加上引号。

卸载 适用于 Windows 的客户端驱动程序和工具错误

在某些情况下，Windows 软件包的客户端驱动程序和工具的卸载失败并显示需要 .NET Framework的消息。以下是导致此问题的场景。

1. 安装 Windows 的客户端驱动程序和工具
2. 然后安装 Visual Studio 2010 或 2012，其中包括安装 .NET Framework 4.0 或 4.5。
3. 使用 Windows 控制面板卸载 .NET Framework。
4. 然后，您尝试卸载 Windows 的客户端驱动程序和工具。卸载将会失败并显示需要 .NET Framework的消息。

要更正此问题，请执行以下操作：

1. 使用 Windows 控制面板手动重新安装 .NET Framework 4.0 或 4.5。
2. 卸载 Windows 的客户端驱动程序和工具

2.1.1.3 - 卸载、修改或修复客户端驱动程序和工具

要卸载、修改或修复客户端驱动程序和工具，请运行适用于 Windows 的客户端驱动程序和工具安装程序。

该安装程序提供以下三个选项：

在静默模式下卸载客户端驱动程序和工具

1. 以 Windows 管理员身份，打开命令行会话，然后将目录更改为包含安装程序的文件夹。

2. 运行命令：

   VerticaSetup.exe -q -uninstall
   

将在静默模式下卸载客户端驱动程序和工具。

2.1.2 - FIPS 客户端驱动程序

Vertica 提供符合 FIPS 的版本的 ODBC 和 JDBC 客户端驱动程序。

2.1.2.1 - 为 JDBC 安装 FIPS 客户端驱动程序

Vertica 提供符合联邦信息处理标准 (FIPS) 的 JDBC 客户端驱动程序。使用此 JDBC 客户端驱动程序访问与 FIPS 兼容的系统。有关 FIPS 的详细信息，请参阅美国联邦信息处理标准。

在 JDBC 客户端上实施 FIPS 需要一个名为 BouncyCastle 的第三方 JRE 扩展，它是一组用于加密的 API。将 BouncyCastle API 与 JDK 1.7 和 1.8 以及支持的符合 FIPS 的操作系统一起使用。

以下过程将 FIPS BouncyCastle .jar 添加为 JVM JSSE 提供程序：

1. 下载 BouncyCastle FIPS .jar 文件 bc-fips-1.0.0.jar。

2. 将 bc-fips-1.0.0.jar 添加为 JRE 库扩展：

   path/to/jre/lib/ext/bc-fips-1.0.0.jar
   

3. 在 <path to jre>/lib/security/java.security 中将 BouncyCastle 添加为 SSL 安全提供程序：

   security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastle FipsProvider
   security.provider.2=com.sun.net.ssl.internal.ssl.Provider BCFIPS
   security.provider.3=sun.security.provider.Sun
   

4. 使用以下 JVM java -D 系统属性命令实参将 KeyStore 和 TrustStore 文件设置为 BCFIPS：

   export JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStoreProvider=BCFIPS
   export JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStoreProvider=BCFIPS
   

5. 在 path/to/jre/lib/security/java.security 中将 KeyStore 实施的默认类型设置为 BCFKS：

   keystore type=BCFKS
   ssl.keystore.type=BCFKS
   

   注意

   如果您将 FIPS 与 BouncyCastle 一起使用，则必须创建具有 BCFKS 存储类型的所有客户端密钥和证书（包括 Vertica 到 Kafka 连接的密钥和证书）。

6. 创建 BCFKS 类型的密钥库和信任库：

   cd path/to/jre
   -storetype BCFKS
   -providername BCFIPS
   -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
   -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
   -providerpath bc-fips-1.0.0.jar
   -alias CARoot
   -import -file path/to/server.crt.der
   

7. 出现提示时，输入密钥库密码。系统将显示以下消息以确认已将证书添加到密钥库：

   "Certificate was added to the keystore"
   

8. 使用 SSL DB 运行 Java 程序：

   1. 将 vertica.kafka.keystore.bcfks 密钥库从 path/to/jre/lib/ext/ 复制到 Java 程序文件夹。

   2. 将 Vertica 服务器证书转换为能够由 Java 理解的形式：

      $ path/to/java/bin/keytool -keystore verticastore -keypasswd -storepass password
                              -importkeystore -noprompt -alias verticasql -import -file server.crt.der
      

   3. 安装 JDBC。

9. 对实施进行测试：

   $ java -Djavax.net.debug=ssl -Djavax.net.ssl.keyStore='vertica.kafka.keystore.bcfks'
   -Djavax.net.ssl.keyStorePassword='password'
   -Djavax.net.ssl.trustStore='path/to/verticastore'
   -Djavax.net.ssl.trustStorePassword='password'
   -cp .:vertica-jdbc-12.0.0-0.jar FIPSTest
   

2.1.2.2 - 为 ODBC 和 vsql 安装 FIPS 客户端驱动程序

Vertica 为与 FIPS 兼容的系统提供 FIPS 客户端。与 FIPS 兼容的系统启用了 FIPS，其中包含 OpenSSL 库。

FIPS 客户端支持 ODBC 和 vsql，仅提供 64 位版本。

先决条件

确认主机系统正在运行受 Vertica 支持且符合 FIPS 的操作系统。

FIPS 客户端安装程序会检查您的主机系统以获取 sysctl 参数 crypto.fips_enabled 的值。您必须将此参数设置为 1（启用）。如果未启用您的主机，则客户端不会安装。

安装 FIPS 客户端

要安装 FIPS 客户端驱动程序包：

1. 从 Vertica 驱动程序下载页面 下载 FIPS 客户端包。

2. 以 root 身份登录客户端系统。

3. 安装已下载的 RPM 包：

   # rpm -Uvh package_name.rpm
   

对于 ODBC，在您安装了客户端包之后，创建 DSN 并设置一些额外的配置参数。有关详细信息，请参阅：

• 为 Linux 创建 ODBC DSN
• ODBC 驱动程序设置

您可以选择将 vsql 客户端添加到 PATH 环境变量，以便不需要输入完整路径即可运行该客户端。为此，将下行添加到主目录中的 .profile 文件或全局 /etc/profile 文件：

export PATH=$PATH:/opt/vertica/bin

客户端如何搜索 OpenSSL 库

当您启动客户端应用程序以连接到服务器时，客户端会为支持的 OpenSSL 版本搜索并加载 OpenSSL 库 libcrypto.so.10 和 libssl.so.10：

• 客户端首先检查是否已设置 LD_LIBRARY_PATH。

• 如果 LD_LIBARY_PATH 位置不包含库，它会检查 RunPath、/opt/vertica/lib 或 ODBC 或 vsql 目录结构 (../lib)。

下图描述了 OpenSSL 库的搜索过程：

2.1.3 - JDBC 客户端驱动程序

Vertica JDBC 客户端驱动程序符合 JDK 5 规范，它提供了一个接口，通过该接口可以使用 Java 与 Vertica 数据库进行通信。有关此 API 和其他 API 的详细信息，请参阅 API 参考。

要安装 JDBC 客户端驱动程序，请参阅安装 JDBC 客户端驱动程序。

2.1.3.1 - 安装 JDBC 客户端驱动程序

JDBC 客户端驱动程序符合 JDK 5 规范。根据您的环境和要求下载 JDBC 客户端驱动程序。如果您需要使用符合 FIPS 的驱动程序，请参阅为 JDBC 安装 FIPS 客户端驱动程序。

从 RPM 安装 Vertica 会自动安装 JDBC 客户端驱动程序。要使用 JDBC 客户端驱动程序，您只需将 Vertica JDBC .jar 添加到您的 CLASSPATH。

要手动安装 JDBC 客户端驱动程序：

1. 从客户端驱动程序下载页面，下载与您的 Vertica 版本兼容的 JDBC 客户端驱动程序版本。

2. 在希望从中访问 Vertica 的每个客户端系统上将 .jar 文件复制到 Java CLASSPATH 中的目录。您可以执行以下操作之一：

   • 将 .jar 文件复制到其自己的目录（例如 /opt/vertica/java/lib），然后将该目录添加到 CLASSPATH（建议采用此方法）。有关详细信息，请参阅修改 Java CLASSPATH。

   • 将 .jar 文件复制到已存在于 CLASSPATH 中的目录（例如，已将应用程序所依赖的其他 .jar 文件放置到的目录）。

   • 将 .jar 文件复制到系统范围的 Java 扩展目录。确切的位置因操作系统不同而异。一些示例包括：

     • Windows： C:\Program Files\Java\jrex.x.x_x\lib\ext\\

     • Mac OS： /Library/Java/Extensions 或 /Users/username/Library/Java/Extensions

3. 创建连接以测试您的配置。

2.1.3.2 - 修改 Java CLASSPATH

CLASSPATH 环境变量包含目录的列表，Java 运行时将从该列表的目录查找库类文件。要让 Java 客户端代码访问 Vertica，您必须将包含 Vertica JDBC .jar 的目录添加到 CLASSPATH。

将符号链接用于 CLASSPATH

您可以选择将符号链接 vertica-jdbc-x.x.x.jar（其中 x.x.x 是版本号，此符号链接指向 JDBC 库 .jar 文件而非 .jar 文件本身）添加到 CLASSPATH。

使用符号链接可确保对 JDBC 库 .jar 文件（此文件使用其他文件名）进行的任何更新不会使 CLASSPATH 设置失效，因为符号链接的文件名将保持不变。您只需要更新符号链接，使其指向新的 .jar 文件。

Linux 和 OS X

以下示例使用符合 POSIX 的 shell。

要为当前会话设置 CLASSPATH：

$ export CLASSPATH=$CLASSPATH:/opt/vertica/java/lib/vertica-jdbc-x.x.x.jar

要为每个会话设置 CLASSPATH，请将以下内容添加到启动文件（例如 ~/.profile 或 /etc/profile）：

$ export CLASSPATH=$CLASSPATH:/opt/vertica/java/lib/vertica-jdbc-x.x.x.jar

Windows

提供指向 .jar、.zip 或 .class 文件的类路径。

C:> SET CLASSPATH=classpath1;classpath2...

例如：

C:> SET CLASSPATH=C:\java\MyClasses\vertica-jdbc-x.x.x.jar

与 Linux/UNIX 设置一样，此设置仅持续到当前会话关闭。若要永久设置 CLASSPATH，请设置环境变量：

1. 在 Windows 控制面板中，单击系统。

2. 单击高级 或高级系统设置。

3. 单击环境变量。

4. 在“用户变量”下，单击新建。

5. 在“变量名”框中，键入 CLASSPATH。

6. 在“变量值 (Variable value)”框中，键入指向系统上的 Vertica JDBC .jar 文件的路径（例如， C:\Program Files (x86)\Vertica\JDBC\vertica-jdbc-x.x.x.jar）

在 Java 命令中指定库目录

另一种与操作系统无关的、告知 Java 运行时在何处可以找到 Vertica JDBC 驱动程序的方法是：使用 -cp 或 -classpath 实参将包含 .jar 文件的目录显式添加到 Java 命令行。例如，可以使用以下命令启动客户端应用程序：

java -classpath /opt/vertica/java/lib/vertica-jdbc-x.x.x.jar myapplication.class

Java IDE 还可让您将目录添加到 CLASSPATH，或者可让您将 Vertica JDBC 驱动程序导入到项目中。有关详细信息，请参阅 IDE 文档。

2.1.4 - ODBC 客户端驱动程序

Vertica ODBC 客户端驱动程序提供了一个接口，通过该接口可以使用多种语言创建客户端应用程序：

• C/C++

• Python

• Perl

• PHP

要安装 ODBC，请参阅安装 ODBC 客户端驱动程序。

2.1.4.1 - 安装 ODBC 客户端驱动程序

要安装 ODBC，请按照您的平台说明进行操作。有关受支持平台的列表，请参阅客户端驱动程序支持。

本页介绍非 FIPS 安装。要在符合 FIPS 的系统上安装 ODBC，请参阅为 ODBC 和 vsql 安装 FIPS 客户端驱动程序。

在 Linux 上安装

从 RPM 安装 Vertica 会自动安装 ODBC 客户端驱动程序，因此您无需在运行 Vertica 的计算机上再次安装它们。要在这种情况下使用 ODBC 客户端驱动程序，请创建 DSN。

要在其他计算机上手动安装 ODBC 客户端驱动程序：

1. 以 root 身份登录客户端系统。

2. 验证您的系统是否装有受支持的 ODBC 驱动程序管理器。

3. 以适合您的发行版的格式，下载适用于 Linux 的 ODBC 客户端驱动程序。

4. 安装或解压缩驱动程序：

   • 如果您下载了 .rpm，请安装该驱动程序：

     注意

     如果客户端驱动程序已安装在您的系统上（通过手动安装或通过 Vertica RPM 自动安装），则在您尝试手动重新安装，会收到错误消息。要跳过这些错误并覆盖现有的驱动程序安装，请使用 --force 标志。

     $ rpm -Uvh driver_name.rpm
     

   • 如果您下载了 .tar，则创建 /opt/vertica/ 目录（如果该目录不存在），将 .tar 复制到其中，导航到它，然后解压缩 .tar：

     
     $ mkdir -p /opt/vertica/
     $ cp driver_name.tar.gz /opt/vertica/
     $ tar vzxf driver_name.tar.gz
     

     这将创建两个目录：

     • /opt/vertica/include：包含头文件。

     • /opt/vertica/lib64/（64 位）或 /opt/vertica/lib/（32 位）：包含库文件。

5. 在 vertica.ini 中设置以下 ODBC 驱动程序设置。有关每个设置的详细信息，请参阅 ODBC 驱动程序设置：

   • ErrorMessagesPath：必需，包含 ODBC 驱动程序的错误消息文件的目录路径。

   • ODBCInstLib：ODBC 安装程序库的路径。仅当驱动管理器的安装库不在环境变量 LD_LIBRARY_PATH 或 LIB_PATH 中时才需要。

   • DriverManagerEncoding：驱动程序管理器使用的 UTF 编码标准。仅当您的驱动程序管理器不使用 UTF-8 时才需要。

   下面是 vertica.ini 中的示例配置：

   • 使用 64 位 UNIXODBC 驱动程序管理器的编码。

   • 使用标准 Vertica 64 位 ODBC 驱动程序安装目录中定义的错误消息。

   • 将所有警告和严重性更高的消息记录到日志文件 /tmp/

     [Driver]
     DriverManagerEncoding=UTF-16
     ODBCInstLib=/usr/lib64/libodbcinst.so
     ErrorMessagesPath=/opt/vertica
     LogLevel=4
     LogPath=/tmp
     

6. 创建 DSN。

在 macOS 上安装

要在 macOS 上安装 ODBC 客户端驱动程序：

1. 验证您的系统是否装有兼容的驱动程序管理器。该驱动程序旨在与 macOS 附带的标准 iODBC 驱动程序管理器一起使用。您也可以使用 unixODBC。

2. 下载 ODBC 客户端驱动程序。

3. 如果已安装以前版本的 ODBC 驱动程序，则系统可能已注册了名为“Vertica”的驱动程序。在从 .pkg 安装程序安装新版本之前，您必须移除或重命名旧版本的驱动程序。重命名旧版本可让您在安装新版本后保留旧版本。

4. 运行安装程序。

5. 创建 DSN。

静默安装

1. 通过以下两种方式之一登录客户端 macOS：

   • 以管理员帐户登录（如果您安装驱动程序是为了在系统范围使用）。

   • 以需要使用 Vertica ODBC 驱动程序的用户身份登录。

2. 打开终端。

3. 使用以下命令安装包含 ODBC 驱动程序的 .pkg 文件：

   sudo installer -pkg path/to/client/driver/vertica-odbc-xx.x.x-x.pkg -target /
   

在 Windows 上安装

要在 Windows 上安装 ODBC 客户端驱动程序：

1. 下载适用于 Windows 的客户端驱动程序安装程序。

2. 运行安装程序。

3. 创建 DSN。

静默安装

1. 以管理员身份打开终端。

2. 运行以下命令将驱动程序静默安装到 C:\Program Files\Vertica Systems：

   VerticaSetup.exe -q -install InstallFolder="C:\Program Files\Vertica Systems"
   

2.1.4.2 - 升级和降级 ODBC

Linux

要升级 ODBC：

1. 卸载当前版本的驱动程序。

2. 安装新版本的驱动程序。

macOS

要升级或降级 ODBC：

• 升级：新安装的适用于 macOS 的 Vertica ODBC 驱动程序版本会自动升级相关的驱动程序系统设置。除了开始使用较新版本的驱动程序之外，与以前版本的驱动程序关联的任何 DSN 不受影响。

• 降级：运行卸载脚本以移除适用于 macOS 的 Vertica ODBC 驱动程序的当前版本。在安装旧版本的驱动程序之前完成此步骤。

Windows

1. 下载 Windows 客户端驱动安装程序。

2. 运行安装程序并按照提示升级驱动程序。安装程序会升级现有的驱动程序。

3. 重新启动系统。

2.1.4.3 - 卸载 ODBC

Linux

如果您使用 .rpm 安装了 ODBC：

$ rpm -e package_name

如果您使用 .tar 安装了 ODBC，请手动删除该目录。

macOS

卸载 macOS ODBC 客户端驱动程序不会移除与该驱动程序关联的任何现有 DSN。

若要卸载，请执行下列操作：

1. 打开终端窗口。

2. 运行命令：

   sudo /Library/Vertica/ODBC/bin/Uninstall
   

Windows

1. 打开添加或删除程序 (Add or Remove Programs) 菜单。

2. 或者卸载 Vertica Client Installer 以从系统中移除所有客户端驱动程序，或者仅卸载 ODBC 以卸载以下应用程序：

   • Vertica ODBC 驱动程序（32 位）

   • Vertica ODBC 驱动程序（64 位）

2.1.4.4 - 创建 ODBC 数据源名称 (DSN)

数据源名称 (DSN) 是由开放式数据库连接 (ODBC) 使用的逻辑名称，用于引用从数据源访问数据而所需的驱动程序和其他信息。无论您是开发自己的 ODBC 客户端代码，还是使用需要通过 ODBC 访问 Vertica 的第三方工具，都需要配置和测试 DSN。您使用的方法取决于所用的客户端操作系统。

有关特定于您的客户端操作系统的信息，请参阅以下部分。

2.1.4.4.1 - 为 Linux 创建 ODBC DSN

在 Linux 和其他类 UNIX 平台上，您可以在文本文件中定义 DSN。客户端的驱动程序管理器会读取该文件，以确定如何连接到 Vertica 数据库。驱动程序管理器通常在以下两个位置查找 DSN 定义：

• /etc/odbc.ini

• ~/.odbc.ini （用户主目录中名为 .odbc.ini 的文件）

用户必须能够读取 odbc.ini 文件，才能使用它连接到数据库。如果使用全局 odbc.ini 文件，请考虑创建一个对该文件具有读取权限的 UNIX 组。然后，将需要使用 DSN 的用户添加到该组。

这些文件的结构是相同的，只是所在位置不同而已。如果这两个文件都存在，则 ~/.odbc.ini 文件通常会替代系统范围 /etc/odbc.ini 文件。

odbc.ini 文件结构

odbc.ini 是一个包含以下两种类型的行的文本文件：

• 节定义，是用方括号括起来的文本字符串。

• 参数定义，其中依次包含参数名称、等号 (=) 和参数值。

文件的第一节始终名为 [ODBC Data Sources]，其中包含 odbc.ini 文件所定义的所有 DSN 的列表。此节中的参数是 DSN 的名称，这些参数稍后在文件中显示为节定义。值是 DSN 的文本描述，并不起任何作用。例如，定义了名为 Vertica DSN 的单个 DSN 的 odbc.ini 文件可能包含以下 ODBC 数据源节：

[ODBC Data Sources]
VerticaDSN = "vmartdb"

显示在 ODBC 数据源节之后的节定义了每个 DSN。DSN 节的名称必须与 ODBC 数据源节中定义的名称之一匹配。

配置 odbc.ini 文件：

若要创建或编辑 DSN 定义文件，请执行下列操作：

1. 使用所选文本编辑器打开 odbc.ini 或 ~/.odbc.ini。

2. 创建 ODBC 数据源节并定义参数：

   • 其名称是要创建的 DSN 的名称

   • 其值是 DSN 的描述

   例如，若要创建名为 VMart 的 DSN，您应输入以下命令：

   [ODBC Data Sources]
   VMart = "VMart database on Vertica"
   

3. 创建名称与您在步骤 2 中定义的 DSN 名称匹配的节。在此节中，您应添加定义了 DSN 的设置的参数。最常定义的参数如下：

   • Description – 有关数据源的附加信息。

   • Driver – Vertica ODBC 驱动程序的位置和指定，或 odbcinst.ini 文件中定义的驱动程序的名称（请参阅下文）。为了确保将来的兼容性，请使用库目录（而非库文件）中的符号链接的名称：

     • /opt/vertica/lib（在 32 位客户端上）

     • /opt/vertica/lib64，（在 64 位客户端上）

     例如，64 位 ODBC 驱动程序库的符号链接是：

     /opt/vertica/lib64/libverticaodbc.so
     

     符号链接始终指向最新版本的 Vertica 客户端 ODBC 库。请使用此链接，以便不需要在更新客户端驱动程序后更新所有 DSN。

   • Database – 在服务器中运行的数据库的名称。此示例使用 vmartdb 来表示 vmartdb。

   • ServerName — 安装了 Vertica 的服务器的名称。如果 Vertica 已安装在同一台计算机上，则使用 localhost。

     您可以提供 IPv4 地址、IPv6 地址或主机名。

     在 IPv4/IPv6 混合网络中，DNS 服务器配置决定了哪个 IP 版本地址最先发送。可使用 PreferredAddressFamily 选项来强制连接使用 IPv4 或 IPv6。

   • UID — 数据库超级用户（名称与数据库管理员帐户相同）或超级用户已创建并向其授予了权限的用户。此示例使用用户名 dbadmin。

   • PWD — 指定的用户名的密码。此示例将密码字段留空。

   • Port — Vertica 用来侦听 ODBC 连接的端口号。例如，5433。

   • ConnSettings — 可以包含用分号分隔的 SQL 命令。这些命令可以在连接到服务器之后立即运行。

   • SSLKeyFile — 客户端私钥的文件路径和名称。此文件可以驻留在系统上的任意位置。

   • SSLCertFile — 客户端公用证书的文件路径和名称。此文件可以驻留在系统上的任意位置。

   • Locale — 用于会话的默认区域设置。默认情况下，数据库的区域设置是：en_US@collation=binary (English as in the United States of America)。将区域设置指定为 ICU 区域设置。有关可用于指定区域设置的完整参数列表，请参阅 ICU 用户指南 (http://userguide.icu-project.org/locale)。

   • PreferredAddressFamily：

     如果客户端和服务器都有 IPv4 和 IPv6 地址而且您已经提供了主机名时要使用的 IP 版本，则使用的 IP 版本是以下之一：

     • ipv4：使用 IPv4 连接到服务器。

     • ipv6：使用 IPv6 连接到服务器。

     • none：使用 DNS 服务器提供的 IP 地址。

例如：

[VMart]
Description = Vmart Database
Driver = /opt/vertica/lib64/libverticaodbc.so
Database = vmartdb
Servername = host01
UID = dbadmin
PWD =
Port = 5433
ConnSettings =
AutoCommit = 0
SSLKeyFile = /home/dbadmin/client.key
SSLCertFile = /home/dbadmin/client.crt
Locale = en_US@collation=binary

有关包括 Vertica 特定参数的完整参数列表，请参阅 ODBC DSN 连接属性。

使用 odbcinst.ini 文件

您可以使用在 odbcinst.ini 文件中定义的驱动程序的名称，而不必在 DSN 定义中指定 ODBC 驱动程序库的路径。如果您有许多 DSN 并且经常需要更新这些 DSN 以指向新的驱动程序库，则此方法很有用。使用此方法，您还可以设置一些其他 ODBC 参数，例如线程模型。

与 odbc.ini 文件一样，odbcinst.ini 文件中也包含一些节。每个节定义了可在 odbc.ini 文件中引用的 ODBC 驱动程序。

在一个节中，您可以定义以下参数：

• Description — 有关数据源的附加信息。

• Driver — Vertica ODBC 驱动程序的位置和指定，例如 /opt/vertica/lib64/libverticaodbc.so

例如：

[Vertica]
Description = Vertica ODBC Driver
Driver = /opt/vertica/lib64/libverticaodbc.so

然后，在 odbc.ini 文件中，您可以使用已在 odbcinst.ini 文件中创建的节（描述了要使用的驱动程序）的名称。例如：

[VMart]
Description = Vertica Vmart database
Driver = Vertica

如果使用的是 unixODBC 驱动程序管理器，您还应添加一个 ODBC 节以替代其标准线程设置。默认情况下，unixODBC 通过 ODBC 将所有 SQL 调用序列化，这样可以阻止多个并行加载。若要更改其默认行为，请将以下行添加到 odbcinst.ini 文件中：

[ODBC]
Threading = 1

配置其他 ODBC 设置

在 Linux 和 UNIX 系统上，您需要先配置一些其他驱动程序设置，然后才能使用 DSN。有关详细信息，请参阅ODBC 驱动程序设置。

2.1.4.4.1.1 - 使用 isql 测试 ODBC DSN

unixODBC 驱动程序管理器包含一个名为 isql 的实用程序，此实用程序是一个简单的 ODBC 命令行客户端。使用此实用程序，您可以连接到 DSN 以发送命令和接收结果，类似于 vsql。

若要使用 isql 测试 DSN 连接，请执行下列操作：

1. 运行以下命令：

   $ isql –v DSNname
   

   其中 DSNname 是已创建的 DSN 的名称。

   此时将显示连接消息和 SQL 提示。如果它们未显示，则可能表明存在配置问题，或者可能表明所使用的用户名或密码不正确。

2. 尝试执行简单 SQL 语句。例如：

   SQL> SELECT table_name FROM tables;
   

   isql 工具将返回 SQL 语句的结果。

2.1.4.4.2 - 为 Windows 客户端创建 ODBC DSN

若要为 Microsoft Windows 客户端创建 DSN，您必须执行以下任务：

2.1.4.4.2.1 - 设置 ODBC DSN

数据源名称 (DSN) 是 ODBC 逻辑名称，用来表示驱动程序和访问数据源中的数据所需的其他信息。此名称由 Internet 信息服务 (Internet Information Services, IIS) 用于与 ODBC 数据源的连接。

此部分介绍如何使用 Vertica ODBC 驱动程序设置 ODBC DSN。本主题假设您已按照在 Windows 中安装客户端驱动程序中所述安装了驱动程序。

设置 DSN

1. 打开 ODBC 管理器。例如，可以导航到“开始 > 控制面板 > 管理工具 (Administration Tools) > 数据源 (ODBC)”。

   注意

   用于打开 ODBC 管理器的方法取决于 Windows 版本。Windows 版本之间的差异和开始菜单 自定义可能要求执行不同的操作以打开 ODBC 管理器。

2. 确定是否希望客户端系统上的所有用户都能访问 Vertica 数据库的 DSN。

   • 如果想让所有用户都可访问，则单击系统 DSN (System DSN) 选项卡。

   • 否则，单击用户 DSN 选项卡以创建仅供您的 Windows 用户帐户使用的 DSN。

3. 单击添加 (Add) 以创建用于连接到 Vertica 数据库的新的 DSN。

4. 滚动浏览“创建新数据源 (Create a New Data Source)”对话框中的驱动程序列表以查找 Vertica 驱动程序。选择该驱动程序，然后单击完成。

   注意

   如果在 Windows 客户端系统上安装了多个版本的 Vertica 客户端驱动程序，您可能会在此列表中看到该驱动程序的多个版本。选择您知道与客户端应用程序和 Vertica 分析数据库服务器兼容的版本。如果不确定，可以使用最新版本的驱动程序。

   此时将显示 Vertica ODBC DSN 配置对话框。

5. 单击更多 >>> (More >>>) 按钮，以查看正在编辑的字段和由 DSN 定义的连接字符串的描述。

6. 输入 DSN 的信息。以下字段是必填的：

   • DSN 名称 — DSN 的名称。客户端使用此名称来标识要连接到的 DSN。DSN 名称必须满足以下要求：

     • 最大长度为 32 个字符。

     • 它由 ASCII 字符组成，但以下字符除外： { } , ; ? * = ! @ \

     • 它不包含空格。

   • 服务器 — 要连接到的 Vertica 服务器的主机名或 IP 地址。如果 Vertica 已安装在同一台计算机上，则使用 localhost。

     您可以提供 IPv4 地址、IPv6 地址或主机名。

     在 IPv4/IPv6 混合网络中，DNS 服务器配置决定了哪个 IP 版本地址最先发送。可使用 PreferredAddressFamily 选项来强制连接使用 IPv4 或 IPv6。

     PreferredAddressFamily 选项在“客户端设置”选项卡上可用。

   • 备份服务器 — 用于在“服务器”字段中指定的服务器已关闭时连接到的主机名或 IP 地址的逗号分隔列表。可选。

   • 数据库 — Vertica 数据库的名称。

   • 用户名 — 在连接到数据库时使用的用户帐户的名称。在连接到 DSN 时，如果应用程序不提供自己的用户名，则会使用此帐户名称登录到数据库。

   其余字段是可选的。有关可以定义的 DSN 参数的详细信息，请参阅 DSN 参数。

7. 如果要测试连接，请执行下列操作：

   1. 至少输入有效的 DSN 名称、服务器名称、数据库，并输入用户名 或选择 Windows 身份验证。

   2. 如果未选择 Windows 身份验证，您可以在密码 框中输入密码。或者，您也可以选择密码提示，以让驱动程序在连接时提示您输入密码。

   3. 单击测试连接。

8. 完成编辑和测试 DSN 后，单击确定。Vertica ODBC DSN 配置窗口将关闭，并且新的 DSN 会在“ODBC 数据源管理器”窗口中列出。

9. 单击确定 (OK) 以关闭 ODBC 数据源管理器。

创建 DSN 后，您可以使用 Microsoft Excel 2007 进行测试。

在 64 位版本的 Microsoft Windows 上设置 32 位 DSN

在 64 位版本的 Windows 上，ODBC 数据源管理器在默认情况下会创建并编辑与 64 位 Vertica ODBC 库关联的 DSN。

尝试将这些 64 位 DSN 与 32 位客户端应用程序结合使用会生成架构不匹配错误。相反，您必须通过运行 32 位 ODBC 管理器为 32 位客户端创建特定的 32 位 DSN，该管理器通常位于以下位置：

c:\Windows\SysWOW64\odbcad32.exe

此管理器窗口可用于编辑与 32 位 ODBC 库关联的一组 DSN。使用此版本的 ODBC 管理器创建的 DSN 可与 32 位客户端应用程序结合使用。

2.1.4.4.2.2 - ODBC DSN 的密码加密

当您安装 ODBC 驱动程序并创建数据源名称 (DSN) 时，DSN 设置（其中包括）将存储在注册表中。ODBC DSN 的密码加密仅适用于 Windows 系统。

对 ODBC 数据源名称 (DSN) 的密码进行加密，可防止未经授权的数据库访问。密码默认不加密，以纯文本形式存储。

启用密码加密

使用 EncryptPassword 参数，可为 ODBC DSN 启用或禁用密码加密：

• EncryptPassword = true 启用密码加密

• EncryptPassword = false （默认）禁用密码加密

在 Windows 注册表中设置 EncryptPassword - HKEY_LOCAL_MACHINE > Software > Vertica > ODBC > Driver EncryptPassword=<true/false>。

加密密码在以下注册表位置更新：

对于用户 DSN：

HKEY_CURRENT_USER-> Software -> ODBC -> ODBC.INI -> DSNNAME -> PWD

对于系统 DSN：

HKEY_LOCAL_MACHINE-> Software -> ODBC -> ODBC.INI -> DSNNAME -> PWD

验证密码加密

使用 Windows 注册表编辑器，根据 EncryptPassword 的值确定是否已启用密码加密。根据您安装的 DSN 类型，检查以下内容：

对于用户 DSN： HKEY_CURRENT_USER > Software > ODBC > ODBC.INI > dsn name > isPasswordEncrypted=<1/0>

对于系统 DSN： HKEY_LOCAL_MACHINE > Software > ODBC > ODBC.INI > dsn name > isPasswordEncrypted=<1/0>

对于每个 DSN，isPasswordEncrypted 参数值表示密码加密的状态。其中，1 表示密码已加密，0 表示密码未加密。

2.1.4.4.2.3 - 使用 Excel 测试 ODBC DSN

可以使用 Microsoft Excel 验证应用程序是否能够连接到 ODBC 数据源或其他 ODBC 应用程序。

1. 打开 Microsoft Excel，然后选择数据 (Data) > 获取外部数据 (Get External Data) > 来自其他来源 (From Other Sources) > 来自 Microsoft Query (From Microsoft Query)。

2. 当“选择数据源 (Choose Data Source)”对话框打开之后：

   1. 请选择新建数据源 (New Data Source)，然后单击确定 (OK)。

      1. 输入数据源的名称。

      2. 选择 Vertica 驱动程序。

      3. 单击连接。

3. 当“Vertica 连接对话框 (Vertica Connection Dialog)”打开之后，输入 DSN 的连接信息，然后单击确定 (OK)。

4. 在“创建新数据源”对话框上单击确定，以返回到“选择数据源”对话框。

5. 选择“VMart_Schema*”，并验证是否已取消选中“使用查询向导 (Use the Query Wizard)”复选框。单击确定 (OK)。

6. 当“添加表”对话框打开后，单击关闭。

7. 当“Microsoft 查询 (Microsoft Query)”窗口打开之后，单击 SQL 按钮。

8. 在“SQL”窗口中，编写任意简单查询以测试连接。例如：

   SELECT DISTINCT calendar_year FROM date_dimension;
   

9. *如果您看到提醒“SQL Query 无法以图形表示。是否继续？(SQL Query can't be represented graphically. Continue anyway?)”，请单击**确定 (OK)**。      *数据值 2003、2004、2005、2006、2007 表示已成功连接到 ODBC，并通过 ODBC 执行了查询。
   

10. 选择文件 (File) > 将数据返回到 Microsoft Office Excel (Return Data to Microsoft Office Excel)。

11. 在“导入数据”对话框中，单击确定。

    数据当前在 Excel 工作表中可用。

2.1.4.4.3 - 为 macOS 客户端创建 ODBC DSN

可以使用 Vertica ODBC 驱动程序设置 ODBC DSN。此过程假设您已按照安装 ODBC 客户端驱动程序中所述安装了驱动程序。

设置 DSN

1. 使用 Web 浏览器下载并安装 Apple ODBC Administrator Tool。

2. 安装之后，找到并打开 ODBC 管理员工具：

   1. 导航至 Finder (查找器) > 应用程序 (Applications) > 实用程序 (Utilities)。

   2. 打开 ODBC 管理员工具。

3. 单击驱动程序 (Drivers) 选项卡，然后验证是否已安装 Vertica 驱动程序。
   

4. 指定是否希望客户端系统上的所有用户都能访问 Vertica 数据库的 DSN：

   • 如果想让所有用户都可访问，则单击系统 DSN (System DSN) 选项卡。

   • 否则，单击用户 DSN (User DSN) 选项卡以创建仅供您的 Macintosh 用户帐户使用的 DSN。

5. 单击添加... (Add...) 创建用于连接到 Vertica 数据库的新的 DSN。

6. 滚动浏览“选择驱动程序 (Choose A Driver)”对话框中的驱动程序列表以查找 Vertica 驱动程序。选择该驱动程序，然后单击确定 (OK)。此时将打开一个对话框，请求提供 DSN 参数信息。

7. 在对话框中，输入数据源名称 (DSN) 和可选的 描述 (Description)。为此，请单击 添加 (Add) 以插入关键字（参数）和定义连接到数据库所需设置的值，其中包括数据库名称、服务器主机、数据库用户名（例如 dbaadmin）、数据库密码和端口。然后单击确定 (OK).

8. 在“ODBC Administrator”对话框中，单击应用 (Apply)。

   有关包括 Vertica 特定参数的完整参数列表，请参阅 ODBC DSN 连接属性。

配置 ODBC 管理员工具之后，您可能需要配置其他驱动程序设置才能使用 DSN，具体取决于环境。有关详细信息，请参阅其他 ODBC 驱动程序配置设置。

2.1.4.4.3.1 - 使用 iodbctest 测试 ODBC DSN

Mac OS X 上的标准 iODBC 驱动程序管理器包含一个名为 iodbctest 的实用程序，您可以使用此实用程序测试 DSN，以验证该 DSN 是否配置正确。应向此命令传递与用于打开 ODBC 数据库连接的连接字符串格式相同的连接字符串。配置 DSN 连接之后，您可以运行查询以验证该连接是否正常工作。

例如：

# iodbctest "DSN=VerticaDSN;UID=dbadmin;PWD=password"
iODBC Demonstration program
This program shows an interactive SQL processor
Driver Manager: 03.52.0607.1008
Driver: 07.01.0200 (verticaodbcw.so)
SQL> SELECT table_name FROM tables;
table_name
--------------------------------------------------------------------------------------------------------------------------------
customer_dimension
product_dimension
promotion_dimension
date_dimension
vendor_dimension
employee_dimension
shipping_dimension
warehouse_dimension
inventory_fact
store_dimension
store_sales_fact
store_orders_fact
online_page_dimension
call_center_dimension
online_sales_fact
numbers
result set 1 returned 16 rows.

2.1.4.4.4 - ODBC DSN 连接属性

下表列出了可以在 DSN 中设置以与 Vertica ODBC 驱动程序结合使用的连接属性。要设置这些参数，请参阅 设置 DSN 连接属性。

所需的连接属性

若要创建正常工作的 DSN，您至少需要设置这些连接属性。

可选属性

高级设置

标识

OAuth 连接属性

以下连接属性与 ODBC 中的 OAuth 相关。

加密

第三方兼容性

Kerberos 连接属性

可以将以下属性用于使用 Kerberos 的客户端身份验证。

另请参阅

2.1.4.4.5 - 设置 DSN 连接属性

以下表中的属性是所有用户 DSN 条目和所有系统 DSN 条目共用的。所提供的示例适用于 Windows 客户端。

要编辑 DSN 属性：

• 在 UNIX 和 Linux 客户端平台上，您可以编辑 odbc.ini 文件。此文件的位置特定于驱动程序管理器。请参阅为 Linux 创建 ODBC DSN。

• 在 Windows 客户端平台上，您可以使用 Vertica ODBC 客户端驱动程序界面编辑部分 DSN 属性。请参阅为 Windows 客户端创建 ODBC DSN。

• 您也可以直接编辑 DSN 属性，方法是在 Windows 注册表中（例如在 HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\\DSNname 中）打开 DSN 条目。直接编辑注册表会带来风险，因此，只应对无法通过 ODBC 驱动程序用户界面或客户端代码进行设置的属性使用此方法。

• 当使用 SQLDriverConnect() 函数打开连接时，您可以在连接字符串中设置属性：

  sqlRet = SQLDriverConnect(sql_hDBC, 0, (SQLCHAR*)"DSN=DSNName;Locale=en_GB@collation=binary", SQL_NTS, szDNS, 1024,&nSize, SQL_DRIVER_NOPROMPT);
  

  注意

  在连接字符串中，“;”是预留符号。如果需要设置多个属性作为 ConnSettings 属性的一部分，请使用“%3B”来替代“;”，并使用“+”来替代空格。

  例如：

  sqlRet = SQLDriverConnect(sql_hDBC, 0, (SQLCHAR*)"DSN=Vertica SQL;ConnSettings=set+search_path+to+a,b,c%3Bset+locale=ch;SSLMode=prefer", SQL_NTS,
  szDNS, 1024,&nSize, SQL_DRIVER_NOPROMPT);
  

• 已使用 SQLGetConnectAttr() 和 SQLGetStmtAttr() API 调用建立与 Vertica 的连接后，客户端代码可以检索 DSN 属性值。可以使用 SQLSetConnectAttr() 和 SQLSetStmtAttr() 设置部分属性。

  有关特定于 Vertica 的属性的列表，请参阅特定于 Vertica 的 ODBC 头文件。

2.1.4.5 - ODBC 驱动程序设置

• DriverManagerEncoding：驱动程序管理器使用的 UTF 编码标准。可以是以下内容之一：

  • UTF-8

  • UTF-16

  • UTF-32

  ODBC 驱动程序编码必须与驱动程序管理器的编码相匹配。下表列出了不设置该参数时生效的各种平台的默认编码。如果默认值与驱动程序管理器使用的编码不匹配，则必须进行手动设置。有关驱动程序管理器编码的详细信息，请参阅驱动程序管理器文档。

  注意

  虽然 UTF-16 和 UTF-8 都是 DataDirect 驱动程序管理器的有效设置，但建议使用 UTF-16。

• ErrorMessagesPath：必需，包含 ODBC 驱动程序的错误消息文件的目录路径。这些文件（ODBCMessages.xml 和 VerticaMessages.xml）存储在 Vertica ODBC 驱动程序文件所在的目录（例如，已下载的 .tar 所在的 opt/vertica/en-US）中。

• ODBCInstLib：ODBC 安装程序库的路径。只有当未在 LD_LIBRARY_PATH 或 LIB_PATH 环境变量中设置包含该库的目录时，才需要此设置。主要驱动程序管理器的库文件如下：

  • UnixODBC： libodbcinst.so

  • iODBC： libiodbcinst.so （在 macOS 上为 libiodbcinst.2.dylib）

  • DataDirect： libodbcinst.so

您还可以控制 ODBC 和 ADO.NET 的客户端-服务器消息日志记录。有关详细信息，请参阅配置 ODBC 日志。

Linux 和 macOS

要在 Linux 或 macOS 上设置这些参数：

1. 在客户端系统的任何位置创建文件 vertica.ini。公共位置在共享配置的 /etc/ 中，或者在每个用户配置的主目录中。

2. 验证 ODBC 驱动程序的用户是否具有文件的读取权限。

3. 将 VERTICAINI 环境变量设置为 vertica.ini 的路径。例如：

   $ export VERTICAINI=/etc/vertica.ini
   

4. 在 vertica.ini 中创建名为 [Driver] 的部分：

   [Driver]
   

5. 在 [Driver] 下，按如下格式设置参数。每个参数必须有其自己的行：

   [Driver]
   DriverManagerEncoding=UTF-16
   ODBCInstLib=/usr/lib64/libodbcinst.so
   

Windows

Windows 客户端驱动程序安装程序自动为 ODBC 驱动程序配置所有必要的设置。设置存储在注册表中的 HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\ODBC\Driver 下。

如果要进一步配置 ODBC，请使用 ODBC 数据源 程序。

2.1.4.6 - 配置 ODBC 日志

以下参数控制 ODBC 客户端驱动程序是否以及如何记录客户端和服务器之间的消息。

设置这些参数的方式因操作系统不同而异：

• 在 Linux 和 macOS 上，编辑您在安装期间创建的 vertica.ini。例如，要将所有警告和更严重的消息记录到 /tmp/ 中的日志文件：

  [Driver]
  LogLevel=4
  LogPath=/tmp
  

• 在 Windows 上的 Windows 注册表中，编辑 HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\ODBC\Driver 下面的键。

参数

• LogLevel：在客户端和服务器之间记录的消息的严重性。有效值包括：

  • 0：无日志记录

  • 1：严重错误

  • 2：错误

  • 3：警告

  • 4：信息

  • 5：Debug

  • 6：跟踪（所有消息）

  为此设置指定的值设置了要记录的消息的最低严重性。例如，如果将 LogLevel 设置为 3，则表示客户端驱动程序将记录所有警告、错误和严重错误。

• LogPath：用于存储日志文件的目录的绝对路径。例如： /var/log/verticaodbc

将日志条目转移到 ETW (Windows)

在 Windows 客户端上，可以将 ODBC 日志条目发送到 Windows 事件跟踪 (ETW)，以便它们显示在 Windows 事件查看器中：

• 将驱动程序注册为 Windows 事件日志提供程序，并启用日志。

• 通过将带有数据 ETW 的字符串值 LogType 添加到 Windows 注册表来激活 ETW。

• 了解 Vertica 如何压缩 Windows 事件查看器的日志级别。

• 了解在事件查看器中的何处可以找到日志。

• 了解日志条目中事件 ID 的含义。

将 ODBC 驱动程序注册为 Windows 事件日志提供程序

要使用 ETW 日志记录，必须将 ODBC 驱动程序注册为 Windows 事件日志提供程序。您可以选择注册 32 位或 64 位驱动程序。注册驱动程序后，必须启用日志。

1. 以管理员身份打开命令提示符窗口，或使用“以管理员身份运行 (Run as Administrator)”选项启动命令提示符。

   重要

   您必须具有管理员权限才能成功完成下一步。

2. 运行命令 wevtutil im 以注册 32 位或 64 位版本的驱动程序。

   • 对于 64 位 ODBC 驱动程序，运行：

     wevtutil im "c:\Program Files\Vertica Systems\ODBC64\lib\VerticaODBC64.man"
     /resourceFilePath:"c:\Program Files\Vertica Systems\ODBC64\lib\vertica_9.1_odbc_3.5.dll"
     /messageFilePath:"c:\Program Files\Vertica Systems\ODBC64\lib\vertica_9.1_odbc_3.5.dll"
     

   • 对于 32 位 ODBC 驱动程序，运行：

     wevtutil im "c:\Program Files (x86)\Vertica Systems\ODBC32\lib\VerticaODBC32.man"
     /resourceFilePath:"c:\Program Files (x86)\Vertica Systems\ODBC32\lib\vertica_9.1_odbc_3.5.dll"
     /messageFilePath:"c:\Program Files (x86)\Vertica Systems\ODBC32\lib\vertica_9.1_odbc_3.5.dll"
     

3. 运行命令 wevtutil sl 以启用日志。

   • 对于 64 位 ODBC 驱动程序日志，运行：

     wevtutil sl VerticaODBC64/e:true
     

   • 对于 32 位 ODBC 驱动程序日志，运行：

     wevtutil sl VerticaODBC32/e:true
     

   注意

   如果您想稍后禁用日志，则可以使用相同的 wevtutil sl 命令，在发出语句时用 /e:false 代替 /e:true。或者，您可以在 Windows 事件查看器本身中启用或禁用日志。

添加字符串值 LogType

默认情况下，Vertica 不会将 ODBC 日志条目发送到 ETW。要激活 ETW，请将字符串 LogType 添加到 Windows 注册表，并将其值设置为 ETW。

1. 通过在 Windows“运行 (Run)”命令框中键入 regedit.exe 来启动注册表编辑器。

2. 导航到注册表中的 HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\ODBC\Driver。

3. 在注册表编辑器 (Registry Editor) 窗口的右窗格中右键单击。

4. 选择新建 (New)，然后选择字符串值 (String Value)。

5. 将字符串值的名称从 New Value #1 更改为 LogType。

6. 双击新的 LogType 条目。当系统提示输入新值时，输入 ETW。

7. 退出注册表编辑器。

默认情况下，禁用 ETW。启用 ETW 后，您可以通过从 LogType 字符串中清除值 ETW 来禁用它。

虽然 LogLevel 的范围从 0 到 6，但对于 Windows 事件查看器，此范围被压缩到 0 到 3 的范围。

以下示例显示了在 Windows 事件查看器中显示时如何转换 LogLevel。

• LogLevel 为 5 将致命错误、错误、警告、信息和调试日志级别条目作为级别 4（信息）发送到事件查看器。

• LogLevel 为 6 将致命错误、错误、警告、调试和跟踪日志级别条目作为级别 4 发送到事件查看器。

在事件查看器中查找日志

1. 启动 Windows 事件查看器。

2. 从事件查看器(本地) (Event Viewer (Local))，展开应用程序和服务日志 (Applications and Services Logs)。

3. 展开包含您要查看的日志的文件夹（例如 VerticaODBC64）。

4. 选择文件夹下的 Vertica ODBC 日志。条目出现在右窗格中。

5. 请注意事件 ID (Event ID) 字段中的值。每个事件日志条目包含四个事件 ID 之一：

   • 0：信息性（调试、信息和跟踪事件）

   • 1：错误

   • 2：严重事件

   • 3：警告

2.1.5 - Python 客户端驱动程序

Vertica 支持多个用于创建客户端应用程序的 Python 驱动程序。

先决条件

要创建 Python 客户端应用程序，您必须安装所需的驱动程序。

2.1.5.1 - 安装 Python 客户端驱动程序

Vertica 支持多个 Python 客户端驱动程序。

安装 Vertica-Python

有关安装和使用说明，请参阅 Vertica-Python 存储库。

安装 Pyodbc

Pyodbc 模块与 Vertica ODBC 客户端驱动程序交互。要安装它：

1. 安装 ODBC 客户端驱动程序。

2. 安装兼容版本的 Python 和 Pyodbc。

2.1.6 - Node.js 客户端驱动程序

开源 vertica-nodejs 客户端驱动程序允许您使用 JavaScript 与数据库交互。有关详细信息，请参阅 npm 上的 vertica-nodejs 包。

2.1.7 - OLE DB 客户端驱动程序

OLE DB 客户端驱动程序是 Microsoft Analysis Services (SSAS) 和 C# 客户端应用程序与 Vertica 数据库交互的接口。

2.1.7.1 - 安装 OLE DB 客户端驱动程序

要安装 Vertica OLE DB 客户端驱动程序：

1. 下载 Windows 客户端驱动安装程序。有关此安装程序中包含的驱动程序的详细信息，请参阅 Windows 客户端驱动程序安装程序。

2. 运行安装程序并按照提示安装驱动程序。

3. 重新启动系统。

安装 OLE DB 客户端驱动程序后，您可以配置 ETW 日志记录。

有关 OLE DB 客户端驱动程序如何与其他 Microsoft 组件集成的详细信息，请参阅 Microsoft 组件配置。

有关连接属性的列表，请参阅 OLE DB 连接属性。

2.1.7.1.1 - OLE DB 连接属性

可以使用“连接管理器 (Connection Manager)”设置 OLE DB 连接字符串属性，这些属性定义了连接。可以从 Visual Studio 中访问“连接管理器 (Connection Manager)”。

这些连接参数会显示在“连接 (Connection)”页面上。

连接管理器 (Connection Manager) 对话框中的 全部 (All) 页面列出了提供程序的所有可能的连接字符串属性。

下表列出了全部 (All) 页面中的连接参数。

有关特定于 Microsoft 的 OLE DB 属性，请参阅 Microsoft 文档 [OLE DB Properties](https://msdn.microsoft.com/en-us/library/windows/desktop/ms723130(v=vs.85)。

2.1.7.1.2 - 配置 OLE DB 日志

以下参数控制 OLE DB 客户端驱动程序如何记录客户端和服务器之间的消息。要设置它们，请编辑 Windows 注册表中 HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\OLEDB\Driver 下的密钥：

• LogLevel：在客户端和服务器之间记录的消息的严重性。有效值包括：

  • 0：无日志记录

  • 1：严重错误

  • 2：错误

  • 3：警告

  • 4：信息

  • 5：调试

  • 6：跟踪（所有消息）

  为此设置指定的值设置了要记录的消息的最低严重性。例如，如果将 LogLevel 设置为 3，则表示客户端驱动程序将记录所有警告、错误和严重错误。

• LogPath：用于存储日志文件的目录的绝对路径。例如： /var/log/verticaoledb

将 OLE DB 日志条目转移到 ETW

在 Windows 客户端上，您可以指示 Vertica 将 OLE DB 日志条目发送到 Windows 事件跟踪 (ETW)。设置后，OLE DB 日志条目将出现在 Windows 事件查看器中。要使用 ETW：

• 将驱动程序注册为 Windows 事件日志提供程序，并启用日志。

• 通过将字符串值添加到 Windows 注册表来激活 ETW。

• 了解 Vertica 如何压缩 Windows 事件查看器的日志级别。

• 了解在事件查看器中的何处可以找到日志。

• 了解日志条目中事件 ID 的含义。

将 OLE DB 驱动程序注册为 Windows 事件日志提供程序

要使用 ETW 日志记录，您必须将 OLE DB 驱动程序注册为 Windows 事件日志提供程序。您可以选择注册 32 位或 64 位驱动程序。注册驱动程序后，您必须启用日志。

1. 以管理员身份打开命令提示符窗口，或使用“以管理员身份运行 (Run as Administrator)”选项启动命令提示符。

   重要

   您必须具有管理员权限才能成功完成下一步。

2. 运行命令 wevtutil im 以注册 32 位或 64 位版本的驱动程序。

   1. 对于 64 位 OLE DB 驱动程序，运行：

      wevtutil im "c:\Program Files\Vertica Systems\OLEDB64\lib\VerticaOLEDB64.man"
      /resourceFilePath:"c:\Program Files\Vertica Systems\OLEDB64\lib\vertica_8.1_oledb.dll"
      /messageFilePath:"c:\Program Files\Vertica Systems\OLEDB64\lib\vertica_8.1_oledb.dll"
      

   2. 对于 32 位 OLE DB 驱动程序，运行：

      wevtutil im "c:\Program Files (x86)\Vertica Systems\OLEDB32\lib\VerticaOLEDB32.man"
      /resourceFilePath:"c:\Program Files (x86)\Vertica Systems\OLEDB32\lib\vertica_8.1_oledb.dll"
      /messageFilePath:"c:\Program Files (x86)\Vertica Systems\OLEDB32\lib\vertica_8.1_oledb.dll"
      

3. 运行命令 wevtutil sl 以启用日志。

   1. 对于 64 位 OLE DB 驱动程序日志，运行：

      wevtutil sl VerticaOLEDB64/e:true
      

   2. 对于 32 位 ODBC 驱动程序日志，运行：

      wevtutil sl VerticaOLEDB32/e:true
      

   注意

   如果您想稍后禁用日志，则可以使用相同的 wevtutil sl 命令，在发出语句时用 /e:false 代替 /e:true。或者，您可以在 Windows 事件查看器本身中启用或禁用日志。

添加字符串值 LogType

默认情况下，Vertica 不会将 OLE DB 日志条目发送到 ETW。要激活 ETW，请将字符串 LogType 添加到 Windows 注册表，并将其值设置为 ETW。

1. 通过在 Windows“运行 (Run)”命令框中键入 regedit.exe 来启动注册表编辑器。

2. 在注册表中，导航到：HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\OLEDB\Driver。

3. 在注册表编辑器 (Registry Editor) 窗口的右窗格中右键单击。

4. 选择新建 (New)，然后选择字符串值 (String Value)。

5. 将字符串值的名称从 New Value #1 更改为 LogType。

6. 双击新的 LogType 条目。当系统提示输入新值时，输入 ETW。

7. 退出注册表编辑器。

默认情况下，ETW 设置为 off。激活 ETW 后，您可以稍后通过从 LogType 字符串中清除值 ETW 将其关闭。

虽然 LogLevel 的范围从 0 到 6，但对于 Windows 事件查看器，此范围被压缩到 0 到 3 的范围。

以下示例显示了在 Windows 事件查看器中显示时如何转换 LogLevel。

• LogLevel 为 5 将致命错误、错误、警告、信息和调试日志级别条目作为级别 4（信息）发送到事件查看器。

• LogLevel 为 6 将致命错误、错误、警告、调试和跟踪日志级别条目作为级别 4 发送到事件查看器。

在事件查看器中查找日志

1. 启动 Windows 事件查看器。

2. 从事件查看器(本地) (Event Viewer (Local))，展开应用程序和服务日志 (Applications and Services Logs)。

3. 展开包含您要查看的日志的文件夹（例如 VerticaOLEDB64）。

4. 选择文件夹下的 Vertica ODBC 日志。条目出现在右窗格中。

5. 请注意事件 ID (Event ID) 字段中的值。每个事件日志条目包含四个事件 ID 之一：

   • 0：信息性（调试、信息和跟踪事件）

   • 1：错误

   • 2：严重事件

   • 3：警告

2.1.7.2 - 适用于 Windows 的 Microsoft Connectivity Pack

适用于 Windows 的 Vertica Microsoft Connectivity Pack 提供了一个用于访问 Microsoft Business Intelligence 工具的配置文件。Connectivity Pack 作为 Windows 客户端驱动程序和工具的一部分安装。

有关 Microsoft Connectivity Pack 中包含的组件的详细信息，请参阅 Microsoft 组件。

2.1.7.2.1 - Microsoft 组件

本节介绍可与 Microsoft Visual Studio 和 Microsoft SQL Server 结合使用的 Microsoft Business Intelligence 组件。配置后，您可以使用这些 Microsoft 组件来开发使用 Vertica 服务器的业务解决方案。

2.1.7.2.1.1 - Microsoft 组件配置

使用 Vertica ADO.NET 驱动程序、Visual Studio 插件和 OLE DB 驱动程序，您可以将 Vertica 服务器与包含先前已安装在系统上的 Microsoft 组件的环境集成。还有其他工具可用于与 Microsoft SQL Server 集成。

可用的驱动程序提供了与以下 Microsoft 组件的集成：

• 适用于 Visual Studio 2008 的 Business Intelligence Development Studio (BIDS)，与 SQL Server 2012 结合使用。BIDS 是一个基于客户端的应用程序，用于开发基于 Microsoft Visual Studio 开发环境的商业智能解决方案。此应用程序包含其他特定于 SQL Server Business Intelligence 的项目类型。作为开发人员，您可以使用 BIDS 开发业务解决方案。

• 适用于 Visual Studio 2008/2010/2012/2013/2015 的 SQL Server Data Tools - Business Intelligence (SSDT-BI)，与 SQL Server 2012、SQL Server 2014 和 SQL Server 2016 结合使用。SSDT-BI 取代适用于 Visual Studio 2008、Visual Studio 2010、Visual Studio 2012、Visual Studio 2013 和 Visual Studio 2015 的 BIDS。此组件的用途与 BIDS 相同，即提供用于开发商业智能解决方案的开发环境。

• 适用于 SQL Server 2012、SQL Server 2014 和 SQL Server 2016 的 SQL Server Analysis Services (SSAS)。可以使用 SSAS 进行 OLAP 和数据挖掘，同时使用 Vertica 作为多维数据集创建的源。

• 适用于 SQL Server 2012、SQL Server 2014 和 SQL Server 2016 的 SQL Server Integration Services (SSIS)。SSIS 提供了 SQL Server 类型映射，用于在 Vertica 和 SQL Server 之间映射数据类型。可以将 SSIS 用于数据迁移、数据集成和工作流以及 ETL。

下图显示了 Microsoft 组件和 Vertica 依赖项之间的关系。

2.1.7.2.1.2 - BIDS 和 SSDT-BI

Microsoft Visual Studio 2008 中提供 Business Intelligence Development Studio (BIDS) 和其他特定于 SQL Server Business Intelligence 的项目类型。BIDS 是用于开发包括分析服务、集成服务和报告服务项目在内的业务解决方案的主要环境。

SQL Server Data Tools - Business Intelligence (SSDT-BI) 取代适用于 Visual Studio 2010、2012、2013 和 2015 的 BIDS。此组件的用途与 BIDS 相同，即提供用于开发业务解决方案的开发环境。

BIDS 和 SSDT-BI 都是基于客户端的应用程序，并且都包含其他特定于 SQL Server Business Intelligence 的项目类型。

可以使用 Visual Studio Shell 集成插件从 Visual Studio Server Explorer 中浏览数据库。使用此功能，您可以在 BIDS 或 SSDT-BI 开发环境外部工作，以执行诸如列出表或插入数据等任务。在 BIDS 或 SSDT-BI 模式下使用 Visual Studio 时，您可以使用 Vertica 数据库中的数据开发业务解决方案。例如，您可以创建多维数据集或打开表。

Microsoft 不支持以下配置：

• 不能将 Microsoft Visual Studio 2008 与 BIDS 开发环境结合使用以创建 SQL Server 2012 Business Intelligence 解决方案。

• 不能将 Microsoft Visual Studio 2010/2012/2013/2015 与 SSDT-BI 开发环境结合使用以创建 SQL Server 2008 Business Intelligence 解决方案。

2.1.7.2.1.3 - SQL Server Analysis Services (SSAS) 支持

BIDS 或 SSDT-BI 包含 Analysis Services 项目，该项目可用于开发适用于商业智能应用程序的联机分析处理 (Online Analytical Processing, OLAP)。此项目类型包含以下内容的模板：

• 多维数据集

• 维度

• 数据源

• 数据源视图

它还提供处理这些对象的工具。

可以在 OLE DB 连接属性 中找到 OLE DB 连接属性。

2.1.7.2.1.4 - SQL Server Integration Services (SSIS) 支持

BIDS 或 SSDT-BI 包含用于开发 ETL 解决方案的 Integration Services 项目。此项目类型包含以下内容的模板：

• 包

• 数据源

• 数据源视图

它还提供处理这些对象的工具。

通过 SSIS 和导入/导出向导，您可以使用 Vertica 作为数据源和数据目标。必须在集成服务器和 BIDS 工作站或 SSDT-BI 工作站上安装特定于 Vertica 的映射文件才能启用此功能。适用于 Windows 的 Vertica 客户端驱动程序和工具将以 32 位和 64 位版本安装这些映射文件作为“SQL Server 类型映射”组件。

2.1.7.2.1.5 - SQL Server Reporting Services (SSRS) 支持

BIDS 或 SSDT-BI 包含用于开发报表解决方案的报表项目。

可以使用 Vertica 作为 Reporting Services 的数据源。安装程序将实施各种配置文件修改，以在 BIDS 工作站或 SSDT-BI 工作站和 Reporting Services 服务器上启用此功能。

2.1.7.2.2 - 兼容性问题和限制

本节列出兼容性问题以及将 Microsoft Connectivity Pack 与 Microsoft Visual Studio 和 Microsoft SQL Server 集成的限制。

2.1.7.2.2.1 - BIDS 和 SSDT-BI 限制

BIDS 和 SSDT-BI 是适用于 Analysis Services、Integration Services 和 Reporting Services 项目的 32 位开发环境。它们并非设计用于在 64 位 Itanium 架构上运行，因此不会安装在 Itanium 服务器上。

2.1.7.2.2.2 - SSAS 限制

• 不支持 SSAS 表格模型。

• 安装 Vertica OLE DB 驱动程序后，如果 SSAS 多维数据集构建失败，请重新启动 SSAS 服务。

2.1.7.2.2.3 - SSIS 数据类型限制

以下部分介绍了使用 SQL Server Integration Services (SSIS) 时的数据类型限制。

时间数据传输

传输时间数据时，SSIS 使用支持超过六位数精度的 TimeSpan 数据类型。Vertica ADO.NET 驱动程序会将 TimeSpan 转换为最多支持六位数的 Interval 数据类型。传输过程中，Interval 类型不会转换为 TimeSpan 类型。因此，如果时间值的精度超过六位数，则数据会被截断（而不是舍入）。

有关 ADO.NET 数据类型的信息，请参考 ADO.NET 数据类型。

DATE 和 DATETIME 精度

为确保正常运行而不发生错误，DATE 和 DATETIME 的范围介于 0001-01-01 00:00:00.0000000 到 9999-12-31 23:59:59.999999 之间。

在 SSIS 中，DATETIME 类型 (DT_TIMESTAMP) 对秒最多支持三个小数位。系统会自动丢弃后面的小数。只能对介于 January 1, 1753 到 December 31, 9999 之间的 DATETIME 值执行派生列转换。

数值精度

允许的最大和最小十进制值为：

• 最大值： +79,228,162,514,264,337,593,543,950,335

• 最小值： -79,228,162,514,264,337,593,543,950,335

例如，如果位数是 16，值的范围为：

+/- 7,922,816,251,426.4337593543950335

有效位数范围为小于 29 以及大于 38 的任何数字。使用 29 和 38 之间的小数位数不会生成错误。

请参阅：http://msdn.microsoft.com/en-us/library/system.decimal.maxvalue.aspx

不支持的浮点值

SQL Server 不支持 NaN、Infinity 或 –Infinity 值。使用 SSIS 在 Vertica 实例之间进行传输时，可以使用这些值，但这些值不能用于 SQL Server 目标。

字符串转换

在 SSIS 中使用的 CHAR 和 VARCHAR 数据类型为 DT_WSTR，其最大长度是 4000 个字符。

在 SSIS 中，Vertica 字符串会转换为 SSIS 中的 Unicode 字符串，以处理多语言数据。可以使用数据转换任务将这些字符串转换为 ASCII。

标度

只要所使用的小数位数超过 38，SSIS 就会将其替换为值 4。

区间转换

SSIS 不支持间隔类型。它会将这些类型转换为 TIME，并去除日组件。时间间隔类型超过一天的任何包将返回不正确的结果。

SQL Server 导入和导出向导的数据映射问题

使用 SQL Server 导入和导出向导创建集成服务包 (SSIS) 时，某些数据类型无法自动正确映射。将该向导与以下提供程序结合使用时，将出现映射问题：

• 适用于 SQL Server 2008 或 SQL Server 2012 的 SQL Server Native OLE DB 提供程序

• 适用于 SQL Server 2010/2012 的 SQL Server Native Client 10.0/11.0 提供程序

要避免此问题，请使用 BIDS 或 SSDT-BI 手动更改类型映射。

数据传输失败

将集成服务包 (SSIS) 与适用于 SQL Server 2008 或 SQL Server 2012 的 SQL Server OLE DB 提供程序结合使用时，如果是从 Vertica 传输到 SQL Server，则某些数据类型的传输会失败。若要避免此问题，请使用 BIDS 或 SSDT-BI 传输数据。

VARBINARY/LONG VARBINARY 数据类型的批量插入

有时，VARBINARY 或 LONG VARBINARY 数据类型的批量插入的行之一会超过数据类型限制：

• VARBINARY：65 KB

• LONG VARBINARY：32 MB

在这种情况下，将拒绝所有行，而非仅拒绝长度超过类型限制的行。批量插入将失败，并显示消息“行被拒绝 (row(s) are rejected)”。

若要避免此问题，请使用谓词从源中筛选出无法适应接收数据库的行。

SQL Server 查询设计器布尔查询

在 SQL Server 查询设计器中发出布尔查询时，必须用引号将布尔列值括起来。否则，您将收到 SQL 执行错误（例如，someboolean = 'true'）。

2.1.7.2.2.4 - SSRS 限制

数据连接向导解决方法

SSRS 报表向导提供一个数据连接向导。选择该向导并输入所有连接信息后，确定 按钮被禁用。您无法保存工作，也无法继续操作。解决方法是不要使用该向导，并改为使用以下面板：

报表向导 - 查询设计器

Vertica 使用报表向导的通用查询设计器。其他数据源使用支持以可视化方式构建查询的图形查询设计器。图形查询设计器是名为 Visual Data Tools (VDT) 的程序包的一部分。图形查询设计器只能与通用 OLE DB 提供程序和内置提供程序配合工作。您不能将其与 Vertica 数据提供程序结合使用。

报表生成器

Report Builder 是一款基于 Web 的报告设计工具。此工具不支持使用自定义数据扩展来创建报表，因此您不能将其与 Vertica 结合使用。使用报表生成器创建报表时，现有 Vertica 数据源会显示在可用数据源的列表中。但是，选择 Vertica 数据源会导致发生错误。

映射 Vertica ** 目标时未自动提供架构名称**

目前，当您映射 Vertica 目标时，不会自动提供架构名称。您必须手动输入架构名称或从下拉菜单中选择架构名称，如下所示：

2.1.8 - ADO.NET 客户端驱动程序

Vertica ADO.NET 驱动程序允许您使用 C# 访问 Vertica。

2.1.8.1 - 安装 ADO.NET 客户端驱动程序

先决条件

ADO.NET 客户端驱动程序需要以下条件：

• 支持的操作系统。

• 至少 512MB 内存

• .NET Framework 的支持版本。如果您不满足此要求，在大多数情况下，安装程序会主动为您安装。

安装

要安装 ADO.NET 客户端驱动程序：

1. 下载 Windows 客户端驱动安装程序。有关此安装程序中包含的驱动程序的详细信息，请参阅 Windows 客户端驱动程序安装程序。

2. 运行安装程序并按照提示安装驱动程序。

3. 重新启动系统。

2.2 - 升级客户端驱动程序

通常会为 Vertica 服务器的每个新发行版更新 Vertica 客户端驱动程序。客户端驱动程序安装包包含相应 Vertica 服务器发行版的版本号。通常，驱动程序与下一个发行版具有向前兼容性，因此在升级到 Vertica Analytics Platform 服务器的下一个版本之后，客户端应用程序仍能使用较旧版本的驱动程序进行连接。有关哪些客户端驱动程序版本适用于每个 Vertica 服务器版本的详细信息，请参阅客户端驱动程序和服务器版本兼容性。

应在升级服务器之后尽快升级客户端，以利用新功能并保持与服务器的最高兼容性。

若要升级驱动程序，请遵循在最初安装驱动程序时使用的相同过程。新安装将覆盖旧安装。有关升级的任何特别说明，请参阅在客户端平台上安装驱动程序的特定说明。

2.3 - 设置客户端连接标记

连接到 Vertica 数据库时，您可以设置客户端连接标记。您还可以使用 SET_CLIENT_LABEL 函数设置客户端连接标记，或使用 GET_CLIENT_LABEL 函数返回客户端连接标记。

设置客户端连接标记：

=> SELECT SET_CLIENT_LABEL('py_data_load_application');
               SET_CLIENT_LABEL
----------------------------------------------
 client_label set to py_data_load_application
(1 row)

返回当前的客户端连接标记：

=> SELECT GET_CLIENT_LABEL();
     GET_CLIENT_LABEL
--------------------------
 py_data_load_application
(1 row)

JDBC

JDBC 客户端具有用于设置和返回客户端连接标签的方法：getClientInfo() 和 setClientInfo()。这些方法可与 SQL 函数 GET_CLIENT_LABEL 和 SET_CLIENT_LABEL 配合使用。

使用这两种方法时，请确保向 setter 和 getter 方法都传递字符串值 APPLICATIONNAME。

setClientInfo() 用于创建客户端标签，而 getClientInfo() 则用于返回客户端标签：

import java.sql.*;
import java.util.Properties;

public class ClientLabelJDBC {

    public static void main(String[] args) {
        Properties myProp = new Properties();
        myProp.put("user", "dbadmin");
        myProp.put("password", "");
        myProp.put("loginTimeout", "35");
        Connection conn;
        try {
            conn = DriverManager.getConnection(
                    "jdbc:vertica://docc05.verticacorp.com:5433/doccdb", myProp);
            System.out.println("Connected!");
            conn.setClientInfo("APPLICATIONNAME", "JDBC Client - Data Load");
            System.out.println("New Conn label: " + conn.getClientInfo("APPLICATIONNAME"));
            conn.close();
        } catch (SQLTransientConnectionException connException) {
            // There was a potentially temporary network error
            // Could automatically retry a number of times here, but
            // instead just report error and exit.
            System.out.print("Network connection issue: ");
            System.out.print(connException.getMessage());
            System.out.println(" Try again later!");
            return;
        } catch (SQLInvalidAuthorizationSpecException authException) {
            // Either the username or password was wrong
            System.out.print("Could not log into database: ");
            System.out.print(authException.getMessage());
            System.out.println(" Check the login credentials and try again.");
            return;
        } catch (SQLException e) {
            // Catch-all for other exceptions
            e.printStackTrace();
        }
    }
}

运行此方法时，会将以下结果打印到标准输出：

Connected!
New Conn Label: JDBC Client - Data Load

2.4 - 使用旧版驱动程序

Vertica 服务器支持来自以前版本的客户端驱动程序的连接。有关 Vertica 服务器和 Vertica 客户端版本之间兼容性的详细信息，请参阅客户端驱动程序和服务器版本兼容性。

3 - 访问 Vertica

下表显示了使用受支持的编程语言访问 Vertica 时必须设置的客户端驱动程序：

3.1 - C/C++

Vertica 提供开放式数据库连接 (ODBC) 驱动程序，此驱动程序可使应用程序能够连接到 Vertica 数据库。此驱动程序可供自定义编写的客户端应用程序（使用 ODBC API 与 Vertica 交互）使用。ODBC 还可由许多第三方应用程序（包括商业智能应用程序以及提取、转换和加载 (Extract, Transform, and Load, ETL) 应用程序）用来连接到 Vertica。

此部分详细介绍配置 Vertica ODBC 驱动程序的过程。此部分还介绍如何在自己的客户端应用程序中使用 ODBC API 连接到 Vertica。

尽管使用 C、C++、Perl、PHP 等编写的客户端应用程序均使用 ODBC 客户端驱动程序连接到 Vertica，但此部分仅阐述 C 和 C++ 应用程序。

3.1.1 - ODBC 体系结构

ODBC 架构包含四个层：

• 客户端应用程序

  此层是一个应用程序，用于通过数据源名称 (DSN) 打开数据源。然后，此应用程序会将请求发送到数据源，并接收这些请求的结果。请求以调用 ODBC 函数的方式发出。

• 驱动程序管理器

  此层是客户端系统上的一个库，用作客户端应用程序和一个或多个驱动程序之间的中介。该驱动程序管理器执行下列操作：

  • 解析由客户端应用程序提供的 DSN。

  • 加载访问 DSN 中定义的特定数据库所需的驱动程序。

  • 处理来自客户端的 ODBC 函数调用，或将这些调用传递到驱动程序。

  • 从驱动程序检索结果。

  • 在不再需要时卸载驱动程序。

  在 Windows 和 macOS 客户端系统上，驱动程序管理器由操作系统提供。在 Linux 系统上，您通常需要安装驱动程序管理器。有关可在客户端平台上与 Vertica 结合使用的驱动程序管理器的列表，请参阅客户端驱动程序支持。

• Driver

  此层是客户端系统上的一个库，提供对特定数据库的访问。此层可将请求转换为数据库所需的格式，还可将结果重新转换为客户端应用程序所需的格式。

• 数据库

  数据库可处理在客户端应用程序上启动的请求并返回结果。

3.1.2 - ODBC 功能支持

适用于 Vertica 的 ODBC 驱动程序支持 Microsoft ODBC 3.5 规范中定义的大部分功能。以下功能不受支持：

• 可更新的结果集

• 向后滚动光标

• 光标属性

• 每个连接有多个打开的语句。同时执行的语句必须各自属于不同的连接。例如，当其他语句的结果集处于打开状态时，您无法执行新语句。要使用相同的连接/会话执行另一条语句，请等待当前语句完成执行并关闭其结果集，然后执行新语句。

• 键集

• 书签

Vertica ODBC 驱动程序会准确报告其功能。如果需要确定驱动程序是否符合特定功能，您应使用 SQLGetInfo() 函数直接查询驱动程序的功能。

3.1.3 - Vertica 和 ODBC 数据类型转换

大多数数据类型均可在 Vertica 和 ODBC 之间透明地进行转换。此部分介绍了几种需要特殊处理的数据类型。

注意

• GEOMETRY 和 GEOGRAPHY 数据类型被 ODBC 驱动程序视为 LONG VARCHAR 数据。

• Vertica 支持 ODBC 所支持的标准间隔数据类型。请参阅 Microsoft 的 ODBC 参考文档中的间隔数据类型。

• Vertica 9.0.0 版引入了 UUID 数据类型，包括对 UUID 的 JDBC 支持。Vertica ADO.NET、ODBC 和 OLE DB 客户端在 9.0.1 版中添加了对 UUID 的完全支持。Vertica 保持与不支持 UUID 数据类型的旧 受支持 客户端驱动程序版本的向后兼容性，如下所示：

另请参阅

• 数据类型
• 将 LONG VARCHAR 和 LONG VARBINARY 数据类型与 ODBC 配合使用
• 将 GEOMETRY 和 GEOGRAPHY 数据类型用于 ODBC

• Microsoft ODBC 参考文档中的 SQL 数据类型

3.1.4 - ODBC 头文件

Vertica ODBC 驱动程序提供了名为 verticaodbc.h 的 C 头文件，该头文件定义了几个可在应用程序中使用的有用常数。使用这些常数，您可以访问和更改特定于 Vertica 的设置。

此文件的位置取决于客户端操作系统：

• Linux和UNIX系统：/opt/vertica/include
• Windows系统：C:\Program Files (x86)\Vertica\ODBC\include

下面列出了此文件中定义的常数。

3.1.5 - 连接到数据库

在任何 ODBC 应用程序中，第一步总是连接到数据库。创建与使用 ODBC 的数据源的连接时，应使用 DSN（其中包含要使用的驱动程序的详细信息、数据库主机和有关连接到数据源的其他基本信息）的名称。

若要连接到数据库，您需要对应用程序执行以下 4 个步骤：

1. 调用 SQLAllocHandle() 来为 ODBC 环境分配句柄。此句柄用于创建连接对象和设置应用程序范围设置。

2. 使用环境句柄设置应用程序要使用的 ODBC 版本。这样可确保数据源知道应用程序将使用哪个 API 与其交互。

3. 通过调用 SQLAllocHandle() 来分配数据库连接句柄。此句柄代表与特定数据源的连接。

4. 使用 SQLConnect() 或 SQLDriverConnect() 函数打开与数据库的连接。

   注意

   如果在连接字符串或 DSN 中指定区域设置，调用连接函数将返回有关成功连接的 SQL_SUCCESS_WITH_INFO，并显示有关区域设置状态的消息。

创建与数据库的连接时，如果在连接时只需要设置用户名和密码选项，请使用 SQLConnect()。如果要更改诸如区域设置等选项，请使用 SQLDriverConnect()。

以下示例演示了使用名为 ExampleDB 的 DSN 连接到数据库。成功创建连接后，此示例仅关闭该连接。

// Demonstrate connecting to Vertica using ODBC.
// Standard i/o library
#include <stdio.h>
#include <stdlib.h>
// Only needed for Windows clients
// #include <windows.h>
// SQL include files that define data types and ODBC API
// functions
#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>
int main()
{
    SQLRETURN ret;   // Stores return value from ODBC API calls
    SQLHENV hdlEnv;  // Handle for the SQL environment object
    // Allocate an a SQL environment object
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate a handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated an environment handle.\n");
    }

    // Set the ODBC version we are going to use to
    // 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
            (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    if(!SQL_SUCCEEDED(ret)) {
         printf("Could not set application version to ODBC 3.\n");
         exit(EXIT_FAILURE);
    } else {
         printf("Set application version to ODBC 3.\n");
    }
    // Allocate a database handle.
    SQLHDBC hdlDbc;
     ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
     if(!SQL_SUCCEEDED(ret)) {
          printf("Could not allocate database handle.\n");
          exit(EXIT_FAILURE);
     } else {
          printf("Allocated Database handle.\n");
     }
    // Connect to the database using
    // SQL Connect
    printf("Connecting to database.\n");
    const char *dsnName = "ExampleDB";
    const char* userID = "ExampleUser";
    const char* passwd = "password123";
    ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
        SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
        (SQLCHAR*)passwd, SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not connect to database.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Connected to database.\n");
    }
    // We're connected. You can do real
    // work here

    // When done, free all of the handles to close them
    // in an orderly fashion.
    printf("Disconnecting and freeing handles.\n");
    ret = SQLDisconnect( hdlDbc );
    if(!SQL_SUCCEEDED(ret)) {
        printf("Error disconnecting from database. Transaction still open?\n");
        exit(EXIT_FAILURE);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    exit(EXIT_SUCCESS);
}

运行以上代码后，将输出以下内容：

Allocated an environment handle.
Set application version to ODBC 3.
Allocated Database handle.
Connecting to database.
Connected to database.
Disconnecting and freeing handles.

有关使用 SQLDriverConnect 连接到数据库的示例，请参阅设置 ODBC 会话的区域设置和编码。

注意

• 如果您使用 DataDirect^® 驱动程序管理器，则应在连接到 Vertica 时始终对 SQLDriverConnect 函数的 DriverCompletion 参数（函数调用中的最终参数）使用 SQL_DRIVER_NOPROMPT 值。Linux 和 UNIX 平台上 Vertica 的 ODBC 驱动程序不包含 UI，因此无法提示用户输入密码。

• 在 Windows 客户端平台上，ODBC 驱动程序会提示用户提供连接信息。有关详细信息，请参阅提示 Windows 用户提供缺少的连接属性。

• 如果数据库不符合 Vertica 许可协议，应用程序将在 SQLConnect() 函数的返回值中收到警告消息。始终应让应用程序检查此返回值是否为 SQL_SUCCESS_WITH_INFO。如果是，应让应用程序提取消息并向用户显示。

3.1.6 - 负载均衡

本机连接负载均衡

本机连接负载均衡有助于在 Vertica 数据库中的主机上分散客户端连接所带来的开销。服务器和客户端都必须启用本机连接负载均衡。如果两者者都启用了本机负载均衡，则当客户端最初连接到数据库中的主机时，此主机会从数据库中当前正在运行的主机列表中选择一个主机来处理客户端连接，并通知客户端它所选择的主机。

如果最初联系的主机没有选择自身来处理连接，则客户端会断开连接，然后打开指向第一个主机所选主机的另一个连接。指向此第二个主机的连接进程将照常进行—如果启用了 SSL，则会启动 SSL 协商，否则客户端会启动身份验证过程。有关详细信息，请参阅关于本机连接负载均衡。

若要在客户端上启用本机连接负载均衡，请在 DSN 条目或连接字符串中将 ConnectionLoadBalance 连接参数设置为 true。以下示例说明了如何在本机连接负载均衡已启用的情况下多次连接到数据库，以及从 V_MONITOR.CURRENT_SESSION 系统表获取处理连接的节点的名称。

// Demonstrate enabling native load connection balancing.
// Standard i/o library
#include <stdlib.h>
#include <iostream>
#include <assert.h>
// Only needed for Windows clients
// #include <windows.h>
// SQL include files that define data types and ODBC API
// functions
#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>

using namespace std;
int main()
{
    SQLRETURN ret;   // Stores return value from ODBC API calls
    SQLHENV hdlEnv;  // Handle for the SQL environment object
    // Allocate an a SQL environment object
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    assert(SQL_SUCCEEDED(ret));

    // Set the ODBC version we are going to use to
    // 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
            (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    assert(SQL_SUCCEEDED(ret));

    // Allocate a database handle.
    SQLHDBC hdlDbc;
    ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    assert(SQL_SUCCEEDED(ret));

    // Connect four times. If load balancing is on, client should
    // connect to different nodes.
    for (int x=1; x <= 4; x++) {

        // Connect to the database using SQLDriverConnect. Set
        // ConnectionLoadBalance to 1 (true) to enable load
        // balancing.
        cout << endl << "Connection attempt #" << x << "... ";
        const char *connStr = "DSN=VMart;ConnectionLoadBalance=1;"
            "UID=ExampleUser;PWD=password123";


        ret = SQLDriverConnect(hdlDbc, NULL, (SQLCHAR*)connStr, SQL_NTS,
               NULL, 0, NULL, SQL_DRIVER_NOPROMPT );
        if(!SQL_SUCCEEDED(ret)) {
            cout << "failed. Exiting." << endl;
            exit(EXIT_FAILURE);
        } else {
            cout << "succeeded" << endl;
        }
        // We're connected. Query the v_monitor.current_session table to
        // find the name of the node we've connected to.

        // Set up a statement handle
        SQLHSTMT hdlStmt;
        SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
        assert(SQL_SUCCEEDED(ret));

        ret = SQLExecDirect( hdlStmt, (SQLCHAR*)"SELECT node_name FROM "
            "V_MONITOR.CURRENT_SESSION;", SQL_NTS );

        if(SQL_SUCCEEDED(ret)) {
            // Bind varible to column in result set.
            SQLTCHAR node_name[256];
            ret = SQLBindCol(hdlStmt, 1, SQL_C_TCHAR, (SQLPOINTER)node_name,
                sizeof(node_name), NULL);
            while(SQL_SUCCEEDED(ret = SQLFetchScroll(hdlStmt, SQL_FETCH_NEXT,1))) {
                // Print the bound variables, which now contain the values from the
                // fetched row.
                cout << "Connected to node " << node_name << endl;
            }
        }
        // Free statement handle
        SQLFreeHandle(SQL_HANDLE_STMT,hdlStmt);
        cout << "Disconnecting." << endl;
        ret = SQLDisconnect( hdlDbc );
        assert(SQL_SUCCEEDED(ret));
    }
    // When done, free all of the handles to close them
    // in an orderly fashion.
    cout << endl << "Freeing handles..." << endl;
    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    cout << "Done!" << endl;
    exit(EXIT_SUCCESS);
}

运行以上示例后，将生成类似于以下内容的输出：

Connection attempt #1... succeeded
Connected to node v_vmart_node0001
Disconnecting.

Connection attempt #2... succeeded
Connected to node v_vmart_node0002
Disconnecting.

Connection attempt #3... succeeded
Connected to node v_vmart_node0003
Disconnecting.

Connection attempt #4... succeeded
Connected to node v_vmart_node0001
Disconnecting.

Freeing handles...
Done!

基于主机名的负载均衡

您还可以通过将单个主机名解析为多个 IP 地址来平衡工作负载。ODBC 客户端驱动程序通过自动将主机名随机解析为指定的 IP 地址之一来实现负载均衡。

例如，假设主机名 verticahost.example.com 在 etc/hosts 中有以下条目：

192.0.2.0 verticahost.example.com
192.0.2.1 verticahost.example.com
192.0.2.2 verticahost.example.com

指定主机名 verticahost.example.com 会随机解析为列出的 IP 地址之一。

3.1.7 - 连接故障转移

如果客户端应用程序尝试连接到 Vertica 群集中处于关闭状态的主机，则使用默认连接配置时连接尝试将会失败。此故障通常会向用户返回一个错误。用户必须等待主机恢复并重试连接，或者手动编辑连接设置以选择其他主机。

由于 Vertica 分析型数据库采用分布式架构，通常您不会关注哪个数据库主机处理客户端应用程序的连接。可以使用客户端驱动程序的连接故障转移功能来防止用户在无法访问连接设置中所指定主机的情况下收到连接错误。JDBC 驱动程序可通过几种方式让客户端驱动程序在无法访问连接参数中所指定的主机时自动尝试连接到其他主机：

• 将 DNS 服务器配置为返回一个主机名的多个 IP 地址。在连接设置中使用此主机名时，客户端会尝试连接到 DNS 找到的第一个 IP 地址。如果位于该 IP 地址的主机无法访问，则客户端会尝试连接到第二个 IP，依此类推，直到其成功地连接到某个主机或试过所有 IP 地址为止。

• 提供当您在连接参数中指定的主要主机无法访问时客户端驱动程序尝试连接的备份主机列表。

• （仅限 JDBC）在尝试连接到下一个节点之前，使用特定于驱动程序的连接属性来管理超时。

在所有方法中，故障转移过程对于客户端应用程序是透明的（除了在选择使用列表故障转移方法时需指定备份主机列表之外）。如果主要主机无法访问，客户端驱动程序会自动尝试连接到其他主机。

故障转移仅适用于初次建立客户端连接的情况。如果连接断开，驱动程序不会自动尝试重新连接到数据库中的其他主机。

通常可选择上述两种故障转移方法中的一种。但它们可以一起使用。如果您的 DNS 服务器返回多个 IP 地址，并且您提供了备份主机列表，则客户端会首先尝试连接 DNS 服务器返回的所有 IP，然后再尝试连接备份列表中的主机。

DNS 故障转移方法可集中处理配置客户端故障转移。在向 Vertica 分析型数据库群集添加新节点时，可以选择通过编辑 DNS 服务器设置来将这些节点添加到故障转移列表中。所有使用 DNS 服务器连接到 Vertica 分析型数据库的客户端系统都会自动采用连接故障转移，而无需更改任何设置。但此方法需要对所有客户端用于连接到 Vertica 分析型数据库群集的 DNS 服务器具有管理访问权限。这在贵组织中可能无法实现。

使用备份服务器列表要比编辑 DNS 服务器设置更加容易。但此方法不能集中处理故障转移功能。如果更改了 Vertica 分析型数据库群集，您可能需要在每个客户端系统上更新应用程序设置。

使用 DNS 故障转移

若要使用 DNS 故障转移，您需要更改 DNS 服务器的设置，将单一主机名映射为 Vertica 分析型数据库群集中主机的多个 IP 地址。然后让所有客户端应用程序都使用该主机名连接到 Vertica 分析型数据库。

您可以选择让 DNS 服务器为主机名返回任何所需数量的 IP 地址。在小型群集中，您可以选择让其返回群集中所有主机的 IP 地址。但对于大型群集，应考虑选择返回一部分主机。否则可能会导致长时间延迟，因为客户端驱动程序尝试连接到数据库中处于关闭状态的每个主机会失败。

使用备份主机列表

若要启用基于备份列表的连接故障转移，需要在客户端应用程序的 BackupServerNode 参数中指定主机的至少一个 IP 地址或主机名。可以视情况在主机名或 IP 后面使用冒号和端口号。如果未提供端口号，驱动程序会默认使用标准 Vertica 端口号 (5433)。若要列出多个主机，请用逗号分隔这些主机。

以下示例演示了如何通过设置 BackupServerNode 连接参数来指定可尝试连接的其他主机。由于有意在连接字符串中使用了一个不存在的节点，因此初始连接失败。客户端驱动程序必须尝试通过备份主机来与 Vertica 建立连接。

// Demonstrate using connection failover.
// Standard i/o library
#include <stdlib.h>
#include <iostream>
#include <assert.h>

// Only needed for Windows clients
// #include <windows.hgt;

// SQL include files that define data types and ODBC API
// functions
#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>

using namespace std;

int main()
{
    SQLRETURN ret;   // Stores return value from ODBC API calls
    SQLHENV hdlEnv;  // Handle for the SQL environment object
    // Allocate an a SQL environment object
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    assert(SQL_SUCCEEDED(ret));

    // Set the ODBC version we are going to use to
    // 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
            (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    assert(SQL_SUCCEEDED(ret));

    // Allocate a database handle.
    SQLHDBC hdlDbc;
    ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    assert(SQL_SUCCEEDED(ret));

/* DSN for this connection specifies a bad node, and good backup nodes:
[VMartBadNode]
Description=VMart Vertica Database
Driver=/opt/vertica/lib64/libverticaodbc.so
Database=VMart
Servername=badnode.example.com
BackupServerNode=v_vmart_node0002.example.com,v_vmart_node0003.example.com
*/

    // Connect to the database using SQLConnect
    cout << "Connecting to database." << endl;
    const char *dsnName = "VMartBadNode"; // Name of the DSN
    const char* userID = "ExampleUser"; // Username
    const char* passwd = "password123"; // password
    ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
        SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
        (SQLCHAR*)passwd, SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        cout << "Could not connect to database." << endl;
        exit(EXIT_FAILURE);
    } else {
        cout << "Connected to database." << endl;
    }
    // We're connected. Query the v_monitor.current_session table to
    // find the name of the node we've connected to.

    // Set up a statement handle
    SQLHSTMT hdlStmt;
    SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
    assert(SQL_SUCCEEDED(ret));

    ret = SQLExecDirect( hdlStmt, (SQLCHAR*)"SELECT node_name FROM "
        "v_monitor.current_session;", SQL_NTS );

    if(SQL_SUCCEEDED(ret)) {
        // Bind varible to column in result set.
        SQLTCHAR node_name[256];
        ret = SQLBindCol(hdlStmt, 1, SQL_C_TCHAR, (SQLPOINTER)node_name,
            sizeof(node_name), NULL);
        while(SQL_SUCCEEDED(ret = SQLFetchScroll(hdlStmt, SQL_FETCH_NEXT,1))) {
            // Print the bound variables, which now contain the values from the
            // fetched row.
            cout << "Connected to node " << node_name << endl;
        }
    }

    cout << "Disconnecting." << endl;
    ret = SQLDisconnect( hdlDbc );
    assert(SQL_SUCCEEDED(ret));

    // When done, free all of the handles to close them
    // in an orderly fashion.
    cout << endl << "Freeing handles..." << endl;
    SQLFreeHandle(SQL_HANDLE_STMT,hdlStmt);
    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    cout << "Done!" << endl;
    exit(EXIT_SUCCESS);
}

运行此示例后，系统控制台上的输出类似于以下内容：

Connecting to database.
Connected to database.
Connected to node v_vmart_node0002
Disconnecting.

Freeing handles...
Done!

请注意，系统会与备份列表中的第一个节点建立连接（节点 2）。

3.1.8 - 提示 Windows 用户提供缺少的连接属性

如果缺少必需信息，Vertica Windows ODBC 驱动程序会提示用户提供连接信息。当客户端应用程序调用 SQLDriverConnect 以连接到 Vertica 并且以下任一条件成立时，驱动程序将显示“Vertica 连接对话框 (Vertica Connection Dialog)”：

• DriverCompletion 属性已设置为 SQL_DRIVER_PROMPT。

• DriverCompletion 属性已设置为 SQL_DRIVER_COMPLETE 或 SQL_DRIVER_COMPLETE_REQUIRED，且用于建立连接的连接字符串或 DSN 缺少服务器、数据库或端口信息。

如果以上任一条件成立，驱动程序将向用户显示“Vertica 连接对话框 (Vertica Connection Dialog)”以提示用户提供连接信息。

该对话框包含填入的连接字符串或 DSN 中提供的所有属性值。

连接对话框上的必填字段是“数据库 (Database)”、“UID”、“服务器 (Server)”和“端口 (Port)”。填充这些字段后，表单将启用确定 (OK) 按钮。

如果用户在该对话框上单击取消 (Cancel)，SQLDriverConnect 函数调用将立即返回 SQL_NO_DATA，而不会尝试连接到 Vertica。如果用户提供的连接信息不完整或不正确，连接函数将在连接尝试失败后返回 SQL_ERROR。

3.1.9 - 提示 Windows 用户提供密码

如果向 SQLDriverConnect 函数（客户端应用程序调用此函数以连接到 Vertica）提供的连接字符串或 DSN 缺少连接到数据库所需的任何必需的连接属性，Vertica Windows ODBC 驱动程序将打开一个对话框，提示用户输入缺失的信息（请参阅提示 Windows 用户提供缺少的连接属性）。一般情况下，不将用户密码视为必需的连接属性，因为 Vertica 用户帐户可能不具有密码。如果缺少密码属性，ODBC 驱动程序仍会在未提供密码的情况下尝试连接到 Vertica。

您可以使用 PromptOnNoPassword DSN 参数来强制 ODBC 驱动程序将密码视为必需的连接属性。如果不想在 DSN 条目中存储密码，则此参数很有用。保存在 DSN 条目中的密码是不安全的，因为这些密码作为明文存储在 Windows 注册表中，从而对同一个系统上的其他用户可见。

还有另外两个因素决定 ODBC 驱动程序是否显示 Vertica“连接 (Connection)”对话框。这两个因素如下所示（按优先级顺序）：

• SQLDriverConnect 函数调用的 DriverCompletion 参数。

• DSN 或连接字符串是否包含密码。

下表显示了 PromptOnNoPassword DSN 参数、SQLDriverConnect 函数的 DriverCompletion 参数以及“DSN 或连接字符串是否包含密码”如何交互以控制是否显示 Vertica“连接 (Connection)”对话框。

以下示例代码演示了如何在 C++ 中将 PromptOnNoPassword DSN 参数和系统 DSN 一起使用：

wstring connectString = L "DSN=VerticaDSN;PromptOnNoPassword=1;";
retcode = SQLDriverConnect(
    hdbc,
    0,
    (SQLWCHAR * ) connectString.c_str(),
    connectString.length(),
    OutConnStr,
    255, &
    amp; OutConnStrLen,
    SQL_DRIVER_COMPLETE);

无密码条目与空密码

连接字符串或 DSN 中不包含密码和包含空密码是两种不同情况。仅当连接字符串或 DSN 不具有 PWD 属性（存放用户密码）时，PromptOnNoPassword DSN 参数才起作用。如果具有该属性，则即使该属性为空，PromptOnNoPassword 也不会提示 Windows ODBC 驱动程序显示 Vertica“连接 (Connection)”对话框。

如果要使用 DSN 为连接提供属性，则此差别会造成混乱。在 Windows ODBC 管理器中为 DSN 连接输入密码并保存该 DSN 连接后，Windows 会将 PWD 属性添加到注册表中的 DSN 定义。如果以后删除该密码，PWD 属性会保留在 DSN 定义中（只会将其值设置为空字符串）。即使您只是使用 ODBC 管理器对话框上的“测试 (Test)”按钮测试 DSN，并且稍后在保存之前清除了该 DSN，也会创建 PWD 属性。

设置了密码后，从 DSN 定义中移除 PWD 属性的唯一方法是使用 Windows 注册表编辑器：

1. 单击 Windows“开始”菜单，然后单击“运行”。

2. 在“运行”对话框中，键入 regedit，然后单击“确定”。

3. 在“注册表编辑器 (Registry Editor)”窗口中，单击“编辑 (Edit)”>“查找 (Find)”（或按 Ctrl+F）。

4. 在“查找”窗口中，输入要删除其 PWD 属性的 DSN 的名称，然后单击“确定”。

5. 如果查找操作无法定位到 ODBC.INI 文件夹下的某个文件夹，请单击“编辑 (Edit)”>“查找下一个 (Find Next)”（或按 F3），直至已突出显示与 DSN 的名称匹配的文件夹为止。
   

6. 选择 PWD 项，然后按 Delete。

7. 单击“是”以确认删除该值。

该 DSN 现已不具有 PWD 属性，并且可以在与 PromptOnNoPassword=true 和 DriverConnect=SQL_DRIVER_COMPLETE 一起使用时促使连接对话框显示出来。

3.1.10 - 设置 ODBC 会话的区域设置和编码

Vertica 提供以下方法来设置 ODBC 会话的区域设置和编码：

• 使用 DSN 指定所有已建立的连接的区域设置：

  • 在 Linux 和其他类 UNIX 平台上： 为 Linux 创建 ODBC DSN

  • 在 Windows 平台上，在 ODBC DSN 配置编辑器的“服务器设置 (Server Settings)”选项卡上的“区域设置 (Locale)”字段中设置区域设置。有关详细信息，请参阅为 Windows 客户端创建 ODBC DSN。

• 在 SQLDriverConnect() 函数的连接字符串中设置 Locale 连接参数。例如：

  SQLDriverConnect(conn, NULL, (SQLCHAR*)"DSN=Vertica;Locale=en_GB@collation=binary", SQL_NTS, szConnOut, sizeof(szConnOut), &iAvailable, SQL_DRIVER_NOPROMPT)
  

• 使用 SQLSetConnectAttr() 设置编码和区域设置。通常，您应该始终使用此函数设置编码，而不是在 DSN 中设置它。

  • 传递 SQL_ATTR_VERTICA_LOCALE 常量和 ICU 字符串作为属性值。例如：

    => SQLSetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, (SQLCHAR*)newLocale,
            SQL_NTS);
    

  • 传递 SQL_ATTR_AP_WCHAR_TYPE 常量和编码作为属性值。例如：

    => rc = SQLSetConnectAttr (hdbc, SQL_ATTR_APP_WCHAR_TYPE, (void *)SQL_DD_CP_UTF16, SQL_IS_INTEGER);
    

注意

• 如果让客户端系统使用非 Unicode 区域设置（例如，在 Linux 平台上设置 LANG=C）并对与 Vertica 的连接使用 Unicode 区域设置，则会生成诸如“(10170) 来自数据源的数据进行字符串数据右截断 (String data right truncation on data from data source)”等错误。如果从 Vertica 收到的数据不采用 UTF-8 格式，驱动程序将基于系统的区域设置来分配字符串内存，并且非 UTF-8 数据会触发超限。如果始终在客户端系统上使用 Unicode 区域设置，您可以避免这些错误。

  如果在连接字符串或 DSN 中指定区域设置，调用连接函数将返回有关成功连接的 SQL_SUCCESS_WITH_INFO，并显示有关区域设置状态的消息。

• ODBC 应用程序可以处于 ANSI 模式或 Unicode 模式：

  • 如果处于 Unicode 模式，则 ODBC 使用的编码是 UCS-2。

  • 如果处于 ANSI 模式，则数据必须采用单字节 ASCII 编码，此编码与数据库服务器上的 UTF-8 兼容。

  向 Vertica 服务器传递数据时，ODBC 驱动程序会将 UCS-2 转换为 UTF-8，并会将 Vertica 服务器发来的数据从 UTF-8 转换为 UCS-2。

• 如果最终用户应用程序尚未处于 UCS-2 编码模式，则应用程序应负责将输入数据转换为 UCS-2，否则会出现意外结果。例如：

  • 向 ODBC API 传递非 UCS-2 数据时，如果该数据解释为 UCS-2，将导致向 API 传递无效的 UCS-2 符号，从而生成错误。

  • 或者在备用编码中提供的符号可能是有效的 UCS-2 符号；在这种情况下，会将不正确的数据插入到数据库。

  ODBC 应用程序应使用 SQLSetConnectAttr 设置正确的服务器会话区域设置（如果与数据库范围设置不同），以便在服务器上设置正确的排序规则和字符串函数行为。

以下示例代码演示了同时使用连接字符串和 SQLSetConnectAttr() 函数来设置区域设置。

// Standard i/o library
#include <stdio.h>
#include <stdlib.h>
// Only needed for Windows clients
// #include <windows.h>
// SQL include files that define data types and ODBC API
// functions
#include <sql.h>
#include <sqlext.h>
#include <sqltypes.h>
// Vertica-specific definitions. This include file is located as
// /opt/vertica/include on database hosts.
#include <verticaodbc.h>
int main()
{
    SQLRETURN ret;   // Stores return value from ODBC API calls
    SQLHENV hdlEnv;  // Handle for the SQL environment object
    // Allocate an a SQL environment object
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate a handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated an environment handle.\n");
    }
    // Set the ODBC version we are going to use to 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not set application version to ODBC 3.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Set application version to ODBC 3.\n");
    }
    // Allocate a database handle.
    SQLHDBC hdlDbc;
    ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate database handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated Database handle.\n");
    }
    // Connect to the database using SQLDriverConnect
    printf("Connecting to database.\n");
    // Set the locale to English in Great Britain.
    const char *connStr = "DSN=ExampleDB;locale=en_GB;"
        "UID=dbadmin;PWD=password123";
    ret = SQLDriverConnect(hdlDbc, NULL, (SQLCHAR*)connStr, SQL_NTS,
               NULL, 0, NULL, SQL_DRIVER_NOPROMPT );
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not connect to database.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Connected to database.\n");
    }
    // Get the Locale
    char locale[256];
    SQLGetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, locale, sizeof(locale),
        0);
    printf("Locale is set to: %s\n", locale);
    // Set the locale to a new value
    const char* newLocale = "en_GB";
    SQLSetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, (SQLCHAR*)newLocale,
        SQL_NTS);

    // Get the Locale again
    SQLGetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, locale, sizeof(locale),
        0);
    printf("Locale is now set to: %s\n", locale);

    // Set the encoding
    SQLSetConnectAttr (hdbc, SQL_ATTR_APP_WCHAR_TYPE, (void *)SQL_DD_CP_UTF16,
        SQL_IS_INTEGER);

    // When done, free all of the handles to close them
    // in an orderly fashion.
    printf("Disconnecting and freeing handles.\n");
    ret = SQLDisconnect( hdlDbc );
    if(!SQL_SUCCEEDED(ret)) {
        printf("Error disconnecting from database. Transaction still open?\n");
        exit(EXIT_FAILURE);
    }
    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    exit(EXIT_SUCCESS);
}

3.1.11 - AUTOCOMMIT 事务和 ODBC 事务

AUTOCOMMIT 连接属性控制 INSERT、ALTER、COPY 和其他数据处理语句是否在完成后自动提交。默认情况下，AUTOCOMMIT 已启用，所有语句将在执行后提交。这通常不是最佳设置，因为效率较低。此外，您通常想要控制是否作为一个整体提交一组语句，而非逐个提交语句。例如，您可能只想在所有插入都成功时才提交一系列插入。如果 AUTOCOMMIT 已禁用，则当其中一个语句失败时，您可以回退事务。

如果 AUTOCOMMIT 已打开，则会在执行语句之后立即提交这些语句的结果。不能回退在 AUTOCOMMIT 模式下执行的语句。

例如，如果 AUTOCOMMIT 已打开，将自动提交以下单个 INSERT 语句：

ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"INSERT INTO customers VALUES(500,"
    "'Smith, Sam', '123-456-789');", SQL_NTS);

如果 AUTOCOMMIT 已关闭，您需要在执行语句之后手动提交事务。例如：

ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"INSERT INTO customers VALUES(500,"
    "'Smith, Sam', '123-456-789');", SQL_NTS);
// Other inserts and data manipulations
// Commit the statements(s)
ret = SQLEndTran(SQL_HANDLE_DBC, hdlDbc, SQL_COMMIT);

只有在调用 SQLEndTran() 时，才会提交插入的行。提交事务之前，您可以随时回退 INSERT 和其他语句。

以下示例演示了关闭 AUTOCOMMIT 以及执行插入和手动提交事务。

// Some standard headers
#include <stdio.h>
#include <stdlib.h>
// Only needed for Windows clients
// #include <windows.h>
// Standard ODBC headers
#include <sql.h>
#include <sqltypes.h>
#include <sqlext.h>
int main()
{
    // Set up the ODBC environment
    SQLRETURN ret;
    SQLHENV hdlEnv;
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate a handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated an environment handle.\n");
    }
    // Tell ODBC that the application uses ODBC 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not set application version to ODBC3.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Set application to ODBC 3.\n");
    }
    // Allocate a database handle.
    SQLHDBC hdlDbc;
    ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate database handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated Database handle.\n");
    }
    // Connect to the database
    printf("Connecting to database.\n");
    const char *dsnName = "ExampleDB";
    const char* userID = "dbadmin";
    const char* passwd = "password123";
    ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
        SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
        (SQLCHAR*)passwd, SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not connect to database.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Connected to database.\n");
    }
    // Get the AUTOCOMMIT state
    SQLINTEGER  autoCommitState;
    SQLGetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, &autoCommitState, 0, NULL);
    printf("Autocommit is set to: %d\n", autoCommitState);


    // Disable AUTOCOMMIT
    printf("Disabling autocommit.\n");
    ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF,
        SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not disable autocommit.\n");
        exit(EXIT_FAILURE);
    }

    // Get the AUTOCOMMIT state again
    SQLGetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, &autoCommitState, 0, NULL);
    printf("Autocommit is set to: %d\n", autoCommitState);

    // Set up a statement handle
    SQLHSTMT hdlStmt;
    SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);


    // Create a table to hold the data
    SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers",
        SQL_NTS);
    SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers "
        "(CustID int, CustName varchar(100), Phone_Number char(15));",
        SQL_NTS);


    // Insert a single row.
    ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"INSERT INTO customers VALUES(500,"
        "'Smith, Sam', '123-456-789');", SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not perform single insert.\n");
    } else {
        printf("Performed single insert.\n");
    }


    // Need to commit the transaction before closing, since autocommit is
    // disabled. Otherwise SQLDisconnect returns an error.
    printf("Committing transaction.\n");
    ret =  SQLEndTran(SQL_HANDLE_DBC, hdlDbc, SQL_COMMIT);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Error committing transaction.\n");
        exit(EXIT_FAILURE);
    }

    // Clean up
    printf("Free handles.\n");
    ret = SQLDisconnect(hdlDbc);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Error disconnecting from database. Transaction still open?\n");
        exit(EXIT_FAILURE);
    }
    SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    exit(EXIT_SUCCESS);
}

运行以上代码后，将生成以下输出：

Allocated an environment handle.
Set application to ODBC 3.
Allocated Database handle.
Connecting to database.
Connected to database.
Autocommit is set to: 1
Disabling autocommit.
Autocommit is set to: 0
Performed single insert.
Committing transaction.
Free handles.

3.1.12 - 检索数据

若要通过 ODBC 检索数据，应执行将返回结果集的查询（例如 SELECT），然后使用以下两种方法之一检索结果：

• 使用 SQLFetch() 函数检索结果集的某个行，然后通过调用 SQLGetData() 访问该行中的列值。

• 使用 SQLBindColumn() 函数将变量或数组绑定到结果集中的某个列，然后调用 SQLExtendedFetch() 或 SQLFetchScroll() 以读取结果集的某个行并将其值插入到该变量或数组中。

使用以上两种方法时，应在结果集中循环直至到达结尾（由 SQL_NO_DATA 返回状态指示）或遇到错误为止。

以下代码示例演示了如何通过以下过程从 Vertica 检索数据：

1. 连接到数据库。

2. 执行将返回所有表的 ID 和名称的 SELECT 语句。

3. 将两个变量绑定到结果集中的两个列。

4. 在结果集中循环，并输出 ID 和名称值。

// Demonstrate running a query and getting results by querying the tables
// system table for a list of all tables in the current schema.
// Some standard headers
#include <stdlib.h>
#include <sstream>
#include <iostream>
#include <assert.h>
// Standard ODBC headers
#include <sql.h>
#include <sqltypes.h>
#include <sqlext.h>

// Use std namespace to make output easier
using namespace std;
// Helper function to print SQL error messages.
template <typename HandleT>
void reportError(int handleTypeEnum, HandleT hdl)
{
    // Get the status records.
    SQLSMALLINT   i, MsgLen;
    SQLRETURN ret2;
    SQLCHAR       SqlState[6], Msg[SQL_MAX_MESSAGE_LENGTH];
    SQLINTEGER    NativeError;
    i = 1;
    cout << endl;
    while ((ret2 = SQLGetDiagRec(handleTypeEnum, hdl, i, SqlState, &NativeError,
        Msg, sizeof(Msg), &MsgLen)) != SQL_NO_DATA) {
        cout << "error record #" << i++ << endl;
        cout << "sqlstate: " << SqlState << endl;
        cout << "detailed msg: " << Msg << endl;
        cout << "native error code: " << NativeError << endl;
    }
}

typedef struct {
    SQLHENV hdlEnv;
    SQLHDBC hdlDbc;
} DBConnection;

void connect(DBConnection *pConnInfo)
{
    // Set up the ODBC environment
    SQLRETURN ret;
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &pConnInfo->hdlEnv);
    assert(SQL_SUCCEEDED(ret));
    // Tell ODBC that the application uses ODBC 3.
    ret = SQLSetEnvAttr(pConnInfo->hdlEnv, SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER)SQL_OV_ODBC3, SQL_IS_UINTEGER);
    assert(SQL_SUCCEEDED(ret));

    // Allocate a database handle.
    ret = SQLAllocHandle(SQL_HANDLE_DBC, pConnInfo->hdlEnv, &pConnInfo->hdlDbc);
    assert(SQL_SUCCEEDED(ret));
    // Connect to the database
    cout << "Connecting to database." << endl;
    const char* dsnName = "ExampleDB";
    const char* userID = "dbadmin";
    const char* passwd = "password123";
    ret = SQLConnect(pConnInfo->hdlDbc, (SQLCHAR*)dsnName,
        SQL_NTS, (SQLCHAR*)userID, SQL_NTS,
        (SQLCHAR*)passwd, SQL_NTS);
    if (!SQL_SUCCEEDED(ret)) {
        cout << "Could not connect to database" << endl;
        reportError<SQLHDBC>(SQL_HANDLE_DBC, pConnInfo->hdlDbc);
        exit(EXIT_FAILURE);
    }
    else {
        cout << "Connected to database." << endl;
    }
}

void disconnect(DBConnection *pConnInfo)
{
    SQLRETURN ret;
    // Clean up by shutting down the connection
    cout << "Free handles." << endl;
    ret = SQLDisconnect(pConnInfo->hdlDbc);
    if (!SQL_SUCCEEDED(ret)) {
        cout << "Error disconnecting. Transaction still open?" << endl;
        exit(EXIT_FAILURE);
    }
    SQLFreeHandle(SQL_HANDLE_DBC, pConnInfo->hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, pConnInfo->hdlEnv);
}

void executeQuery(SQLHDBC hdlDbc, SQLCHAR* pQuery)
{
    SQLRETURN ret;
    // Set up a statement handle
    SQLHSTMT hdlStmt;
    SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
    assert(SQL_SUCCEEDED(ret));

    // Execute a query to get the names and IDs of all tables in the schema
    // search p[ath (usually public).
    ret = SQLExecDirect(hdlStmt, pQuery, SQL_NTS);

    if (!SQL_SUCCEEDED(ret)) {
        // Report error an go no further if statement failed.
        cout << "Error executing statement." << endl;
        reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);
        exit(EXIT_FAILURE);
    }
    else {
        // Query succeeded, so bind two variables to the two colums in the
        // result set,
        cout << "Fetching results..." << endl;
        SQLBIGINT table_id;       // Holds the ID of the table.
        SQLTCHAR table_name[256]; // buffer to hold name of table
        ret = SQLBindCol(hdlStmt, 1, SQL_C_SBIGINT, (SQLPOINTER)&table_id,
            sizeof(table_id), NULL);
        ret = SQLBindCol(hdlStmt, 2, SQL_C_TCHAR, (SQLPOINTER)table_name,
            sizeof(table_name), NULL);

        // Loop through the results,
        while (SQL_SUCCEEDED(ret = SQLFetchScroll(hdlStmt, SQL_FETCH_NEXT, 1))) {
            // Print the bound variables, which now contain the values from the
            // fetched row.
            cout << table_id << " | " << table_name << endl;
        }


        // See if loop exited for reasons other than running out of data
        if (ret != SQL_NO_DATA) {
            // Exited for a reason other than no more data... report the error.
            reportError<SQLHDBC>(SQL_HANDLE_STMT, hdlStmt);
        }
    }
    SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
}

int main()
{
    DBConnection conn;

    connect(&conn);
    executeQuery(conn.hdlDbc,
        (SQLCHAR*)"SELECT table_id, table_name FROM tables ORDER BY table_name");
    executeQuery(conn.hdlDbc,
        (SQLCHAR*)"SELECT table_id, table_name FROM tables ORDER BY table_id");
    disconnect(&conn);
    exit(EXIT_SUCCESS);
}

在 vmart 数据库中运行以上示例代码后，将生成类似于以下内容的输出：

Connecting to database.
Connected to database.
Fetching results...
45035996273970908 | call_center_dimension
45035996273970836 | customer_dimension
45035996273972958 | customers
45035996273970848 | date_dimension
45035996273970856 | employee_dimension
45035996273970868 | inventory_fact
45035996273970904 | online_page_dimension
45035996273970912 | online_sales_fact
45035996273970840 | product_dimension
45035996273970844 | promotion_dimension
45035996273970860 | shipping_dimension
45035996273970876 | store_dimension
45035996273970894 | store_orders_fact
45035996273970880 | store_sales_fact
45035996273972806 | t
45035996273970852 | vendor_dimension
45035996273970864 | warehouse_dimension
Fetching results...
45035996273970836 | customer_dimension
45035996273970840 | product_dimension
45035996273970844 | promotion_dimension
45035996273970848 | date_dimension
45035996273970852 | vendor_dimension
45035996273970856 | employee_dimension
45035996273970860 | shipping_dimension
45035996273970864 | warehouse_dimension
45035996273970868 | inventory_fact
45035996273970876 | store_dimension
45035996273970880 | store_sales_fact
45035996273970894 | store_orders_fact
45035996273970904 | online_page_dimension
45035996273970908 | call_center_dimension
45035996273970912 | online_sales_fact
45035996273972806 | t
45035996273972958 | customers
Free handles.

3.1.13 - 加载数据

许多客户端应用程序的主要任务是将数据加载到 Vertica 数据库。有多种不同方法可用于通过 ODBC 插入数据，本节中的主题介绍这些方法。

3.1.13.1 - 使用单行插入

将数据加载到 Vertica 的最简单方法是使用 SQLExecuteDirect 函数运行 INSERT SQL 语句。但此方法仅能插入单个数据行。

ret = SQLExecDirect(hstmt, (SQLTCHAR*)"INSERT into Customers values"
      "(1,'abcda','efgh','1')", SQL_NTS);

3.1.13.2 - 使用预定义的语句

Vertica 支持将服务器端预定义的语句与 ODBC 和 JDBC 结合使用。使用预定义的语句，您只需定义一个语句一次，然后可以使用不同的参数多次运行该语句。要执行的语句包含占位符而非参数。执行语句时，应为每个占位符提供值。

在以下示例查询中，占位符用问号 (?) 表示：

SELECT * FROM public.inventory_fact WHERE product_key = ?

服务器端预定义的语句用于以下用途：

• 优化查询。Vertica 只需要解析语句一次。

• 防止 SQL 注入攻击。如果过滤用户输入时未能正确过滤嵌入在 SQL 语句中的字符串字面量转义字符，或者如果用户输入由于未强类型化而意外运行，则将发生 SQL 注入攻击。由于预定义的语句与输入数据分开进行解析，因此数据库不可能意外执行数据。

• 将直接变量绑定到返回列。通过指向数据结构，代码不必执行额外转换。

以下示例演示了使用预定义的语句执行单一插入。

// Some standard headers
#include <stdio.h>
#include <stdlib.h>
// Only needed for Windows clients
// #include <windows.h>
// Standard ODBC headers
#include <sql.h>
#include <sqltypes.h>
#include <sqlext.h>
// Some constants for the size of the data to be inserted.
#define CUST_NAME_LEN 50
#define PHONE_NUM_LEN 15
#define NUM_ENTRIES 4
int main()
{
    // Set up the ODBC environment
    SQLRETURN ret;
    SQLHENV hdlEnv;
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate a handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated an environment handle.\n");
    }
    // Tell ODBC that the application uses ODBC 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not set application version to ODBC3.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Set application to ODBC 3.\n");
    }
    // Allocate a database handle.
    SQLHDBC hdlDbc;
    ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    // Connect to the database
    printf("Connecting to database.\n");
    const char *dsnName = "ExampleDB";
    const char* userID = "dbadmin";
    const char* passwd = "password123";
    ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
        SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
        (SQLCHAR*)passwd, SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not connect to database.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Connected to database.\n");
    }

    // Disable AUTOCOMMIT
    printf("Disabling autocommit.\n");
    ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF,
        SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not disable autocommit.\n");
        exit(EXIT_FAILURE);
    }


    // Set up a statement handle
    SQLHSTMT hdlStmt;
    SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);
    SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers",
        SQL_NTS);
    SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers "
        "(CustID int, CustName varchar(100), Phone_Number char(15));",
        SQL_NTS);

    // Set up a bunch of variables to be bound to the statement
    // parameters.

    // Create the prepared statement. This will insert data into the
    // table we created above.
    printf("Creating prepared statement\n");
    ret = SQLPrepare (hdlStmt, (SQLTCHAR*)"INSERT INTO customers (CustID, "
        "CustName,  Phone_Number) VALUES(?,?,?)", SQL_NTS) ;
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not create prepared statement\n");
        SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
        SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
        SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
        exit(EXIT_FAILURE);
    } else {
        printf("Created prepared statement.\n");
    }
    SQLINTEGER custID = 1234;
    SQLCHAR custName[100] = "Fein, Fredrick";
    SQLVARCHAR phoneNum[15] = "555-123-6789";
    SQLLEN strFieldLen = SQL_NTS;
    SQLLEN custIDLen = 0;
    // Bind the data arrays to the parameters in the prepared SQL
    // statement
    ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER,
        0, 0, &custID, 0 , &custIDLen);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind custID array\n");
        SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
        SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
        SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
        exit(EXIT_FAILURE);
    } else {
        printf("Bound custID to prepared statement\n");
    }
    // Bind CustNames
    SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
        50, 0, (SQLPOINTER)custName,  0, &strFieldLen);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind custNames\n");
        SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
        SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
        SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
        exit(EXIT_FAILURE);
    } else {
        printf("Bound custName to prepared statement\n");
    }
    // Bind phoneNums
    SQLBindParameter(hdlStmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
        15, 0, (SQLPOINTER)phoneNum, 0, &strFieldLen);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind phoneNums\n");
        SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
        SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
        SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
        exit(EXIT_FAILURE);
    } else {
        printf("Bound phoneNum to prepared statement\n");
    }
    // Execute the prepared statement.
    printf("Running prepared statement...");
    ret = SQLExecute(hdlStmt);
    if(!SQL_SUCCEEDED(ret)) {
        printf("not successful!\n");
    }  else {
        printf("successful.\n");
    }

    // Done with batches, commit the transaction
    printf("Committing transaction\n");
    ret = SQLEndTran(SQL_HANDLE_DBC, hdlDbc, SQL_COMMIT);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not commit transaction\n");
    }  else {
        printf("Committed transaction\n");
    }

    // Clean up
    printf("Free handles.\n");
    ret = SQLDisconnect( hdlDbc );
    if(!SQL_SUCCEEDED(ret)) {
        printf("Error disconnecting. Transaction still open?\n");
        exit(EXIT_FAILURE);
    }
    SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    exit(EXIT_SUCCESS);
}

3.1.13.3 - 使用批量插入

可以使用批量插入将数据区块插入到数据库中。通过将数据拆分为多个批，您可以在加载每个批后收到有关任何拒绝的行的信息，从而监控加载进度。若要通过 ODBC 执行批量加载，通常可以将预定义的语句与绑定到数组（包含要加载的数据）结合使用。对于每个批，应将新的数据集加载到数组中，然后执行预定义的语句。

执行批量加载时，Vertica 使用 COPY 语句加载数据。所加载的其他每个批使用同一个 COPY 语句。该语句将保持打开，直至您执行以下操作为止：结束语句，关闭语句的光标或执行非 INSERT 语句。

将单个 COPY 语句用于多个批可以通过以下途径提高批量加载效率：

• 减少插入各个批的开销

• 将各个批合并为较大的 ROS 容器

虽然 Vertica 使用单个 COPY 语句插入一个事务中的多个批，但您可以在加载每个批之后查找由于行格式无效或存在数据类型问题而被拒绝的行（如果有）。有关详细信息，请参阅跟踪加载状态 (ODBC)。

由于批量加载共享一个 COPY 语句，因此一个批中的错误会导致回退同一个事务中较早的批。

批量插入步骤

应用程序执行 ODBC 批量插入所需完成的步骤如下：

1. 连接到数据库。

2. 禁用连接的自动提交。

3. 创建可插入要加载的数据的预定义的语句。

4. 将该预定义的语句的参数绑定到包含要加载的数据的数组。

5. 使用各个批的数据填充数组。

6. 执行该预定义的语句。

7. （可选）检查批量加载的结果，以查找拒绝的行。

8. 重复以上三个步骤，直至已加载所有要加载的数据为止。

9. 提交事务。

10. （可选）检查整个批处理事务的结果。

以下示例代码演示了以上步骤的简化版本。

// Some standard headers
#include <stdio.h>
#include <stdlib.h>
// Only needed for Windows clients
// #include <windows.h>
// Standard ODBC headers
#include <sql.h>
#include <sqltypes.h>
#include <sqlext.h>
int main()
{
    // Number of data rows to insert
    const int NUM_ENTRIES = 4;

    // Set up the ODBC environment
    SQLRETURN ret;
    SQLHENV hdlEnv;
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlEnv);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate a handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated an environment handle.\n");
    }
    // Tell ODBC that the application uses ODBC 3.
    ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not set application version to ODBC3.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Set application to ODBC 3.\n");
    }
    // Allocate a database handle.
    SQLHDBC hdlDbc;
    ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlEnv, &hdlDbc);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not allocate database handle.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Allocated Database handle.\n");
    }
    // Connect to the database
    printf("Connecting to database.\n");
    const char *dsnName = "ExampleDB";
    const char* userID = "dbadmin";
    const char* passwd = "password123";
    ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName,
        SQL_NTS,(SQLCHAR*)userID,SQL_NTS,
        (SQLCHAR*)passwd, SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not connect to database.\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Connected to database.\n");
    }


    // Disable AUTOCOMMIT
    printf("Disabling autocommit.\n");
    ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF,
                            SQL_NTS);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not disable autocommit.\n");
        exit(EXIT_FAILURE);
    }

    // Set up a statement handle
    SQLHSTMT hdlStmt;
    SQLAllocHandle(SQL_HANDLE_STMT, hdlDbc, &hdlStmt);

    // Create a table to hold the data
    SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers",
        SQL_NTS);
    SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers "
        "(CustID int, CustName varchar(100), Phone_Number char(15));",
        SQL_NTS);

    // Create the prepared statement. This will insert data into the
    // table we created above.
    printf("Creating prepared statement\n");
    ret = SQLPrepare (hdlStmt, (SQLTCHAR*)"INSERT INTO customers (CustID, "
        "CustName,  Phone_Number) VALUES(?,?,?)", SQL_NTS) ;
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not create prepared statement\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Created prepared statement.\n");
    }
    // This is the data to be inserted into the database.
    SQLCHAR custNames[][50] = { "Allen, Anna", "Brown, Bill", "Chu, Cindy",
        "Dodd, Don" };
    SQLINTEGER custIDs[] = { 100, 101, 102, 103};
    SQLCHAR phoneNums[][15] = {"1-617-555-1234", "1-781-555-1212",
        "1-508-555-4321", "1-617-555-4444"};
    // Bind the data arrays to the parameters in the prepared SQL
    // statement. First is the custID.
    ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER,
        0, 0, (SQLPOINTER)custIDs, sizeof(SQLINTEGER) , NULL);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind custID array\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Bound CustIDs array to prepared statement\n");
    }
    // Bind CustNames
    ret = SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
        50, 0, (SQLPOINTER)custNames, 50, NULL);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind custNames\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Bound CustNames array to prepared statement\n");
    }
    // Bind phoneNums
    ret = SQLBindParameter(hdlStmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
        15, 0, (SQLPOINTER)phoneNums, 15, NULL);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind phoneNums\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Bound phoneNums array to prepared statement\n");
    }
    // Tell the ODBC driver how many rows we have in the
    // array.
    ret = SQLSetStmtAttr( hdlStmt, SQL_ATTR_PARAMSET_SIZE,
        (SQLPOINTER)NUM_ENTRIES, 0 );
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not bind set parameter size\n");
        exit(EXIT_FAILURE);
    } else {
        printf("Bound phoneNums array to prepared statement\n");
    }

    // Add multiple batches to the database. This just adds the same
    // batch of data four times for simplicity's sake. Each call adds
    // the 4 rows into the database.
    for (int batchLoop=1; batchLoop<=5; batchLoop++) {
        // Execute the prepared statement, loading all of the data
        // in the arrays.
        printf("Adding Batch #%d...", batchLoop);
        ret = SQLExecute(hdlStmt);
        if(!SQL_SUCCEEDED(ret)) {
           printf("not successful!\n");
        }  else {
            printf("successful.\n");
        }
    }
    // Done with batches, commit the transaction
    printf("Committing transaction\n");
    ret = SQLEndTran(SQL_HANDLE_DBC, hdlDbc, SQL_COMMIT);
    if(!SQL_SUCCEEDED(ret)) {
        printf("Could not commit transaction\n");
    }  else {
        printf("Committed transaction\n");
    }

    // Clean up
    printf("Free handles.\n");
    ret = SQLDisconnect( hdlDbc );
    if(!SQL_SUCCEEDED(ret)) {
        printf("Error disconnecting. Transaction still open?\n");
        exit(EXIT_FAILURE);
    }
    SQLFreeHandle(SQL_HANDLE_STMT, hdlStmt);
    SQLFreeHandle(SQL_HANDLE_DBC, hdlDbc);
    SQLFreeHandle(SQL_HANDLE_ENV, hdlEnv);
    exit(EXIT_SUCCESS);
}