1DBD::mysql::INSTALL(3)User Contributed Perl DocumentationDBD::mysql::INSTALL(3)
2
6 DBD::mysql::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 check the section on "SUPPORT".
29
31 Perl
32 Preferably a version of Perl, that comes preconfigured with your
33 system. For example, all Linux and FreeBSD distributions come with
34 Perl. For Windows, use ActivePerl
35 <https://www.activestate.com/activeperl> or Strawberry Perl
36 <http://www.strawberryperl.com>.
37 MySQL
39 You need not install the actual MySQL database server, the client
40 files and the development files are sufficient. For example, Fedora
41 Linux distribution comes with RPM files (using YUM) mysql and
42 mysql-server (use "yum search" to find exact package names). These
43 are sufficient, if the MySQL server is located on a foreign
44 machine. You may also create client files by compiling from the
45 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 or Strawberry Perl),
51 then you must ensure that the header and library files are
52 installed. This may require choosing a "Custom installation" and
53 selecting the appropriate option when running the MySQL setup
54 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.
80 Windows
82 Strawberry Perl
83 Strawberry Perl comes bundled with DBD::mysql and the needed client
85 libraries.
86 ActiveState Perl
88 ActivePerl offers a PPM archive of DBD::mysql. All you need to do is
90 typing in a cmd.exe window:
91 ppm install DBD-mysql
93 This will fetch the module via HTTP and install them. If you need to
95 use a WWW proxy server, the environment variable HTTP_proxy must be
96 set:
97 set HTTP_proxy=http://myproxy.example.com:8080/
99 ppm install DBD-mysql
100 Of course you need to replace the host name "myproxy.example.com" and
102 the port number 8080 with your local values.
103 If the above procedure doesn't work, please upgrade to the latest
105 version of ActivePerl. ActiveState has a policy where it only provides
106 access free-of-charge for the PPM mirrors of the last few stable Perl
107 releases. If you have an older perl, you'd either need to upgrade your
108 perl or contact ActiveState about a subscription.
109 Red Hat Enterprise Linux (RHEL), CentOS and Fedora
111 Red Hat Enterprise Linux, its community derivatives such as CentOS, and
112 Fedora come with MySQL and DBD::mysql.
113 Use the following command to install DBD::mysql:
115 yum install "perl(DBD::mysql)"
117 Debian and Ubuntu
119 On Debian, Ubuntu and derivatives you can install DBD::mysql from the
120 repositories with the following command:
121 sudo apt-get install libdbd-mysql-perl
123 SLES and openSUSE
125 On SUSE Linux Enterprise and the community version openSUSE, you can
126 install DBD::mysql from the repositories with the following command:
127 zypper install perl-DBD-mysql
129 Other systems
131 In the case of other Linux or FreeBSD distributions it is very likely
132 that all you need comes with your distribution. I just cannot give you
133 names, as I am not using these systems.
134 Please let me know if you find the files in your favorite Linux or
136 FreeBSD distribution so that I can extend the above list.
137
139 So you need to install from sources. If you are lucky, the Perl module
140 "CPAN" will do all for you, thanks to the excellent work of Andreas
141 König. Otherwise you will need to do a manual installation. All of
142 these installation types have their own section: "CPAN installation",
143 "Manual installation" and "Configuration".
144 The DBD::mysql Makefile.PL needs to know where to find your MySQL
146 installation. This may be achieved using command line switches (see
147 "Configuration") or automatically using the mysql_config binary which
148 comes with most MySQL distributions. If your MySQL distribution
149 contains mysql_config the easiest method is to ensure this binary is on
150 your path.
151 Typically, this is the case if you've installed the mysql library from
153 your systems' package manager.
154 e.g.
156 PATH=$PATH:/usr/local/mysql/bin
158 export PATH
159 As stated, to compile DBD::mysql you'll need a C compiler. This should
161 be the same compiler as the one used to build perl AND the mysql client
162 libraries. If you're on linux, this is most typically the case and you
163 need not worry. If you're on UNIX systems, you might want to pay
164 attention.
165 Also you'll need to get the MySQL client and development headers on
167 your system. The easiest is to get these from your package manager.
168 To run the tests that ship with the module, you'll need access to a
170 running MySQL server. This can be running on localhost, but it can also
171 be on a remote machine.
172 On Fedora the process is as follows. Please note that Fedora actually
174 ships with MariaDB but not with MySQL. This is not a problem, it will
175 work just as well. In this example we install and start a local server
176 for running the tests against.
177 yum -y install make gcc mariadb-devel mariadb-libs mariadb-server
179 yum -y install "perl(Test::Deep)" "perl(Test::More)"
180 systemctl start mariadb.service
181 Environment Variables
183 For ease of use, you can set environment variables for DBD::mysql
184 installation. You can set any or all of the options, and export them by
185 putting them in your .bashrc or the like:
186 export DBD_MYSQL_CFLAGS=-I/usr/local/mysql/include/mysql
188 export DBD_MYSQL_LIBS="-L/usr/local/mysql/lib/mysql -lmysqlclient"
189 export DBD_MYSQL_EMBEDDED=
190 export DBD_MYSQL_CONFIG=mysql_config
191 export DBD_MYSQL_NOCATCHSTDERR=0
192 export DBD_MYSQL_NOFOUNDROWS=0
193 export DBD_MYSQL_NOSSL=
194 export DBD_MYSQL_TESTDB=test
195 export DBD_MYSQL_TESTHOST=localhost
196 export DBD_MYSQL_TESTPASSWORD=s3kr1+
197 export DBD_MYSQL_TESTPORT=3306
198 export DBD_MYSQL_TESTUSER=me
199 The most useful may be the host, database, port, socket, user, and
201 password.
202 Installation will first look to your mysql_config, and then your
204 environment variables, and then it will guess with intelligent
205 defaults.
206 CPAN installation
208 Installation of DBD::mysql can be incredibly easy:
209 cpan DBD::mysql
211 Please note that this will only work if the prerequisites are
213 fulfilled, which means you have a C-compiler installed, and you have
214 the development headers and mysql client libraries available on your
215 system.
216 If you are using the CPAN module for the first time, just answer the
218 questions by accepting the defaults which are fine in most cases.
219 If you cannot get the CPAN module working, you might try manual
221 installation. If installation with CPAN fails because the your local
222 settings have been guessed wrong, you need to ensure MySQL's
223 mysql_config is on your path (see "SOURCE INSTALLATION") or
224 alternatively create a script called "mysql_config". This is described
225 in more details later. "Configuration".
226 Manual installation
228 For a manual installation you need to fetch the DBD::mysql source
229 distribution. The latest version is always available from
230 https://metacpan.org/module/DBD::mysql
232 The name is typically something like
234 DBD-mysql-4.025.tar.gz
236 The archive needs to be extracted. On Windows you may use a tool like
238 7-zip, on *nix you type
239 tar xf DBD-mysql-4.025.tar.gz
241 This will create a subdirectory DBD-mysql-4.025. Enter this
243 subdirectory and type
244 perl Makefile.PL
246 make
247 make test
248 (On Windows you may need to replace "make" with "dmake" or "nmake".) If
250 the tests seem to look fine, you may continue with
251 make install
253 If the compilation (make) or tests fail, you might need to configure
255 some settings.
256 For example you might choose a different database, the C compiler or
258 the linker might need some flags. "Configuration". "Compiler flags".
259 "Linker flags".
260 For Cygwin there is a special section below. "Cygwin".
262 Configuration
264 The install script "Makefile.PL" can be configured via a lot of
265 switches. All switches can be used on the command line. For example,
266 the test database:
267 perl Makefile.PL --testdb=<db>
269 If you do not like configuring these switches on the command line, you
271 may alternatively create a script called "mysql_config". This is
272 described later on.
273 Available switches are:
275 testdb
277 Name of the test database, defaults to test.
278 testuser
280 Name of the test user, defaults to empty. If the name is empty,
281 then the currently logged in users name will be used.
282 testpassword
284 Password of the test user, defaults to empty.
285 testhost
287 Host name or IP number of the test database; defaults to localhost.
288 testport
290 Port number of the test database
291 ps-protcol=1 or 0
293 Whether to run the test suite using server prepared statements or
294 driver emulated prepared statements. ps-protocol=1 means use server
295 prepare, ps-protocol=0 means driver emulated.
296 cflags
298 This is a list of flags that you want to give to the C compiler.
299 The most important flag is the location of the MySQL header files.
300 For example, on Red Hat Linux the header files are in
301 /usr/include/mysql and you might try
302 -I/usr/include/mysql
304 On Windows the header files may be in C:\mysql\include and you
306 might try
307 -IC:\mysql\include
309 The default flags are determined by running
311 mysql_config --cflags
313 More details on the C compiler flags can be found in the following
315 section. "Compiler flags".
316 libs
318 This is a list of flags that you want to give to the linker or
319 loader. The most important flags are the locations and names of
320 additional libraries. For example, on Red Hat Linux your MySQL
321 client libraries are in /usr/lib/mysql and you might try
322 -L/usr/lib/mysql -lmysqlclient -lz
324 On Windows the libraries may be in C:\mysql\lib and
326 -LC:\mysql\lib -lmysqlclient
328 might be a good choice. The default flags are determined by running
330 mysql_config --libs
332 More details on the linker flags can be found in a separate
334 section. "Linker flags".
335 If a switch is not present on the command line, then the script
337 "mysql_config" will be executed. This script comes as part of the MySQL
338 distribution. For example, to determine the C compiler flags, we are
339 executing
340 mysql_config --cflags
342 mysql_config --libs
343 If you want to configure your own settings for database name, database
345 user and so on, then you have to create a script with the same name,
346 that replies
347 Compiler flags
349 Note: the following info about compiler and linker flags, you shouldn't
350 have to use these options because Makefile.PL is pretty good at
351 utilizing mysql_config to get the flags that you need for a successful
352 compile.
353 It is typically not so difficult to determine the appropriate flags for
355 the C compiler. The linker flags, which you find in the next section,
356 are another story.
357 The determination of the C compiler flags is usually left to a
359 configuration script called mysql_config, which can be invoked with
360 mysql_config --cflags
362 When doing so, it will emit a line with suggested C compiler flags, for
364 example like this:
365 -L/usr/include/mysql
367 The C compiler must find some header files. Header files have the
369 extension ".h". MySQL header files are, for example, mysql.h and
370 mysql_version.h. In most cases the header files are not installed by
371 default. For example, on Windows it is an installation option of the
372 MySQL setup program (Custom installation), whether the header files are
373 installed or not. On Red Hat Linux, you need to install an RPM archive
374 mysql-devel or MySQL-devel.
375 If you know the location of the header files, then you will need to add
377 an option
378 -L<header directory>
380 to the C compiler flags, for example "-L/usr/include/mysql".
382 Linker flags
384 Appropriate linker flags are the most common source of problems while
385 installing DBD::mysql. I will only give a rough overview, you'll find
386 more details in the troubleshooting section. "KNOWN PROBLEMS"
387 The determination of the C compiler flags is usually left to a
389 configuration script called mysql_config, which can be invoked with
390 mysql_config --libs
392 When doing so, it will emit a line with suggested C compiler flags, for
394 example like this:
395 -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt
397 The following items typically need to be configured for the linker:
399 The mysqlclient library
401 The MySQL client library comes as part of the MySQL distribution.
402 Depending on your system it may be a file called
403 F<libmysqlclient.a> statically linked library, Unix
405 F<libmysqlclient.so> dynamically linked library, Unix
406 F<mysqlclient.lib> statically linked library, Windows
407 F<mysqlclient.dll> dynamically linked library, Windows
408 or something similar.
410 As in the case of the header files, the client library is typically
412 not installed by default. On Windows you will need to select them
413 while running the MySQL setup program (Custom installation). On Red
414 Hat Linux an RPM archive mysql-devel or MySQL-devel must be
415 installed.
416 The linker needs to know the location and name of the mysqlclient
418 library. This can be done by adding the flags
419 -L<lib directory> -lmysqlclient
421 or by adding the complete path name. Examples:
423 -L/usr/lib/mysql -lmysqlclient
425 -LC:\mysql\lib -lmysqlclient
426 If you would like to use the static libraries (and there are
428 excellent reasons to do so), you need to create a separate
429 directory, copy the static libraries to that place and use the -L
430 switch above to point to your new directory. For example:
431 mkdir /tmp/mysql-static
433 cp /usr/lib/mysql/*.a /tmp/mysql-static
434 perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient"
435 make
436 make test
437 make install
438 rm -rf /tmp/mysql-static
439 The gzip library
441 The MySQL client can use compression when talking to the MySQL
442 server, a nice feature when sending or receiving large texts over a
443 slow network.
444 On Unix you typically find the appropriate file name by running
446 ldconfig -p | grep libz
448 ldconfig -p | grep libgz
449 Once you know the name (libz.a or libgz.a is best), just add it to
451 the list of linker flags. If this seems to be causing problem you
452 may also try to link without gzip libraries.
453
455 Connecting to your servers over an encrypted connection (SSL) is only
456 possible if you enabled this setting at build time. Since version
457 4.034, this is the default.
458 Attempting to connect to a server that requires an encrypted connection
460 without first having DBD::mysql compiled with the "--ssl" option will
461 result in an error that makes things appear as if your password is
462 incorrect.
463 If you want to compile DBD::mysql without SSL support, which you might
465 probably only want if you for some reason can't install libssl headers,
466 you can do this by passing the "--nossl" option to Makefile.PL or by
467 setting the DBD_MYSQL_NOSSL environment variable to '1'.
468
470 The MariaDB native client is another option for connecting to a MySQL·
471 database licensed LGPL 2.1. To build DBD::mysql against this client,
472 you will first need to build the client. Generally, this is done with
473 the following:
474 cd path/to/src/mariadb-native-client
476 cmake -G "Unix Makefiles'
477 make
478 sudo make install
479 Once the client is built and installed, you can build DBD::mysql
481 against it:
482 perl Makefile.PL --testuser=xxx --testpassword=xxx --testsocket=/path/to//mysqld.sock --mysql_config=/usr/local/bin/mariadb_config·
484 make
485 make test
486 make install
487
489 Below you find information on particular systems:
490 macOS
492 For installing DBD::mysql you need to have the libssl header files and
493 the mysql client libs. The easiest way to install these is using
494 Homebrew (<https://brew.sh/>).
495 Once you have Homebrew set up, you can simply install the dependencies
497 using
498 brew install openssl mysql-connector-c
500 Then you can install DBD::mysql using your cpan client.
502 Cygwin
504 If you are a user of Cygwin you already know, it contains a nicely
505 running perl 5.6.1, installation of additional modules usually works
506 like a charm via the standard procedure of
507 perl makefile.PL
509 make
510 make test
511 make install
512 The Windows binary distribution of MySQL runs smoothly under Cygwin.
514 You can start/stop the server and use all Windows clients without
515 problem. But to install DBD::mysql you have to take a little special
516 action.
517 Don't attempt to build DBD::mysql against either the MySQL Windows or
519 Linux/Unix BINARY distributions: neither will work!
520 You MUST compile the MySQL clients yourself under Cygwin, to get a
522 'libmysqlclient.a' compiled under Cygwin. Really! You'll only need that
523 library and the header files, you don't need any other client parts.
524 Continue to use the Windows binaries. And don't attempt (currently) to
525 build the MySQL Server part, it is unnecessary, as MySQL AB does an
526 excellent job to deliver optimized binaries for the mainstream
527 operating systems, and it is told, that the server compiled under
528 Cygwin is unstable.
529 Install a MySQL server for testing against. You can install the regular
531 Windows MySQL server package on your Windows machine, or you can also
532 test against a MySQL server on a remote host.
533 Build MySQL clients under Cygwin:
535 download the MySQL LINUX source from <https://www.mysql.com/downloads>,
537 unpack mysql-<version>.tar.gz into some tmp location and from this
538 directory run configure:
539 ./configure --prefix=/usr/local/mysql --without-server
541 This prepares the Makefile with the installed Cygwin features. It takes
543 some time, but should finish without error. The 'prefix', as given,
544 installs the whole Cygwin/MySQL thingy into a location not normally in
545 your PATH, so that you continue to use already installed Windows
546 binaries. The --without-server parameter tells configure to only build
547 the clients.
548 make
550 This builds all MySQL client parts ... be patient. It should finish
552 finally without any error.
553 make install
555 This installs the compiled client files under /usr/local/mysql/.
557 Remember, you don't need anything except the library under
558 /usr/local/mysql/lib and the headers under /usr/local/mysql/include!
559 Essentially you are now done with this part. If you want, you may try
561 your compiled binaries shortly; for that, do:
562 cd /usr/local/mysql/bin
564 ./mysql -h 127.0.0.1
565 The host (-h) parameter 127.0.0.1 targets the local host, but forces
567 the mysql client to use a TCP/IP connection. The default would be a
568 pipe/socket connection (even if you say '-h localhost') and this
569 doesn't work between Cygwin and Windows (as far as I know).
570 If you have your MySQL server running on some other box, then please
572 substitute '127.0.0.1' with the name or IP-number of that box.
573 Please note, in my environment the 'mysql' client did not accept a
575 simple RETURN, I had to use CTRL-RETURN to send commands ... strange,
576 but I didn't attempt to fix that, as we are only interested in the
577 built lib and headers.
578 At the 'mysql>' prompt do a quick check:
580 mysql> use mysql
582 mysql> show tables;
583 mysql> select * from db;
584 mysql> exit
585 You are now ready to build DBD::mysql!
587 compile DBD::mysql
589 download and extract DBD-mysql-<version>.tar.gz from CPAN
591 cd into unpacked dir DBD-mysql-<version> you probably did that already,
593 if you are reading this!
594 cp /usr/local/mysql/bin/mysql_config .
596 This copies the executable script mentioned in the DBD::mysql docs from
598 your just built Cywin/MySQL client directory; it knows about your
599 Cygwin installation, especially about the right libraries to link with.
600 perl Makefile.PL --testhost=127.0.0.1
602 The --testhost=127.0.0.1 parameter again forces a TCP/IP connection to
604 the MySQL server on the local host instead of a pipe/socket connection
605 for the 'make test' phase.
606 make
608 This should run without error
610 make test
612 make install
613 This installs DBD::mysql into the Perl hierarchy.
615
617 no gzip on your system
618 Some Linux distributions don't come with a gzip library by default.
619 Running "make" terminates with an error message like
620 LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc
622 -o blib/arch/auto/DBD/mysql/mysql.so -shared
623 -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql
624 -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96
625 -lgcc -lz
626 /usr/bin/ld: cannot find -lz
627 collect2: ld returned 1 exit status
628 make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1
629 If this is the case for you, install an RPM archive like libz-devel,
631 libgz-devel, zlib-devel or gzlib-devel or something similar.
632 different compiler for mysql and perl
634 If Perl was compiled with gcc or egcs, but MySQL was compiled with
635 another compiler or on another system, an error message like this is
636 very likely when running "Make test":
637 t/00base............install_driver(mysql) failed: Can't load
639 '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
640 ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
641 at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
642 line 168.
643 This means, that your linker doesn't include libgcc.a. You have the
645 following options:
646 The solution is telling the linker to use libgcc. Run
648 gcc --print-libgcc-file
650 to determine the exact location of libgcc.a or for older versions of
652 gcc
653 gcc -v
655 to determine the directory. If you know the directory, add a
657 -L<directory> -lgcc
659 to the list of C compiler flags. "Configuration". "Linker flags".
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 dbi-users
665 mailing list, which is available at
666 <http://groups.google.com/group/perl.dbi.users?hl=en&lr=>
667 To subscribe to this list, send and email to
669 dbi-users-subscribe@perl.org
671 If you don't find an appropriate posting and reply in the mailing list,
673 please post a question. Typically a reply will be seen within one or
674 two days.
675perl v5.38.0 2023-07-20 DBD::mysql::INSTALL(3)