invest-mind-store/packages/design-document/机生文档/PostgreSQL-Mac使用手册.md

PostgreSQL Mac 端使用手册

目录

1. 安装 PostgreSQL
2. 连接数据库
3. 查看所有数据库
4. 创建数据库
5. 切换数据库
6. 查看表
7. 创建表
8. 常用操作命令

---

一、安装 PostgreSQL

1.1 使用 Homebrew 安装（推荐）

# 安装 PostgreSQL（推荐使用最新版本）
brew install postgresql@18

# 或者安装其他版本
brew install postgresql@18
brew install postgresql@18

1.2 启动 PostgreSQL 服务

# 启动服务（开机自启）
brew services start postgresql@18

# 停止服务
brew services stop postgresql@18

# 重启服务
brew services restart postgresql@18

# 查看服务状态
brew services list

1.3 验证安装

# 查看版本
psql --version

# 查看 PostgreSQL 是否运行
pg_isready

---

二、连接数据库

2.1 使用 psql 命令行连接

# 方式1：连接到默认数据库（使用当前系统用户名）
psql

# 方式2：连接到指定数据库
psql -d postgres

# 方式3：指定用户名和数据库
psql -U postgres -d postgres

# 方式4：指定主机、端口、用户名和数据库
psql -h localhost -p 5432 -U postgres -d postgres

# 方式5：连接时输入密码（推荐用于脚本）
PGPASSWORD=your_password psql -U postgres -d postgres

2.2 连接后的提示符

连接成功后，你会看到类似这样的提示符：

postgres=#

• postgres 是当前连接的数据库名
• # 表示你是超级用户（$ 表示普通用户）

2.3 退出连接

-- 方式1：使用命令
\q

-- 方式2：使用快捷键
Ctrl + D

---

三、查看所有数据库

3.1 在 psql 中查看

-- 方式1：使用命令（推荐）
\l

-- 方式2：使用详细模式
\l+

-- 方式3：使用 SQL 查询
SELECT datname FROM pg_database;

-- 方式4：查看数据库详细信息
SELECT 
    datname AS "数据库名",
    pg_size_pretty(pg_database_size(datname)) AS "大小",
    datcollate AS "排序规则",
    datctype AS "字符集"
FROM pg_database
ORDER BY datname;

3.2 在命令行中查看（不进入 psql）

# 列出所有数据库
psql -l

# 或者
psql -U postgres -l

---

四、创建数据库

4.1 基本语法

CREATE DATABASE database_name;

4.2 创建数据库示例

-- 示例1：创建简单数据库
CREATE DATABASE myapp;

-- 示例2：创建数据库（指定编码和排序规则）
CREATE DATABASE myapp 
    WITH ENCODING 'UTF8' 
    LC_COLLATE='en_US.UTF-8' 
    LC_CTYPE='en_US.UTF-8';

-- 示例3：创建数据库（指定所有者）
CREATE DATABASE myapp OWNER username;

-- 示例4：创建数据库（指定模板）
CREATE DATABASE myapp TEMPLATE template0;

4.3 创建数据库的完整选项

CREATE DATABASE database_name
    [ [ WITH ] [ OWNER [=] user_name ]
    [ TEMPLATE [=] template ]
    [ ENCODING [=] encoding ]
    [ LC_COLLATE [=] lc_collate ]
    [ LC_CTYPE [=] lc_ctype ]
    [ TABLESPACE [=] tablespace_name ]
    [ ALLOW_CONNECTIONS [=] allowconn ]
    [ CONNECTION LIMIT [=] connlimit ]
    [ IS_TEMPLATE [=] istemplate ] ];

4.4 常用参数说明

参数	说明	示例
OWNER	数据库所有者	OWNER myuser
TEMPLATE	模板数据库	TEMPLATE template0
ENCODING	字符编码	ENCODING 'UTF8'
LC_COLLATE	排序规则	LC_COLLATE='en_US.UTF-8'
LC_CTYPE	字符分类	LC_CTYPE='en_US.UTF-8'

4.5 创建数据库的完整示例

-- 创建生产环境数据库
CREATE DATABASE vest_mind_prod
    WITH 
    OWNER = postgres
    ENCODING = 'UTF8'
    LC_COLLATE = 'en_US.UTF-8'
    LC_CTYPE = 'en_US.UTF-8'
    TEMPLATE = template0
    CONNECTION LIMIT = 100;

-- 创建开发环境数据库
CREATE DATABASE vest_mind_dev
    WITH 
    OWNER = postgres
    ENCODING = 'UTF8'
    TEMPLATE = template0;

4.6 验证数据库是否创建成功

-- 方式1：查看所有数据库（推荐）
\l

-- 方式2：使用 SQL 查询
SELECT datname FROM pg_database WHERE datname = 'database_name';

-- 方式3：查看数据库详细信息
SELECT 
    datname AS "数据库名",
    pg_size_pretty(pg_database_size(datname)) AS "大小",
    datcollate AS "排序规则",
    datctype AS "字符集"
FROM pg_database
WHERE datname = 'database_name';

4.7 创建数据库的注意事项

1. 数据库名称规则：

   • 必须以字母开头
   • 只能包含字母、数字、下划线和连字符
   • 不能使用 PostgreSQL 保留关键字
   • 建议使用小写字母和下划线

2. 权限要求：

   • 需要 CREATEDB 权限
   • 超级用户（如 postgres）可以创建任何数据库

3. 模板数据库：

   • template0：干净的模板，推荐使用
   • template1：默认模板，可以修改
   • 自定义模板：基于现有数据库创建

4. 字符编码：

   • 推荐使用 UTF8 编码
   • 确保 LC_COLLATE 和 LC_CTYPE 设置正确

4.8 创建数据库后立即使用

-- 创建数据库
CREATE DATABASE myapp;

-- 切换到新创建的数据库
\c myapp

-- 或者退出后重新连接
\q
psql -d myapp

4.9 删除数据库

-- 删除数据库（注意：需要先断开所有连接）
DROP DATABASE database_name;

-- 删除数据库（如果存在）
DROP DATABASE IF EXISTS database_name;

-- 强制删除数据库（终止所有连接后删除）
-- 首先终止所有连接
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE datname = 'database_name' AND pid <> pg_backend_pid();

-- 然后删除
DROP DATABASE database_name;

4.10 重命名数据库

-- 重命名数据库
ALTER DATABASE old_name RENAME TO new_name;

---

五、切换数据库

5.1 在 psql 中切换

-- 使用 \c 命令切换数据库
\c database_name

-- 切换到指定数据库并显示连接信息
\c database_name username

-- 查看当前连接的数据库
SELECT current_database();

-- 或者使用命令
\conninfo

5.2 退出后重新连接

# 退出当前连接
\q

# 重新连接到指定数据库
psql -d database_name

---

六、查看表

6.1 查看当前数据库中的所有表

-- 方式1：使用命令（推荐）
\dt

-- 方式2：查看详细信息（包括大小、描述等）
\dt+

-- 方式3：使用 SQL 查询
SELECT 
    schemaname AS "模式",
    tablename AS "表名"
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY tablename;

-- 方式4：查看所有表（包括系统表）
\dt *.*

6.2 查看表结构

-- 方式1：查看表结构（推荐）
\d table_name

-- 方式2：查看详细信息（包括索引、约束等）
\d+ table_name

-- 方式3：只查看列信息
\d table_name

-- 方式4：使用 SQL 查询列信息
SELECT 
    column_name AS "列名",
    data_type AS "数据类型",
    character_maximum_length AS "最大长度",
    is_nullable AS "可空",
    column_default AS "默认值"
FROM information_schema.columns
WHERE table_name = 'table_name'
ORDER BY ordinal_position;

6.3 查看表的索引

-- 查看表的所有索引
\d table_name

-- 或者使用 SQL
SELECT 
    indexname AS "索引名",
    indexdef AS "索引定义"
FROM pg_indexes
WHERE tablename = 'table_name';

6.4 查看表的约束

-- 查看表的所有约束
\d table_name

-- 或者使用 SQL
SELECT 
    conname AS "约束名",
    contype AS "约束类型",
    pg_get_constraintdef(oid) AS "约束定义"
FROM pg_constraint
WHERE conrelid = 'table_name'::regclass;

---

七、创建表

7.1 基本语法

CREATE TABLE table_name (
    column1_name data_type [constraints],
    column2_name data_type [constraints],
    ...
);

7.2 创建表示例

-- 示例1：创建用户表
CREATE TABLE users (
    user_id BIGSERIAL PRIMARY KEY,
    username VARCHAR(100) NOT NULL UNIQUE,
    email VARCHAR(100) UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

-- 示例2：创建订单表（带外键）
CREATE TABLE orders (
    order_id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
);

-- 示例3：创建带检查约束的表
CREATE TABLE products (
    product_id BIGSERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10, 2) NOT NULL CHECK (price > 0),
    stock INTEGER NOT NULL DEFAULT 0 CHECK (stock >= 0),
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

7.3 常用数据类型

数据类型	说明	示例
BIGSERIAL	自增整数（64位）	user_id BIGSERIAL PRIMARY KEY
BIGINT	大整数（64位）	user_id BIGINT
INTEGER	整数（32位）	age INTEGER
VARCHAR(n)	可变长度字符串	username VARCHAR(100)
TEXT	长文本	description TEXT
DECIMAL(p,s)	精确小数	price DECIMAL(10, 2)
BOOLEAN	布尔值	is_active BOOLEAN
DATE	日期	birthday DATE
TIMESTAMP	时间戳	created_at TIMESTAMP
JSONB	JSON 二进制	metadata JSONB

7.4 常用约束

-- PRIMARY KEY：主键
user_id BIGSERIAL PRIMARY KEY

-- NOT NULL：非空
username VARCHAR(100) NOT NULL

-- UNIQUE：唯一
email VARCHAR(100) UNIQUE

-- DEFAULT：默认值
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

-- CHECK：检查约束
price DECIMAL(10, 2) CHECK (price > 0)

-- FOREIGN KEY：外键
user_id BIGINT REFERENCES users(user_id)

-- 组合约束
CONSTRAINT pk_user PRIMARY KEY (user_id),
CONSTRAINT uk_email UNIQUE (email),
CONSTRAINT fk_order_user FOREIGN KEY (user_id) REFERENCES users(user_id)

7.5 验证表是否创建成功

-- 查看所有表
\dt

-- 查看表结构
\d table_name

-- 查看表是否存在
SELECT EXISTS (
    SELECT FROM information_schema.tables 
    WHERE table_name = 'table_name'
);

---

八、常用操作命令

8.1 数据库操作

-- 创建数据库
CREATE DATABASE database_name;

-- 创建数据库（指定编码）
CREATE DATABASE database_name 
    WITH ENCODING 'UTF8' 
    LC_COLLATE='en_US.UTF-8' 
    LC_CTYPE='en_US.UTF-8';

-- 删除数据库
DROP DATABASE database_name;

-- 重命名数据库
ALTER DATABASE old_name RENAME TO new_name;

8.2 表操作

-- 删除表
DROP TABLE table_name;

-- 删除表（如果存在）
DROP TABLE IF EXISTS table_name;

-- 清空表数据（保留表结构）
TRUNCATE TABLE table_name;

-- 重命名表
ALTER TABLE old_name RENAME TO new_name;

-- 添加列
ALTER TABLE table_name ADD COLUMN column_name data_type;

-- 删除列
ALTER TABLE table_name DROP COLUMN column_name;

-- 修改列类型
ALTER TABLE table_name ALTER COLUMN column_name TYPE new_type;

-- 添加约束
ALTER TABLE table_name ADD CONSTRAINT constraint_name CHECK (condition);

8.3 数据操作（CRUD）

-- 插入数据
INSERT INTO users (username, email, password_hash) 
VALUES ('john', 'john@example.com', 'hashed_password');

-- 查询数据
SELECT * FROM users;
SELECT username, email FROM users WHERE user_id = 1;

-- 更新数据
UPDATE users SET email = 'newemail@example.com' WHERE user_id = 1;

-- 删除数据
DELETE FROM users WHERE user_id = 1;

8.4 psql 常用命令

-- 帮助命令
\?          -- 查看所有命令
\h          -- SQL 命令帮助
\h CREATE TABLE  -- 查看特定 SQL 命令帮助

-- 数据库相关
\l          -- 列出所有数据库
\c dbname   -- 连接到数据库
\conninfo   -- 显示当前连接信息

-- 表相关
\dt         -- 列出所有表
\d table    -- 查看表结构
\d+ table   -- 查看表详细信息

-- 其他
\q          -- 退出
\du         -- 列出所有用户
\dn         -- 列出所有模式（schema）
\df         -- 列出所有函数
\timing     -- 开启/关闭执行时间显示
\x          -- 开启/关闭扩展显示（用于宽表）

8.5 查看执行计划

-- 查看查询执行计划
EXPLAIN SELECT * FROM users WHERE user_id = 1;

-- 查看详细执行计划（包含实际执行时间）
EXPLAIN ANALYZE SELECT * FROM users WHERE user_id = 1;

---

九、实用技巧

9.1 设置用户名和密码

9.1.1 为现有用户设置密码

-- 为 postgres 用户设置密码
ALTER USER postgres WITH PASSWORD 'your_password';

-- 为当前用户设置密码
ALTER USER current_user WITH PASSWORD 'your_password';

-- 查看当前用户
SELECT current_user;

9.1.2 创建新用户并设置密码

-- 创建新用户并设置密码
CREATE USER username WITH PASSWORD 'your_password';

-- 创建用户并指定更多选项
CREATE USER username 
    WITH PASSWORD 'your_password'
    CREATEDB  -- 允许创建数据库
    CREATEROLE;  -- 允许创建角色

-- 查看所有用户
\du

9.1.3 为用户授予数据库权限

-- 授予数据库的所有权限
GRANT ALL PRIVILEGES ON DATABASE database_name TO username;

-- 授予特定权限
GRANT CONNECT ON DATABASE database_name TO username;
GRANT CREATE ON DATABASE database_name TO username;

-- 授予表的权限（需要先连接到数据库）
\c database_name
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO username;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO username;

-- 授予未来创建的表和序列的权限
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
    GRANT ALL ON TABLES TO username;
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
    GRANT ALL ON SEQUENCES TO username;

9.1.4 完整示例：为新数据库设置用户和密码

-- 1. 连接到 PostgreSQL（使用超级用户）
psql -d postgres

-- 2. 创建新用户
CREATE USER vest_mind_user WITH PASSWORD 'your_secure_password';

-- 3. 授予数据库权限
GRANT ALL PRIVILEGES ON DATABASE vest_mind TO vest_mind_user;

-- 4. 切换到目标数据库
\c vest_mind

-- 5. 授予 schema 权限
GRANT ALL ON SCHEMA public TO vest_mind_user;

-- 6. 授予现有表的权限
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO vest_mind_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO vest_mind_user;

-- 7. 授予未来创建的表和序列的权限
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
    GRANT ALL ON TABLES TO vest_mind_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
    GRANT ALL ON SEQUENCES TO vest_mind_user;

-- 8. 验证权限
\du vest_mind_user

9.1.5 使用新用户连接数据库

# 方式1：使用密码连接
psql -U vest_mind_user -d vest_mind

# 方式2：使用环境变量（用于脚本）
PGPASSWORD=your_secure_password psql -U vest_mind_user -d vest_mind

# 方式3：在连接字符串中指定
psql "postgresql://vest_mind_user:your_secure_password@localhost:5432/vest_mind"

9.1.6 修改用户密码

-- 修改用户密码
ALTER USER username WITH PASSWORD 'new_password';

-- 强制用户下次登录时修改密码
ALTER USER username WITH PASSWORD 'new_password' VALID UNTIL '2025-12-31';

9.1.7 删除用户

-- 删除用户（如果用户拥有对象，需要先转移所有权）
DROP USER username;

-- 或者先转移所有权再删除
REASSIGN OWNED BY username TO postgres;
DROP OWNED BY username;
DROP USER username;

9.1.8 配置 PostgreSQL 认证方式（可选）

如果需要强制使用密码认证，可以编辑 PostgreSQL 配置文件：

# 找到配置文件位置（Homebrew 安装）
# 通常在：/opt/homebrew/var/postgresql@18/pg_hba.conf
# 或：/usr/local/var/postgresql@18/pg_hba.conf

# 编辑配置文件
nano /opt/homebrew/var/postgresql@18/pg_hba.conf

在 pg_hba.conf 文件中，找到类似这样的行：

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     trust
host    all             all             127.0.0.1/32            trust

修改为需要密码认证：

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     md5
host    all             all             127.0.0.1/32            md5

然后重启 PostgreSQL 服务：

brew services restart postgresql@18

认证方式说明：

• trust：无需密码（当前默认）
• md5：使用 MD5 加密的密码
• password：使用明文密码（不推荐）
• scram-sha-256：使用 SCRAM-SHA-256 加密（推荐，PostgreSQL 10+）

9.2 导出和导入数据

# 导出数据库
pg_dump -U postgres -d database_name > backup.sql

# 导入数据库
psql -U postgres -d database_name < backup.sql

# 导出表
pg_dump -U postgres -d database_name -t table_name > table_backup.sql

# 导出为 CSV
psql -U postgres -d database_name -c "COPY table_name TO STDOUT WITH CSV HEADER" > data.csv

9.3 查看数据库大小

-- 查看当前数据库大小
SELECT pg_size_pretty(pg_database_size(current_database()));

-- 查看所有数据库大小
SELECT 
    datname AS "数据库名",
    pg_size_pretty(pg_database_size(datname)) AS "大小"
FROM pg_database
ORDER BY pg_database_size(datname) DESC;

-- 查看表大小
SELECT 
    schemaname AS "模式",
    tablename AS "表名",
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS "大小"
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

9.4 查看连接信息

-- 查看当前连接
\conninfo

-- 查看所有活动连接
SELECT 
    pid,
    usename,
    datname,
    client_addr,
    state,
    query
FROM pg_stat_activity
WHERE datname IS NOT NULL;

9.5 环境变量配置（可选）

在 ~/.zshrc 或 ~/.bash_profile 中添加：

# PostgreSQL 路径配置
export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"
export LDFLAGS="-L/opt/homebrew/opt/postgresql@18/lib"
export CPPFLAGS="-I/opt/homebrew/opt/postgresql@18/include"

# PostgreSQL 连接别名（可选）
alias pgstart='brew services start postgresql@18'
alias pgstop='brew services stop postgresql@18'
alias pgrestart='brew services restart postgresql@18'
alias pgstatus='brew services list | grep postgresql'

---

十、快速参考

10.1 常用连接方式

# 最简单的方式
psql

# 指定数据库
psql -d mydb

# 指定用户和数据库
psql -U postgres -d mydb

# 带密码连接（用于脚本）
PGPASSWORD=password psql -U postgres -d mydb

10.2 常用 SQL 命令速查

-- 数据库
CREATE DATABASE dbname;
DROP DATABASE dbname;
\l

-- 表
CREATE TABLE tname (...);
DROP TABLE tname;
\dt
\d tname

-- 数据
INSERT INTO tname VALUES (...);
SELECT * FROM tname;
UPDATE tname SET ... WHERE ...;
DELETE FROM tname WHERE ...;

-- 用户
CREATE USER username WITH PASSWORD 'password';
\du

10.3 故障排查

# 检查 PostgreSQL 是否运行
pg_isready

# 查看日志（Homebrew 安装）
tail -f /opt/homebrew/var/log/postgresql@18.log

# 或者
tail -f /usr/local/var/log/postgresql@18.log

# 重启服务
brew services restart postgresql@18

---

十一、示例：完整工作流程

# 1. 启动 PostgreSQL
brew services start postgresql@18

# 2. 连接到数据库
psql -d postgres

# 3. 创建数据库
CREATE DATABASE myapp;

# 4. 切换到新数据库
\c myapp

# 5. 创建表
CREATE TABLE users (
    user_id BIGSERIAL PRIMARY KEY,
    username VARCHAR(100) NOT NULL UNIQUE,
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

# 6. 查看表
\dt
\d users

# 7. 插入数据
INSERT INTO users (username, email) 
VALUES ('john', 'john@example.com');

# 8. 查询数据
SELECT * FROM users;

# 9. 退出
\q

---

十二、图形化工具推荐

12.1 pgAdmin

• 官网：https://www.pgadmin.org/
• 功能强大的 PostgreSQL 管理工具

12.2 DBeaver

• 官网：https://dbeaver.io/
• 免费、跨平台的数据库管理工具

12.3 TablePlus

• 官网：https://tableplus.com/
• Mac 上优秀的数据库管理工具（付费）

12.4 Postico

• 官网：https://eggerapps.at/postico/
• Mac 专用的 PostgreSQL 客户端（付费）

---

十三、常见问题

Q1: 连接时提示 "password authentication failed"

A: 检查用户名和密码是否正确，或者重置 postgres 用户密码：

ALTER USER postgres WITH PASSWORD 'new_password';

Q2: 找不到 psql 命令

A: 需要将 PostgreSQL 的 bin 目录添加到 PATH：

export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"

Q3: 端口 5432 已被占用

A: 检查端口占用情况：

lsof -i :5432

Q4: 如何查看 PostgreSQL 版本

A:

psql --version
# 或者在 psql 中
SELECT version();

---

文档版本： v1.0
最后更新： 2024年