1DBD::mysql::INSTALL(3)User Contributed Perl DocumentationDBD::mysql::INSTALL(3)
2
3
4

NAME

6       DBD::mysql::INSTALL - How to install and configure DBD::mysql
7

SYNOPSIS

9         perl Makefile.PL [options]
10         make
11         make test
12         make install
13

DESCRIPTION

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
20       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
26       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

PREREQUISITES

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
38       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
47             configure --without-server
48
49           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
56       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
60       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
68           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
72       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

BINARY INSTALLATION

78       Binary installation is possible in the most cases, depending on your
79       system.
80
81   Windows
82       Strawberry Perl
83
84       Strawberry Perl comes bundled with DBD::mysql and the needed client
85       libraries.
86
87       ActiveState Perl
88
89       ActivePerl offers a PPM archive of DBD::mysql. All you need to do is
90       typing in a cmd.exe window:
91
92         ppm install DBD-mysql
93
94       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
98         set HTTP_proxy=http://myproxy.example.com:8080/
99         ppm install DBD-mysql
100
101       Of course you need to replace the host name "myproxy.example.com" and
102       the port number 8080 with your local values.
103
104       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
110   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
114       Use the following command to install DBD::mysql:
115
116           yum install "perl(DBD::mysql)"
117
118   Debian and Ubuntu
119       On Debian, Ubuntu and derivatives you can install DBD::mysql from the
120       repositories with the following command:
121
122           sudo apt-get install libdbd-mysql-perl
123
124   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
128           zypper install perl-DBD-mysql
129
130   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
135       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

SOURCE INSTALLATION

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
145       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
152       Typically, this is the case if you've installed the mysql library from
153       your systems' package manager.
154
155       e.g.
156
157         PATH=$PATH:/usr/local/mysql/bin
158         export PATH
159
160       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
166       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
169       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
173       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
178           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
182   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
187           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
200       The most useful may be the host, database, port, socket, user, and
201       password.
202
203       Installation will first look to your mysql_config, and then your
204       environment variables, and then it will guess with intelligent
205       defaults.
206
207   CPAN installation
208       Installation of DBD::mysql can be incredibly easy:
209
210         cpan DBD::mysql
211
212       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
217       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
220       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
227   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
231         https://metacpan.org/module/DBD::mysql
232
233       The name is typically something like
234
235         DBD-mysql-4.025.tar.gz
236
237       The archive needs to be extracted. On Windows you may use a tool like
238       7-zip, on *nix you type
239
240         tar xf DBD-mysql-4.025.tar.gz
241
242       This will create a subdirectory DBD-mysql-4.025. Enter this
243       subdirectory and type
244
245         perl Makefile.PL
246         make
247         make test
248
249       (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
252         make install
253
254       If the compilation (make) or tests fail, you might need to configure
255       some settings.
256
257       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
261       For Cygwin there is a special section below.  "Cygwin".
262
263   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
268         perl Makefile.PL --testdb=<db>
269
270       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
274       Available switches are:
275
276       testdb
277           Name of the test database, defaults to test.
278
279       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
283       testpassword
284           Password of the test user, defaults to empty.
285
286       testhost
287           Host name or IP number of the test database; defaults to localhost.
288
289       testport
290           Port number of the test database
291
292       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
297       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
303             -I/usr/include/mysql
304
305           On Windows the header files may be in C:\mysql\include and you
306           might try
307
308             -IC:\mysql\include
309
310           The default flags are determined by running
311
312             mysql_config --cflags
313
314           More details on the C compiler flags can be found in the following
315           section. "Compiler flags".
316
317       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
323             -L/usr/lib/mysql -lmysqlclient -lz
324
325           On Windows the libraries may be in C:\mysql\lib and
326
327             -LC:\mysql\lib -lmysqlclient
328
329           might be a good choice. The default flags are determined by running
330
331             mysql_config --libs
332
333           More details on the linker flags can be found in a separate
334           section.  "Linker flags".
335
336       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
341         mysql_config --cflags
342         mysql_config --libs
343
344       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
348   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
354       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
358       The determination of the C compiler flags is usually left to a
359       configuration script called mysql_config, which can be invoked with
360
361         mysql_config --cflags
362
363       When doing so, it will emit a line with suggested C compiler flags, for
364       example like this:
365
366         -L/usr/include/mysql
367
368       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
376       If you know the location of the header files, then you will need to add
377       an option
378
379         -L<header directory>
380
381       to the C compiler flags, for example "-L/usr/include/mysql".
382
383   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
388       The determination of the C compiler flags is usually left to a
389       configuration script called mysql_config, which can be invoked with
390
391         mysql_config --libs
392
393       When doing so, it will emit a line with suggested C compiler flags, for
394       example like this:
395
396          -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt
397
398       The following items typically need to be configured for the linker:
399
400       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
404             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
409           or something similar.
410
411           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
417           The linker needs to know the location and name of the mysqlclient
418           library. This can be done by adding the flags
419
420             -L<lib directory> -lmysqlclient
421
422           or by adding the complete path name. Examples:
423
424             -L/usr/lib/mysql -lmysqlclient
425             -LC:\mysql\lib -lmysqlclient
426
427           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
432             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
440       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
445           On Unix you typically find the appropriate file name by running
446
447             ldconfig -p | grep libz
448             ldconfig -p | grep libgz
449
450           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

ENCRYPTED CONNECTIONS via SSL

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
459       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
464       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

MARIADB NATIVE CLIENT INSTALLATION

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
475         cd path/to/src/mariadb-native-client
476         cmake -G "Unix Makefiles'
477         make
478         sudo make install
479
480       Once the client is built and installed, you can build DBD::mysql
481       against it:
482
483         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

SPECIAL SYSTEMS

489       Below you find information on particular systems:
490
491   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
496       Once you have Homebrew set up, you can simply install the dependencies
497       using
498
499           brew install openssl mysql-connector-c
500
501       Then you can install DBD::mysql using your cpan client.
502
503   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
508           perl makefile.PL
509           make
510           make test
511           make install
512
513       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
518       Don't attempt to build DBD::mysql against either the MySQL Windows or
519       Linux/Unix BINARY distributions: neither will work!
520
521       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
530       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
534       Build MySQL clients under Cygwin:
535
536       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
540         ./configure --prefix=/usr/local/mysql --without-server
541
542       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
549         make
550
551       This builds all MySQL client parts ... be patient. It should finish
552       finally without any error.
553
554         make install
555
556       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
560       Essentially you are now done with this part. If you want, you may try
561       your compiled binaries shortly; for that, do:
562
563         cd /usr/local/mysql/bin
564         ./mysql -h 127.0.0.1
565
566       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
571       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
574       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
579       At the 'mysql>' prompt do a quick check:
580
581         mysql> use mysql
582         mysql> show tables;
583         mysql> select * from db;
584         mysql> exit
585
586       You are now ready to build DBD::mysql!
587
588       compile DBD::mysql
589
590       download and extract DBD-mysql-<version>.tar.gz from CPAN
591
592       cd into unpacked dir DBD-mysql-<version> you probably did that already,
593       if you are reading this!
594
595         cp /usr/local/mysql/bin/mysql_config .
596
597       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
601         perl Makefile.PL --testhost=127.0.0.1
602
603       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
607         make
608
609       This should run without error
610
611         make test
612         make install
613
614       This installs DBD::mysql into the Perl hierarchy.
615

KNOWN PROBLEMS

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
621         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
630       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
633   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
638         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
644       This means, that your linker doesn't include libgcc.a. You have the
645       following options:
646
647       The solution is telling the linker to use libgcc. Run
648
649         gcc --print-libgcc-file
650
651       to determine the exact location of libgcc.a or for older versions of
652       gcc
653
654         gcc -v
655
656       to determine the directory. If you know the directory, add a
657
658         -L<directory> -lgcc
659
660       to the list of C compiler flags. "Configuration". "Linker flags".
661

SUPPORT

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
668       To subscribe to this list, send and email to
669
670           dbi-users-subscribe@perl.org
671
672       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.
675
676
677
678perl v5.34.0                      2021-07-22            DBD::mysql::INSTALL(3)
Impressum