Linux系统下配置数据源

在通过ODBC访问数据库之前，需要确保环境中已正确安装ODBC驱动及相关依赖。应用程序与数据库之间的通信依赖数据源（Data Source Name，DSN）配置，ODBC驱动程序管理器将根据DSN信息加载对应驱动、建立连接，并向应用程序提供统一的API接口。

本节说明如何在Linux系统下配置ODBC数据源（包含驱动配置文件与DSN配置文件的编辑要求），以及这些配置在连接流程中的作用。完成此步骤后，应用程序即可使用标准ODBC API调用数据库。

操作步骤

安装unixODBC（默认已获取unixODBC源码包）。若机器已安装了其他版本的unixODBC，可直接覆盖安装。
以unixODBC-2.3.7版本为例，在客户端执行如下命令安装unixODBC：
```
tar zxvf unixODBC-2.3.7.tar.gz
cd unixODBC-2.3.7

./configure --enable-gui=no #若在ARM架构服务器上编译，请追加一个configure参数： --build=aarch64-unknown-linux-gnu 
make
#安装可能需要root权限
make install
```
- 目前不支持unixODBC-2.2.1版本。
- 默认安装至“/usr/local”目录下，生成数据源文件到 “/usr/local/etc”目录下，库文件生成到“/usr/local/lib”目录。
- 通过编译带有--enable-fastvalidate=yes选项的unixODBC可提升性能，但可能会导致向ODBC API传递无效句柄的应用程序发生故障，而非返回SQL_INVALID_HANDLE错误。
替换客户端GaussDB驱动程序。

解压GaussDB-Kernel_数据库版本号_操作系统信息_64bit_Odbc.tar.gz，解压后会得到lib和odbc两个文件夹，在odbc文件夹中还会有一个lib文件夹，将/lib文件夹与/odbc/lib文件夹中的所有动态库都复制到“/usr/local/lib”目录下。

配置数据源。

配置ODBC驱动文件。

在“/usr/local/etc/odbcinst.ini”文件中追加以下内容：

[GaussMPP]
Driver64=/usr/local/lib/gsqlodbcw.so
setup=/usr/local/lib/gsqlodbcw.so

odbcinst.ini文件中的配置参数说明如表1所示：

表1 odbcinst.ini文件配置参数
参数	描述	示例
[DriverName]	驱动器名称，对应数据源DSN中的驱动名。	[GaussMPP]
Driver64	驱动动态库的路径。	Driver64=/usr/local/lib/gsqlodbcw.so
setup	驱动安装路径，与Driver64中动态库的路径一致。	setup=/usr/local/lib/gsqlodbcw.so

配置数据源文件。
在“/usr/local/etc/odbc.ini”文件中追加以下内容：
```
[gaussdb]
Driver=GaussMPP
#数据库Server IP
Servername=127.0.0.1
#数据库名
Database=db1
#数据库用户名
Username=omm
#数据库用户密码
Password=
#数据库侦听端口
Port=8000
Sslmode=allow
```
当需要变更已有数据源的参数（如服务器IP、端口、数据库名称或认证信息）时，可直接编辑odbc.ini文件中对应的DSN（Data Source Name）条目并更新相关配置项。修改并保存后，新配置将在应用程序下一次建立连接时生效。

若不再使用某个数据源，可在odbc.ini文件中删除该DSN的完整配置段。删除后，依赖该DSN的应用程序将无法再通过其建立ODBC连接。

odbc.ini文件配置参数说明如表1所示：

在客户端配置环境变量。

vim ~/.bashrc

在配置文件中追加以下内容：

export LD_LIBRARY_PATH=/usr/local/lib/:$LD_LIBRARY_PATH
export ODBCSYSINI=/usr/local/etc
export ODBCINI=/usr/local/etc/odbc.ini

执行如下命令使设置生效。
```
source ~/.bashrc
```
测试连接。

安装后，/usr/bin目录下面会存放生成的二进制文件。

执行以下命令，其中“gaussdb”为数据源名称：
```
isql -v gaussdb
```
- 若显示如下信息，表明配置正确，连接成功。
```
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
```
- 若显示ERROR信息，则表明配置错误。请检查上述配置步骤是否正确执行。
- 若是集群环境，需要在所有机器上都复制配置一份unixODBC。
目前通过ODBC连接数据库时，会如下设置内核参数：
```
SET extra_float_digits = 2;
SET DateStyle = 'ISO';
```
这些参数可能会导致ODBC客户端的行为与gsql客户端的行为不一致，例如，Date数据显示方式、浮点数精度表示。如果实际期望和这些配置不符，建议在ODBC应用代码中显式设定这些参数。

M-Compatibility模式数据库下，extra_float_digits的默认值为0。

常见问题处理

[UnixODBC][Driver Manager]Can't open lib 'xxx/xxx/gsqlodbcw.so':file not found.
此问题的可能原因：
- odbcinst.ini文件中配置的路径不正确。
  确认的方法：执行ls命令查询错误信息中的路径，以确保该gsqlodbcw.so文件存在，同时具有执行权限。
- gsqlodbcw.so的依赖库不存在，或者不在系统环境变量中。
  确认的方法：执行ldd命令查询错误信息中的路径，如果是缺少libodbc.so.1等UnixODBC的库，那么按照“操作步骤”中的方法重新配置UnixODBC，并确保它的安装路径下的lib目录添加到了LD_LIBRARY_PATH中。如果重装仍无法解决，可以手动将数据库安装包下的unixodbc/lib下的内容复制到UnixODBC的安装路径下的lib目录。如果是缺少其他库，请将ODBC驱动包中的lib目录添加到LD_LIBRARY_PATH中。如果缺少其他标准库，请自行安装。
[UnixODBC]connect to server failed: no such file or directory
此问题的可能原因：
- 配置了错误的/不可达的数据库地址或者端口。
  请检查数据源配置中的Servername及Port配置项。
- 服务器侦听不正确。
  如果确认Servername及Port配置正确，请根据操作步骤中数据库服务器的相关配置，确保数据库侦听了合适的网卡及端口。
- 防火墙及网闸设备。
  请确认防火墙设置，将数据库的通信端口添加到可信端口中。
  
  如果有网闸设备，请确认相关的设置。
[unixODBC]The password-stored method is not supported.
此问题的可能原因：

数据源中未配置Sslmode配置项。

请配置该选项至allow或以上选项。此配置的更多信息，请参见表2。
Server common name "xxxx" does not match host name "xxxxx"
此问题的可能原因：

使用了SSL加密的“verify-full”选项，驱动程序会验证证书中的主机名与实际部署数据库的主机名是否一致。

碰到此问题可以使用“verify-ca”选项，不再校验主机名，或者重新生成一套与数据库所在主机名相同的服务端证书。
Driver's SQLAllocHandle on SQL_HANDLE_DBC failed
此问题的可能原因：

可执行文件（比如UnixODBC的isql，以下都以isql为例）与数据库驱动（gsqlodbcw.so）依赖于不同的ODBC的库版本：libodbc.so.1或者libodbc.so.2。此问题可以通过如下方式确认：
```
ldd `which isql` | grep odbc
ldd gsqlodbcw.so | grep odbc
```
这时，如果输出的libodbc.so最后的后缀数字不同或者指向不同的磁盘物理文件，那么基本就可以断定是此问题。isql与gsqlodbcw.so都会要求加载libodbc.so，这时如果它们加载的是不同的物理文件，便会导致两套完全同名的函数列表，同时出现在同一个可见域里（UnixODBC的libodbc.so.*的函数导出列表完全一致），产生冲突，无法加载数据库驱动。

确定一个要使用的UnixODBC，卸载另外一个（比如卸载库版本号为.so.2的UnixODBC），然后将剩下的.so.1的库，新建一个同名但是后缀为.so.2的软链接，便可解决此问题。
FATAL: Forbid remote connection with trust method!
此问题的可能原因：

由于安全原因，数据库CN禁止集群内部其他节点无认证接入。

如果需要在集群内部访问CN，请将ODBC程序部署在CN所在机器，服务器地址使用“127.0.0.1”。建议业务系统单独部署在集群外部，否则可能会影响数据库运行性能。
[unixODBC][Driver Manager]Invalid attribute value
此问题的可能原因：

在使用SQL on other GaussDB功能时出现此问题，可能与非推荐版本的unixODBC相关。

建议通过执行“odbcinst --version”命令验证环境中的unixODBC版本。
authentication method 10 not supported.
使用开源客户端时出现此错误。可能原因：

数据库中用户密码仅以SHA256哈希值的形式存储，而不存储明文密码。

早期版本为了兼容某些开源客户端，同时存储了MD5哈希值和SHA256哈希值两种格式。当用户登录时，服务端会优先尝试使用客户端发送的校验方式（MD5或SHA256）进行验证对应的哈希值。

在从旧版本数据库升级到新版本时，由于哈希算法的单向不可逆特性，系统无法从已有的SHA256哈希值逆推出原始明文密码，也就无法再生成对应的MD5哈希值。因此升级完成后，数据库中只保留了SHA256哈希值，导致使用MD5校验方式的开源客户端认证失败，报此错误。

MD5算法已被证明存在严重的安全缺陷，不再推荐使用。建议所有客户端逐步升级到支持SHA256或更强哈希算法的版本，以彻底消除兼容性与安全隐患。

该问题的解决方案包括：
- 更新用户密码（请参见《参考》中“SQL参考 > SQL语法 > A > ALTER USER”）。
- 新建用户并赋予和原用户同等的权限（请参见《参考》中“SQL参考 > SQL语法 > C > CREATE USER”），使用新用户连接数据库。
unsupported frontend protocol 3.51: server supports 1.0 to 3.0
此问题的可能原因：

目标数据库版本过低，或者目标数据库为开源数据库。

请使用与目标数据库版本匹配的数据库驱动连接目标数据库。
FATAL: GSS authentication method is not allowed because XXXX user password is not disabled.
目标CN的gs_hba.conf文件中，配置了当前客户端IP使用“gss”方式来做认证。该认证算法不支持用作客户端的身份认证。请修改配置为“sha256”后重试。
isql：error while loading shared libraries:xxx
当前环境缺少该动态库文件，需要自行安装对应的动态库。