Wiki source code of MySQL Installation

Last modified by Thomas Mortagne on 2023/11/16

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Compatibility Considerations =
6
7 See [[Database support strategy>>dev:Community.DatabaseSupportStrategy]] for the supported versions.
8
9 XWiki expects the database to use ##utf8## or ##utf8mb4## encoding with collation ##*_bin## and it's highly recommended to use ##utf8mb4## (and ##utf8mb4_bin##) which is the default since MySQL 8.
10
11 == MyISAM storage engine ==
12
13 MyISAM (the default storage engine for MySQL until release 5.5.5 in 2010) does not support transactions. If there is an error while data is being saved to the database, XWiki will attempt to roll back the transaction to its previous known good state. If you use MyISAM, it will do nothing, leaving the database in whatever state it was in when the error occurred.
14
15 {{warning}}
16 If you use MySQL with any engine that does not support transactions, you will most likely corrupt your database.** We highly recommend using a storage engine such as InnoDB which supports transactions.**
17 {{/warning}}
18
19 == MySQL versions older than 5.0 ==
20
21 XWiki does not fully work with MySQL versions 4.x or lower, due to several limitations of the way the SQL standards are implemented in MySQL, limited support for non-latin1 encodings, the flaky integration of Hibernate and MySQL 4, and other things. Most parts of the application work fine, but there are some parts that cannot be easily fixed, so if you must use MySQL 4.x, you're doing it on your own. MySQL 4 is pretty old and buggy, so we recommend upgrading.
22
23 == MySQL versions older than 5.7 and utf8mb4 ==
24
25 If you use utf8mb4 encoding, you won't be able to use a version of MySQL older than 5.7 out of the box because of a limitation in the default maximum size of the keys and the default row format.
26
27 == JDBC Driver Version ==
28
29 * It's recommended to use the latest version of the MySQL JDBC driver (8.x).
30
31 = Installation Steps =
32
33 Follow these instructions:
34
35 * Install MySQL 5.7 or greater and start it. It's always recommended to use the best method depending on your environment (for example a package on a Linux server), you can download it on [[MySQL>>http://www.mysql.com/]] if you want to manually install it.
36 * Create the wiki database. You can use the name you want for the database, but you will have to set the hibernate configuration file and ##xwiki.cfg## file accordingly.(((
37 You can create the database in several ways. For example use:
38
39 {{code language="shell"}}
40 mysql -u root -e "create database xwiki default character set utf8mb4 collate utf8mb4_bin"
41 {{/code}}
42 )))
43 * Create the ##xwiki## user with password ##xwiki##(((
44 {{code language="shell"}}
45 mysql -u root -e "CREATE USER 'xwiki'@'localhost' IDENTIFIED BY 'xwiki'";
46 {{/code}}
47 )))
48 * Give privileges to the ##xwiki## user for accessing and creating databases (for the multi wiki support). Specifically the ##xwiki## users needs permissions to be able to execute {{code language="sql"}}CREATE DATABASE{{/code}}, {{code language="sql"}}DROP SCHEMA{{/code}}, and then all CRUD operations on tables. Note that the command below should be tuned to be more restrictive as granting all permissions is not required:(((
49 {{code language="shell"}}
50 mysql -u root -e "grant all privileges on *.* to xwiki@localhost"
51 {{/code}}
52 )))
53 * If the above command fails with a password-does-not-meet-requirements error, uninstall the MySQL password_validate plugin or pick a more complex password and update the password used by default in ##hibernate.cfg.xml##:(((
54 {{code language="shell"}}
55 mysql -u root -p -e "uninstall plugin validate_password;"
56 {{/code}}
57 )))
58 * You need to have the MySQL JDBC Driver JAR (named ##mysql-connector-java*.jar##) installed in XWiki's WAR file. If this file isn't present in XWiki's ##WEB-INF/lib## directory you'll need to download it and copy it there. You can download it from the [[MySQL Connector/J Driver page>>http://www.mysql.com/downloads/connector/j/]] or directly from the [[Maven Central Repository>>https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/]].(((
59 {{warning}}
60 It's generally recommended to use the latest one.
61 {{/warning}}
62 )))
63 * Now you need to tell XWiki to use MySQL. To do this, edit the ##WEB-INF/hibernate.cfg.xml## file where you have expanded the XWiki WAR file and replace the matching properties with the following ones:(((
64 {{code language="xml"}}
65 <property name="connection.url">jdbc:mysql://localhost/xwiki</property>
66 <property name="connection.username">xwiki</property>
67 <property name="connection.password">xwiki</property>
68 <property name="connection.driver_class">com.mysql.cj.jdbc.Driver</property>
69 <property name="connection.useUnicode">true</property>
70 <property name="connection.characterEncoding">UTF-8</property>
71 {{/code}}
72
73 {{info}}
74 * By default MySQL only accepts packets that are smaller than 1MB. If you get the "Packet for query is too large (max_allowed_packet)" error then see the [[Packet too large error page>>http://dev.mysql.com/doc/refman/5.0/en/packet-too-large.html]]. For example to increase the packet size to 32M you could start the MySQL server with {{code language='shell'}}mysqld --console --max_allowed_packet=32M{{/code}} or you can modify directly the ##my.cnf## configuration file to set this value permanently.
75 * If an empty XWiki starts with no errors, but you are unable to upload the default set of pages (XAR file) try to increase the ##max_allowed_packet## parameter as shown above.
76 {{/info}}
77 )))
78
79 = Indexes =
80
81 See [[Database Administration>>Documentation.AdminGuide.Performances.Database Administration.WebHome]].
82
83 {{code language="mysql"}}
84 // Required
85 create index xwl_value on xwikilargestrings (xwl_value(50));
86 create index xwd_parent on xwikidoc (xwd_parent(50));
87 create index xwd_class_xml on xwikidoc (xwd_class_xml(20));
88 create index xda_docid1 on xwikiattrecyclebin (xda_docid);
89 create index solr_iterate_all_documents on xwikidoc (XWD_WEB(500), XWD_NAME(253), XWD_LANGUAGE(5), XWD_VERSION(10));
90 // Only required if you use stats (feature is off by default)
91 create index xws_number on xwikistatsdoc (XWS_NUMBER);
92 create index xws_classname on xwikistatsdoc (XWS_CLASSNAME);
93 create index xwr_number on xwikistatsreferer (XWR_NUMBER);
94 create index xwr_classname on xwikistatsreferer (XWR_CLASSNAME);
95 create index xwr_referer on xwikistatsreferer (XWR_REFERER(50));
96 create index xwv_user_agent on xwikistatsvisit (XWV_USER_AGENT(255));
97 create index xwv_cookie on xwikistatsvisit (XWV_COOKIE(255));
98 create index xwv_classname on xwikistatsvisit (XWV_CLASSNAME);
99 create index xwv_number on xwikistatsvisit (XWV_NUMBER);
100 {{/code}}
101
102 {{info}}
103 Note to XWiki developers: The following indexes could be created automatically though since they're less than 255 characters and thus should be added in a future version of XWiki so that they don't need to be created manually:
104
105 {{code language="mysql"}}
106 create index xws_number on xwikistatsdoc (XWS_NUMBER);
107 create index xws_classname on xwikistatsdoc (XWS_CLASSNAME);
108 create index xwr_number on xwikistatsreferer (XWR_NUMBER);
109 create index xwr_classname on xwikistatsreferer (XWR_CLASSNAME);
110 create index xwv_classname on xwikistatsvisit (XWV_CLASSNAME);
111 create index xwv_number on xwikistatsvisit (XWV_NUMBER);
112 create index xda_docid1 on xwikiattrecyclebin (xda_docid);
113 {{/code}}
114 {{/info}}
115
116 = Tips =
117
118 == MySQL 8 ==
119
120 * If you're using MySQL 8+ you'll need to configure MySQL with native password: ##default-authentication-plugin=mysql_native_password##.
121 * You'll also be able to switch from ##com.mysql.jdbc.Driver## to ##com.mysql.cj.jdbc.Driver## JDBC driver (since the previous driver class is now deprecated).
122 * If you get the following error then you'll need to force the timezone to use either by setting it in:(((
123 * The MySQL conf file on the server
124 * In the XWiki ##hibernate.cfg.xml## file in the ##hibernate.connection.serverTimezone## property (e.g. ##<property name="hibernate.connection.serverTimezone">Europe/Berlin</property>##).
125 * In the XWiki ##hibernate.cfg.xml## file inside the JDBC URL string as in ##jdbc:mysql:~/~/localhost:3306/myschema?serverTimezone=UTC##
126
127 {{code language="none"}}
128 The server timezone value 'CDT' is unrecognized or represents more than one timezone. You must configure either the server or JDBC driver (via the serverTimezone configuration property) to use a more specifc timezone value if you want to utilize timezone support.
129 {{/code}}
130
131 For more details see [[this explanation post>>https://stackoverflow.com/a/54256150/153102]].
132 )))
133
134 == Convert a database to utf8mb4/utf8mb4_bin ==
135
136 {{code language="shell"}}
137 #!/bin/bash
138
139 db=xwiki
140 to_character_set=utf8mb4
141 to_collation=utf8mb4_bin
142
143 mysql_cmd="mysql -u root"
144
145 $mysql_cmd -e "ALTER DATABASE $db CHARACTER SET $to_character_set COLLATE $to_collation;"
146
147 TBL_LIST=$($mysql_cmd -N -s -r -e "use $db;show tables;")
148
149 echo "Temporarily disable all the foreign keys"
150
151 $MYSQL_COMMAND -e "SET FOREIGN_KEY_CHECKS=0;"
152 for tbl_name in $TBL_LIST;
153 do
154 $mysql_cmd -e "alter table $db.$tbl_name convert to character set $to_character_set collate $to_collation;"
155 done
156
157 echo "Turn foreign keys back on"
158
159 $MYSQL_COMMAND -e "SET FOREIGN_KEY_CHECKS=1;"
160
161 echo "Here the result of the operation:"
162 $mysql_cmd -e "USE $db;SELECT TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLLATION_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA=DATABASE();"
163 {{/code}}
164
165 {{info}}
166 In case the above script fails with "ERROR 1118 (42000) at line 1: Row size too large. The maximum row size for the used table type, not counting BLOBs, is 65535. This includes storage overhead, check the manual. You have to change some columns to TEXT or BLOBs
167 xwikistatsvisit", you can use the following SQL statements to change tables column types to LONGTEXT to be able to convert the tables to utf8mb4.
168 {{/info}}
169
170 {{code}}
171 ALTER TABLE activitystream_events MODIFY ase_url LONGTEXT, MODIFY ase_title LONGTEXT, MODIFY ase_body LONGTEXT, MODIFY ase_param1 LONGTEXT, MODIFY ase_param2 LONGTEXT, MODIFY ase_param3 LONGTEXT, MODIFY ase_param4 LONGTEXT, MODIFY ase_param5 LONGTEXT;
172 ALTER TABLE xwikistatsreferer MODIFY XWR_REFERER LONGTEXT;
173 ALTER TABLE xwikistatsvisit MODIFY XWV_USER_AGENT LONGTEXT, MODIFY XWV_COOKIE LONGTEXT;
174 ALTER TABLE xwikipreferences MODIFY XWP_LEFT_PANELS LONGTEXT, MODIFY XWP_RIGHT_PANELS LONGTEXT, MODIFY XWP_DOCUMENT_BUNDLES LONGTEXT;
175 {{/code}}
176
177 You can also look at [[this snippet to perform this conversion inside XWiki>>snippets:Extension.Migrate MySQL databases to utf8mb4]].
178
179 == Convert from MyISAM to InnoDB ==
180
181 {{code language="shell"}}
182 #!/bin/bash
183
184 MYSQL_COMMAND=mysql
185 TO_ENGINE=INNODB
186
187 DATABASES=$(mysql -N -s -r -e 'show databases'|grep -v ^information_schema$|grep -v ^mysql$)
188
189 for db in $DATABASES
190 do
191
192 echo "Working on database $db..."
193 echo ""
194
195 TABLES=$(mysql -N -s -r -e "show tables from $db;")
196
197 for tb in $TABLES
198 do
199
200 $MYSQL_COMMAND -e "ALTER TABLE $db.$tb ENGINE = $TO_ENGINE;"
201
202 done
203
204 $MYSQL_COMMAND -e "SELECT table_name,Engine,table_collation FROM information_schema.tables WHERE table_schema = DATABASE();"
205
206 echo ""
207 echo ""
208
209 done
210 {{/code}}
211
212 = Troubleshooting =
213
214 == "Incorrect string value" error with MySQL connector between 8.0.29 and 8.0.32 ==
215
216 {{info}}
217 This is fixed in the connector 8.0.33.
218 {{/info}}
219
220 There seems to be a regression in MySQL connector 8.0.29 that leads to using the default encoding even when it's explicitly indicated in the hibernate.cfg.xml file (which is what you have in the MySQL configuration recommendation provided by XWiki). We are currently searching what could be the cause and find a workaround in https://jira.xwiki.org/browse/XWIKI-19853 but in the (and in general) it's recommended to make sure that you are running XWiki with the right default Java encoding. You can do that by making sure Java is run with ##-Dfile.encoding=utf8## (this is generally the default in standard Tomcat packages of various Linux distribution, but it might not always be the case).
221
222 == Unable to login to MySQL Console ==
223
224 When running {{code language="shell"}}mysql -u root -e "create database xwiki default character set utf8mb4{{/code}} you may get a {{code}}ERROR 1045 (28000): Access denied for user 'xwiki'@'localhost' (using password: YES){{/code}} error.
225 This means that you have a password set for the MySQL root user, but you are not specifying it in the console command. You must also use the //-p// parameter. Using this you will be prompted to enter the password and be allowed to login to the MySQL console and create the database.
226
227 == Can't create test file ==
228
229 When running ##mysqld ~-~-console## you may get the following (especially if you're on a Mac):
230
231 {{code language="none"}}
232 071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
233 071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
234 mysqld: Can't change dir to '/usr/local/mysql-5.0.45-osx10.4-i686/data/' (Errcode: 13)
235 071111 17:20:53 [ERROR] Aborting
236 {{/code}}
237
238 To start MySQL run the following command instead:
239
240 {{code}}
241 sudo /usr/local/mysql/bin/mysqld_safe --user=mysql
242 {{/code}}
243
244 == Data Truncation Error ==
245
246 If you receive an Exception like the following while installing/upgrading XWiki, chances are that you are using an outdated version of MySQLConnectorJ.
247
248 {{code language="none"}}
249 Caused by: java.sql.BatchUpdateException: Data truncation: Out of
250 range value adjusted for column 'XWD_HIDDEN' at row 1
251 at com.mysql.jdbc.PreparedStatement.executeBatch(PreparedStatement.java:894)
252 at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
253 at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
254 at org.hibernate.jdbc.BatchingBatcher.doExecuteBatch(BatchingBatcher.java:48)
255 at org.hibernate.jdbc.AbstractBatcher.executeBatch(AbstractBatcher.java:246)
256 {{/code}}
257
258 On Linux, mysql-connector-java-3.x has proven **not** to work due to a bug in the handling of UTF-8 and lack of support for Boolean types.
259
260 Upgrading to the latest version of MySQLConnectorJ should solve such an error in most of the cases.
261
262 == HTTP 500 Error ==
263
264 {{code language="none"}}
265 HTTP Status 500 -
266
267 type Exception report
268
269 message
270
271 descriptionThe server encountered an internal error () that prevented it from fulfilling this request.
272
273 exception
274
275 javax.servlet.ServletException: com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
276 Wrapped Exception: Error number 3001 in 3: Cannot load class com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
277 Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
278 Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.
279
280 root cause
281
282 com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
283 Wrapped Exception: Error number 3001 in 3: Cannot load class com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
284 Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
285 Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.
286 {{/code}}
287
288 In this case, try to disable **skip-networking** in MySQL *.ini file. Thanks a lot //M Rawash// (see his comment below).
289
290 == Unknown database 'xwiki' ==
291
292 If you get the following error:
293
294 {{code language="none"}}
295 Caused by: class com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown database 'xwiki'
296 at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
297 at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
298 at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
299 at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
300 at com.mysql.jdbc.Util.handleNewInstance(Util.java:408)
301 at com.mysql.jdbc.Util.getInstance(Util.java:383)
302 at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1062)
303 at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4226)
304 at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4158)
305 at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:2615)
306 at com.mysql.jdbc.MysqlIO.sqlQueryDirect(MysqlIO.java:2776)
307 at com.mysql.jdbc.ConnectionImpl.execSQL(ConnectionImpl.java:2834)
308 at com.mysql.jdbc.ConnectionImpl.setCatalog(ConnectionImpl.java:5456)
309 at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
310 at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
311 at org.apache.commons.dbcp.PoolingDataSource$PoolGuardConnectionWrapper.setCatalog(PoolingDataSource.java:333)
312 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
313 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
314 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
315 at java.lang.reflect.Method.invoke(Method.java:606)
316 at org.hibernate.jdbc.BorrowedConnectionProxy.invoke(BorrowedConnectionProxy.java:74)
317 at com.sun.proxy.$Proxy47.setCatalog(Unknown Source)
318 at com.xpn.xwiki.store.XWikiHibernateBaseStore.setDatabase(XWikiHibernateBaseStore.java:729)
319 at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:911)
320 at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:843)
321 at com.xpn.xwiki.store.XWikiHibernateStore.loadXWikiDoc(XWikiHibernateStore.java:830)
322 ...
323 {{/code}}
324
325 It means that XWiki could connect to your database but there's no ##xwiki## schema available there. This is the default name of the schema XWiki is looking for, for the main wiki database.
326
327 It probably means you've created a database named other than ##xwiki## (for example you might have created a database named ##abcd## and set the following connection URL in your ##hibernate.cfg## file: {{code language="none"}}<property name="connection.url">jdbc:mysql://localhost/abcd</property>{{/code}}).
328
329 If this is the case [[you need to tell XWiki that you're using a different schema by setting the ##xwiki.db## configuration property>>Documentation.AdminGuide.Configuration#HConfigurethenamesofdatabaseschemas]].
330
331 == MySQLSyntaxErrorException: Row size too large (> 8126) ==
332
333 if you get the following error:
334
335 {{code language="none"}}
336 MySQLSyntaxErrorException: Row size too large (> 8126).
337 Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.
338 In current row format, BLOB prefix of 768 bytes is stored inline.
339 {{/code}}
340
341 When you are using a MySQL Server 5.6.20 you can get a "row size too large error."
342 In the release notes, it is explained that a innodb_log_file_size which is too small will trigger a "Row size too large error."
343
344 You can solve the problem by changing the innodb_log_file_size in the my.ini text file.
345 Find more details in the link below.
346 http://dev.mysql.com/doc/relnotes/mysql/5.6/en/news-5-6-20.html

Get Connected