DOC Changing ClassName from Enum to Varchar

silverstripe · Sep 9, 2024 · d980a50 · d980a50
1 parent 9304c71
commit d980a50
Show file tree

Hide file tree

Showing 2 changed files with 61 additions and 0 deletions.
diff --git a/en/02_Developer_Guides/08_Performance/06_ORM.md b/en/02_Developer_Guides/08_Performance/06_ORM.md
@@ -49,3 +49,17 @@ SilverStripe\ORM\Connect\DBSchemaManager:
 ```
 
 You can always manually trigger a check and repair (e.g. in a [`BuildTask`](api:SilverStripe/Dev/BuildTask)) by calling [`DB::check_and_repair_table()`](api:SilverStripe\ORM\DB::check_and_repair_table()). This ignores the above configuration.
+
+## Changing `ClassName` column from enum to varchar {#classname-varchar}
+
+On websites with very large database tables it can take a long time to run `dev/build`, which can be a problem when deploying changes to production. This is because the `ClassName` column is an `enum` type which requires an a `ALTER TABLE` query to be run affecting every row whenever there is a new valid value for the column.
+
+For a very rough benchmark, running an `ALTER TABLE` query on a database table of 10 million records took 28.52 seconds on a mid-range 2023 laptop, though this time will vary depending on the database and hardware being used.
+
+You may wish to change the `ClassName` column to a `varchar` type which remove the need to run `ALTER TABLE` whenever there is a new valid value. Enabling this will result in a trade-off where the size of the database will increase by approximately 7 MB per 100,000 rows. There will also be a very slow initial `dev/build` as all of the `ClassName` columns are switched to `varchar`. To enable this, add the following configuration:
+
+```yml
+SilverStripe\ORM\DataObject:
+  fixed_fields:
+    ClassName: DBClassNameVarchar
+```
diff --git a/en/08_Changelogs/5.4.0.md b/en/08_Changelogs/5.4.0.md
@@ -0,0 +1,47 @@
+---
+title: 5.4.0 (unreleased)
+---
+
+# 5.4.0 (unreleased)
+
+## Overview
+
+- [Features and enhancements](#features-and-enhancements)
+  - [Option to change `ClassName` column from enum to varchar](#classname-varchar)
+  - [Other new features](#other-new-features)
+- [API changes](#api-changes)
+- [Bug fixes](#bug-fixes)
+
+## Features and enhancements
+
+### Option to change `ClassName` column from enum to varchar {#classname-varchar}
+
+On websites with very large database tables it can take a long time to run `dev/build`, which can be a problem when deploying changes to production. This is because the `ClassName` column is an `enum` type which requires an a `ALTER TABLE` query to be run affecting every row whenever there is a new valid value for the column. For a very rough benchmark, running an `ALTER TABLE` query on a database table of 10 million records took 28.52 seconds on a mid-range 2023 laptop, though this time will vary depending on the database and hardware being used.
+
+This release introduces a new configuration option to change the `ClassName` column to a `varchar` type which removes the need to run `ALTER TABLE` whenever there is a new valid value.
+
+Enabling this will result in a trade-off where the size of the database will increase by approximately 7 MB per 100,000 rows. There will also be a very slow initial `dev/build` as all of the `ClassName` columns are switched to `varchar`. To enable this, add the following configuration:
+
+```yml
+SilverStripe\ORM\DataObject:
+  fixed_fields:
+    ClassName: DBClassNameVarchar
+```
+
+### Other new features
+
+- (fill this is as features are added)
+
+## API changes
+
+- (fill this is as API changes are added)
+
+## Bug fixes
+
+- (fill this is as bug fixes are added)
+
+This release includes a number of bug fixes to improve a broad range of areas. Check the change logs for full details of these fixes split by module. Thank you to the community members that helped contribute these fixes as part of the release!
+
+<!--- Changes below this line will be automatically regenerated -->
+
+<!--- Changes above this line will be automatically regenerated -->