FastAPI.9

Alembic

一、什么是Alembic

1. Alembic是一种用于数据迁移和版本控制的工具，特别适用于Python编写的数据库应用程序。它允许你按照预定的数据库模型定义，在不丢失现有数据的情况下进行数据库模式的更改。
2. Alembic的一些关键概念和功能

   1. 迁移文件（Migration Files）：
     Alembic通过迁移文件定义数据库模式的更改。每个迁移文件都包含一组变更指令，比如创建新表格、添加或删除列等等。
   
   2. 版本控制：
     迁移文件按照版本进行控制和管理。每个版本对应一个迁移文件。Alembic会跟踪应用的迁移历史，并根据需要自动应用最新的迁移文件。
   
   3. 自动创建迁移文件：
     Alembic可以自动检测数据库模型的更改，并生成相应的迁移文件。你只需运行一个命令，就可以生成迁移文件，省去了手动编写迁移文件的工作。
   
   4. 命令行工具：
     Alembic提供了一个命令行工具，可以方便地执行各种数据库迁移任务，如初始化迁移环境、创建和应用迁移文件等。
   
   5. 数据库支持：
     Alembic支持多种流行的数据库，包括MySQL、PostgreSQL、SQLite等。
   
   6. Python集成：
     Alembic是基于Python的，可以灵活地集成到你的Python应用程序中，并使用Python代码来编写和执行数据库迁移逻辑。
   

二、Alembic的配置文件alembic.ini

1. alembic.ini是Alembic的配置文件，其中包含了一些关键的配置信息，用于指定Alembic工具的行为和连接到数据库的方式。
2. 常见的alembic.ini配置选项

   1. sqlalchemy.url：
   连接数据库的URL。根据你使用的数据库类型和具体的设置，可以在这里指定数据库的连接信息，比如数据库类型、主机名、端口、用户名、密码等。
   
   2. script_location：
   迁移文件的存储位置。这个选项指定了存放迁移文件的目录路径。迁移文件通常存储在项目的一个特定目录中，用于管理数据库模式的更改。
   
   3. version_locations:
   版本文件的存储位置。这个选项指定了存放版本文件的目录路径。版本文件是记录每个迁移版本的文件，用于跟踪应用的迁移历史。
   
   4. databases：
   数据库配置选项。如果你的应用程序使用多个数据库，你可以在这里配置每个数据库的连接信息。
   
   5. lude_object和exclude_object：
   包含和排除对象的过滤配置。你可以使用这些选项来过滤掉特定的数据库对象，比如表格、索引等，或者只包含特定的对象。
   
   6. ration_dir和upgrade：
   迁移文件和升级脚本的配置选项。你可以在这里指定迁移文件和升级脚本的存储位置和命名规则。
   

3. alembic.ini文件中的配置项可以分为以下几个部分：

   [alembic] 部分：包含了一些全局的配置选项。
   
   script_location：指定了存放迁移文件的目录路径。
   
   prepend_sys_path：指定了sys.path路径，可以将其添加到sys.path中。
   
   timezone：指定了在迁移文件和文件名中使用的时区。
   
   version_path_separator：指定了版本文件存放路径的分隔符，可以使用os.pathsep或其他指定的分隔符。
   
   [post_write_hooks] 部分：定义了在生成新的迁移脚本后要运行的脚本或Python函数。
   
   [loggers]、[handlers]和[formatters] 部分：定义了日志记录的配置。
   
   [logger_root]、[logger_sqlalchemy]和[logger_alembic] 部分：定义了不同的日志记录器和级别。
   
   [handler_console] 部分：定义了控制台处理程序，将日志输出到标准错误流。
   
   [formatter_generic] 部分：定义了日志消息的格式和日期格式。
   

   在配置文件的最后部分，有一个sqlalchemy.url项，是连接到数据库的URL。你可以在这里指定具体的数据库连接信息，比如驱动程序、用户名、密码、主机名等。这些配置项用于指定Alembic工具的行为，比如指定迁移文件的存储位置、数据库连接信息、日志记录等。根据具体项目的需求和数据库配置，可以根据需要调整和添加这些配置选项。

三、如何使用

1. 安装：pip install alembic
2. 去官网点这里：https://alembic.sqlalchemy.org/en/latest/tutorial.html
3. 建立Alembic脚本环境：alembic init alembic，会看到以下输出，即脚本环境创建完成

   (.venv) ➜  server alembic init alembic
     Creating directory /<path>/alembic ...  done
     Creating directory /<path>/versions ...  done
     Generating /<path>/alembic/script.py.mako ...  done
     Generating /<path>/alembic/env.py ...  done
     Generating /<path>/alembic/README ...  done
     Generating /<path>/alembic.ini ...  done
     Please edit configuration/connection/logging settings in '/Users/keinYe/Work/python/server/alembic.ini' before proceeding.
   

4. 生成的目录

   ├── alembic                # 迁移脚本的根目录
   │   ├── README             # 说明文件
   │   ├── env.py             # 一个python文件，在调用Alembic命令时运行该脚本
   │   ├── script.py.mako     # mako模板文件，用于生成新的迁移脚本文件
   │   └── versions           # 存放各个版本的迁移脚本，通过revision命令生成新的迁移脚本
   |—— alembic.init           # Alembic的配置文件，需要配置 sqlalchemy.url 指向自己的数据库地址
   

5. 数据库迁移
   生成迁移脚本：alembic revision --autogenerate -m '内容'
   更新数据库：alembic upgrade head

   1. alembic revision -m "first create script"
   # 初始的迁移脚本中并没有实际有效的内容，相当于一个空白的模板文件「增加了版本信息」。def upgrade()和def downgrade()都是pass
   """
   first create script
   
   Revision ID: aac015d0e5be
   Revises: 
   Create Date: 2023-09-07 09:43:28.363561
   from typing import Sequence, Union
   
   from alembic import op
   import sqlalchemy as sa
   
   
   # revision identifiers, used by Alembic.
   revision: str = 'aac015d0e5be'
   down_revision: Union[str, None] = None
   branch_labels: Union[str, Sequence[str], None] = None
   depends_on: Union[str, Sequence[str], None] = None
   
   
   def upgrade() -> None:
   	pass
   
   
   def downgrade() -> None:
   	pass
   """
   
   2. alembic upgrade head
   # 更新到最新版本
   3. alembic revision --autogenerate -m 'add age in user table'
   '''
   INFO  [alembic.runtime.migration] Context impl MySQLImpl.
   INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
   INFO  [alembic.autogenerate.compare] Detected added column 'user.age'
     Generating /home/zxb/my_fastapi_project/alembic/versions/1ad97cc53a3d_add_age_in_user_table.py done
   可以看见成功在user表添加age字段
   '''
   4. alembic upgrade head
   # 更新到最新版本，此时可以在数据库中看到新的字段
   

6. 变更数据库
   Alembic 最重要的功能是自动完成数据库的迁移「变更」，所做的配置以及生成的脚本文件都是为数据的迁移做准备的，数据库的迁移主要用到 upgrade 和 downgrade 子命令。
   • alembic upgrade head：将数据库升级到最新版本
   • alembic downgrade base：将数据库降级到最初版本
   • alembic upgrade <version>：将数据库升级到指定版本
   • alembic downgrade <version>：将数据库降级到指定版本
   • alembic upgrade +2：相对升级，将数据库升级到当前版本的后两个版本
   • alembic downgrade +2：相对降级，将数据库降级到当前版本的前两个版本
     以上的升降级方式都是在线实时更新，Alembic提供了生成SQL脚本的形式，提供离线升降级的功能
   • alembic upgrade <version> --sql > migration.sql
   • alembic downgrade <version> --sql > migration.sql
7. 查看线上数据库版本
   • alebmic current：1ad97cc53a3d (head)
   • alembic history --verbose：查看历史版本

     Rev: 1ad97cc53a3d (head)
     Parent: aac015d0e5be
     Path: /home/zxb/my_fastapi_project/alembic/versions/1ad97cc53a3d_add_age_in_user_table.py
     
     	add age in user table
     
     	Revision ID: 1ad97cc53a3d
     	Revises: aac015d0e5be
     	Create Date: 2023-09-07 09:47:23.254569
     	Rev: aac015d0e5be
     Parent: <base>
     Path: /home/zxb/my_fastapi_project/alembic/versions/aac015d0e5be_first_create_script.py
     
     	first create script
     
     	Revision ID: aac015d0e5be
     	Revises: 
     	Create Date: 2023-09-07 09:43:28.363561