1DBD::MariaDB::INSTALL(3U)ser Contributed Perl DocumentatiDoBnD::MariaDB::INSTALL(3)
2
6 DBD::MariaDB::INSTALL - How to install and configure DBD::MariaDB
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::MariaDB, the Perl DBI driver for the MariaDB and MySQL database.
17 Before reading on, make sure that you have the prerequisites available:
18 Perl, MariaDB/MySQL and DBI. For details see the separate section
19 "PREREQUISITES".
20 Finally, if you encounter any problems, do not forget to read the
22 section on known problems "KNOWN PROBLEMS". If that doesn't help, you
23 should check the section on "SUPPORT".
24
26 Perl
27 Preferably a version of Perl, that comes preconfigured with your
28 system. For example, all Linux and FreeBSD distributions come with
29 Perl. For Windows, use ActivePerl
30 <https://www.activestate.com/activeperl> or Strawberry Perl
31 <http://www.strawberryperl.com>.
32 MariaDB/MySQL
34 You need not install the actual MariaDB or MySQL database server,
35 the client files and the development files are sufficient. They are
36 distributed either in Connector/C package or as part of server
37 package. You need at least MySQL version 4.1.8.
38 For example, Fedora, RedHat, CentOS Linux distribution comes with
40 RPM files (using YUM) "mariadb-devel", "mariadb-embedded-devel",
41 "mysql-devel" or "mysql-embedded-devel" (use "yum search" to find
42 exact package names). Debian and Ubuntu comes with DEB packages
43 "libmariadb-dev", "libmariadbclient-dev", "libmariadbd-dev",
44 "libmysqlclient-dev" or "libmysqld-dev" (use "apt-cache search" to
45 find exact package names).
46 In some cases MariaDB or MySQL libraries depends on external
48 libpcre, libaio, libnuma, libjemalloc or libwrap libraries. If it
49 is that case, they needs to be installed before MariaDB/MySQL
50 libraries.
51 These are sufficient, if the MariaDB/MySQL server is located on a
53 foreign machine. You may also create client files by compiling from
54 the MariaDB/MySQL source distribution and using
55 ./configure --without-server
57 or
59 cmake -DWITHOUT_SERVER=ON
61 If you are using Windows and need to compile from sources (which is
63 only the case if you are not using ActivePerl or Strawberry Perl),
64 then you must ensure that the header and library files are
65 installed. This may require choosing a Custom installation and
66 selecting the appropriate option when running the MariaDB/MySQL
67 setup program.
68 DBI DBD::MariaDB is a DBI driver, hence you need DBI. It is available
70 from the same source where you got the DBD::MariaDB distribution
71 from.
72 C compiler
74 A C compiler is required if you install from source. Make sure,
75 that it is the same C compiler that was used for compiling Perl and
76 MariaDB/MySQL! Otherwise you will almost definitely encounter
77 problems because of differences in the underlying C runtime
78 libraries.
79 In the worst case, this might mean to compile Perl and
81 MariaDB/MySQL yourself. But believe me, experience shows that a
82 lot of problems are fixed this way.
83 Gzip libraries
85 Late versions of MySQL and MariaDB come with support for
86 compression. Thus it may be required that you have install an RPM
87 package like "libz-devel", "libgz-devel" or something similar.
88
90 So you need to install from sources? If you are lucky, the Perl module
91 "CPAN" will do all for you, thanks to the excellent work of Andreas
92 König. Otherwise you will need to do a manual installation. All of
93 these installation types have their own section: "CPAN installation",
94 "Manual installation" and "Configuration".
95 The DBD::MariaDB "Makefile.PL" needs to know where to find your MySQL
97 installation. This may be achieved using command line switches (see
98 "Configuration") or automatically using the "mariadb_config" or
99 "mysql_config" binary which comes with most MariaDB and MySQL
100 distributions. If your MariaDB or MySQL distribution contains
101 "mariadb_config" or "mysql_config" the easiest method is to ensure this
102 binary is on your path.
103 Typically, this is the case if you've installed the mysql library from
105 your systems' package manager.
106 e.g.
108 PATH=$PATH:/usr/local/mysql/bin
110 export PATH
111 As stated, to compile DBD::MariaDB you'll need a C compiler. This
113 should be the same compiler as the one used to build perl AND the
114 MariaDB or MySQL client libraries. If you're on linux, this is most
115 typically the case and you need not worry. If you're on UNIX systems,
116 you might want to pay attention.
117 Also you'll need to get the MariaDB or MySQL client and development
119 headers on your system. The easiest is to get these from your package
120 manager.
121 To run the tests that ship with the module, you'll need access to a
123 running MariaDB or MySQL server. This can be running on localhost, but
124 it can also be on a remote machine. You can use any server version
125 which is greater or equal to 4.1.0. It does not have to be same as
126 version of client library. Also you can use MariaDB client library and
127 MySQL server or vice-versa.
128 On Fedora the process is as follows. In this example we install and
130 start a local server for running the tests against.
131 yum -y install make gcc mariadb-devel mariadb-libs mariadb-server
133 yum -y install "perl(Test::Deep)" "perl(Test::More)"
134 systemctl start mariadb.service
135 Environment Variables
137 For ease of use, you can set environment variables for DBD::MariaDB
138 installation. You can set any or all of the options, and export them by
139 putting them in your .bashrc or the like:
140 export DBD_MARIADB_CFLAGS=-I/usr/local/mysql/include/mysql
142 export DBD_MARIADB_LIBS="-L/usr/local/mysql/lib/mysql -lmysqlclient"
143 export DBD_MARIADB_CONFIG=mysql_config
144 export DBD_MARIADB_TESTDB=test
145 export DBD_MARIADB_TESTHOST=127.0.0.1
146 export DBD_MARIADB_TESTPORT=3306
147 export DBD_MARIADB_TESTSOCKET=/var/run/mysqld/mysqld.sock
148 export DBD_MARIADB_TESTUSER=me
149 export DBD_MARIADB_TESTPASSWORD=s3kr1+
150 The most useful may be the host, database, port, socket, user, and
152 password.
153 Installation will first look to your "mariadb_config", your
155 "mysql_config", and then your environment variables, and then it will
156 guess with intelligent defaults.
157 CPAN installation
159 Installation of DBD::MariaDB can be incredibly easy:
160 cpan DBD::MariaDB
162 Please note that this will only work if the prerequisites are
164 fulfilled, which means you have a C-compiler installed, and you have
165 the development headers and mariadb or mysql client libraries available
166 on your system.
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.
170 If you cannot get the CPAN module working, you might try manual
172 installation. If installation with CPAN fails because your local
173 settings have been guessed wrong, you need to ensure MariaDB's
174 "mariadb_config" or MySQL's "mysql_config" is on your path (see "SOURCE
175 INSTALLATION") or alternatively create a script called "mysql_config".
176 This is described in more details later. "Configuration".
177 Manual installation
179 For a manual installation you need to fetch the DBD::MariaDB source
180 distribution. The latest version is always available from
181 <https://metacpan.org/release/DBD-MariaDB>.
182 The name is typically something like
184 DBD-MariaDB-<version>.tar.gz
186 The archive needs to be extracted. On Windows you may use a tool like
188 7-zip, on *nix you type
189 tar xf DBD-MariaDB-<version>.tar.gz
191 This will create a subdirectory DBD-MariaDB-<version>. Enter this
193 subdirectory and type
194 perl Makefile.PL
196 make
197 make test
198 On Windows you may need to replace "make" with "dmake", "gmake" or
200 "nmake". If the tests seem to look fine, you may continue with
201 make install
203 If the compilation (make) or tests fail, you might need to configure
205 some settings.
206 For example you might choose a different database, the C compiler or
208 the linker might need some flags. "Configuration". "Compiler flags".
209 "Linker flags".
210 For Cygwin there is a special section below. "Cygwin".
212 Configuration
214 The install script "Makefile.PL" can be configured via a lot of
215 switches. All switches can be used on the command line. For example,
216 the test database:
217 perl Makefile.PL --testdb=<db>
219 If you do not like configuring these switches on the command line, you
221 may alternatively create a script called "mariadb_config" or
222 "mysql_config". This is described later on.
223 Available switches are:
225 testdb
227 Name of the test database, defaults to test.
228 testuser
230 Name of the test user, defaults to empty. If the name is empty,
231 then the currently logged in users name will be used.
232 testpassword
234 Password of the test user, defaults to empty.
235 testhost
237 Host name or IP number of the test database; defaults to localhost.
238 testport
240 Port number of the test database; ignored when testhost is set to
241 "localhost".
242 testsocket
244 Unix socket of the test database; takes effect only when testhost
245 is set to "localhost".
246 cflags
248 This is a list of flags that you want to give to the C compiler.
249 The most important flag is the location of the MariaDB or MySQL
250 header files. For example, on Red Hat Linux the header files are in
251 /usr/include/mysql and you might try
252 -I/usr/include/mysql
254 On Windows the header files may be in C:\mysql\include and you
256 might try
257 -IC:\mysql\include
259 The default flags are determined by running
261 mysql_config --cflags
263 More details on the C compiler flags can be found in the following
265 section. "Compiler flags".
266 libs
268 This is a list of flags that you want to give to the linker or
269 loader. The most important flags are the locations and names of
270 additional libraries. For example, on Red Hat Linux your MySQL
271 client libraries are in /usr/lib/mysql and you might try
272 -L/usr/lib/mysql -lmysqlclient -lz
274 On Windows the libraries may be in C:\mysql\lib and
276 -LC:\mysql\lib -lmysqlclient
278 might be a good choice. The default flags are determined by running
280 mysql_config --libs
282 More details on the linker flags can be found in a separate
284 section. "Linker flags".
285 If a switch is not present on the command line, then the script
287 "mariadb_config" or "mysql_config" will be executed. This script comes
288 as part of the MariaDB or MySQL distribution. For example, to determine
289 the C compiler flags, we are executing
290 mysql_config --cflags
292 mysql_config --libs
293 If you want to configure your own settings for cflags or libs, then you
295 have to create a script with same name that provides needed details.
296 Compiler flags
298 Note: the following info about compiler and linker flags, you shouldn't
299 have to use these options because "Makefile.PL" is pretty good at
300 utilizing "mariadb_config" and "mysql_config" to get the flags that you
301 need for a successful compile.
302 It is typically not so difficult to determine the appropriate flags for
304 the C compiler. The linker flags, which you find in the next section,
305 are another story.
306 The determination of the C compiler flags is usually left to a
308 configuration script called "mysql_config", which can be invoked with
309 mysql_config --cflags
311 When doing so, it will emit a line with suggested C compiler flags, for
313 example like this:
314 -L/usr/include/mysql
316 The C compiler must find some header files. Header files have the
318 extension .h. MySQL header files are, for example, mysql.h and
319 mysql_version.h. In most cases the header files are not installed by
320 default. For example, on Windows it is an installation option of the
321 MySQL setup program (Custom installation), whether the header files are
322 installed or not. On Red Hat Linux, you need to install an RPM archive
323 "mariadb-devel", "mariadb-embedded-devel", "mysql-devel" or
324 "mysql-embedded-devel".
325 If you know the location of the header files, then you will need to add
327 an option
328 -L<header directory>
330 to the C compiler flags, for example "-L/usr/include/mysql".
332 Linker flags
334 Appropriate linker flags are the most common source of problems while
335 installing DBD::MariaDB. I will only give a rough overview, you'll find
336 more details in the troubleshooting section. "KNOWN PROBLEMS"
337 The determination of the C compiler flags is usually left to a
339 configuration script called "mysql_config", which can be invoked with
340 mysql_config --libs
342 When doing so, it will emit a line with suggested C compiler flags, for
344 example like this:
345 -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt
347 The following items typically need to be configured for the linker:
349 The mariadb/mysqlclient library
351 The MariaDB or MySQL client library comes as part of the MariaDB or
352 MySQL distribution. Depending on your system it may be a file
353 called
354 libmariadb.a statically linked library, Unix
356 libmariadb.so dynamically linked library, Unix
357 libmysqlclient.a statically linked library, Unix
358 libmysqlclient.so dynamically linked library, Unix
359 libmysqld.a statically linked library with embedded server, Unix
360 libmysqld.so dynamically linked library with embedded server, Unix
361 libmariadbd.a statically linked library with embedded server, Unix
362 libmariadbd.so dynamically linked library with embedded server, Unix
363 mariadb.lib statically linked library, Windows
364 libmariadb.lib statically linked library, Windows
365 mariadbclient.lib statically linked library, Windows
366 libmariadb.dll dynamically linked library, Windows
367 mysqlclient.lib statically linked library, Windows
368 mysqlclient.dll dynamically linked library, Windows
369 or something similar.
371 As in the case of the header files, the client library is typically
373 not installed by default. On Windows you will need to select them
374 while running the MySQL setup program (Custom installation). On Red
375 Hat Linux an RPM archive "mysql-devel" or "MySQL-devel" must be
376 installed.
377 The linker needs to know the location and name of the
379 mariadb/mysqlclient library. This can be done by adding the flags
380 -L<lib directory> -lmysqlclient
382 or by adding the complete path name. Examples:
384 -L/usr/lib/mysql -lmysqlclient
386 -LC:\mysql\lib -lmysqlclient
387 If you would like to use the static libraries, you need to create a
389 separate directory, copy the static libraries to that place and use
390 the "-L" switch above to point to your new directory. For example:
391 mkdir /tmp/mysql-static
393 cp /usr/lib/mysql/*.a /tmp/mysql-static
394 perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient"
395 make
396 make test
397 make install
398 rm -rf /tmp/mysql-static
399 The gzip library
401 The MariaDB or MySQL client can use compression when talking to the
402 MariaDB or MySQL server, a nice feature when sending or receiving
403 large texts over a slow network.
404 On Unix you typically find the appropriate file name by running
406 ldconfig -p | grep libz
408 ldconfig -p | grep libgz
409 Once you know the name (libz.a or libgz.a is best), just add it to
411 the list of linker flags. If this seems to be causing problem you
412 may also try to link without gzip libraries.
413
415 The MariaDB native client is another option for connecting to a MySQL
416 database licensed LGPL 2.1. To build DBD::MariaDB against this client,
417 you will first need to build the client. Generally, this is done with
418 the following:
419 cd path/to/src/mariadb-native-client
421 cmake -G "Unix Makefiles'
422 make
423 sudo make install
424 Once the client is built and installed, you can build DBD::MariaDB
426 against it:
427 perl Makefile.PL --testuser=xxx --testpassword=xxx \
429 --testsocket=/path/to/mysqld.sock \
430 --mariadb_config=/usr/local/bin/mariadb_config
431 make
432 make test
433 make install
434
436 Below you find information on particular systems:
437 macOS
439 For installing DBD::MariaDB you need to have the libssl header files
440 and the mysql client libs. The easiest way to install these is using
441 Homebrew (<https://brew.sh/>).
442 Once you have Homebrew set up, you can simply install the dependencies
444 using
445 brew install openssl mysql-connector-c
447 Then you can install DBD::MariaDB using your cpan client.
449 Cygwin
451 If you are a user of Cygwin you already know, it contains a nicely
452 running perl 5.6.1, installation of additional modules usually works
453 like a charm via the standard procedure of
454 perl makefile.PL
456 make
457 make test
458 make install
459 The Windows binary distribution of MySQL runs smoothly under Cygwin.
461 You can start/stop the server and use all Windows clients without
462 problem. But to install DBD::MariaDB you have to take a little special
463 action.
464 Don't attempt to build DBD::MariaDB against either the MySQL Windows or
466 Linux/Unix distributions: neither will work!
467 You MUST compile the MySQL clients yourself under Cygwin, to get a
469 libmysqlclient.a compiled under Cygwin. Really! You'll only need that
470 library and the header files, you don't need any other client parts.
471 Continue to use the Windows binaries. And don't attempt (currently) to
472 build the MySQL Server part, it is unnecessary, as MySQL AB does an
473 excellent job to deliver optimized binaries for the mainstream
474 operating systems, and it is told, that the server compiled under
475 Cygwin is unstable.
476 Install a MySQL server for testing against. You can install the regular
478 Windows MySQL server package on your Windows machine, or you can also
479 test against a MySQL server on a remote host.
480 Build MySQL clients under Cygwin:
482 Download the MySQL LINUX source from <https://www.mysql.com/downloads>,
484 unpack mysql-<version>.tar.gz into some tmp location and from this
485 directory run configure:
486 ./configure --prefix=/usr/local/mysql --without-server
488 This prepares the Makefile with the installed Cygwin features. It takes
490 some time, but should finish without error. The "--prefix", as given,
491 installs the whole Cygwin/MySQL thingy into a location not normally in
492 your PATH, so that you continue to use already installed Windows
493 binaries. The "--without-server" parameter tells configure to only
494 build the clients.
495 make
497 This builds all MySQL client parts ... be patient. It should finish
499 finally without any error.
500 make install
502 This installs the compiled client files under /usr/local/mysql/.
504 Remember, you don't need anything except the library under
505 /usr/local/mysql/lib and the headers under /usr/local/mysql/include!
506 Essentially you are now done with this part. If you want, you may try
508 your compiled binaries shortly; for that, do:
509 cd /usr/local/mysql/bin
511 ./mysql -h 127.0.0.1
512 The host ("-h") parameter 127.0.0.1 targets the local host, but forces
514 the mysql client to use a TCP/IP connection. The default would be a
515 pipe/socket connection (even if you say "-h localhost") and this
516 doesn't work between Cygwin and Windows (as far as I know).
517 If you have your MySQL server running on some other box, then please
519 substitute 127.0.0.1 with the name or IP-number of that box.
520 Please note, in my environment the "mysql" client did not accept a
522 simple RETURN, I had to use CTRL-RETURN to send commands ... strange,
523 but I didn't attempt to fix that, as we are only interested in the
524 built lib and headers.
525 At the "mysql>" prompt do a quick check:
527 mysql> use mysql
529 mysql> show tables;
530 mysql> select * from db;
531 mysql> exit
532 You are now ready to build DBD::MariaDB!
534 compile DBD::MariaDB
536 Download and extract DBD-MariaDB-<version>.tar.gz from CPAN, "cd" into
538 unpacked dir DBD-MariaDB-<version> you probably did that already, if
539 you are reading this!
540 cp /usr/local/mysql/bin/mysql_config .
542 This copies the executable script mentioned in the DBD::MariaDB docs
544 from your just built Cywin/MySQL client directory; it knows about your
545 Cygwin installation, especially about the right libraries to link with.
546 perl Makefile.PL --testhost=127.0.0.1
548 The "--testhost=127.0.0.1" parameter again forces a TCP/IP connection
550 to the MySQL server on the local host instead of a pipe/socket
551 connection for the "make test" phase.
552 make
554 This should run without error
556 make test
558 make install
559 This installs DBD::MariaDB into the Perl hierarchy.
561
563 no gzip on your system
564 Some Linux distributions don't come with a gzip library by default.
565 Running "make" terminates with an error message like
566 LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc
568 -o blib/arch/auto/DBD/mysql/mysql.so -shared
569 -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql
570 -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96
571 -lgcc -lz
572 /usr/bin/ld: cannot find -lz
573 collect2: ld returned 1 exit status
574 make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1
575 If this is the case for you, install an RPM archive like "libz-devel",
577 "libgz-devel", "zlib-devel" or "gzlib-devel" or something similar.
578 different compiler for mysql and perl
580 If Perl was compiled with gcc or egcs, but MySQL was compiled with
581 another compiler or on another system, an error message like this is
582 very likely when running "make test":
583 t/00base............install_driver(mysql) failed: Can't load
585 '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::MariaDB:
586 ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
587 at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
588 line 168.
589 This means, that your linker doesn't include libgcc.a. You have the
591 following options:
592 The solution is telling the linker to use "libgcc". Run
594 gcc --print-libgcc-file
596 to determine the exact location of libgcc.a or for older versions of
598 gcc
599 gcc -v
601 to determine the directory. If you know the directory, add a
603 -L<directory> -lgcc
605 to the list of C compiler flags. "Configuration". "Linker flags".
607
609 Finally, if everything else fails, you are not alone. First of all, for
610 an immediate answer, you should look into the archives of the dbi-users
611 mailing list, which is available at Perl DBI Users' Forum
612 <https://groups.google.com/forum/#!forum/perl.dbi.users>.
613 To subscribe to this list, send and email to
615 "dbi-users-subscribe@perl.org" <mailto:dbi-users-subscribe@perl.org>.
616 If you don't find an appropriate posting and reply in the mailing list,
618 please post a question. Typically a reply will be seen within one or
619 two days.
620perl v5.36.0 2023-01-20 DBD::MariaDB::INSTALL(3)