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 sec‐
27 tion 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, the Red
42 Hat Linux distribution comes with RPM files mysql-client and mysql-
43 devel. These are sufficient, if the MySQL server is located on a
44 foreign machine. You may also create client files by compiling from
45 the MySQL source distribution and using
46 configure --without-server
48 If you are using Windows and need to compile from sources (which is
50 only the case if you are not using ActivePerl), then you must
51 ensure that the header and library files are installed. This may
52 require choosing a "Custom installation" and selecting the appro‐
53 priate option when running the MySQL setup program.
54 DBI DBD::mysql is a DBI driver, hence you need DBI. It is available
56 from the same source where you got the DBD::mysql distribution
57 from.
58 C compiler
60 A C compiler is only required, if you install from source. In most
61 cases there are binary distributions of DBD::mysql available. How‐
62 ever, if you need a C compiler, make sure, that it is the same C
63 compiler that was used for compiling Perl and MySQL! Otherwise you
64 will almost definitely encounter problems because of differences in
65 the underlying C runtime libraries.
66 In the worst case, this might mean to compile Perl and MySQL your‐
68 self. But believe me, experience shows that a lot of problems are
69 fixed this way.
70 Gzip libraries
72 Late versions of MySQL come with support for compression. Thus it
73 may be required that you have install an RPM package like
74 libz-devel, libgz-devel or something similar.
75
77 Binary installation is possible in the most cases, depending on your
78 system. I give some examples:
79 Windows
81 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 ver‐
102 sion of ActivePerl. Versions before build 623 are known to have prob‐
103 lems.
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
117 need to ensure that the following RPM's are installed:
118 mysql
120 perl-DBI
121 perl-DBD-MySQL
122 For installation from source the following RPM's are required
124 mysql-devel
126 libz-devel
127 Optional are
129 mysql-server
131 Other systems
133 In the case of Linux or FreeBSD distributions it is very likely that
135 all you need comes with your distribution, as in the case of Red Hat
136 Linux. I just cannot give you names, as I am not using these systems.
137 Please let me know if you find the files in your SuSE Linux, Debian
139 Linux or FreeBSD distribution so that I can extend the above list.
140
142 So you need to install from sources. If you are lucky, the Perl module
143 "CPAN" will do all for you, thanks to the excellent work of Andreas
144 Koenig. Otherwise you will need to do a manual installation. Some of
145 you, in particular system administrators of multiple sites, will choose
146 automatic installation. All of these installation types have an own
147 section. "CPAN installation". "Manual installation". "Configuration".
148 The DBD::mysql Makefile.PL needs to know where to find your MySQL
150 installation. This may be achieved using command line switches (see
151 "Configuration") or automatically using the mysql_config binary which
152 comes with most MySQL distributions. If your MySQL distribution con‐
153 tains mysql_config the easiest method is to ensure this binary is on
154 your path.
155 e.g.
157 PATH=$PATH:/usr/local/mysql/bin
159 export PATH
160 CPAN installation
162 Installation of DBD::mysql can be incredibly easy:
164 cpan
166 install DBD::mysql
167 If you are using the CPAN module for the first time, just answer the
169 questions by accepting the defaults which are fine in most cases. If
170 you are using an older version of Perl, you might instead need a
171 perl -MCPAN -e shell
173 install DBD::mysql
174 If you cannot get the CPAN module working, you might try manual instal‐
176 lation. If installation with CPAN fails because the your local settings
177 have been guessed wrong, you need to ensure MySQL's mysql_config is on
178 your path (see "SOURCE INSTALLATION") or alternatively create a script
179 called "mysql_config". This is described in more details later. "Con‐
180 figuration".
181 Manual installation
183 For a manual installation you need to fetch the DBD::mysql source dis‐
185 tribution. The latest version is always available from
186 http://www.cpan.org/modules/by-module/DBD/
188 The name is typically something like
190 DBD-mysql-1.2216.tar.gz
192 The archive needs to be extracted. On Windows you may use a tool like
194 WinZip, on Unix you type
195 gzip -cd DBD-mysql-1.2216.tar.gz ⎪ tar xf -
197 This will create a subdirectory DBD-mysql-1.2216. Enter this subdirec‐
199 tory and type
200 perl Makefile.PL
202 make
203 make test
204 (On Windows you may need to replace "make" with "nmake" or "dmake".) If
206 the tests seem to look fine, you may continue with
207 make install
209 If the make or tests fail, you might need to configure some settings.
211 For example you might choose a different database, the C compiler or
212 the linker might need some flags. "Configuration". "Compiler flags".
213 "Linker flags".
214 For Windows/CygWin there is a special section below. "CygWin" in Win‐
216 dows.
217 Configuration
219 The install script "Makefile.PL" can be configured via a lot of
221 switches. All switches can be used on the command line. For example,
222 the test database:
223 perl Makefile.PL --testdb=<db>
225 If you do not like configuring these switches on the command line, you
227 may alternatively create a script called "mysql_config". This is
228 described later on.
229 Available switches are:
231 testdb
233 Name of the test database, defaults to test.
234 testuser
236 Name of the test user, defaults to empty. If the name is empty,
237 then the currently logged in users name will be used.
238 testpassword
240 Password of the test user, defaults to empty.
241 testhost
243 Host name or IP number of the test database; defaults to localhost.
244 testport
246 Port number of the test database
247 cflags
249 This is a list of flags that you want to give to the C compiler.
250 The most important flag is the location of the MySQL header files.
251 For example, on Red Hat Linux the header files are in
252 /usr/include/mysql and you might try
253 -I/usr/include/mysql
255 On Windows the header files may be in C:\mysql\include and you
257 might try
258 -IC:\mysql\include
260 The default flags are determined by running
262 mysql_config --cflags
264 More details on the C compiler flags can be found in the following
266 section. "Compiler flags".
267 libs
269 This is a list of flags that you want to give to the linker or
270 loader. The most important flags are the locations and names of
271 additional libraries. For example, on Red Hat Linux your MySQL
272 client libraries are in /usr/lib/mysql and you might try
273 -L/usr/lib/mysql -lmysqlclient -lz
275 On Windows the libraries may be in C:\mysql\lib and
277 -LC:\mysql\lib -lmysqlclient
279 might be a good choice. The default flags are determined by running
281 mysql_config --libs
283 More details on the linker flags can be found in a separate sec‐
285 tion. "Linker flags".
286 If a switch is not present on the command line, then the script
288 "mysql_config" will be executed. This script comes as part of the MySQL
289 distribution. For example, to determine the C compiler flags, we are
290 executing
291 mysql_config --cflags
293 mysql_config --libs
294 If you want to configure your own settings for database name, database
296 user and so on, then you have to create a script with the same name,
297 that replies
298 Compiler flags
300 It is typically not so difficult to determine the appropriate flags for
302 the C compiler. The linker flags, which you find in the next section,
303 are another story.
304 The determination of the C compiler flags is usually left to a configu‐
306 ration script called mysql_config, which can be invoked with
307 mysql_config --cflags
309 When doing so, it will emit a line with suggested C compiler flags, for
311 example like this:
312 -L/usr/include/mysql
314 The C compiler must find some header files. Header files have the
316 extension ".h". MySQL header files are, for example, mysql.h and
317 mysql_version.h. In most cases the header files are not installed by
318 default. For example, on Windows it is an installation option of the
319 MySQL setup program (Custom installation), whether the header files are
320 installed or not. On Red Hat Linux, you need to install an RPM archive
321 mysql-devel or MySQL-devel.
322 If you know the location of the header files, then you will need to add
324 an option
325 -L<header directory>
327 to the C compiler flags, for example "-L/usr/include/mysql".
329 Linker flags
331 Appropriate linker flags are the most common source of problems while
333 installing DBD::mysql. I will only give a rough overview, you'll find
334 more details in the troubleshooting section. "KNOWN PROBLEMS"
335 The determination of the C compiler flags is usually left to a configu‐
337 ration script called mysql_config, which can be invoked with
338 mysql_config --libs
340 When doing so, it will emit a line with suggested C compiler flags, for
342 example like this:
343 -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt
345 The following items typically need to be configured for the linker:
347 The mysqlclient library
349 The MySQL client library comes as part of the MySQL distribution.
350 Depending on your system it may be a file called
351 F<libmysqlclient.a> statically linked library, Unix
353 F<libmysqlclient.so> dynamically linked library, Unix
354 F<mysqlclient.lib> statically linked library, Windows
355 F<mysqlclient.dll> dynamically linked library, Windows
356 or something similar.
358 As in the case of the header files, the client library is typically
360 not installed by default. On Windows you will need to select them
361 while running the MySQL setup program (Custom installation). On Red
362 Hat Linux an RPM archive mysql-devel or MySQL-devel must be
363 installed.
364 The linker needs to know the location and name of the mysqlclient
366 library. This can be done by adding the flags
367 -L<lib directory> -lmysqlclient
369 or by adding the complete path name. Examples:
371 -L/usr/lib/mysql -lmysqlclient
373 -LC:\mysql\lib -lmysqlclient
374 If you would like to use the static libraries (and there are excel‐
376 lent reasons to do so), you need to create a separate directory,
377 copy the static libraries to that place and use the -L switch above
378 to point to your new directory. For example:
379 mkdir /tmp/mysql-static
381 cp /usr/lib/mysql/*.a /tmp/mysql-static
382 perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient"
383 make
384 make test
385 make install
386 rm -rf /tmp/mysql-static
387 The gzip library
389 The MySQL client can use compression when talking to the MySQL
390 server, a nice feature when sending or receiving large texts over a
391 slow network.
392 On Unix you typically find the appropriate file name by running
394 ldconfig -p ⎪ grep libz
396 ldconfig -p ⎪ grep libgz
397 Once you know the name (libz.a or libgz.a is best), just add it to
399 the list of linker flags. If this seems to be causing problem you
400 may also try to link without gzip libraries.
401
403 Below you find information on particular systems:
404 Windows/CygWin
406 If you are a user of Cygwin (the Redhat distribution) you already know,
408 it contains a nicely running perl 5.6.1, installation of additional
409 modules usually works as a charme via the standard procedure of
410 perl makefile.PL
412 make
413 make test
414 make install
415 The Windows binary distribution of MySQL runs smoothly under Cygwin.
417 You can start/stop the server and use all Windows clients without prob‐
418 lem. But to install DBD::mysql you have to take a little special
419 action.
420 Don't attempt to build DBD::mysql against either the MySQL Windows or
422 Linux/Unix BINARY distributions: neither will work!
423 You MUST compile the MySQL clients yourself under Cygwin, to get a
425 'libmysqlclient.a' compiled under Cygwin. Really! You'll only need that
426 library and the header files, you don't need any other client parts.
427 Continue to use the Windows binaries. And don't attempt (currently) to
428 build the MySQL Server part, it is unneccessary, as MySQL AB does an
429 excellent job to deliver optimized binaries for the mainstream operat‐
430 ing systems, and it is told, that the server compiled under Cygwin is
431 unstable.
432 Install MySQL (if you havn't already)
434 - download the MySQL Windows Binaries from http://www.mysql.com/down‐
436 loads/index.html
437 - unzip mysql-<version>-win.zip into some temporary location
439 - start the setup.exe there and follow the instructions
441 - start the server
443 - alternatively download, install and start the server on a remote
445 server, on what supported OS ever
446 Build MySQL clients under Cygwin:
448 - download the MySQL LINUX source from http://www.mysql.com/down‐
450 loads/index.html
451 - unpack mysql-<version>.tar.gz into some tmp location
453 - cd into the unpacked dir mysql-<version>
455 ./configure --prefix=/usr/local/mysql --without-server
457 This prepares the Makefile with the installed Cygwin features. It
459 takes some time, but should finish without error. The 'prefix', as
460 given, installs the whole Cygwin/MySQL thingy into a location not
461 normally in your PATH, so that you continue to use already
462 installed Windows binaries. The --without-server parameter tells
463 configure to only build the clients.
464 -
466 make
467 This builds all MySQL client parts ... be patient. It should finish
469 finally without any error.
470 -
472 make install
473 This installs the compiled client files under /usr/local/mysql/.
475 Remember, you don't need anything except the library under
476 /usr/local/mysql/lib and the headers under
477 /usr/local/mysql/include!
478 Essentially you are now done with this part. If you want, you may
480 try your compiled binaries shortly; for that, do:
481 -
483 cd /usr/local/mysql/bin
484 ./mysql -h 127.0.0.1
485 The host (-h) parameter 127.0.0.1 targets the local host, but
487 forces the mysql client to use a TCP/IP connection. The default
488 would be a pipe/socket connection (even if you say '-h localhost')
489 and this doesn't work between Cygwin and Windows (as far as I
490 know).
491 If you have your MySQL server running on some other box, then
493 please substitute '127.0.0.1' with the name or IP-number of that
494 box.
495 Please note, in my environment the 'mysql' client did not accept a sim‐
497 ple RETURN, I had to use CTRL-RETURN to send commands ... strange, but
498 I didn't attempt to fix that, as we are only interested in the built
499 lib and headers.
500 At the 'mysql>' prompt do a quick check:
502 mysql> use mysql
504 mysql> show tables;
505 mysql> select * from db;
506 mysql> exit
507 You are now ready to build DBD::mysql!
509 Build DBD::mysql:
511 - download DBD-mysql-<version>.tar.gz from CPAN
513 - unpack DBD-mysql-<version>.tar.gz
515 - cd into unpacked dir DBD-mysql-<version> you probably did that
517 already, if you are reading this!
518 -
520 cp /usr/local/mysql/bin/mysql_config .
521 This copies the executable script mentioned in the DBD::mysql docs
523 from your just built Cywin/MySQL client directory; it knows about
524 your Cygwin installation, especially about the right libraries to
525 link with.
526 -
528 perl Makefile.PL --testhost=127.0.0.1
529 The --testhost=127.0.0.1 parameter again forces a TCP/IP connection
531 to the MySQL server on the local host instead of a pipe/socket con‐
532 nection for the 'make test' phase.
533 -
535 make
536 This should run without error
538 -
540 make test
541 with DBD-mysql-2.1022 or earlier you will see several errors in
543 dbdadmin.t, mysql.t and mysql2.t; with later versions you should
544 not get errors (except possibly one, indicating, that some tables
545 could not be dropped. I'm hunting for a solution to that problem,
546 but have none yet).
547 -
549 make install
550 This installs DBD::mysql into the Perl hierarchy.
552 Notes:
554 This was tested with MySQL version 3.23.54a and DBD::mysql version
556 2.1022. I patched the above mentioned test scripts and sent the patches
557 to the author of DBD::mysql Jochen Wiedman.
558 Georg Rehfeld 15. Jan. 2003
560
562 1.) Some Linux distributions don't come with a gzip library by default.
563 Running "make" terminates with an error message like
564 LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc
566 -o blib/arch/auto/DBD/mysql/mysql.so -shared
567 -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql
568 -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96
569 -lgcc -lz
570 /usr/bin/ld: cannot find -lz
571 collect2: ld returned 1 exit status
572 make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1
573 If this is the case for you, install an RPM archive like
575 libz-devel, libgz-devel, zlib-devel or gzlib-devel or something
576 similar.
577 2.) If Perl was compiled with gcc or egcs, but MySQL was compiled with
579 another compiler or on another system, an error message like this
580 is very likely when running "Make test":
581 t/00base............install_driver(mysql) failed: Can't load
583 '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
584 ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
585 at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
586 line 168.
587 This means, that your linker doesn't include libgcc.a. You have the
589 following options:
590 The solution is telling the linker to use libgcc. Run
592 gcc --print-libgcc-file
594 to determine the exact location of libgcc.a or for older versions
596 of gcc
597 gcc -v
599 to determine the directory. If you know the directory, add a
601 -L<directory> -lgcc
603 to the list of C compiler flags. "Configuration". "Linker flags".
605 3.) There are known problems with shared versions of libmysqlclient, at
607 least on some Linux boxes. If you receive an error message similar
608 to
609 install_driver(mysql) failed: Can't load
611 '/usr/lib/perl5/site_perl/i586-linux/auto/DBD/mysql/mysql.so'
612 for module DBD::mysql: File not found at
613 /usr/lib/perl5/i586-linux/5.00404/DynaLoader.pm line 166
614 then this error message can be misleading: It's not mysql.so that
616 fails being loaded, but libmysqlclient.so! The usual problem is
617 that this file is located in a directory like
618 /usr/lib/mysql
620 where the linker doesn't look for it.
622 The best workaround is using a statically linked mysqlclient
624 library, for example
625 /usr/lib/mysql/libmysqlclient.a
627 The use of a statically linked library is described in the previous
629 section on linker flags. "Configuration". "Linker flags".
630 4.) Red Hat 8 & 9 set the Default locale to UTF which causes problems
632 with MakeMaker. To build DBD::mysql on these systems, do a 'unset
633 LANG' before runing 'perl Makefile.PL'
634
636 Finally, if everything else fails, you are not alone. First of all, for
637 an immediate answer, you should look into the archives of the mailing
638 list perl@lists.mysql.com. See http://www.mysql.com for archive loca‐
639 tions.
640 If you don't find an appropriate posting and reply in the mailing list,
642 please post a question. Typically a reply will be seen within one or
643 two days.
644perl v5.8.8 2006-10-16 DBD::mysql::INSTALL(3)