@@ -70,6 +70,72 @@ DeclareSchema::Migration::Migrator.before_generating_migration do
7070end
7171```
7272
73+ ## Declaring Character Set and Collation
74+ _ Note: This feature currently only works for MySQL database configurations._
75+
76+ MySQL originally supported UTF-8 in the range of 1-3 bytes (` mb3 ` or "multi-byte 3")
77+ which covered the full set of Unicode code points at the time: U+0000 - U+FFFF.
78+ But later, Unicode was extended beyond U+FFFF to make room for emojis, and with that
79+ UTF-8 require 1-4 bytes (` mb4 ` or "multi-byte 4"). With this addition, there has
80+ come a need to dynamically define the character set and collation for individual
81+ tables and columns in the database. With ` declare_schema ` this can be configured
82+ at three separate levels
83+
84+ ### Global Configuration
85+ The character set and collation for all tables and fields can be set at the global level
86+ using the ` Generators::DeclareSchema::Migrator.default_charset= ` and
87+ ` Generators::DeclareSchema::Migrator.default_collation= ` configuration methods.
88+
89+ For example, adding the following to your ` config/initializers ` directory will
90+ turn all tables into ` utf8mb4 ` supporting tables:
91+
92+ ** declare_schema.rb**
93+ ``` ruby
94+ # frozen_string_literal: true
95+
96+ Generators ::DeclareSchema ::Migration ::Migrator .default_charset = " utf8mb4"
97+ Generators ::DeclareSchema ::Migration ::Migrator .default_collation = " utf8mb4_general"
98+ ```
99+
100+ ### Table Configuration
101+ In order to configure a table's default character set and collation, the ` charset ` and
102+ ` collation ` arguments can be added to the ` fields ` block.
103+
104+ For example, if you have a comments model that needs ` utf8mb4 ` support, it would look
105+ like the following:
106+
107+ ** app/models/comment.rb**
108+ ``` ruby
109+ # frozen_string_literal: true
110+
111+ class Comment < ActiveRecord ::Base
112+ fields charset: " utf8mb4" collation: " utf8mb4_general" do
113+ subject :string , limit: 255
114+ content :text , limit: 0xffff_ffff
115+ end
116+ end
117+ ```
118+
119+ ### Field Configuration
120+ If you're looking to only change the character set and collation for a single field
121+ in the table, simply set the ` charset ` and ` collation ` configuration options on the
122+ field definition itself.
123+
124+ For example, if you only want to support ` utf8mb4 ` for the content of a comment, it would
125+ look like the following:
126+
127+ ** app/models/comment.rb**
128+ ``` ruby
129+ # frozen_string_literal: true
130+
131+ class Comment < ActiveRecord ::Base
132+ fields do
133+ subject :string , limit: 255
134+ context :text , limit: 0xffff_ffff , charset: " utf8mb4" collation: " utf8mb4_general"
135+ end
136+ end
137+ ```
138+
73139## Installing
74140
75141Install the ` DeclareSchema ` gem directly:
0 commit comments