欢迎使用 HarborDB！本指南将引导您完成创建第一个 PostgreSQL 连接的过程。无论您是连接到 Mac 上的本地数据库还是远程服务器，HarborDB 都使这个过程变得简单安全。

先决条件

开始之前，请确保您有：

已安装 HarborDB（参见安装指南）
PostgreSQL 服务器正在运行且可访问
连接详细信息准备就绪：
- 主机名或 IP 地址
- 端口号（默认：5432）
- 数据库名称
- 用户名和密码
- 可选：如果需要，SSL 证书

步骤 1：启动 HarborDB 并访问连接

从您的应用程序文件夹或启动台打开 HarborDB
找到窗口左侧的连接侧边栏
点击"+"按钮或转到文件 → 添加连接

步骤 2：填写连接详细信息

连接对话框有几个字段需要填写：

基本信息

名称：此连接的友好名称（例如，"本地开发"、"生产服务器"）
主机：PostgreSQL 服务器地址
- 本地数据库：localhost 或 127.0.0.1
- 远程服务器：IP 地址或主机名（例如，db.example.com）
端口：PostgreSQL 端口（默认：5432）
数据库：要连接的特定数据库
用户名：您的 PostgreSQL 用户名
密码：您的 PostgreSQL 密码

高级选项（可选）

模式：首选模式（默认为 public）
SSL 模式：根据您的服务器配置选择：
- prefer：如果可用则使用 SSL
- require：需要 SSL 连接
- verify-full：需要 SSL 并验证证书
超时：连接超时时间（秒）
应用程序名称：此连接的自定义标识符

步骤 3：测试您的连接

保存前，始终测试您的连接：

在对话框中点击"测试连接"
等待确认 - 您应该看到"连接成功"
查看任何警告关于 SSL 或其他设置

常见测试结果

✅ 成功：您可以保存并连接了
❌ 失败：检查错误消息获取线索：
- "连接被拒绝"：服务器未运行或防火墙阻止
- "认证失败"：用户名/密码错误
- "数据库不存在"：数据库名称不正确

步骤 4：保存并保护您的连接

密码存储选项

HarborDB 提供安全的密码存储：

保存在钥匙串中（推荐）：密码在 macOS 钥匙串中加密
保存在连接中：密码与连接设置一起存储（安全性较低）
每次询问：每次连接时提示输入密码

选择正确的选项

| 存储方法 | 安全性 | 便利性 | 最适合 | | ------------ | ---------- | ---------- | ------------------------------ | | macOS 钥匙串 | 🔒 高 | ⚡ 高 | 日常使用，可信计算机 | | 连接文件 | 🔒 中等 | ⚡ 高 | 快速设置，测试 | | 每次询问 | 🔒 最高 | ⚡ 低 | 共享计算机，高安全性 |

保存您的连接

选择密码存储方法
**点击"保存"**存储连接
在连接侧边栏中找到您的连接
双击连接

步骤 5：连接并探索

连接后，您可以：

导航您的数据库

展开连接查看数据库
在侧边栏中浏览模式和表
右键单击表进行快速操作：
- 查看表结构
- 预览前 100 行
- 生成 SELECT 查询

快速开始操作

打开查询编辑器：点击 SQL 图标或按 ⌘ + N
运行测试查询：
```
SELECT version();
```
探索界面：熟悉选项卡、面板和工具

连接管理

组织多个连接

添加更多连接时，保持它们有序：

收藏：为常用连接加星标以便快速访问
分组：按项目、环境或团队组织
颜色编码：使用标签或命名约定

编辑现有连接

在侧边栏中右键单击连接
选择"编辑连接"
根据需要更新任何字段
测试并保存更改

复制连接

通过复制类似连接节省时间：

右键单击源连接
选择"复制"
仅修改更改的字段
另存为新连接

安全最佳实践

密码安全

切勿共享钥匙串密码
使用强密码用于 PostgreSQL 用户
定期轮换密码
避免在不同服务器间重复使用密码

连接安全

使用 SSL进行远程连接
限制数据库权限到必要操作
使用只读连接进行报告
定期审核连接日志

网络安全

防火墙配置：仅允许受信任的 IP
VPN 访问用于远程数据库
SSH 隧道用于额外的安全层

常见连接场景

本地 PostgreSQL（通过 Homebrew 安装）

名称：本地 PostgreSQL
主机：localhost
端口：5432
数据库：postgres
用户名：您的用户名
密码：[钥匙串]

Docker PostgreSQL 容器

名称：Docker 开发数据库
主机：localhost
端口：5432  # 如果映射不同，则为自定义端口
数据库：app_database
用户名：postgres
密码：postgres_password

Amazon RDS PostgreSQL

名称：AWS 生产环境
主机：your-db-instance.region.rds.amazonaws.com
端口：5432
数据库：production_db
用户名：app_user
SSL 模式：verify-full

Google Cloud SQL

名称：GCP Cloud SQL
主机：/cloudsql/project:region:instance
端口：5432
数据库：cloud_db
SSL 模式：require

连接问题故障排除

"无法连接到服务器"

验证 PostgreSQL 是否正在运行：

# 在终端中
pg_isready -h localhost -p 5432

检查防火墙设置：
- macOS 防火墙（系统偏好设置 → 安全性与隐私）
- 网络防火墙规则

测试网络连接性：

# 在终端中
ping your-server-address
telnet your-server-address 5432

"密码认证失败"

检查 PostgreSQL 认证方法：
- 查看 pg_hba.conf 文件
- 确保 md5 或 scram-sha-256 认证

如果需要，重置密码：

ALTER USER username WITH PASSWORD 'new_password';

验证用户是否有数据库访问权限：

-- 以超级用户身份连接
\du  -- 列出用户
\l   -- 列出数据库

SSL/TLS 连接错误

检查 SSL 要求：
- 服务器可能需要特定的 SSL 模式
- 可能需要导入证书
在连接设置中调整 SSL 模式
如果使用 verify-full 模式，导入证书

性能提示

连接池

保持连接打开用于频繁使用
关闭未使用的连接以释放资源
为应用程序使用连接池

网络优化

本地连接：使用 localhost 以获得最佳性能
远程连接：确保足够的带宽
压缩：处理大型结果集时启用

下一步

现在您已连接：

探索查询基础 - 学习编写和执行 SQL 查询
数据库导航 - 探索模式、表和关系
导出数据 - 将结果保存为 CSV 或 JSON

获取帮助

如果您仍然遇到困难：

**查看我们的支持指南**获取更多故障排除信息
**访问FAQ**获取常见问题
**联系支持**获取个性化帮助

创建您的第一个连接