excellent_migrations下载excellent_migrations源代码下载

出色的迁移

检测数据库迁移中潜在的危险或破坏性操作。

安装

可以通过添加:excellent_migrations mix.exs安装该软件包。

 def deps do
  [
    { :excellent_migrations , "~> 0.1" , only: [ :dev , :test ] , runtime: false }
  ]
end

文档

可以在Hexdocs上获得文档。

它如何工作

该工具分析迁移文件的代码（AST）。您无需编辑或在迁移文件中包含任何其他代码，除了偶尔添加配置注释以确保安全性。

如何使用它

有多种与出色的迁移相结合的方法。

Credo Check

出色的迁移提供了自定义，可用来的信用。

添加ExcellentMigrations.CredoCheck.MigrationsSafety到您的.credo文件：

 % {
  configs: [
    % {
      # …
      checks: [
        # …
        { ExcellentMigrations.CredoCheck.MigrationsSafety , [ ] }
      ]
    }
  ]
}

示例Credo警告：

  Warnings - please take a look
┃
┃ [W] ↗ Raw SQL used
┃       apps/cookbook/priv/repo/migrations/20211024133700_create_recipes.exs:13 #(Cookbook.Repo.Migrations.CreateRecipes.up)
┃ [W] ↗ Index added not concurrently
┃       apps/cookbook/priv/repo/migrations/20211024133705_create_index_on_veggies.exs:37 #(Cookbook.Repo.Migrations.CreateIndexOnVeggies.up)

混合任务

mix excellent_migrations.check_safety

此混合任务分析迁移并记录检测到的每种危险的警告。

迁移任务

mix excellent_migrations.migrate

执行此任务将首先分析迁移。如果未发现危险，它将进行并进行mix ecto.migrate 。如果有的话，它将记录错误并停止。

代码

您也可以在代码中使用它。为此，您需要获取迁移文件的源代码和AST，例如通过File.read!/1和Code.string_to_quoted/2 。然后将它们传递到ExcellentMigrations.DangersDetector.detect_dangers(ast) 。它将返回一个关键字列表，其中包含检测到的危险类型和线条。

检查

潜在危险的行动：

添加检查约束
添加带有默认值的列
回填数据
违约列的列
更改列的类型
直接执行SQL
删除列
重命名一列
重命名桌子
在现有列上设置不为空

特定于Postgres的检查：

添加JSON列
添加参考
非连续添加索引
同时添加索引而不禁用锁定或交易

最佳实践：

将非唯一索引保持在三列或更少

您也可以禁用特定的检查。

删除列

如果仍在将ECTO配置为在应用程序的任何运行实例中读取列，则在将数据加载到您的结构中时，查询将失败。这可以在多节点部署中发生，或者如果您在运行迁移之前启动应用程序。

坏的

 # Without a code change to the Ecto Schema

def change do
  alter table ( "recipes" ) do
    remove :no_longer_needed_column
  end
end

好✅

如果首先更新应用程序代码以删除对列的引用，则可以确保安全性，以免加载或查询。然后，可以安全地从表格中删除列。

部署代码更改以删除对字段的引用。
部署迁移更改以删除列。

第一次部署：

 # First deploy, in the Ecto schema

defmodule Cookbook.Recipe do
  schema "recipes" do
-   column :no_longer_needed_column, :text
  end
end

第二部署：

 def change do
  alter table ( "recipes" ) do
    remove :no_longer_needed_column
  end
end

添加带有默认值的列

在现有表中添加带有默认值的列可能会导致表重写。在此期间，读取和写入被封锁，并在MySQL和Mariadb中被阻止。

坏的

注意：这变得安全：

Postgres 11+
MySQL 8.0.12+
Mariadb 10.3.2+

 def change do
  alter table ( "recipes" ) do
    add :favourite , :boolean , default: false
    # This took 10 minutes for 100 million rows with no fkeys,

    # Obtained an AccessExclusiveLock on the table, which blocks reads and
    # writes.
  end
end

好✅

首先添加列，然后将其更改以包含默认值。

第一次迁移：

 def change do
  alter table ( "recipes" ) do
    add :favourite , :boolean
    # This took 0.27 milliseconds for 100 million rows with no fkeys,
  end
end

第二迁移：

 def change do
  alter table ( "recipes" ) do
    modify :favourite , :boolean , default: false
    # This took 0.28 milliseconds for 100 million rows with no fkeys,
  end
end

模式更改以读取新列：

schema "recipes" do
+ field :favourite, :boolean, default: false
end

违约列的列

如果默认值是挥发性的（例如， clock_timestamp() ， uuid_generate_v4() ， random() ）每行都需要在执行ALTER TABLE中计算的值时更新。

坏的

将波动性默认值添加到列：

 def change do
  alter table ( :recipes ) do
    modify ( :identifier , :uuid , default: fragment ( "uuid_generate_v4()" ) )
  end
end

添加具有挥发性默认值的列：

 def change do
  alter table ( :recipes ) do
    add ( :identifier , :uuid , default: fragment ( "uuid_generate_v4()" ) )
  end
end

好✅

为了避免潜在的冗长更新操作，尤其是如果您打算用大多数非默认值填充列，则可能比：

添加无默认的列
使用UPDATE查询插入正确的值
只有然后添加任何所需的默认值

同样，用挥发性默认值创建一个带有列列的新表也是安全的，因为它不包含任何记录。

回填数据

ECTO围绕每个迁移创建一项交易，并在相同的交易中进行回填，该交易改变了表格在回填充期间将表锁定的锁定。此外，运行单个查询以更新数据可能会引起大表格问题。

坏的

 defmodule Cookbook.BackfillRecipes do
  use Ecto.Migration
  import Ecto.Query

  def change do
    alter table ( "recipes" ) do
      add :new_data , :text
    end

    flush ( )

    Cookbook.Recipe
    |> where ( new_data: nil )
    |> Cookbook.Repo . update_all ( set: [ new_data: "some data" ] )
  end
end

好✅

有几种不同的策略来执行安全的回填。本文在很好的细节上解释了它们。

更改列的类型

更改列的类型可能会导致表重写。在此期间，读取和写入被封锁，并在MySQL和Mariadb中被阻止。

坏的

在Postgres中安全：

增加VARCHAR的长度或删除极限
将varchar更改为文字
将文本更改为varchar，没有长度限制
Postgres 9.2+-提高十进制或数字列的精度（注意：不尺度）。例如，增加8,2至10,2是安全的。增加8,2到8,4是不安全的。
Postgres 9.2+-更改小数或数字，不受约束
Postgres 12+ - 会话TZ是UTC时，将时间戳更改为Timestamptz

MySQL/Mariadb的安全：

VARCHAR的长度从<255到255。
从> 255到最大的VARCHAR的长度增加。

 def change do
  alter table ( "recipes" ) do
    modify :my_column , :boolean , from: :text
  end
end

好✅

采用分阶段的方法：

创建一个新列
在应用程序代码中，写入两个列
从旧列到新列的回填数据
在应用程序代码中，将读取从旧列移至新列
在应用程序代码中，从ECTO模式中删除旧列。
放下旧列。

重命名一列

问问自己：“我真的需要重命名专栏吗？”。可能不是，但是如果您必须，请继续阅读并意识到它需要时间和精力。

如果将ECTO配置为在应用程序的任何运行实例中读取列，则将数据加载到您的结构中时，查询将失败。这可以在多节点部署中发生，或者如果您在运行迁移之前启动应用程序。

有一个快捷方式：不要重命名数据库列，而是重命名架构的字段名称并将其配置为指向数据库列。

坏的

 # In your schema
schema "recipes" do
  field :summary , :text
end


# In your migration
def change do
  rename table ( "recipes" ) , :title , to: :summary
end

您的迁移和应用程序获得新代码之间的时间可能会遇到麻烦。

好✅

策略1

仅在模式中重命名字段，然后将其配置为指向数据库列，并保持数据库列相同。确保还更新了所有依赖旧字段名称的调用代码以引用新字段名称。

 defmodule Cookbook.Recipe do
  use Ecto.Schema

  schema "recipes" do
    field :author , :string
    field :preparation_minutes , :integer , source: :prep_min
  end
end

 # # Update references in other parts of the codebase:
   recipe = Repo.get(Recipe, "my_id")
-  recipe.prep_min
+  recipe.preparation_minutes

策略2

采用分阶段的方法：

创建一个新列
在应用程序代码中，写入两个列
从旧列到新列的回填数据
在应用程序代码中，将读取从旧列移至新列
在应用程序代码中，从ECTO模式中删除旧列。
放下旧列。

重命名桌子

问问自己：“我真的需要重命名桌子吗？”。可能不是，但是如果您必须，请继续阅读并意识到它需要时间和精力。

如果仍将ECTO配置为在应用程序的任何运行实例中读取表，则在将数据加载到您的结构中时，查询将失败。这可以在多节点部署中发生，或者如果您在运行迁移之前启动应用程序。

有一个快捷方式：仅重命名架构，并且不要更改基础数据库表名称。

坏的

 def change do
  rename table ( "recipes" ) , to: table ( "dish_algorithms" )
end

好✅

策略1

仅重命名架构和所有调用代码，并且不要重命名表：

 - defmodule Cookbook.Recipe do
+ defmodule Cookbook.DishAlgorithm do
  use Ecto.Schema

  schema "dish_algorithms" do
    field :author, :string
    field :preparation_minutes, :integer
  end
end

# and in calling code:
- recipe = Cookbook.Repo.get(Cookbook.Recipe, "my_id")
+ dish_algorithm = Cookbook.Repo.get(Cookbook.DishAlgorithm, "my_id")

策略2

采用分阶段的方法：

创建新表。这应该包括创建模仿旧表行为的新约束（检查和外键）。
在应用程序代码中，写入两个表，继续从旧表中读取。
从旧表到新表的回填数据
在应用程序代码中，将读取从旧表移动到新表格
在应用程序代码中，从ECTO模式中删除旧表。
放下旧桌子。

添加检查约束

添加检查约束块会读取并写入Postgres的表格，并在检查每行时在MySQL/Mariadb中写入。

坏的

 def change do
  create constraint ( "ingredients" , :price_must_be_positive , check: "price > 0" )
  # Creating the constraint with validate: true (the default when unspecified)
  # will perform a full table scan and acquires a lock preventing updates
end

好✅

发生了两项操作：

为新的或更新记录创建新约束
验证现有记录的新约束

如果这些命令同时发生，则在验证整个表并对表进行充分扫描时，将在表上获得锁定。为了避免此完整的桌子扫描，我们可以将操作分开。

一个迁移：

 def change do
  create constraint ( "ingredients" , :price_must_be_positive , check: "price > 0" , validate: false )
  # Setting validate: false will prevent a full table scan, and therefore
  # commits immediately.
end

在下一个迁移中：

 def change do
  execute "ALTER TABLE ingredients VALIDATE CONSTRAINT price_must_be_positive" , ""
  # Acquires SHARE UPDATE EXCLUSIVE lock, which allows updates to continue
end

这些可以在同一部署中，但请确保有2个单独的迁移。

在现有列上设置不为空

在检查每一行时，在现有列块上设置不为null会读取和写入。就像添加支票约束方案一样，发生了两种操作：

为新的或更新记录创建新约束
验证现有记录的新约束

为了避免全表扫描，我们可以将这两个操作分开。

坏的

 def change do
  alter table ( "recipes" ) do
    modify :favourite , :boolean , null: false
  end
end

好✅

添加检查约束而无需验证它，回填数据以满足约束并验证它。这将在功能上等效。

在第一次迁移中：

 # Deployment 1
def change do
  create constraint ( "recipes" , :favourite_not_null , check: "favourite IS NOT NULL" , validate: false )
end

这将在所有新行中执行约束，但在更新该行之前不关心现有行。

此时可能需要数据迁移，以确保满足约束。

然后，在下一个部署的迁移中，我们将对所有行实施约束：

 # Deployment 2
def change do
  execute "ALTER TABLE recipes VALIDATE CONSTRAINT favourite_not_null" , ""
end

如果您使用的是Postgres 12+，则可以在验证约束后将其添加到列中。从Postgres 12个文档中：

如果表中的任何记录都不包含该列的零值，则只能将NOT NULL应用于列。通常，通过扫描整个表格，可以在Alter表格中检查一下。但是，如果找到有效的检查约束，证明没有空的存在，则表跳过表扫描。

 # **Postgres 12+ only**

def change do
  execute "ALTER TABLE recipes VALIDATE CONSTRAINT favourite_not_null" , ""

  alter table ( "recipes" ) do
    modify :favourite , :boolean , null: false
  end

  drop constraint ( "recipes" , :favourite_not_null )
end

如果您的约束失败，则应首先考虑回填数据，以涵盖所需数据完整性中的空白，然后重新访问验证约束。

直接执行SQL

出色的迁移无法确保原始SQL语句的安全性。真正确定您的工作是安全的，然后使用：

 defmodule Cookbook.ExecuteRawSql do
  # excellent_migrations:safety-assured-for-this-file raw_sql_executed

  def change do
    execute ( "..." )
  end
end

非连续添加索引

创建索引将阻止读取和写入。

坏的

 def change do
  create index ( "recipes" , [ :slug ] )

  # This obtains a ShareLock on "recipes" which will block writes to the table
end

好✅

使用Postgres，而是同时创建索引，该索引不会阻止读取。您将需要禁用数据库交易以CONCURRENTLY使用，并且由于ECTO通过数据库交易获得迁移锁，这也意味着竞争节点可能试图尝试运行相同的迁移（例如，在启动之前运行迁移的多节点Kubernetes环境中）。因此，由于各种原因，有些节点会失败。

 @ disable_ddl_transaction true
@ disable_migration_lock true

def change do
  create index ( "recipes" , [ :slug ] , concurrently: true )
end

迁移可能仍需一段时间才能运行，但是对行的阅读和更新将继续起作用。例如，对于100,000,000行，添加运行迁移的时间为165秒，但是在运行时可能会进行选择和更新。

在同一迁移中没有其他变化；仅同时创建索引，并将其他更改与以后的迁移分开。

同时添加索引而不禁用锁定或交易

同时索引需要将@disable_ddl_transaction和@disable_migration_lock设置为true。查看更多：

坏的

 defmodule Cookbook.AddIndex do
  def change do
    create index ( :recipes , [ :cookbook_id , :cuisine ] , concurrently: true )
  end
end

好✅

 defmodule Cookbook.AddIndex do
  @ disable_ddl_transaction true
  @ disable_migration_lock true

  def change do
    create index ( :recipes , [ :cookbook_id , :cuisine ] , concurrently: true )
  end
end

添加参考

在两个表上添加外键块写入。

坏的

 def change do
  alter table ( "recipes" ) do
    add :cookbook_id , references ( "cookbooks" )
  end
end

好✅

在第一次迁移中

 def change do
  alter table ( "recipes" ) do
    add :cookbook_id , references ( "cookbooks" , validate: false )
  end
end

在第二次迁移中

 def change do
  execute "ALTER TABLE recipes VALIDATE CONSTRAINT cookbook_id_fkey" , ""
end

这些迁移可以处于同一部署，但请确保它们是单独的迁移。

添加`json`列

在Postgres中，没有针对JSON列类型的平等操作员，这可能会在应用程序中为现有选择的不同查询造成错误。

坏的

 def change do
  alter table ( "recipes" ) do
    add :extra_data , :json
  end
end

好✅

改用JSONB。有人说这就像“ json”，但“ b etter”。

 def change do
  alter table ( "recipes" ) do
    add :extra_data , :jsonb
  end
end

将非唯一索引保持在三列或更少

坏的

添加一个超过三列的非独特索引很少会提高性能。

 defmodule Cookbook.AddIndexOnIngredients do
  def change do
    create index ( :recipes , [ :a , :b , :c , :d ] , concurrently: true )
  end
end

好✅

取而代之的是，启动一个索引，其列最缩小结果的缩小。

 defmodule Cookbook.AddIndexOnIngredients do
  def change do
    create index ( :recipes , [ :b , :d ] , concurrently: true )
  end
end

对于Postgres，请确保同时添加它们。

确保安全

将迁移中的操作标记为安全使用配置注释。在分析过程中将被忽略。

有两个配置注释可用：

excellent_migrations:safety-assured-for-next-line <operation_type>
excellent_migrations:safety-assured-for-this-file <operation_type>

忽略给定行的支票：

 defmodule Cookbook.AddTypeToRecipesWithDefault do
  def change do
    alter table ( :recipes ) do
      # excellent_migrations:safety-assured-for-next-line column_added_with_default
      add ( :type , :string , default: "dessert" )
    end
  end
end

忽略整个文件的支票：

 defmodule Cookbook.AddTypeToRecipesWithDefault do
  # excellent_migrations:safety-assured-for-this-file column_added_with_default

  def change do
    alter table ( :recipes ) do
      add ( :type , :string , default: "dessert" )
    end
  end
end

可能的操作类型是：

check_constraint_added
column_added_with_default
column_reference_added
column_removed
column_renamed
column_type_changed
column_volatile_default
index_concurrently_without_disable_ddl_transaction
index_concurrently_without_disable_migration_lock
index_not_concurrently
json_column_added
many_columns_index
not_null_added
operation_delete
operation_insert
operation_update
raw_sql_executed
table_dropped
table_renamed

禁用支票

忽略所有迁移检查的特定危险：

 config :excellent_migrations , skip_checks: [ :raw_sql_executed , :not_null_added ]

现有迁移

为了跳过分析在添加此软件包之前创建的迁移，请在配置中的start_after中的最后一个迁移设置时间戳：

 config :excellent_migrations , start_after: "20191026080101"

类似的工具和资源

https://github.com/ankane/strong_migrations（Ruby）
https://github.com/rrrrene/credo（Elixir）
https://github.com/fly-apps/safe-ecto migrations - 特别感谢您不安全的动作说明和食谱。
https://www.postgresql.org/docs/current/sql-altertable.html#notes

贡献

鼓励和欢迎每个人，以帮助改进该项目。以下是您可以提供帮助的几种方法：

给予反馈 - 您的意见很重要
访问TODO列表
提交拉拉请求
建议功能
报告错误
改善文档

版权和许可

版权（C）2021 Artur Sulej

这项工作是免费的。您可以根据MIT许可证的条款对其进行重新分配和/或对其进行修改。有关更多详细信息，请参见许可证文件。

展开

excellent_migrations

出色的迁移

安装

文档

它如何工作

如何使用它

Credo Check

混合任务

迁移任务

代码

检查

删除列

添加带有默认值的列

违约列的列

回填数据

更改列的类型

重命名一列

重命名桌子

添加检查约束

在现有列上设置不为空

直接执行SQL

非连续添加索引

同时添加索引而不禁用锁定或交易

添加参考

添加json列

将非唯一索引保持在三列或更少

确保安全

禁用支票

现有迁移

类似的工具和资源

贡献

版权和许可

添加`json`列