#连接数据库

# 连接信息

YashanDB服务端的连接信息主要包括认证信息和服务端地址。若使用驱动连接YashanDB，可能还涉及多地址连接。

# 认证信息

认证信息是指用于登录YashanDB的用户名和认证凭据。

格式说明

username/password
/ 连接并登录数据库的用户名和密码，通过操作系统认证登录时可免密（即省略用户名和密码），但不能省略/。
如果在yashan模式下创建用户时用户名未使用双引号包围，使用yasql连接时大小写不敏感。
如果用户名或密码中含有OS命令相关的特殊字符（例如@、/、.、!、$、'等）需进行转义改写。

as role_name 声明用户登录时采用的角色，可选项包括系统管理员SYSDBA、管理员DBA、安全管理员SECURITY_ADMIN、审计管理员AUDIT_ADMIN以及普通用户NORMAL，其中NORMAL声明与否均无影响。角色名称大小写不敏感。

在以下场景中，登录时必须声明角色且用户与角色匹配才能登录成功：
* 采用操作系统认证登录时，必须声明角色为SYSDBA。
* 开启三权分立且强制要求管理员用户登录时声明角色（默认不强制，如需启用该功能请联系我们的技术支持）时，各类管理员登录时必须声明其相应的角色。

格式	说明
username/password /	连接并登录数据库的用户名和密码，通过操作系统认证登录时可免密（即省略用户名和密码），但不能省略`/`。如果在yashan模式下创建用户时用户名未使用双引号包围，使用yasql连接时大小写不敏感。如果用户名或密码中含有OS命令相关的特殊字符（例如`@`、`/`、`.`、`!`、`$`、`'`等）需进行转义改写。
as role_name	声明用户登录时采用的角色，可选项包括系统管理员`SYSDBA`、管理员`DBA`、安全管理员`SECURITY_ADMIN`、审计管理员`AUDIT_ADMIN`以及普通用户`NORMAL`，其中`NORMAL`声明与否均无影响。角色名称大小写不敏感。在以下场景中，登录时必须声明角色且用户与角色匹配才能登录成功： * 采用操作系统认证登录时，必须声明角色为SYSDBA。 * 开启三权分立且强制要求管理员用户登录时声明角色（默认不强制，如需启用该功能请联系我们的技术支持）时，各类管理员登录时必须声明其相应的角色。

用户名或密码中含有特殊符号（下划线除外）时，处理建议如下：

创建/管理用户等操作中指定相应值时需使用双引号包围。
登录数据库时，为确保yasql能正确向数据库服务端转递用户名和密码的值，建议分步登录，此类用户名或密码只需使用双引号包围即可，若直接登录则需对其进行相应改写：
- 如果用户名或密码中本身不存在单引号，直接使用单引号包围即可进行传递，例如user@name、password$需转义改写为'"user@name"'/'"password$"'。
- 如果用户名或密码中本身已存在单引号，则无法再使用单引号进行传递，需酌情使用转义符和双引号：
  - 如果同时存在单引号和Linux系统等环境下的功能符号，例如变量替换符号、变量替换符、转义符等，即\、$、"、'，需使用多重转义，例如user'1$name、pass'1\word需转义改写为"\"user'1\$name\""/"\"pass'1\\word\""。
  - 如果存在单引号且不存在上述功能符号，则需要叠加使用双引号，例如user'name、password需转义改写为"\"user'name\""/password。

# 服务端地址

服务端地址可以为URL或别名，需正确且唯一指向目标服务端的监听地址（即yasboot cluster status命令回显结果中的listen_address）。

信息类型	格式	说明
URL	@host:port[/pdb_name]	* host：数据库所在服务器的网络地址，可以为IPv4地址、IPv6地址或域名。在共享集群部署中，若已配置SCAN或VIP，还可以使用相应的域名或IP地址。 * port：数据库服务端监听端口，如安装过程中未进行调整，默认为1688。 * pdb_name：仅用于容器数据库，指定连接到具体某个PDB，省略则默认连接至根容器。
无URL		采用UDS本地连接访问$YASDB_DATA环境变量对应的数据库实例。在容器数据库中，该方式只能连接至根容器。使用该方式连接数据库属于高权限操作，请合理使用。
别名	@别名	使用自定义的别名连接数据库。别名需提前在客户端所在设备的$YASDB_HOME/client/yasc_service.ini文件中定义，格式为`alias = host:port[/pdb_name]`。例如别名定义为`yashan = 192.168.1.2:1688`则可直接使用`@yashan`连接该地址所指向的数据库。

# 多地址连接

在使用驱动连接存在多个节点的YashanDB服务端时，可以配置多个或多组监听地址（host:port）进行连接。

多个监听地址间用,分隔，连接时根据服务类型（serverType参数）配置对相应节点进行连接。
多组监听地址间用;分隔，同组内的多个监听地址间用,分隔，连接时先在组内根据serverType配置对相应节点进行连接，当组内所有连接均失败后按顺序优先级（越靠前优先级越高）访问下一组。

Note:

在共享集群/分布式集群部署中，若已配置SCAN或VIP，直接使用数据库服务端提供的高可用能力即可，无需额外配置多地址连接。

配置多地址连接共享集群/分布式集群时：
若为单集群部署，驱动会将其所有实例视作主节点。

在主备集群部署中，驱动会将主集群的所有实例视作主节点、备集群的所有实例视作备节点。

多组监听地址连接的故障切换效率低于多个监听地址连接，分组主要用于尽可能保障仅通过第一组地址建立数据库连接，请根据实际需求选择是否分组。

serverType	说明	适用驱动（yashan模式）	适用驱动（mysql模式）
primary	按顺序优先级连接主节点，驱动将按照指定的监听地址先后顺序对节点进行角色判断并连接首个主节点。默认类型，可省略。	JDBC驱动 C驱动 OCI驱动 ODBC驱动 Go驱动 Python驱动	JDBC驱动 C驱动
standby	按顺序优先级连接备节点，驱动将按照指定的监听地址先后顺序对节点进行角色判断并连接首个符合要求的节点。	JDBC驱动 C驱动 OCI驱动 ODBC驱动	JDBC驱动 C驱动
loadBalance	负载均衡连接最优节点，驱动将自动识别出连接数最少的节点并连接。	JDBC驱动 C驱动 OCI驱动 ODBC驱动 Go驱动 Python驱动	JDBC驱动 C驱动
primaryLoadBalance	负载均衡连接最优的主节点，驱动会先判别节点角色，再识别出连接数最少的主节点进行连接。若连接数相同，则按优先级顺序连接靠前的节点。	JDBC驱动 C驱动 OCI驱动 ODBC驱动	JDBC驱动 C驱动
standbyLoadBalance	负载均衡连接最优的备节点，驱动会先判别节点角色，再识别出连接数最少的备节点进行连接。若连接数相同，则按优先级顺序连接靠前的节点。	JDBC驱动 C驱动 OCI驱动 ODBC驱动	JDBC驱动 C驱动

# 连接YashanDB（yashan模式）

连接YashanDB服务端（yashan模式）的工具包括YashanDB客户端（yasql）、YashanDB驱动、YashanDB配套的崖山开发者中心YDC以及通用型第三方数据库管理工具（例如DBeaver、Navicat）等。

# 前提条件

在容器数据库中，指定pdb_name连接指定PDB时，需使用配套的v23.5.1.100及以上版本的客户端。
已完成YashanDB客户端安装和环境变量配置，如在服务端所在服务器的安装用户下连接本地数据库，则无需重复安装yasql。
需确保用户已具有CREATE SESSION权限（或CONNECT角色）。
需确保发起连接的设备IP不在黑名单中。

# 连接操作

本文仅介绍如何使用YashanDB客户端（yasql）连接YashanDB服务端（yashan模式），YashanDB驱动/配套工具的连接方式将在对应文档中详细介绍。

# 一步登录

命令格式如下：

# 一步登录
$ yasql [-S] {认证信息}{服务端地址} [登录角色]
# 常见写法如下：
$ yasql [-S] username/password@host:port[/pdb_name]
$ yasql [-S] / as sysdba

- S表示静默登录，需确保-S为首个参数，该参数不区分大小写。使用该方式登录并连接数据库不返回命令行提示、命令回显信息、登录提示信息和版本信息。

以sys用户登录数据库示例：（若当前环境为容器数据库则表示登录根容器）

# 本地登录时可以使用操作系统认证方式登录
$ yasql / as sysdba

# 使用密码认证方式登录
$ yasql sys/********@192.168.1.2:1688

YashanDB SQL Enterprise Edition Release {version_number} x86_64

Connected to:
YashanDB Server Enterprise Edition Release {version_number} x86_64 - Linux

SQL>

以sales用户登录PDB1示例：

$ yasql sales/********@192.168.1.2:1688/pdb1
YashanDB SQL Enterprise Edition Release {version_number} x86_64

Connected to:
YashanDB Server Enterprise Edition Release {version_number} x86_64 - Linux

SQL>

出现SQL命令行提示符表示连接成功，若为静默登录则不会出现SQL提示符。

# 分步登录

命令格式如下：

# 1. 启动yasql，打开登录窗口
$ yasql /nolog

# 2. 使用connect或conn命令连接并登录数据库
SQL> conn {认证信息}{服务端地址}

以sales用户登录示例：

$ yasql /nolog
YashanDB SQL Enterprise Edition Release {version_number} x86_64
SQL> conn sales/********@192.168.1.2:1688

Connected to:
YashanDB Server Enterprise Edition Release {version_number} x86_64 - Linux

SQL>

# 退出登录

命令格式如下：

exit

# 连接YashanDB（mysql模式）

连接YashanDB服务端（mysql模式）的工具除了YashanDB客户端（yasql）、YashanDB JDBC驱动、YashanDB C驱动外，还支持MySQL的生态周边配套工具，例如MySQL客户端、MySQL Connector/J等。

本章节仅介绍通过YashanDB客户端（yasql）和MySQL客户端连接崖山数据库。

当通过驱动连接数据库时，可参考JDBC驱动和C驱动了解详细的连接方式。

Note:

以mysql模式安装后，在数据库OPEN阶段新建的所有会话默认为mysql模式，在NOMOUNT或MOUNT阶段创建的会话则仍为yashan模式。

# 使用yasql连接

# 前提条件

已完成YashanDB客户端安装和环境变量配置，如在服务端所在服务器的安装用户下连接本地数据库，则无需重复安装yasql。
需确保发起连接的设备IP不在黑名单中。

# 连接操作

为正确将用户名传递至数据库服务端，使用yasql以mysql模式下创建的用户连接YashanDB服务端（mysql模式）时需要使用双引号将用户名包围。

分步登录

命令格式如下：

# 1. 启动yasql，打开登录窗口
$ yasql /nolog

# 2. 使用connect或conn命令连接并登录数据库
SQL> conn {认证信息}{服务端地址}

以sales用户登录示例：

$ yasql /nolog
YashanDB SQL Enterprise Edition Release {version_number} x86_64
SQL> conn "sales"/********@192.168.1.2:1688

Connected to:
YashanDB Server Enterprise Edition Release {version_number} x86_64 - Linux

SQL>

一键登录

命令格式如下：
```
# 一步登录
$ yasql [-S] {认证信息}{服务端地址}  
# 常见写法如下：
$ yasql [-S] username/password@host:port[/pdb_name]  
$ yasql [-S] / as sysdba
```
参数介绍：
- - S：表示静默登录，需确保-S为首个参数，该参数不区分大小写。使用该方式登录并连接数据库不返回命令行提示、命令回显信息、登录提示信息和版本信息。
- {认证信息}、{服务端地址}：详情请查阅连接信息。
以sales用户登录示例：
```
$ yasql \"sales\"/********@192.168.1.2:1688
YashanDB SQL Enterprise Edition Release {version_number} x86_64

Connected to:
YashanDB Server Enterprise Edition Release {version_number} x86_64 - Linux

SQL> 
```
出现SQL命令行提示符表示连接成功，若为静默登录则不会出现SQL提示符。
退出登录
```
exit
```

# 使用MySQL客户端连接

# 使用规则

使用MySQL的生态周边配套工具连接YashanDB（mysql模式）时，存在以下规则：

无法使用超级管理员sys登录。
默认使用MySQL协议的监听地址（即yashandb.toml配置文件中的mysql_addr）。

# 前提条件

已完成MySQL客户端安装和环境变量配置。
已创建普通用户。
需确保发起连接的设备IP不在黑名单中。

# 连接操作

登录

登录命令格式如下：
```
$ mysql -h {host} -P {port} -u {username} -p{password} [-D {database_name}]
```
参数介绍：
- -h {host}：数据库所在服务器的IP地址。
- -P {port}：数据库服务端MySQL协议的监听端口（即yashandb.toml配置文件中mysql_addr的端口部分），如安装过程中未进行调整，端口号默认为1690（单机及单机主备）或1691（共享集群）。
- -u {username}：数据库用户名。
- -p{password}：用户名对应的登录密码。
- {database_name}：可选项，指定连接YashanDB后当前会话中后续操作的默认数据库。如不指定，则不进入任何数据库，连接后可通过USE语句进行指定。
以sales用户登录示例：
```
-- the default port is 1690 (Standalone deployment) or 1691 (YAC deployment)
$ mysql -h 192.168.1.2 -P 1690 -u sales -p********

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 15
Server version: {版本信息}

……

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>
```
退出登录
```
exit
```