Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Compatibility Considerations =
6
7 {{error}}
8 Currently we seem to have some [[problem with MySQL server 8.x or MySQL connector 8.x>>https://jira.xwiki.org/browse/XWIKI-15215]]. It is recommended to use MySQL server 5.7.x or earlier (and connector 5.1.x) if you're using XWiki 10.x (the issue is fixed if you're on XWiki 11.3+).
9 {{/error}}
10
11 See [[Database support strategy>>dev:Community.DatabaseSupportStrategy]] for the supported versions.
12
13 == MyISAM storage engine ==
14
15 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.
16
17 {{warning}}
18 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.**
19 {{/warning}}
20
21 == MySQL versions older than 5.0 ==
22
23 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.
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}}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}}
35 mysql -u root -e "create database xwiki default character set utf8mb4 collate utf8mb4_bin"
36 {{/code}}
37 )))
38 * 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:(((
39 {{code}}
40 mysql -u root -e "grant all privileges on *.* to [email protected] identified by 'xwiki'"
41 {{/code}}
42 )))
43 * 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##:(((
44 {{code}}
45 mysql -u root -p -e "uninstall plugin validate_password;"
46 {{/code}}
47 )))
48 * Please make sure that the DNS-name "localhost" is defined in your hosts-file (i.e. ##/etc/hosts##)
49 * 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/]].(((
50 {{warning}}
51 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.
52 {{/warning}}
53 )))
54 * 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:(((
55 {{code language="xml"}}
56 <property name="connection.url">jdbc:mysql://localhost/xwiki</property>
57 <property name="connection.username">xwiki</property>
58 <property name="connection.password">xwiki</property>
59 <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
60 <property name="dialect">org.hibernate.dialect.MySQL5InnoDBDialect</property>
61 <property name="connection.useUnicode">true</property>
62 <property name="connection.characterEncoding">UTF-8</property>
63 {{/code}}
64
65 {{info}}
66 * 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.
67 * 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.
68 {{/info}}
69 )))
70
71 = Tips =
72
73 == Convert a database from latin1 (or collation utf8_ci) to utf8mb4/utf8mb4_bin ==
74
75 {{code}}
76 #!/bin/bash
77
78 db=xwiki
79 to_character_set=utf8mb4
80 to_collation=utf8mb4_bin
81
82 mysql_cmd="mysql -u root"
83
84 $mysql_cmd -e "ALTER DATABASE $db CHARACTER SET $to_character_set COLLATE $to_collation;"
85
86 TBL_LIST=$($mysql_cmd -N -s -r -e "use $db;show tables;")
87
88 for tbl_name in $TBL_LIST;
89 do
90 $mysql_cmd -e "alter table $db.$tbl_name convert to character set $to_character_set collate $to_collation;"
91 done
92
93 echo "Here the result of the operation:"
94 $mysql_cmd -e "USE $db;SELECT TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLLATION_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA=DATABASE();"
95 {{/code}}
96
97 == Convert from MyISAM to InnoDB ==
98
99 {{code}}
100 #!/bin/bash
101
102 MYSQL_COMMAND=mysql
103 TO_ENGINE=INNODB
104
105 DATABASES=$(mysql -N -s -r -e 'show databases'|grep -v ^information_schema$|grep -v ^mysql$)
106
107
108 for db in $DATABASES
109 do
110
111 echo "Working on database $db..."
112 echo ""
113
114 TABLES=$(mysql -N -s -r -e "show tables from $db;")
115
116 for tb in $TABLES
117 do
118
119 $MYSQL_COMMAND -e "ALTER TABLE $db.$tb ENGINE = $TO_ENGINE;"
120
121 done
122
123 $MYSQL_COMMAND -e "SELECT table_name,Engine,table_collation FROM information_schema.tables WHERE table_schema = DATABASE();"
124
125 echo ""
126 echo ""
127
128 done
129 {{/code}}
130
131 = Troubleshooting =
132
133 == Unable to login to MySQL Console ==
134
135 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.
136 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.
137
138 == Can't create test file ==
139
140 When running ##mysqld ~-~-console## you may get the following (especially if you're on a Mac):
141
142 {{code}}
143 071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
144 071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
145 mysqld: Can't change dir to '/usr/local/mysql-5.0.45-osx10.4-i686/data/' (Errcode: 13)
146 071111 17:20:53 [ERROR] Aborting
147 {{/code}}
148
149 To start MySQL run the following command instead:
150
151 {{code}}
152 sudo /usr/local/mysql/bin/mysqld_safe --user=mysql
153 {{/code}}
154
155 == Data Truncation Error ==
156
157 If you receive an Exception like the following while installing/upgrading XWiki, chances are that you are using an outdated version of MySQLConnectorJ.
158
159 {{code}}
160 Caused by: java.sql.BatchUpdateException: Data truncation: Out of
161 range value adjusted for column 'XWD_HIDDEN' at row 1
162 at com.mysql.jdbc.PreparedStatement.executeBatch(PreparedStatement.java:894)
163 at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
164 at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
165 at org.hibernate.jdbc.BatchingBatcher.doExecuteBatch(BatchingBatcher.java:48)
166 at org.hibernate.jdbc.AbstractBatcher.executeBatch(AbstractBatcher.java:246)
167 {{/code}}
168
169 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.
170
171 Upgrading to the latest version of MySQLConnectorJ should solve such an error in most of the cases.
172
173 == HTTP 500 Error ==
174
175 {{code}}
176 HTTP Status 500 -
177
178 type Exception report
179
180 message
181
182 descriptionThe server encountered an internal error () that prevented it from fulfilling this request.
183
184 exception
185
186 javax.servlet.ServletException: com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
187 Wrapped Exception: Error number 3001 in 3: Cannot load class com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
188 Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
189 Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.
190
191 root cause
192
193 com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
194 Wrapped Exception: Error number 3001 in 3: Cannot load class com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
195 Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
196 Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.
197 {{/code}}
198
199 In this case, try to disable **skip-networking** in MySQL *.ini file. Thanks a lot //M Rawash// (see his comment below).
200
201 == Unknown database 'xwiki' ==
202
203 If you get the following error:
204
205 {{code language="none"}}
206 Caused by: class com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown database 'xwiki'
207 at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
208 at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
209 at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
210 at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
211 at com.mysql.jdbc.Util.handleNewInstance(Util.java:408)
212 at com.mysql.jdbc.Util.getInstance(Util.java:383)
213 at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1062)
214 at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4226)
215 at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4158)
216 at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:2615)
217 at com.mysql.jdbc.MysqlIO.sqlQueryDirect(MysqlIO.java:2776)
218 at com.mysql.jdbc.ConnectionImpl.execSQL(ConnectionImpl.java:2834)
219 at com.mysql.jdbc.ConnectionImpl.setCatalog(ConnectionImpl.java:5456)
220 at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
221 at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
222 at org.apache.commons.dbcp.PoolingDataSource$PoolGuardConnectionWrapper.setCatalog(PoolingDataSource.java:333)
223 at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
224 at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
225 at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
226 at java.lang.reflect.Method.invoke(Method.java:606)
227 at org.hibernate.jdbc.BorrowedConnectionProxy.invoke(BorrowedConnectionProxy.java:74)
228 at com.sun.proxy.$Proxy47.setCatalog(Unknown Source)
229 at com.xpn.xwiki.store.XWikiHibernateBaseStore.setDatabase(XWikiHibernateBaseStore.java:729)
230 at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:911)
231 at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:843)
232 at com.xpn.xwiki.store.XWikiHibernateStore.loadXWikiDoc(XWikiHibernateStore.java:830)
233 ...
234 {{/code}}
235
236 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.
237
238 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}}).
239
240 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]].
241
242 == MySQLSyntaxErrorException: Row size too large (> 8126) ==
243
244 if you get the following error:
245
246 {{code language="none"}}
247 MySQLSyntaxErrorException: Row size too large (> 8126).
248 Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.
249 In current row format, BLOB prefix of 768 bytes is stored inline.
250 {{/code}}
251
252 When you are using a MySQL Server 5.6.20 you can get a "row size too large error."
253 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."
254
255 You can solve the problem by changing the innodb_log_file_size in the my.ini text file.
256 Find more details in the link below.
257 http://dev.mysql.com/doc/relnotes/mysql/5.6/en/news-5-6-20.html

Get Connected