PostgreSQL / 系统课时
使用 psql 连接数据库
使用 psql 连接数据库
安装 PostgreSQL 后,需要先用 psql 连接目标数据库,确认服务器、账号和数据库名都正确。本课从本机登录开始,再通过显式参数建立 TCP 连接,最后使用 SQL 和客户端命令验证连接状态,并排查常见连接错误。
学习目标
- 掌握
psql的本机登录方式和完整连接命令。 - 理解主机、端口、用户和数据库参数的作用。
- 学会验证当前连接,并根据错误信息定位连接失败的原因。
使用 psql 建立连接
psql 是 PostgreSQL 官方命令行客户端,可以执行 SQL、查看数据库对象和管理连接。连接时最核心的信息包括服务器地址、端口、用户名和目标数据库。
如果在 Linux 上通过系统软件包安装 PostgreSQL,通常会创建名为 postgres 的操作系统用户和同名数据库角色。在具备 sudo 权限、数据库服务已经启动的前提下,可以执行:
# 切换为系统用户 postgres,并连接 postgres 数据库
sudo -u postgres psql -d postgres预期输出:
psql (<VERSION>)
Type "help" for help.
postgres=#<VERSION> 表示实际安装的客户端版本,具体数字可能不同。出现 postgres=# 提示符,说明已经成功建立会话。其中 postgres 是当前数据库名,默认提示符中的 # 通常表示当前数据库角色是超级用户,普通角色一般显示 =>。
这条命令依赖 Linux 系统用户与 PostgreSQL 本地认证配置,并不适用于所有安装环境。如果使用 Windows、远程服务器,或者没有相应的系统权限,应改用明确指定连接参数的方式。
指定连接参数
跨用户、跨主机连接时,建议明确指定连接信息。例如,连接本机默认端口上的 postgres 数据库:
# 通过 TCP 连接本机 PostgreSQL,按服务器认证要求提供密码
psql -h 127.0.0.1 -p 5432 -U postgres -d postgres如果服务器要求密码认证,客户端会提示输入密码。认证成功后的预期结果为:
psql (<VERSION>)
Type "help" for help.
postgres=#这条命令要求数据库服务正在运行、postgres 角色与数据库存在,并且服务器允许该连接。能否使用密码登录取决于服务器的认证配置,不能认为所有新安装的 PostgreSQL 都已为 postgres 角色设置密码。
四个参数分别控制不同的连接信息:
-h:数据库服务器地址。127.0.0.1表示通过 TCP 连接本机;连接远程服务器时替换为服务器 IP 或域名。-p:数据库服务端口,PostgreSQL 默认通常使用5432。-U:用于认证的 PostgreSQL 数据库角色,不一定与操作系统用户名相同。-d:目标数据库名称,例如postgres。省略时通常默认使用与连接用户名相同的数据库名。
需要特别区分:在 Linux 上省略 -h 时,psql 通常尝试通过本地 Unix Socket 连接;指定 -h 127.0.0.1 则使用 TCP。两种方式可能匹配 pg_hba.conf 中不同的认证规则,因此同一账号可能出现本地连接成功、TCP 连接失败的情况。
查看当前连接信息
连接成功后,先确认会话实际进入了哪个数据库、正在使用哪个角色。在 psql 提示符中执行:
-- 检查当前数据库名称和认证后的数据库角色
SELECT current_database(), current_user;使用前面的 postgres 角色连接 postgres 数据库时,预期结果为:
current_database | current_user
------------------+--------------
postgres | postgres
(1 row)current_database() 返回当前数据库名称,current_user 返回当前有效数据库角色。它们可以帮助确认是否连错数据库或使用了错误的账号。实际结果以连接时使用的数据库和角色为准。
如果还需要核对连接采用的是 TCP 还是 Unix Socket,以及实际连接的服务器和端口,可以在 psql 中执行客户端元命令:
\conninfo预期结果:客户端显示当前数据库、用户和连接地址信息。TCP 连接通常会列出主机地址与端口,本地 Unix Socket 连接则会显示对应的套接字路径。显示内容取决于实际连接方式。
注意,\conninfo 属于 psql 客户端命令,不是标准 SQL,不能直接当作 SQL 语句发送给数据库驱动。检查完成后,输入 \q 即可退出交互式客户端并返回系统终端。
连接失败排查顺序
连接失败时,应先区分客户端、网络、认证和数据库对象这几个环节,不要一开始就修改服务器配置。
- 检查客户端是否安装。 如果提示
psql: command not found或系统找不到命令,先确认 PostgreSQL 客户端已经安装,且psql所在目录已加入PATH。 - 检查服务和端口。 如果出现
Connection refused,通常说明目标地址或端口没有服务接受连接;如果连接超时,则还需要检查网络连通性、防火墙和服务器监听地址。 - 检查认证方式和账号。
password authentication failed for user表示密码认证失败,应核对角色、密码和认证规则;Peer authentication failed通常与本地系统用户和数据库角色的匹配规则有关。 - 检查数据库是否存在。
database ... does not exist表示指定数据库不存在或数据库名有误,应检查-d参数,而不是反复修改密码。 - 检查访问规则。 如果出现
no pg_hba.conf entry,说明当前连接没有匹配的允许访问规则,需要由管理员检查来源地址、目标数据库、角色和认证配置。修改后按要求重新加载配置。
可以先用 PostgreSQL 提供的 pg_isready 检查本机服务是否接受连接:
# 只检查服务器是否接受连接,不验证账号权限
pg_isready -h 127.0.0.1 -p 5432服务正常接受连接时,预期输出为:
127.0.0.1:5432 - accepting connections如果服务不可达,则可能显示 no response 或 rejecting connections 等状态。pg_isready 的退出状态也可以用于脚本判断,但即使显示 accepting connections,也不代表指定用户已经通过身份认证,或者目标数据库一定存在。
排查时先确认服务可达,再检查 -h、-p、-U、-d 和认证规则。最终应重新执行完整的 psql 连接命令,并使用 SELECT current_database(), current_user; 核对结果;只有连接建立且数据库与角色符合预期,才算完成连接验证。