BookStack Code Mirror - website/blob - content/docs/admin/utf8mb4-upgrade.md

   1 +++
   2 title = "UTF8mb4/Emoji Support"
   3 description = "Adding UTF8mb4 support to allow use of emoji in content"
   4 date = "2017-01-01"
   5 type = "admin-doc"
   6 slug = "ut8mb4-support"
   7 +++
   8
   9
  10 As of BookStack v0.17 `UTF8mb4` is the default database charset and collation which allows emoji support.
  11 If you installed and used BookStack prior to v0.17 you will have to upgrade your database manually
  12 to support emoji.
  13
  14 **WARNING: Before following any of the below create a backup of your database to prevent potential data loss.**
  15
  16 From v0.17.2, BookStack has a helper command to generate the SQL for this change. Ensure you are on BookStack v0.17.2 or above and then run this command from root BookStack folder:
  17
  18 ```bash
  19 php artisan bookstack:db-utf8mb4
  20 ```
  21
  22 You can use the output of this command and execute the SQL output on your database to upgrade your database. Here's a general example of how you might do this on a unix-like system with MySQL.
  23
  24 ```bash
  25 # Navigate to the bookstack folder
  26 cd bookstack-folder
  27
  28 # Generate the upgrade sql and output to a 'dbupgrade.sql' file
  29 php artisan bookstack:db-utf8mb4 > dbupgrade.sql
  30
  31 # Run the SQL via MySQL (Using root account)
  32 mysql -u root < dbupgrade.sql
  33
  34 ```
  35
  36 ### On 'Key too long' Error
  37
  38 You may get an error with a message along the lines of 'Specified key was too long' when following the above steps. In this scenario, If you want full emoji support, it may be best to re-create the database. Below is the recommended approach to achieving this. **BACKUP ALL DB DATA BEFORE PROCEEDING**.
  39
  40 1. Dump all data from the database (Data only). For example:
  41   ```bash
  42   # Change 'bookstack_db' to your bookstack database name
  43   mysqldump -u root --no-create-info bookstack_db > bookstack_data.sql
  44   ```
  45 2. Re-create the database or create a new one.
  46 3. Update your BookStack config with new database details if required.
  47 4. Run `php artisan migrate` from your BookStack folder to migrate the database and re-create all tables.
  48 5. Restore the data from step 1:
  49   ```bash
  50   mysql -u root < bookstack_data.sql
  51   ```
  52 6. Run `php artisan migrate` again to ensure the database is up-to-date.