The default configuration of MySQL++ is suitable for most purposes, but there are a few things you can change to make it meet special needs.
MySQL++ is built on top of the MySQL C API. (Now called Connector/C.) MySQL++ relies on this low-level library for all communication with the database server. Consequently, the build process for MySQL++ may fail if it can’t find the C API headers and library.
On platforms that use Autoconf[19], the configure
script can usually figure out the location of the C API
development files by itself[20] It simply
tries a bunch of common installation locations until it finds one
that works. If your MySQL server was installed in a nonstandard
location, you will have to tell the configure
script where these files are with some combination
of the --with-mysql,
--with-mysql-include, and
--with-mysql-lib flags. See
README-Unix.txt for details.
No other platform allows this sort of auto-discovery, so
the build files for these platforms simply hard-code the default
installation location for the current GA version of Connector/C
at the time that version of MySQL++ was released. For example,
the Visual C++ project files currently assume MySQL is in
c:\Program Files\MySQL\MySQL Server 5.1. If
you’re using some other release of MySQL or you installed it
somewhere else, you will have to modify the build files. How you
do this, exactly, varies based on platform and what tools you
have on hand. See README-Visual-C++.txt,
README-MinGW.txt, or
README-Mac-OS-X.txt, as appropriate.
MySQL++ offers two ways to automatically build SQL
queries at run time: Template Queries and SSQLS. There’s a limit on the number
of fields these mechanisms support, defaulting to 25 fields in the
official MySQL++ packages.[21] The files
embodying these limits are lib/querydef.h and
lib/ssqls.h, each generated by Perl scripts of
the same name but with a .pl extension.
The default querydef.h is small and
its size only increases linearly with respect to maximum field
count.
ssqls.h is a totally
different story. The default 25 field limit
makes ssqls.pl generate an
ssqls.h over 1 MB. Worse,
the field limit to file size relation is
quadratic.[22]
This has a number of bad effects:
Generating header files to support more fields than you actually require is a waste of space and bandwidth.
Some compilers have arbitrary limits on the size of macros they’re able to parse. Exceeding these limits usually causes the compiler to misbehave badly, rather than fail gracefully.
Because it increases the size of two key files used in building MySQL++ itself and programs built on it, it increases compile times significantly. One test I did here showed a tripling of compile time from quadrupling the field limit.
More than 25 fields in a table is a good sign of a bad database design, most likely a denormalization problem.
The default limits try to mitigate against all of these factors while still being high enough to be useful with most DB designs.
If you’re building MySQL++ from source on a platform that uses Autoconf, the easiest way to change these limits is at configuration time:
./configure --with-field-limit=50
That causes the configuration script to pass the -f flag to the two Perl scripts named above, overriding the default of 25 fields. Obviously you need a Perl interpreter on the system for this to work, but Perl is usually installed by default on systems MySQL++ supports via Autoconf.
On all other platforms, you’ll have to give the -f flag to these scripts yourself. This may require installing Perl and putting it in the command path first. Having done that, you can do something like this to raise the limits:
cd lib perl ssqls.pl -f 50 perl querydef.pl -f 50
Note the need to run these commands within the
lib subdirectory of the MySQL++ source
tree. (This is done for you automatically on systems where you
are able to use the Autoconf method.)
It’s common these days on Unixy systems to install
the MySQL C API headers in a mysql directory
under some common include directory. If the
C API headers are in /usr/include/mysql, we
say they are “buried” underneath the system’s
main include directory, /usr/include. Since
the MySQL++ headers depend on these C API headers, it can be
useful for MySQL++ to know this fact.
When MySQL++ includes one of the C API headers, it normally does so in the obvious way:
#include <mysql.h>
But, if you define the
MYSQLPP_MYSQL_HEADERS_BURIED macro, it switches
to this style:
#include <mysql/mysql.h>
In common situations like the
/usr/include/mysql one, this simplifies the
include path options you pass to your compiler.
MySQL++ uses the C99
header stdint.h for portable fixed-size
integer typedefs where possible. The C99 extensions aren’t
yet officially part of the C++ Standard, so there are still
some C++ compilers that don’t offer this header. MySQL++
works around the lack of this header where it knows it needs
to, but your platform might not be recognized, causing
the build to break. If this happens, you can define the
MYSQLPP_NO_STDINT_H macro to make MySQL++
use its best guess for suitable integer types instead of relying
on stdint.h.
MySQL++ also uses C99’s long long
data type where available. MySQL++ has workarounds for platforms
where this is known not to be available, but if you get errors in
common.h about this type, you can define the
macro MYSQLPP_NO_LONG_LONGS to make MySQL++
fall back to portable constructs.
[19] Linux, Solaris, the BSDs, Mac OS X command line (as opposed to the Xcode IDE), Cygwin... Basically, Unix or anything that works like it.
[20] I don’t say “Connector/C” here because the name change generally hasn’t percolated out to Unixy systems. It’s more commonly used on Windows systems, since the separate Connector/C download lets them avoid installing a MySQL server just to get development headers and libraries.
[21] If you’re using a third-party MySQL++ package, its maintainer may have increased these field counts so the resulting headers more closely approach the size limit of the compiler the package was built with. In that case, you can look at the top of each generated header file to find out how many fields each supports.
[22] The file
size equation, for you amateur mathematicians out there,
is Nlines =
18.5f2 + 454.5f + 196.4,
where f is the field count.