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

Get Connected