Wiki source code of MySQL Installation

Last modified by Vincent Massol on 2020/12/02

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 == MyISAM storage engine ==
10
11 MyISAM (the default storage engine for MySQL) does not support transactions. If there is an error while data is being saved to the database, XWiki will attempt to rollback 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.
12
13 {{warning}}
14 If you use MySQL with the default engine MyISAM, you will most likely corrupt your database.**We highly recommend using a storage engine such as InnoDB which supports transactions.**
15 {{/warning}}
16
17 == MySQL versions older than 5.0 ==
18
19 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.
20
21 == MySQL versions older than 5.7 and utf8mb4 ==
22
23 If you use utf8mb4 encoding you won't be able to use 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.
24
25 = Installation Steps =
26
27 Follow these instructions:
28
29 * Download and install [[MySQL>>http://www.mysql.com/]] 5.x or greater.
30 * Start the MySQL server. You can do that in several ways. For example use {{code language='shell'}}mysqld --console{{/code}}
31 * 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.(((
32 You can create the database in several ways. For example use:
33
34 {{code language='shell'}}
35 mysql -u root -e "create database xwiki default character set utf8mb4 collate utf8mb4_bin"
36 {{/code}}
37 )))
38 * Create the ##xwiki## user with password ##xwiki##(((
39 {{code language='shell'}}
40 mysql -u root -e "CREATE USER 'xwiki'@'localhost' IDENTIFIED BY 'xwiki'";
41 {{/code}}
42 )))
43 * 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:(((
44 {{code language='shell'}}
45 mysql -u root -e "grant all privileges on *.* to [email protected]"
46 {{/code}}
47 )))
48 * 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##:(((
49 {{code language='shell'}}
50 mysql -u root -p -e "uninstall plugin validate_password;"
51 {{/code}}
52 )))
53 * Please make sure that the DNS-name "localhost" is defined in your hosts-file (i.e. ##/etc/hosts##)
54 * 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>>http://repo1.maven.org/maven2/mysql/mysql-connector-java/]].(((
55 {{warning}}
56 You need the 5.x version or higher. The 3.x version doesn't handle Boolean data correctly and will either throw errors or will make all documents hidden by default.
57 {{/warning}}
58 )))
59 * 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:(((
60 {{code language="xml"}}
61 <property name="connection.url">jdbc:mysql://localhost/xwiki</property>
62 <property name="connection.username">xwiki</property>
63 <property name="connection.password">xwiki</property>
64 <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
65 <property name="dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>
66 <property name="connection.useUnicode">true</property>
67 <property name="connection.characterEncoding">UTF-8</property>
68 {{/code}}
69
70 {{info}}
71 * 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.
72 * 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.
73 {{/info}}
74 )))
75
76 = Indexes =
77
78 See [[Database Administration>>Documentation.AdminGuide.Performances.Database Administration.WebHome]].
79
80 {{code language='mysql'}}
81 // Required
82 create index xwl_value on xwikilargestrings (xwl_value(50));
83 create index xwd_parent on xwikidoc (xwd_parent(50));
84 create index xwd_class_xml on xwikidoc (xwd_class_xml(20));
85 create index ase_page_date on activitystream_events (ase_page, ase_date);
86 create index xda_docid1 on xwikiattrecyclebin (xda_docid);
87 create index ase_param1 on activitystream_events (ase_param1(200));
88 create index ase_param2 on activitystream_events (ase_param2(200));
89 create index ase_param3 on activitystream_events (ase_param3(200));
90 create index ase_param4 on activitystream_events (ase_param4(200));
91 create index ase_param5 on activitystream_events (ase_param5(200));
92 // Only required if you use stats (feature is off by default)
93 create index xws_number on xwikistatsdoc (XWS_NUMBER);
94 create index xws_classname on xwikistatsdoc (XWS_CLASSNAME);
95 create index xwr_number on xwikistatsreferer (XWR_NUMBER);
96 create index xwr_classname on xwikistatsreferer (XWR_CLASSNAME);
97 create index xwr_referer on xwikistatsreferer (XWR_REFERER(50));
98 create index xwv_user_agent on xwikistatsvisit (XWV_USER_AGENT(255));
99 create index xwv_cookie on xwikistatsvisit (XWV_COOKIE(255));
100 create index xwv_classname on xwikistatsvisit (XWV_CLASSNAME);
101 create index xwv_number on xwikistatsvisit (XWV_NUMBER);
102 {{/code}}
103
104 {{info}}
105 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:
106
107 {{code language='mysql'}}
108 create index xws_number on xwikistatsdoc (XWS_NUMBER);
109 create index xws_classname on xwikistatsdoc (XWS_CLASSNAME);
110 create index xwr_number on xwikistatsreferer (XWR_NUMBER);
111 create index xwr_classname on xwikistatsreferer (XWR_CLASSNAME);
112 create index xwv_classname on xwikistatsvisit (XWV_CLASSNAME);
113 create index xwv_number on xwikistatsvisit (XWV_NUMBER);
114 create index xda_docid1 on xwikiattrecyclebin (xda_docid);
115 {{/code}}
116 {{/info}}
117
118 = Tips =
119
120 == MySQL 8 ==
121
122 * If you're using MySQL 8+ you'll need to configure MySQL with native password: ##default-authentication-plugin=mysql_native_password##.
123 * 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).
124 * If you get the following error then you'll need to force the timezone to use either by setting it in:(((
125 * The MySQL conf file on the server
126 * In the XWiki ##hibernate.cfg.xml## file in the ##hibernate.connection.serverTimezone## property (e.g. ##<property name="hibernate.connection.serverTimezone">Europe/Berlin</property>##).
127 * In the XWiki ##hibernate.cfg.xml## file inside the JDBC URL string as in ##jdbc:mysql:~/~/localhost:3306/myschema?serverTimezone=UTC##
128
129 {{code language='none'}}
130 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.
131 {{/code}}
132
133 For more details see [[this explanation post>>https://stackoverflow.com/a/54256150/153102]].
134 )))
135
136 == Convert a database from latin1 (or collation utf8_ci) to utf8mb4/utf8mb4_bin ==
137
138 {{code language='shell'}}
139 #!/bin/bash
140
141 db=xwiki
142 to_character_set=utf8mb4
143 to_collation=utf8mb4_bin
144
145 mysql_cmd="mysql -u root"
146
147 $mysql_cmd -e "ALTER DATABASE $db CHARACTER SET $to_character_set COLLATE $to_collation;"
148
149 TBL_LIST=$($mysql_cmd -N -s -r -e "use $db;show tables;")
150
151 for tbl_name in $TBL_LIST;
152 do
153 $mysql_cmd -e "alter table $db.$tbl_name convert to character set $to_character_set collate $to_collation;"
154 done
155
156 echo "Here the result of the operation:"
157 $mysql_cmd -e "USE $db;SELECT TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLLATION_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA=DATABASE();"
158 {{/code}}
159
160 You can also look at [[this snippet to perform this conversion inside XWiki>>snippets:Extension.Migrate MySQL databases to utf8mb4]].
161
162 == Convert from MyISAM to InnoDB ==
163
164 {{code language='shell'}}
165 #!/bin/bash
166
167 MYSQL_COMMAND=mysql
168 TO_ENGINE=INNODB
169
170 DATABASES=$(mysql -N -s -r -e 'show databases'|grep -v ^information_schema$|grep -v ^mysql$)
171
172
173 for db in $DATABASES
174 do
175
176 echo "Working on database $db..."
177 echo ""
178
179 TABLES=$(mysql -N -s -r -e "show tables from $db;")
180
181 for tb in $TABLES
182 do
183
184 $MYSQL_COMMAND -e "ALTER TABLE $db.$tb ENGINE = $TO_ENGINE;"
185
186 done
187
188 $MYSQL_COMMAND -e "SELECT table_name,Engine,table_collation FROM information_schema.tables WHERE table_schema = DATABASE();"
189
190 echo ""
191 echo ""
192
193 done
194 {{/code}}
195
196 = Troubleshooting =
197
198 == Unable to login to MySQL Console ==
199
200 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.
201 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.
202
203 == Can't create test file ==
204
205 When running ##mysqld ~-~-console## you may get the following (especially if you're on a Mac):
206
207 {{code language='none'}}
208 071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
209 071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
210 mysqld: Can't change dir to '/usr/local/mysql-5.0.45-osx10.4-i686/data/' (Errcode: 13)
211 071111 17:20:53 [ERROR] Aborting
212 {{/code}}
213
214 To start MySQL run the following command instead:
215
216 {{code}}
217 sudo /usr/local/mysql/bin/mysqld_safe --user=mysql
218 {{/code}}
219
220 == Data Truncation Error ==
221
222 If you receive an Exception like the following while installing/upgrading XWiki, chances are that you are using an outdated version of MySQLConnectorJ.
223
224 {{code language='none'}}
225 Caused by: java.sql.BatchUpdateException: Data truncation: Out of
226 range value adjusted for column 'XWD_HIDDEN' at row 1
227 at com.mysql.jdbc.PreparedStatement.executeBatch(PreparedStatement.java:894)
228 at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
229 at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
230 at org.hibernate.jdbc.BatchingBatcher.doExecuteBatch(BatchingBatcher.java:48)
231 at org.hibernate.jdbc.AbstractBatcher.executeBatch(AbstractBatcher.java:246)
232 {{/code}}
233
234 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.
235
236 Upgrading to the latest version of MySQLConnectorJ should solve such an error in most of the cases.
237
238 == HTTP 500 Error ==
239
240 {{code language='none'}}
241 HTTP Status 500 -
242
243 type Exception report
244
245 message
246
247 descriptionThe server encountered an internal error () that prevented it from fulfilling this request.
248
249 exception
250
251 javax.servlet.ServletException: com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
252 Wrapped Exception: Error number 3001 in 3: Cannot load class com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
253 Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
254 Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.
255
256 root cause
257
258 com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
259 Wrapped Exception: Error number 3001 in 3: Cannot load class com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
260 Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
261 Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.
262 {{/code}}
263
264 In this case, try to disable **skip-networking** in MySQL *.ini file. Thanks a lot //M Rawash// (see his comment below).
265
266 == Unknown database 'xwiki' ==
267
268 If you get the following error:
269
270 {{code language='none'}}
271 Caused by: class com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown database 'xwiki'
272 at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
273 at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
274 at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
275 at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
276 at com.mysql.jdbc.Util.handleNewInstance(Util.java:408)
277 at com.mysql.jdbc.Util.getInstance(Util.java:383)
278 at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1062)
279 at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4226)
280 at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4158)
281 at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:2615)
282 at com.mysql.jdbc.MysqlIO.sqlQueryDirect(MysqlIO.java:2776)
283 at com.mysql.jdbc.ConnectionImpl.execSQL(ConnectionImpl.java:2834)
284 at com.mysql.jdbc.ConnectionImpl.setCatalog(ConnectionImpl.java:5456)
285 at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
286 at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
287 at org.apache.commons.dbcp.PoolingDataSource$PoolGuardConnectionWrapper.setCatalog(PoolingDataSource.java:333)
288 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
289 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
290 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
291 at java.lang.reflect.Method.invoke(Method.java:606)
292 at org.hibernate.jdbc.BorrowedConnectionProxy.invoke(BorrowedConnectionProxy.java:74)
293 at com.sun.proxy.$Proxy47.setCatalog(Unknown Source)
294 at com.xpn.xwiki.store.XWikiHibernateBaseStore.setDatabase(XWikiHibernateBaseStore.java:729)
295 at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:911)
296 at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:843)
297 at com.xpn.xwiki.store.XWikiHibernateStore.loadXWikiDoc(XWikiHibernateStore.java:830)
298 ...
299 {{/code}}
300
301 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.
302
303 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}}).
304
305 If this is the case [[you need to tell XWiki that you're using a different schema by setting the ##xwiki.db## configuration property>>platform:AdminGuide.Configuration#HConfigurethenamesofdatabaseschemas]].
306
307 == MySQLSyntaxErrorException: Row size too large (> 8126) ==
308
309 if you get the following error:
310
311 {{code language='none'}}
312 MySQLSyntaxErrorException: Row size too large (> 8126).
313 Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.
314 In current row format, BLOB prefix of 768 bytes is stored inline.
315 {{/code}}
316
317 When you are using a MySQL Server 5.6.20 you can get a "row size too large error."
318 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."
319
320 You can solve the problem by changing the innodb_log_file_size in the my.ini text file.
321 Find more details in the link below.
322 http://dev.mysql.com/doc/relnotes/mysql/5.6/en/news-5-6-20.html

Get Connected