1DBD::MariaDB::INSTALL(3U)ser Contributed Perl DocumentatiDoBnD::MariaDB::INSTALL(3)
2
3
4

NAME

6       DBD::MariaDB::INSTALL - How to install and configure DBD::MariaDB
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::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
21       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

PREREQUISITES

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
33       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
39           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
47           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
52           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
56             ./configure --without-server
57
58           or
59
60             cmake -DWITHOUT_SERVER=ON
61
62           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
69       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
73       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
80           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
84       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

SOURCE INSTALLATION

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
96       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
104       Typically, this is the case if you've installed the mysql library from
105       your systems' package manager.
106
107       e.g.
108
109         PATH=$PATH:/usr/local/mysql/bin
110         export PATH
111
112       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
118       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
122       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
129       On Fedora the process is as follows. In this example we install and
130       start a local server for running the tests against.
131
132         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
136   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
141         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
151       The most useful may be the host, database, port, socket, user, and
152       password.
153
154       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
158   CPAN installation
159       Installation of DBD::MariaDB can be incredibly easy:
160
161         cpan DBD::MariaDB
162
163       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
168       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
171       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
178   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
183       The name is typically something like
184
185         DBD-MariaDB-<version>.tar.gz
186
187       The archive needs to be extracted. On Windows you may use a tool like
188       7-zip, on *nix you type
189
190         tar xf DBD-MariaDB-<version>.tar.gz
191
192       This will create a subdirectory DBD-MariaDB-<version>. Enter this
193       subdirectory and type
194
195         perl Makefile.PL
196         make
197         make test
198
199       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
202         make install
203
204       If the compilation (make) or tests fail, you might need to configure
205       some settings.
206
207       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
211       For Cygwin there is a special section below. "Cygwin".
212
213   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
218         perl Makefile.PL --testdb=<db>
219
220       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
224       Available switches are:
225
226       testdb
227           Name of the test database, defaults to test.
228
229       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
233       testpassword
234           Password of the test user, defaults to empty.
235
236       testhost
237           Host name or IP number of the test database; defaults to localhost.
238
239       testport
240           Port number of the test database; ignored when testhost is set to
241           "localhost".
242
243       testsocket
244           Unix socket of the test database; takes effect only when testhost
245           is set to "localhost".
246
247       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
253             -I/usr/include/mysql
254
255           On Windows the header files may be in C:\mysql\include and you
256           might try
257
258             -IC:\mysql\include
259
260           The default flags are determined by running
261
262             mysql_config --cflags
263
264           More details on the C compiler flags can be found in the following
265           section.  "Compiler flags".
266
267       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
273             -L/usr/lib/mysql -lmysqlclient -lz
274
275           On Windows the libraries may be in C:\mysql\lib and
276
277             -LC:\mysql\lib -lmysqlclient
278
279           might be a good choice. The default flags are determined by running
280
281             mysql_config --libs
282
283           More details on the linker flags can be found in a separate
284           section.  "Linker flags".
285
286       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
291         mysql_config --cflags
292         mysql_config --libs
293
294       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
297   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
303       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
307       The determination of the C compiler flags is usually left to a
308       configuration script called "mysql_config", which can be invoked with
309
310         mysql_config --cflags
311
312       When doing so, it will emit a line with suggested C compiler flags, for
313       example like this:
314
315         -L/usr/include/mysql
316
317       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
326       If you know the location of the header files, then you will need to add
327       an option
328
329         -L<header directory>
330
331       to the C compiler flags, for example "-L/usr/include/mysql".
332
333   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
338       The determination of the C compiler flags is usually left to a
339       configuration script called "mysql_config", which can be invoked with
340
341         mysql_config --libs
342
343       When doing so, it will emit a line with suggested C compiler flags, for
344       example like this:
345
346         -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt
347
348       The following items typically need to be configured for the linker:
349
350       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
355             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
370           or something similar.
371
372           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
378           The linker needs to know the location and name of the
379           mariadb/mysqlclient library. This can be done by adding the flags
380
381             -L<lib directory> -lmysqlclient
382
383           or by adding the complete path name. Examples:
384
385             -L/usr/lib/mysql -lmysqlclient
386             -LC:\mysql\lib -lmysqlclient
387
388           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
392             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
400       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
405           On Unix you typically find the appropriate file name by running
406
407             ldconfig -p | grep libz
408             ldconfig -p | grep libgz
409
410           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

MARIADB NATIVE CLIENT INSTALLATION

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
420         cd path/to/src/mariadb-native-client
421         cmake -G "Unix Makefiles'
422         make
423         sudo make install
424
425       Once the client is built and installed, you can build DBD::MariaDB
426       against it:
427
428         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

SPECIAL SYSTEMS

436       Below you find information on particular systems:
437
438   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
443       Once you have Homebrew set up, you can simply install the dependencies
444       using
445
446         brew install openssl mysql-connector-c
447
448       Then you can install DBD::MariaDB using your cpan client.
449
450   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
455         perl makefile.PL
456         make
457         make test
458         make install
459
460       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
465       Don't attempt to build DBD::MariaDB against either the MySQL Windows or
466       Linux/Unix distributions: neither will work!
467
468       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
477       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
481       Build MySQL clients under Cygwin:
482
483       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
487         ./configure --prefix=/usr/local/mysql --without-server
488
489       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
496         make
497
498       This builds all MySQL client parts ... be patient. It should finish
499       finally without any error.
500
501         make install
502
503       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
507       Essentially you are now done with this part. If you want, you may try
508       your compiled binaries shortly; for that, do:
509
510         cd /usr/local/mysql/bin
511         ./mysql -h 127.0.0.1
512
513       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
518       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
521       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
526       At the "mysql>" prompt do a quick check:
527
528         mysql> use mysql
529         mysql> show tables;
530         mysql> select * from db;
531         mysql> exit
532
533       You are now ready to build DBD::MariaDB!
534
535       compile DBD::MariaDB
536
537       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
541         cp /usr/local/mysql/bin/mysql_config .
542
543       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
547         perl Makefile.PL --testhost=127.0.0.1
548
549       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
553         make
554
555       This should run without error
556
557         make test
558         make install
559
560       This installs DBD::MariaDB into the Perl hierarchy.
561

KNOWN PROBLEMS

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
567         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
576       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
579   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
584         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
590       This means, that your linker doesn't include libgcc.a. You have the
591       following options:
592
593       The solution is telling the linker to use "libgcc". Run
594
595         gcc --print-libgcc-file
596
597       to determine the exact location of libgcc.a or for older versions of
598       gcc
599
600         gcc -v
601
602       to determine the directory. If you know the directory, add a
603
604         -L<directory> -lgcc
605
606       to the list of C compiler flags. "Configuration". "Linker flags".
607

SUPPORT

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
614       To subscribe to this list, send and email to
615       "dbi-users-subscribe@perl.org" <mailto:dbi-users-subscribe@perl.org>.
616
617       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.
620
621
622
623perl v5.36.0                      2023-01-20          DBD::MariaDB::INSTALL(3)
Impressum