# Frequently-Asked Questions About MySQL++

## What version of MySQL++ should I use?

If you’re writing new code, you should use the [latest stable version](#stable).
If you’re writing new code, you should use the [latest stable version](/#stable).

If you have existing code currently using an older version of MySQL++,
If you have existing code currently using an older version of MySQL++, you may not want to upgrade all the way to the current version, at least not in a single step. You might want to upgrade to an [intermediate version](#oldver) first, just to get bug fixes and maybe some minor features. Then once that step is working and tested, you can think about jumping to the latest stable version.
you may not want to upgrade all the way to the current version, at least
not in a single step. You might want to upgrade to an [intermediate
version](#oldver) first, just to get bug fixes and maybe some minor
features. Then once that step is working and tested, you can think about
jumping to the latest stable version.

MySQL++ uses the standard major.minor.bug-fix version number scheme. A
MySQL++ uses the standard major.minor.bug-fix version number scheme. A change in the library’s major version number denotes changes that will almost certainly require source code changes in your program. See the “[Incompatible Library Changes](doc/html/userman/breakages.html)” chapter of the user manual for details. A change in the minor version number indicates added features that don’t change existing library interfaces. If you don’t want to use those features, you should be able
change in the library’s major version number denotes changes that will
almost certainly require source code changes in your program. See the
“[Incompatible Library Changes](doc/html/userman/breakages.html)”
chapter of the user manual for details. A change in the minor version
number indicates added features that don’t change existing library
interfaces. If you don’t want to use those features, you should be able
to install the new library without rebuilding your program. A change in
to install the new library without rebuilding your program. A change in the bug-fix number indicates internal bug fixes, which don’t affect the library interface at all, so such versions are always safe to install.
the bug-fix number indicates internal bug fixes, which don’t affect the
library interface at all, so such versions are always safe to install.

We haven’t followed this discipline perfectly. The library’s binary
interface [changed a few times](doc/html/userman/breakages.html#abi-1.7.18) between the epochal 1.7.9 release and the final 1.*x* release, 1.7.40. If your program uses
We haven’t followed this discipline perfectly. The library’s binary interface [changed a few times](doc/html/userman/breakages.html#abi-1.7.18) between the epochal 1.7.9 release and the final 1.*x* release, 1.7.40. If your program uses a version in between, be prepared to change the code when upgrading. The library interface also [changed a few times](doc/html/userman/breakages.html#abi-3.0.0) early in the 3.*x* series before settling down.
a version in between, be prepared to change the code when upgrading. The
library interface also [changed a few times](doc/html/userman/breakages.html#abi-3.0.0) early in the 3.*x* series before settling down.


## What platforms does it work on?

MySQL++ should work on any platform that has a C++98 or newer compiler
MySQL++ should work on any platform that has a C++98 or newer compiler and the MySQL C API development files. MySQL++ does use some C99/TR1 features that didn’t make it into C++ until C++11 or C++14, but these are optional, so it still works with C++98 compilers.
and the MySQL C API development files. MySQL++ does use some C99/TR1
features that didn’t make it into C++ until C++11 or C++14, but these
are optional, so it still works with C++98 compilers.

In practice, MySQL++ works best on the platforms that get the most
In practice, MySQL++ works best on the platforms that get the most attention. This means mass-market operating systems on common hardware, and the default tool chain for the platform. There are FAQ items for most common platforms below; if your platform isn’t addressed and it’s outside the mainstream or is older than about 2003, the chance of it working out of the box are low. We’re happy to discuss porting on the mailing list, but be prepared to do most of the work yourself; if MySQL++ hasn’t been ported to your system already, there’s usually a pretty good reason why not.
attention. This means mass-market operating systems on common hardware,
and the default tool chain for the platform. There are FAQ items for
most common platforms below; if your platform isn’t addressed and it’s
outside the mainstream or is older than about 2003, the chance of it
working out of the box are low. We’re happy to discuss porting on the
mailing list, but be prepared to do most of the work yourself; if
MySQL++ hasn’t been ported to your system already, there’s usually a
pretty good reason why not.

If you use a different platform and it isn’t mentioned in the subsequent
If you use a different platform and it isn’t mentioned in the subsequent FAQ items, probably little is known about it. If it builds out of the box, we’d appreciate it if you’d send a report to the mailing list. If not, please send patches to fix this to the mailing list. We will support any platform that gets enough interest from the users.
FAQ items, probably little is known about it. If it builds out of the
box, we’d appreciate it if you’d send a report to the mailing list. If
not, please send patches to fix this to the mailing list. We will
support any platform that gets enough interest from the users.


## What versions of MySQL does it work with?

MySQL++ works best with MySQL version 4.1 or higher, simply because this
MySQL++ works best with MySQL version 4.1 or higher, simply because this is the oldest version that it’s regularly tested against during development.
is the oldest version that it’s regularly tested against during
development.

We do most of the development against MySQL 5.1 or newer, since this is
We do most of the development against MySQL 5.1 or newer, since we don’t use older versions on our production machines. Because MySQL++ is intended for use in production environments, we also don’t test it against bleeding-edge versions of MySQL; the newest version we typically test it with is the current GA release at the time MySQL++ was released. We’re not opposed to supporting newer versions, we just don’t build test environments for these newer versions in advance of need. If you find
the version we use on most of our production machines. Because MySQL++
is intended for use in production environments, we don’t test it against
bleeding-edge versions of MySQL; the newest version we typically test it
with is the current GA release at the time MySQL++ was released. We’re
not opposed to supporting newer versions, we just don’t build test
environments for these newer versions in advance of need. If you find
that MySQL++ isn’t building against a newer release of MySQL, a short
that MySQL++ isn’t building against a newer release of MySQL, a short [bug report](#bugreport) is usually sufficient to get it fixed.
[bug report](#bugreport) is usually sufficient to get it fixed.

MySQL++ probably still builds against MySQL 4.0, but this hasn’t been
tested in quite a long time now. Some of the examples demonstrate the
explicit UTF-8 support available in MySQL 4.1 and newer. If you want to
run the examples, you will need to remove the UTF-8 bits from the
`CREATE TABLE` statements in `examples/resetdb.cpp`. Older versions of
MySQL will allow implicit use of UTF-8, they just won’t let you declare
your intentions, and you don’t get features like UTF-8 aware sorting.

With some work, MySQL++ may be modified to work on older versions of MySQL.
MySQL++ can be made to build against MySQL 3.23, but it won’t do so out
of the box. The last time I tried this, the only thing that needed doing
was changing `MYSQL_TYPE_`\* in `lib/type_info.cpp` to `FIELD_TYPE_`\*.
The UTF-8 comments above also apply equally to older versions of MySQL.


## <a name="mariadb"></a>Does it build against [MariaDB](https://mariadb.org)?

Yes. The library is only called “MySQL++” because it predates MariaDB.


## <a name="license"></a>What software license does MySQL++ use? Is it free?

MySQL++ is free software, licensed under the [GNU
MySQL++ is free software, licensed under the [GNU LGPL](http://www.gnu.org/licenses/lgpl.html).
LGPL](http://www.gnu.org/licenses/lgpl.html).


## <a name="whylgpl"></a>What does the LGPL license mean to me, as far as MySQL++ goes?

The common wisdom regarding LGPL’d libraries is that you can use them
The common wisdom regarding LGPL’d libraries is that you can use them with a program using almost any software license as long as you’re willing to link dynamically. Think of the GNU C library (glibc) on Linux: it’s LGPL’d and linked to almost everything on a Linux system, at least indirectly. If your program’s software license allows dynamic linking to glibc, it should allow you to use MySQL++ dynamically, too.
with a program using almost any software license as long as you’re
willing to link dynamically. Think of the GNU C library (glibc) on
Linux: it’s LGPL’d and linked to almost everything on a Linux system, at
least indirectly. If your program’s software license allows dynamic
linking to glibc, it should allow you to use MySQL++ dynamically, too.

If you link to MySQL++ statically, you trigger the “viral” provisions of
If you link to MySQL++ statically, you trigger the “viral” provisions of the LGPL. Practically speaking, it means your program must be licensed under the LGPL or something compatible with it, such as the GPL. This rules out static linking when you want to keep your source code closed, and even rules out static linking with some open source licenses, since not all of them are compatible with LGPL at that level.
the LGPL. Practically speaking, it means your program must be licensed
under the LGPL or something compatible with it, such as the GPL. This
rules out static linking when you want to keep your source code closed,
and even rules out static linking with some open source licenses, since
not all of them are compatible with LGPL at that level.

MySQL++’s licensing history is tangled, what with the numerous changes
MySQL++’s licensing history is tangled, what with the numerous changes of maintainership and the lack of a copyright assignment system for third-party contributions. That means the license will not be changing, ever. It would simply be impractical to contact all of the past contributors and get them to agree on the licensing changes needed to make this happen.
of maintainership and the lack of a copyright assignment system for
third-party contributions. That means the license will not be changing,
ever. It would simply be impractical to contact all of the past
contributors and get them to agree on the licensing changes needed to
make this happen.

If you need to link to your C++ database library statically and can’t
If you need to link to your C++ database library statically and can’t use the LGPL or something compatible with it for your program, you might consider using MySQL’s Connector/C++ instead. The free version is GPL’d, but they will sell you a commercial license which allows static linking.
use the LGPL or something compatible with it for your program, you might
consider using MySQL’s Connector/C++ instead. The free version is GPL’d,
but they will sell you a commercial license which allows static linking.


## <a name="mysqlclientgpl"></a>Doesn’t the MySQL C API library’s GPL license override MySQL++’s LGPL license?

The MySQL C API library is available under *two* different licenses, not one.

The default license for MySQL (including its C API library) is GPL with
The default license for MySQL (including its C API library) is GPL with the FOSS license exception. This is what you get if you got MySQL for free, such as by downloading it from `mysql.com` or as part of your Linux distro. The less liberal distribution terms of the C API library’s GPL do override the less restrictive ones of MySQL++’s LGPL license. This matters if you want to distribute your program as a binary only, keeping the source to yourself.
the FOSS license exception. This is what you get if you got MySQL for
free, such as by downloading it from `mysql.com` or as part of your
Linux distro. The less liberal distribution terms of the C API library’s
GPL do override the less restrictive ones of MySQL++’s LGPL license.
This matters if you want to distribute your program as a binary only,
keeping the source to yourself.

If you need to be able to distribute closed-source programs, MySQL, Inc.
If you need to be able to distribute closed-source programs, Oracle. will happily sell you a [commercial distribution
will happily sell you a [commercial distribution
license](http://www.mysql.com/about/legal/licensing/oem/) for their C
license](http://www.mysql.com/about/legal/licensing/oem/) for their C API library.
API library.

This issue really has nothing to do with MySQL++. The same restriction
This issue really has nothing to do with MySQL++. The same restriction applies if you write your program directly against the C API library. The only reason I even put this here is because people keep asking the question. Please work out the licensing with Oracle. Having settled that, the previous FAQ item applies.
applies if you write your program directly against the C API library.
The only reason I even put this here is because people keep asking the
question. Please work out the licensing with MySQL, Inc. Having settled
that, the previous FAQ item applies.


## <a name="conncpp"></a>How does MySQL++ compare to MySQL’s Connector/C++?

[Connector/C++](https://dev.mysql.com/downloads/connector/cpp/) is a much
[Connector/C++](https://dev.mysql.com/downloads/connector/cpp/) is a much younger C++ wrapper for the MySQL C API library, fully developed under the MySQL corporate aegis. By contrast, MySQL++ has a long, complex [development history](doc/html/userman/index.html#history). MySQL++ started out as a third-party library, was maintained and enhanced by
younger C++ wrapper for the MySQL C API library, fully developed under
the MySQL corporate aegis. By contrast, MySQL++ has a long, complex
[development history](doc/html/userman/index.html#history). MySQL++
started out as a third-party library, was maintained and enhanced by
MySQL for several years, then got spun back out again, this time
MySQL for several years, then got spun back out again, this time probably for good. MySQL does still host our [mailing
probably for good. MySQL does still host our [mailing
list](http://lists.mysql.com/plusplus/), for which we thank them, but
list](http://lists.mysql.com/plusplus/), for which we thank them, but they don’t control the hosting or development of MySQL++ any more.
they don’t control the hosting or development of MySQL++ any more.

MySQL decided to create a competing library for two reasons. First,
MySQL decided to create a competing library for two reasons. First, having the entire thing to themselves mean they can do the same dual-licensing thing they do with the C API library. Second, after Sun bought MySQL, they wanted to put MySQL support into OpenOffice, and wanted a [JDBC](http://en.wikipedia.org/wiki/Jdbc) style API for that support.
having the entire thing to themselves mean they can do the same
dual-licensing thing they do with the C API library. Second, after Sun
bought MySQL, they wanted to put MySQL support into OpenOffice, and
wanted a [JDBC](http://en.wikipedia.org/wiki/Jdbc) style API for that
support.

By contrast with Connector/C++’s Java-style database API, MySQL++ is
By contrast with Connector/C++’s Java-style database API, MySQL++ is very much a native C++ library: we use STL and other Standard C++ features heavily. If you are a Java developer or simply admire its database interface design, you may prefer Connector/C++.
very much a native C++ library: we use STL and other Standard C++
features heavily. If you are a Java developer or simply admire its
database interface design, you may prefer Connector/C++.

Another way to look at it is that Connector/C++ is new and therefore
Another way to look at it is that Connector/C++ is new and therefore perhaps less crufty, while MySQL++ is mature and featureful.
perhaps less crufty, while MySQL++ is mature and featureful.


## <a name="gcc"><a name="gcc2"></a></a>Will it build under GCC?

Yes, with GCC version 3.0 and up, except on [MinGW](#mingw), which requires 3.4.5 at minimum.

The last version of MySQL++ that works with GCC 2.95.*x* is 1.7.9. It may be less painful to port the current version back to GCC 2.95 than to live with the limitations and bugs of this older version. The main thing breaking this backwards compatibility are the steps forward we’ve taken for Standard C++ compliance. If you work around or revert these, it should work on GCC 2.95 again.

If you’re stuck on anything older than GCC 2.95, we recommend that you use the MySQL C API instead of trying to arm-twist MySQL++ into building under it.


## <a name="vstudio"></a>Will it build under Visual C++?

Yes, it ships with project files for Visual C++ 2005 and 2008.

MySQL++ also works fine with Visual C++ 2010 and newer with a project
MySQL++ also works fine with Visual C++ 2010 and newer with a project file conversion. This may require minor manual adjustments. For example, when VC++ 2013 converts the VS2008 project files, it changes the debug build output directory from `debug` to `debug\x64` but fails to update the linker settings for the executables.
file conversion. This may require minor manual adjustments. For example,
when VC++ 2013 converts the VS2008 project files, it changes the debug
build output directory from `debug` to `debug\x64` but fails to update
the linker settings for the executables.

MySQL++ still mostly works with Visual C++ 2003. The main exception is the [Specialized SQL Structures](doc/html/userman/ssqls.html) feature, which doesn’t work at all any more. It appears to be difficult to fix, because the symptom is that the compiler crashes when you try to build even the most trivial SSQLS code. There are [several possible ways](doc/html/userman/ssqls.html#ssqls-vc2003) to work around this limitation.

If you must use Visual C++ 2002 (a.k.a. 7.0) or older, you can try the [ancient 1.7.1 version](/home/#oldver) of MySQL++. This is a third-party contribution which is [known to have
If you must use Visual C++ 2002 (a.k.a. 7.0) or older, you can try the [ancient 1.7.1 version](/home/#oldver) of MySQL++. This is a third-party contribution which is [known to have bugs](http://lists.mysql.com/plusplus/1069). You might be better off using [Connector/C](http://dev.mysql.com/downloads/connector/c/) instead.
bugs](http://lists.mysql.com/plusplus/1069). You might be better off using [Connector/C](http://dev.mysql.com/downloads/connector/c/) instead.

The library’s primary maintainer only uses MySQL++ seriously on Linux, macOS and FreeBSD systems, and let his MSDN membership lapse years ago. Consequently, he only tests MySQL++ occasionally under the current version of [Visual C++
Community](https://www.visualstudio.com/vs/community/). Consequently, we’re highly reliant on testing and patches from the user base for this platform.

If you’re not using a recent version of Visual C++, you should really
If you’re not using a recent version of Visual C++, you should really consider upgrading as the compliance of the compiler has improved greatly. The [Community edition](https://www.visualstudio.com/vs/community/) now does pretty much everything the pre-2015 Professional editions used to, so you may no longer have a valid excuse for not upgrading.
consider upgrading as the compliance of the compiler has improved
greatly. The [Community
edition](https://www.visualstudio.com/vs/community/) now does pretty
much everything the pre-2015 Professional editions used to, so you may
no longer have a valid excuse for not upgrading.


## <a name="osx"><a name="xcode"></a></a>Will it build on Mac OS X/macOS?

Yes, it builds just fine, both from within the Xcode environment and at
Yes, it builds just fine, both from within the Xcode environment and at the command line. We currently test only on the current and/or prior releases of the OS. The included Xcode project files should work with Xcode 2+, which implies that it may still build on systems as old as OS X 10.4. In the past, we successfully tested command line builds on a 10.3 box.
the command line. We currently test only on the current and/or prior
releases of the OS. The included Xcode project files should work with
Xcode 2+, which implies that it may still build on systems as old as OS
X 10.4. In the past, we successfully tested command line builds on a
10.3 box.

Command line builds are still preferred to Xcode, as there is more
Command line builds are still preferred to Xcode, as there is more flexibility to be had here. See `README-Mac-OS-X.txt` in the MySQL++ tarball for details. That file also contains instructions on getting [Connector/C](https://dev.mysql.com/downloads/connector/c/) for macOS, which MySQL++ builds against.
flexibility to be had here. See `README-Mac-OS-X.txt` in the MySQL++
tarball for details. That file also contains instructions on getting
[Connector/C](https://dev.mysql.com/downloads/connector/c/) for OS X,
which MySQL++ builds against.


## <a name="cygwin"></a>Will it build under Cygwin?

Yes. See [the `README-Cygwin.txt` file](/file/README-Cygwin.txt).

Just use the built-in package manager to install MySQL 5.0 or newer and GCC, and you’re set. Beware, in some versions of Solaris, the “mysql” package is MySQL 4.0, which MySQL++ no longer works 100% with out of the box. (See above.) You want the “mysql5” package instead.


## <a name="borland"></a>Will it build under C++Builder?

It can be made to work, mostly.

The last time it was tried, the [Specialized SQL Structures](doc/html/userman/ssqls.html) feature didn’t work right out of the box due to a compiler limitation. A full discussion of the
The last time it was tried, the [Specialized SQL Structures](doc/html/userman/ssqls.html) feature didn’t work right out of the box due to a compiler limitation. A full discussion of the problem and possible workarounds is in [this mailing list message](http://lists.mysql.com/plusplus/4307).
problem and possible workarounds is in [this mailing list message](http://lists.mysql.com/plusplus/4307).

That was back in the Borland days, so if you’ve verified functionality under one of the newer Embarcadero releases, we’d appreciate a report on the mailing list.


## <a name="hownottobuild"></a>`g++ simple1.cpp -o simple1`?

No!

See [Chapter 9, Using MySQL++ in Your Own Project](doc/html/userman/incorporating.html) in the [MySQL++ User Manual](doc/html/userman/) for more on this.


## <a name="memleak"></a>Why is my program leaking memory?

The current version of MySQL++ has no known memory leaks. If you free all of the MySQL++ objects you allocate, it should not be leaking memory.

If you’re getting a report from a memory debugger about a leak, most
If you’re getting a report from a memory debugger about a leak, most likely you’re seeing memory that the MySQL C API library allocates for its own internal purposes. MySQL++ is built atop this library, so it can look like it’s MySQL++ leaking the memory. This underlying C library automatically allocates multiple blocks of memory in ways that are more or less outside MySQL++’s control. If you feel you must plug these leaks, it is up to your code to call the relevant C API functions.
likely you’re seeing memory that the MySQL C API library allocates for
its own internal purposes. MySQL++ is built atop this library, so it can
look like it’s MySQL++ leaking the memory. This underlying C library
automatically allocates multiple blocks of memory in ways that are more
or less outside MySQL++’s control. If you feel you must plug these
leaks, it is up to your code to call the relevant C API functions.

These “leaks” are all harmless in practice for most programs. A typical
These “leaks” are all harmless in practice for most programs. A typical program using MySQL++ needs database access for its entire effective run time, and the size of the leak doesn’t increase over run time if you follow the instructions in the [threads
program using MySQL++ needs database access for its entire effective run
time, and the size of the leak doesn’t increase over run time if you
follow the instructions in the [threads
chapter](doc/html/userman/threads.html) of the [User
chapter](doc/html/userman/threads.html) of the [User Manual](doc/html/userman/). The OS automatically frees this memory when
Manual](doc/html/userman/). The OS automatically frees this memory when
your program exits.

That said, it’s annoying to see leak reports in a memory debugger,
That said, it’s annoying to see leak reports in a memory debugger, particularly if leak checking is a regular part of your build and test process. You can placate the memory debugger by calling `Connection::thread_end()` from each thread that uses a database
particularly if leak checking is a regular part of your build and test
process. You can placate the memory debugger by calling
`Connection::thread_end()` from each thread that uses a database
connection when that thread finishes using the database. In addition,
connection when that thread finishes using the database. In addition, after the last bit of code that uses MySQL++ stops, you need to call the MySQL C API function `mysql_library_end()`. If you’re using a `ConnectionPool`, you might put this last call in the destructor, since the pool object is typically the last MySQL++ object to be destroyed.
after the last bit of code that uses MySQL++ stops, you need to call the
MySQL C API function `mysql_library_end()`. If you’re using a
`ConnectionPool`, you might put this last call in the destructor, since
the pool object is typically the last MySQL++ object to be destroyed.

If you’ve done that and still think you really have a serious memory
If you’ve done that and still think you really have a serious memory leak — one of those “the longer it runs, the more memory it uses” sorts of leak — you need to tie it to some unit of work. Does memory go up as a function of time? number of queries issued? count of rows retreived? Until you can establish this link, it’s premature to post to the MySQL++ mailing list claiming there’s a leak in MySQL++. Even if you can establish such a link, it’s far more likely that you’re not releasing the MySQL++ objects you allocate than MySQL++ itself failing to release memory.
leak — one of those “the longer it runs, the more memory it uses” sorts
of leak — you need to tie it to some unit of work. Does memory go up as
a function of time? number of queries issued? count of rows retreived?
Until you can establish this link, it’s premature to post to the MySQL++
mailing list claiming there’s a leak in MySQL++. Even if you can
establish such a link, it’s far more likely that you’re not releasing
the MySQL++ objects you allocate than MySQL++ itself failing to release
memory.


## <a name="segfaults"></a>My program is crashing. Help!

The most common cause of crashes in MySQL++ is uncaught exceptions. The library throws exceptions when it detects errors, such as invalid SQL syntax, invalid login parameters, etc. Try running the example programs, since they all catch exceptions properly.

If the examples also crash and you’re using a package built for a
If the examples also crash and you’re using a package built for a different Linux distribution than the one you’re actually running, try rebuilding the package from [source](#source) on the target OS. A binary package is fairly closely tied to the system it is built under, so it’s possible that RPMs you build on your system will work better than those built elsewhere.
different Linux distribution than the one you’re actually running, try
rebuilding the package from [source](#source) on the target OS. A binary
package is fairly closely tied to the system it is built under, so it’s
possible that RPMs you build on your system will work better than those
built elsewhere.


## <a name="broken"></a>Nothing’s working at all! Is it broken?

Maybe, but have you tried running the examples? Follow the instructions in the `README-examples.txt` file. If the examples work but your program doesn’t, chances are good that the error is in your program; study the examples, and [read the manuals](/wiki?name=Documentation). If the examples also fail to work, post to the mailing list with a detailed failure report.