1DBD::mysql::INSTALL(3)User Contributed Perl DocumentationDBD::mysql::INSTALL(3)
2
6 INSTALL - How to install and configure DBD::mysql
7
9 perl Makefile.PL [options]
10 make
11 make test
12 make install
13
15 This document describes the installation and configuration of
16 DBD::mysql, the Perl DBI driver for the MySQL database. Before reading
17 on, make sure that you have the prerequisites available: Perl, MySQL
18 and DBI. For details see the separate section. "PREREQUISITES".
19 Depending on your version of Perl, it might be possible to use a binary
21 distribution of DBD::mysql. If possible, this is recommended. Otherwise
22 you need to install from the sources. If so, you will definitely need
23 a C compiler. Installation from binaries and sources are both described
24 in separate sections. "BINARY INSTALLATION". "SOURCE INSTALLATION".
25 Finally, if you encounter any problems, do not forget to read the
27 section on known problems. "KNOWN PROBLEMS". If that doesn't help, you
28 should look into the archive of the mailing list perl@lists.mysql.com.
29 See http://www.mysql.com for archive locations. And if that still
30 doesn't help, please post a question on this mailing list.
31
33 Perl
34 Preferrably a version of Perl, that comes preconfigured with your
35 system. For example, all Linux and FreeBSD distributions come with
36 Perl. For Windows, ActivePerl is recommended, see
37 http://www.activestate.com for details.
38 MySQL
40 You need not install the actual MySQL database server, the client
41 files and the devlopment files are sufficient. For example, Fedora
42 Core 4 Linux distribution comes with RPM files (using YUM)
43 mysql.i386 and mysql-server.i386 (use "yum search" to find exact
44 package names). These are sufficient, if the MySQL server is
45 located on a foreign machine. You may also create client files by
46 compiling from the MySQL source distribution and using
47 configure --without-server
49 If you are using Windows and need to compile from sources (which is
51 only the case if you are not using ActivePerl), then you must
52 ensure that the header and library files are installed. This may
53 require choosing a "Custom installation" and selecting the
54 appropriate option when running the MySQL setup program.
55 DBI DBD::mysql is a DBI driver, hence you need DBI. It is available
57 from the same source where you got the DBD::mysql distribution
58 from.
59 C compiler
61 A C compiler is only required, if you install from source. In most
62 cases there are binary distributions of DBD::mysql available.
63 However, if you need a C compiler, make sure, that it is the same C
64 compiler that was used for compiling Perl and MySQL! Otherwise you
65 will almost definitely encounter problems because of differences in
66 the underlying C runtime libraries.
67 In the worst case, this might mean to compile Perl and MySQL
69 yourself. But believe me, experience shows that a lot of problems
70 are fixed this way.
71 Gzip libraries
73 Late versions of MySQL come with support for compression. Thus it
74 may be required that you have install an RPM package like libz-
75 devel, libgz-devel or something similar.
76
78 Binary installation is possible in the most cases, depending on your
79 system. I give some examples:
80 Windows
82 ActivePerl offers a PPM archive of DBD::mysql. All you need to do is
83 typing
84 ppm
86 install DBI
87 install DBD-mysql
88 This will fetch the modules via HTTP and install them. If you need to
90 use a WWW proxy server, the environment variable HTTP_proxy must be
91 set:
92 set HTTP_proxy=http://my.proxy.server:8000/
94 ppm
95 install DBI
96 install DBD-mysql
97 Of course you need to replace the host name "my.proxy.server" and the
99 port number 8000 with your local values.
100 If the above procedure doesn't work, please upgrade to the latest
102 version of ActivePerl. Versions before build 623 are known to have
103 problems.
104 PPM 3 is said to miss DBD::mysql in the repository. Thus use of PPM 3
106 is discouraged, in favour of PPM 2. If you need to use PPM 3, try
107 ppm
109 rep add PPM2 http://ppm.activestate.com/PPMPackages/5.6plus/
110 rep 2
111 install DBI
112 install DBD-mysql
113 Red Hat Linux
115 As of version 7.1, Red Hat Linux comes with MySQL and DBD::mysql. You
116 need to ensure that the following RPM's are installed:
117 mysql
119 perl-DBI
120 perl-DBD-MySQL
121 For installation from source the following RPM's are required
123 mysql-devel
125 libz-devel
126 Optional are
128 mysql-server
130 Fedora Core Linux
132 As of version 3, Fedora Linux comes with MySQL and DBD::mysql. You
133 need to ensure that the following RPM's are installed:
134 mysql or mysql-server
136 perl-DBD-MySQL
137 For installation from source the following RPM's are required
139 mysql-devel
141 libz-devel
142 Please try
144 yum search mysql
146 To see the exact names
148 Note: (important) FC 3 comes with MySQL 3.x, and some people have
150 upgraded using MySQL RPMs for newer versions. If you do this, you must
151 re-compile you DBD::mysql because your existing DBD::mysql will be
152 linked against the old version of MySQL's client libs. CPAN has no way
153 to know or detect that you have upgraded MySQL.
154 Other systems
156 In the case of Linux or FreeBSD distributions it is very likely that
157 all you need comes with your distribution, as in the case of Red Hat
158 Linux. I just cannot give you names, as I am not using these systems.
159 Please let me know if you find the files in your SuSE Linux, Debian
161 Linux or FreeBSD distribution so that I can extend the above list.
162
164 So you need to install from sources. If you are lucky, the Perl module
165 "CPAN" will do all for you, thanks to the excellent work of Andreas
166 Koenig. Otherwise you will need to do a manual installation. Some of
167 you, in particular system administrators of multiple sites, will choose
168 automatic installation. All of these installation types have an own
169 section. "CPAN installation". "Manual installation". "Configuration".
170 The DBD::mysql Makefile.PL needs to know where to find your MySQL
172 installation. This may be achieved using command line switches (see
173 "Configuration") or automatically using the mysql_config binary which
174 comes with most MySQL distributions. If your MySQL distribution
175 contains mysql_config the easiest method is to ensure this binary is on
176 your path.
177 e.g.
179 PATH=$PATH:/usr/local/mysql/bin
181 export PATH
182 CPAN installation
184 Installation of DBD::mysql can be incredibly easy:
185 cpan
187 install DBD::mysql
188 If you are using the CPAN module for the first time, just answer the
190 questions by accepting the defaults which are fine in most cases. If
191 you are using an older version of Perl, you might instead need a
192 perl -MCPAN -e shell
194 install DBD::mysql
195 If you cannot get the CPAN module working, you might try manual
197 installation. If installation with CPAN fails because the your local
198 settings have been guessed wrong, you need to ensure MySQL's
199 mysql_config is on your path (see "SOURCE INSTALLATION") or
200 alternatively create a script called "mysql_config". This is described
201 in more details later. "Configuration".
202 Manual installation
204 For a manual installation you need to fetch the DBD::mysql source
205 distribution. The latest version is always available from
206 http://www.cpan.org/modules/by-module/DBD/
208 The name is typically something like
210 DBD-mysql-1.2216.tar.gz
212 The archive needs to be extracted. On Windows you may use a tool like
214 WinZip, on Unix you type
215 gzip -cd DBD-mysql-1.2216.tar.gz | tar xf -
217 This will create a subdirectory DBD-mysql-1.2216. Enter this
219 subdirectory and type
220 perl Makefile.PL
222 make
223 make test
224 (On Windows you may need to replace "make" with "nmake" or "dmake".) If
226 the tests seem to look fine, you may continue with
227 make install
229 If the compilation (make) or tests fail, you might need to configure
231 some settings.
232 For example you might choose a different database, the C compiler or
234 the linker might need some flags. "Configuration". "Compiler flags".
235 "Linker flags".
236 For Windows/CygWin there is a special section below. "CygWin" in
238 Windows.
239 Configuration
241 The install script "Makefile.PL" can be configured via a lot of
242 switches. All switches can be used on the command line. For example,
243 the test database:
244 perl Makefile.PL --testdb=<db>
246 If you do not like configuring these switches on the command line, you
248 may alternatively create a script called "mysql_config". This is
249 described later on.
250 Available switches are:
252 testdb
254 Name of the test database, defaults to test.
255 testuser
257 Name of the test user, defaults to empty. If the name is empty,
258 then the currently logged in users name will be used.
259 testpassword
261 Password of the test user, defaults to empty.
262 testhost
264 Host name or IP number of the test database; defaults to localhost.
265 testport
267 Port number of the test database
268 ps-protcol=1 or 0
270 Whether to run the test suite using server prepared statements or
271 driver emulated prepared statemetns. ps-protocol=1 means use server
272 prepare, ps-protocol=0 means driver emulated.
273 cflags
275 This is a list of flags that you want to give to the C compiler.
276 The most important flag is the location of the MySQL header files.
277 For example, on Red Hat Linux the header files are in
278 /usr/include/mysql and you might try
279 -I/usr/include/mysql
281 On Windows the header files may be in C:\mysql\include and you
283 might try
284 -IC:\mysql\include
286 The default flags are determined by running
288 mysql_config --cflags
290 More details on the C compiler flags can be found in the following
292 section. "Compiler flags".
293 libs
295 This is a list of flags that you want to give to the linker or
296 loader. The most important flags are the locations and names of
297 additional libraries. For example, on Red Hat Linux your MySQL
298 client libraries are in /usr/lib/mysql and you might try
299 -L/usr/lib/mysql -lmysqlclient -lz
301 On Windows the libraries may be in C:\mysql\lib and
303 -LC:\mysql\lib -lmysqlclient
305 might be a good choice. The default flags are determined by running
307 mysql_config --libs
309 More details on the linker flags can be found in a separate
311 section. "Linker flags".
312 If a switch is not present on the command line, then the script
314 "mysql_config" will be executed. This script comes as part of the MySQL
315 distribution. For example, to determine the C compiler flags, we are
316 executing
317 mysql_config --cflags
319 mysql_config --libs
320 If you want to configure your own settings for database name, database
322 user and so on, then you have to create a script with the same name,
323 that replies
324 Compiler flags
326 Note: the folling info about compiler and linker flags, you shouldn't
327 have to use these options because Makefile.PL is pretty good at
328 utilising mysql_config to get the flags that you need for a successful
329 compile.
330 It is typically not so difficult to determine the appropriate flags for
332 the C compiler. The linker flags, which you find in the next section,
333 are another story.
334 The determination of the C compiler flags is usually left to a
336 configuration script called mysql_config, which can be invoked with
337 mysql_config --cflags
339 When doing so, it will emit a line with suggested C compiler flags, for
341 example like this:
342 -L/usr/include/mysql
344 The C compiler must find some header files. Header files have the
346 extension ".h". MySQL header files are, for example, mysql.h and
347 mysql_version.h. In most cases the header files are not installed by
348 default. For example, on Windows it is an installation option of the
349 MySQL setup program (Custom installation), whether the header files are
350 installed or not. On Red Hat Linux, you need to install an RPM archive
351 mysql-devel or MySQL-devel.
352 If you know the location of the header files, then you will need to add
354 an option
355 -L<header directory>
357 to the C compiler flags, for example "-L/usr/include/mysql".
359 Linker flags
361 Appropriate linker flags are the most common source of problems while
362 installing DBD::mysql. I will only give a rough overview, you'll find
363 more details in the troubleshooting section. "KNOWN PROBLEMS"
364 The determination of the C compiler flags is usually left to a
366 configuration script called mysql_config, which can be invoked with
367 mysql_config --libs
369 When doing so, it will emit a line with suggested C compiler flags, for
371 example like this:
372 -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt
374 The following items typically need to be configured for the linker:
376 The mysqlclient library
378 The MySQL client library comes as part of the MySQL distribution.
379 Depending on your system it may be a file called
380 F<libmysqlclient.a> statically linked library, Unix
382 F<libmysqlclient.so> dynamically linked library, Unix
383 F<mysqlclient.lib> statically linked library, Windows
384 F<mysqlclient.dll> dynamically linked library, Windows
385 or something similar.
387 As in the case of the header files, the client library is typically
389 not installed by default. On Windows you will need to select them
390 while running the MySQL setup program (Custom installation). On Red
391 Hat Linux an RPM archive mysql-devel or MySQL-devel must be
392 installed.
393 The linker needs to know the location and name of the mysqlclient
395 library. This can be done by adding the flags
396 -L<lib directory> -lmysqlclient
398 or by adding the complete path name. Examples:
400 -L/usr/lib/mysql -lmysqlclient
402 -LC:\mysql\lib -lmysqlclient
403 If you would like to use the static libraries (and there are
405 excellent reasons to do so), you need to create a separate
406 directory, copy the static libraries to that place and use the -L
407 switch above to point to your new directory. For example:
408 mkdir /tmp/mysql-static
410 cp /usr/lib/mysql/*.a /tmp/mysql-static
411 perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient"
412 make
413 make test
414 make install
415 rm -rf /tmp/mysql-static
416 The gzip library
418 The MySQL client can use compression when talking to the MySQL
419 server, a nice feature when sending or receiving large texts over a
420 slow network.
421 On Unix you typically find the appropriate file name by running
423 ldconfig -p | grep libz
425 ldconfig -p | grep libgz
426 Once you know the name (libz.a or libgz.a is best), just add it to
428 the list of linker flags. If this seems to be causing problem you
429 may also try to link without gzip libraries.
430
432 Below you find information on particular systems:
433 Windows/CygWin
435 If you are a user of Cygwin (the Redhat distribution) you already know,
436 it contains a nicely running perl 5.6.1, installation of additional
437 modules usually works as a charme via the standard procedure of
438 perl makefile.PL
440 make
441 make test
442 make install
443 The Windows binary distribution of MySQL runs smoothly under Cygwin.
445 You can start/stop the server and use all Windows clients without
446 problem. But to install DBD::mysql you have to take a little special
447 action.
448 Don't attempt to build DBD::mysql against either the MySQL Windows or
450 Linux/Unix BINARY distributions: neither will work!
451 You MUST compile the MySQL clients yourself under Cygwin, to get a
453 'libmysqlclient.a' compiled under Cygwin. Really! You'll only need that
454 library and the header files, you don't need any other client parts.
455 Continue to use the Windows binaries. And don't attempt (currently) to
456 build the MySQL Server part, it is unneccessary, as MySQL AB does an
457 excellent job to deliver optimized binaries for the mainstream
458 operating systems, and it is told, that the server compiled under
459 Cygwin is unstable.
460 Install MySQL (if you havn't already)
462 - download the MySQL Windows Binaries from
464 http://www.mysql.com/downloads/index.html
465 - unzip mysql-<version>-win.zip into some temporary location
467 - start the setup.exe there and follow the instructions
469 - start the server
471 - alternatively download, install and start the server on a remote
473 server, on what supported OS ever
474 Build MySQL clients under Cygwin:
476 - download the MySQL LINUX source from
478 http://www.mysql.com/downloads/index.html
479 - unpack mysql-<version>.tar.gz into some tmp location
481 - cd into the unpacked dir mysql-<version>
483 ./configure --prefix=/usr/local/mysql --without-server
485 This prepares the Makefile with the installed Cygwin features. It
487 takes some time, but should finish without error. The 'prefix', as
488 given, installs the whole Cygwin/MySQL thingy into a location not
489 normally in your PATH, so that you continue to use already
490 installed Windows binaries. The --without-server parameter tells
491 configure to only build the clients.
492 -
494 make
495 This builds all MySQL client parts ... be patient. It should finish
497 finally without any error.
498 -
500 make install
501 This installs the compiled client files under /usr/local/mysql/.
503 Remember, you don't need anything except the library under
504 /usr/local/mysql/lib and the headers under
505 /usr/local/mysql/include!
506 Essentially you are now done with this part. If you want, you may
508 try your compiled binaries shortly; for that, do:
509 -
511 cd /usr/local/mysql/bin
512 ./mysql -h 127.0.0.1
513 The host (-h) parameter 127.0.0.1 targets the local host, but
515 forces the mysql client to use a TCP/IP connection. The default
516 would be a pipe/socket connection (even if you say '-h localhost')
517 and this doesn't work between Cygwin and Windows (as far as I
518 know).
519 If you have your MySQL server running on some other box, then
521 please substitute '127.0.0.1' with the name or IP-number of that
522 box.
523 Please note, in my environment the 'mysql' client did not accept a
525 simple RETURN, I had to use CTRL-RETURN to send commands ... strange,
526 but I didn't attempt to fix that, as we are only interested in the
527 built lib and headers.
528 At the 'mysql>' prompt do a quick check:
530 mysql> use mysql
532 mysql> show tables;
533 mysql> select * from db;
534 mysql> exit
535 You are now ready to build DBD::mysql!
537 Build DBD::mysql:
539 - download DBD-mysql-<version>.tar.gz from CPAN
541 - unpack DBD-mysql-<version>.tar.gz
543 - cd into unpacked dir DBD-mysql-<version> you probably did that
545 already, if you are reading this!
546 -
548 cp /usr/local/mysql/bin/mysql_config .
549 This copies the executable script mentioned in the DBD::mysql docs
551 from your just built Cywin/MySQL client directory; it knows about
552 your Cygwin installation, especially about the right libraries to
553 link with.
554 -
556 perl Makefile.PL --testhost=127.0.0.1
557 The --testhost=127.0.0.1 parameter again forces a TCP/IP connection
559 to the MySQL server on the local host instead of a pipe/socket
560 connection for the 'make test' phase.
561 -
563 make
564 This should run without error
566 -
568 make test
569 with DBD-mysql-2.1022 or earlier you will see several errors in
571 dbdadmin.t, mysql.t and mysql2.t; with later versions you should
572 not get errors (except possibly one, indicating, that some tables
573 could not be dropped. I'm hunting for a solution to that problem,
574 but have none yet).
575 -
577 make install
578 This installs DBD::mysql into the Perl hierarchy.
580 Notes:
582 This was tested with MySQL version 3.23.54a and DBD::mysql version
584 2.1022. I patched the above mentioned test scripts and sent the patches
585 to the author of DBD::mysql Jochen Wiedman.
586 Georg Rehfeld 15. Jan. 2003
588
590 1.) Some Linux distributions don't come with a gzip library by default.
591 Running "make" terminates with an error message like
592 LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc
594 -o blib/arch/auto/DBD/mysql/mysql.so -shared
595 -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql
596 -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96
597 -lgcc -lz
598 /usr/bin/ld: cannot find -lz
599 collect2: ld returned 1 exit status
600 make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1
601 If this is the case for you, install an RPM archive like libz-
603 devel, libgz-devel, zlib-devel or gzlib-devel or something similar.
604 2.) If Perl was compiled with gcc or egcs, but MySQL was compiled with
606 another compiler or on another system, an error message like this
607 is very likely when running "Make test":
608 t/00base............install_driver(mysql) failed: Can't load
610 '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
611 ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
612 at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
613 line 168.
614 This means, that your linker doesn't include libgcc.a. You have the
616 following options:
617 The solution is telling the linker to use libgcc. Run
619 gcc --print-libgcc-file
621 to determine the exact location of libgcc.a or for older versions
623 of gcc
624 gcc -v
626 to determine the directory. If you know the directory, add a
628 -L<directory> -lgcc
630 to the list of C compiler flags. "Configuration". "Linker flags".
632 3.) There are known problems with shared versions of libmysqlclient, at
634 least on some Linux boxes. If you receive an error message similar
635 to
636 install_driver(mysql) failed: Can't load
638 '/usr/lib/perl5/site_perl/i586-linux/auto/DBD/mysql/mysql.so'
639 for module DBD::mysql: File not found at
640 /usr/lib/perl5/i586-linux/5.00404/DynaLoader.pm line 166
641 then this error message can be misleading: It's not mysql.so that
643 fails being loaded, but libmysqlclient.so! The usual problem is
644 that this file is located in a directory like
645 /usr/lib/mysql
647 where the linker doesn't look for it.
649 The best workaround is using a statically linked mysqlclient
651 library, for example
652 /usr/lib/mysql/libmysqlclient.a
654 The use of a statically linked library is described in the previous
656 section on linker flags. "Configuration". "Linker flags".
657 4.) Red Hat 8 & 9 set the Default locale to UTF which causes problems
659 with MakeMaker. To build DBD::mysql on these systems, do a 'unset
660 LANG' before runing 'perl Makefile.PL'
661
663 Finally, if everything else fails, you are not alone. First of all, for
664 an immediate answer, you should look into the archives of the mailing
665 list perl@lists.mysql.com. See http://www.mysql.com for archive
666 locations.
667 If you don't find an appropriate posting and reply in the mailing list,
669 please post a question. Typically a reply will be seen within one or
670 two days.
671perl v5.16.3 2012-08-28 DBD::mysql::INSTALL(3)