psql -U fastapi_user -d fastapi_study -h localhost -p 5433

fastapi_study=>     等待新命令
fastapi_study->     语句未结束（换行但未敲分号），等待续行
fastapi_study">     字符串引号未闭合，等待补引号

# 查看容器
docker ps

# 方式1：容器外执行一条命令（用完即走）
docker exec txwx-postgis psql -U fastapi_user -d fastapi_study -c "\dt"

# 方式2：进入容器交互式操作
docker exec -it txwx-postgis psql -U fastapi_user -d fastapi_study

PostgreSQL 实例（一个 pg 进程/容器）
  ├── 数据库 fastapi_study          ← 独立命名空间，库之间完全隔离
  │   ├── Schema public              ← 默认 schema，表都放这
  │   │   ├── 表 users               ← 存用户数据
  │   │   │   ├── 列 id, username ...
  │   │   │   └── 行 (1, 'study_user', ...)
  │   │   └── 表 notes
  │   └── Schema 可再建多个 ...
  ├── 数据库 postgres                ← 系统库，存储全局元数据，不要动
  └── 数据库 txwx_db                 ← 其他项目的库

-- 创建数据库，指定拥有者
CREATE DATABASE fastapi_study OWNER fastapi_user;

-- 删除数据库（需断开其他连接）
DROP DATABASE fastapi_study;

CREATE ROLE myrole;                            -- 不能登录，纯角色（用于权限分组）
CREATE USER myuser WITH PASSWORD '123';        -- 能登录的用户（= CREATE ROLE ... WITH LOGIN）

-- 创建用户
CREATE USER fastapi_user WITH PASSWORD 'fastapi_pass_123';

-- 修改密码
ALTER USER fastapi_user PASSWORD 'new_password';

-- 删除用户
DROP USER fastapi_user;

-- txwx 具有 SUPERUSER 属性，所以能创建新用户、新数据库
CREATE ROLE txwx WITH
    LOGIN           -- 能登录
    PASSWORD 'txms9999'
    SUPERUSER;      -- 超级管理员，无视所有权限检查

GRANT SELECT, INSERT, UPDATE, DELETE ON notes TO fastapi_user;
REVOKE DELETE ON notes FROM fastapi_user;   -- 收回某个权限

Windows 宿主机
  │
  ├── VS Code 插件 → localhost:5433 (TCP)  → 必须密码
  │
  └── docker exec → 容器内 → Unix socket   → 免密码（本地信任）

# TYPE   DATABASE    USER       ADDRESS          METHOD
host     all         all        127.0.0.1/32     scram-sha-256    ← TCP 连接要密码
local    all         all                         trust            ← Unix socket 免密码

-- psql 反斜杠命令（仅 psql 可用）
\d notes

-- 标准 SQL（任何客户端可用）
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'notes'
ORDER BY ordinal_position;

 Column  |          Type          | Nullable |              Default
---------+------------------------+----------+-----------------------------------
 id      | integer                | not null | nextval('notes_id_seq'::regclass)
 title   | character varying(100) | not null |
 content | text                   | not null |
 done    | boolean                | not null |
 user_id | integer                | not null |
Indexes:
    "notes_pkey" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "notes_user_id_fkey" FOREIGN KEY (user_id) REFERENCES users(id)

ERROR:  insert or update on table "notes" violates foreign key constraint "notes_user_id_fkey"
DETAIL:  Key (user_id)=(999) is not present in table "users".

INSERT INTO notes (title, content, done, user_id)
VALUES ('测试', '内容', false, 1);
-- 返回 INSERT 0 1：第一个数是 OID（已废弃，恒为 0），第二个是影响行数

SELECT id, title, done          -- 要哪几列（* 表示全部）
FROM notes                      -- 从哪张表
WHERE done = false              -- 过滤行
ORDER BY id DESC;               -- 排序

UPDATE notes SET done = true WHERE id = 1;
-- 返回 UPDATE 1（影响 1 行）；UPDATE 0 表示 WHERE 未匹配任何行

DELETE FROM notes WHERE id = 5;
-- 返回 DELETE 1

UPDATE notes SET done = true;   -- 改光全表
DELETE FROM notes;              -- 删光全表

1. FROM       确定数据源
2. WHERE      过滤行
3. SELECT     挑选列
4. ORDER BY   排序结果

select(Note)                     # SELECT ... FROM notes
    .where(Note.done == False)   # WHERE done = false
    .order_by(Note.id.desc())    # ORDER BY id DESC
    .offset(skip)                # OFFSET
    .limit(limit)                # LIMIT

note = self._get_owned(note_id, user_id)  # 先 SELECT 查出对象
note.done = True                           # 改属性
self.db.flush()                            # flush 时 ORM 对比变更，生成 UPDATE ... WHERE id=主键

-- 硬删除：数据从表里真的消失，不可恢复
DELETE FROM notes WHERE id = 5;

-- 软删除：加标记列，数据仍在，只标记为"已删除"
UPDATE notes SET deleted_at = now() WHERE id = 5;

is_deleted boolean NOT NULL DEFAULT false   -- 布尔标记
deleted_at timestamp DEFAULT NULL           -- 时间戳：NULL=未删，有值=已删（更常用，能知何时删）

SELECT * FROM notes WHERE deleted_at IS NULL;

0 正常
  ↓ 用户删除（进回收站，delete_scheduled_at = now() + 30天）
1 回收站  ──用户恢复──→  0 正常
  ↓ 定时任务（cron）扫描，scheduled_at 到期
2 逻辑删除（用户彻底不可见）
  ↓ 物理清理任务（更晚，连带清理 MinIO 文件、Redis 缓存等）
真正 DELETE / 归档

UPDATE items
SET delete_status = 2
WHERE delete_status = 1
  AND delete_scheduled_at <= now();   -- 计划时间已过

普通删除：scheduled_at = now() + 30天   → 回收站保留 30 天
立即删除：scheduled_at = 过往时间        → 已"过期"，下一轮扫描立即清理

notes.user_id  ──匹配──→  users.id

SELECT notes.id, notes.title, users.username
FROM notes
JOIN users ON notes.user_id = users.id;

-- INNER JOIN：empty_user 不出现（无匹配笔记）
SELECT users.username, notes.title
FROM users JOIN notes ON users.id = notes.user_id;
-- study_user | 测试 / study_user | 测试文章

-- LEFT JOIN：empty_user 出现，title 为 NULL
SELECT users.username, notes.title
FROM users LEFT JOIN notes ON users.id = notes.user_id;
-- study_user | 测试 / study_user | 测试文章 / empty_user | (NULL)

SELECT users.username FROM users
LEFT JOIN notes ON users.id = notes.user_id
WHERE notes.title IS NULL;   -- 查出没有笔记的用户

FROM A LEFT JOIN B
     ↑           ↑
     左表        右表

SELECT notes FROM notes;
-- 输出一列：(3,测试,内容,f,1)   ← 整行字段拼成复合值

# model.py
notes: Mapped[list["Note"]] = relationship(back_populates="user")
# 访问 user.notes 时，SQLAlchemy 自动生成 JOIN 或子查询拉取关联行