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.


## What platforms does it work on?

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.

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.
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 [forum], 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 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.
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 or a patch to the [forum]. We will support any platform that gets enough interest from the users.


[forum]: /forum
## What versions of MySQL does it work with?

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.

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
that MySQL++ isn’t building against a newer release of MySQL, a short [bug report](/#bugreport) is usually sufficient to get it fixed.

With some work, MySQL++ may be modified to work on 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.


## What versions of MySQL/MariaDB does it work with?

We do most of the development against whatever our current favorite Linux distros and Homebrew are shipping as the MariaDB package at the time of our release.

We may sometimes also incidentally test against an older version, as when checking OS compatibility and using the platform-provided MariaDB package. This isn't formal testing, however.

We’re not opposed to supporting other versions or MySQL++ or MariaDB; we just don’t build test environments for these newer versions in advance of need. If you find that MySQL++ doesn't build or run against your C API library, a short [bug report](/#bugreport) is usually sufficient to get it fixed.


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

MySQL++ is free software, licensed under the [GNU 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?

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

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.


## <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 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
[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 MySQL for several years, then got spun back out again, this time probably for good. Oracle still hosts our [old mailing list](http://lists.mysql.com/plusplus/), which is still useful as an archive of answered questions, for which we thank them, but they don’t control the hosting or development of MySQL++.
MySQL for several years, then got spun back out again, this time probably for good. MySQL does still host our [mailing
list](http://lists.mysql.com/plusplus/), for which we thank them, but they don’t control the hosting or development of MySQL++ any more.

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.
Before Sun (and then Oracle) bought them, MySQL AB decided to create a competing library despite once having controlled MySQL++ in-house 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, they wanted to put MySQL support into OpenOffice, and they wanted it to have a [JDBC](http://en.wikipedia.org/wiki/Jdbc) style API.

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++.

Another way to look at it is that Connector/C++ is new and therefore perhaps less crufty, while MySQL++ is mature and featureful.
Another way to look at it is that Connector/C++ because is newer, it is 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 old version of MySQL++. 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, MySQL++ should work on GCC 2.95 again.

MySQL++ ships with project files for Visual C++ 2005 and 2008. The latter can be converted using Visual C++ 2010 or later, but may require some manual adjustment. For example, when Visual C++ 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.

We’d like to ship newer project files, but the [tool that generates them](http://bakefile.org/) can’t do that yet.

If you're still on an older version of Visual C++ than 2005, we strongly urge you to upgrade. Those old versions are seriously deficient in terms of Standard C++ support, even at the rather modest level required by MySQL++.

Under Satya Nadella, Microsoft has apparently finally given up on trying to arm-twist developers into buying premium tools to support their platform, evidenced by the fact that [Visual Studio
Under Satya Nadella, Microsoft has apparently finally given up on trying to arm-twist developers into buying premium tools to support their platform, evidenced by the fact that [Visual Studio Community](https://www.visualstudio.com/vs/community/) now contains all the features you used to have to pay to get in Visual C++ Professional. This Community edition is perfectly suitable for use in building MySQL++ and programs linked to it. Indeed, this is the only version the MySQL++ maintainer tests the library against regularly now.
Community](https://www.visualstudio.com/vs/community/) now contains all the features you used to have to pay to get in Visual C++ Professional. This Community edition is perfectly suitable for use in building MySQL++ and programs linked to it. Indeed, this is the only version the MySQL++ maintainer tests the library against regularly now.


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

Yes. See [the `README-Mac-OS-X.txt` file](/doc/trunk/README-Mac-OS-X.txt).
Yes. See [the `README-macOS.txt` file](/doc/trunk/README-macOS.txt).

You can build it on the command line using the typical Unix build methods (see [README-Unix.txt](/doc/trunk/README-Unix.txt)) or from within Xcode using the included Xcode project files.
It's best to build it on the command line using the typical Unix build methods (see [README-Unix.txt](/doc/trunk/README-Unix.txt)) rather than from the included Xcode project files.

Command line builds are tested more often than Xcode builds. We've successfully built it on every major release of Mac OS X going back to 10.3, and still occasionally test it on the latest release of macOS this way.
We've successfully built versions of MySQL++ on every major release of Mac OS X going back to 10.3, and still test each release on recent versions of macOS. (Usually the latest major release, sometimes the one just prior, and sometimes both.)

You can build MySQL++ on macOS against either [Connector/C](https://dev.mysql.com/downloads/connector/c/) or against related libraries like the `libmysqlclient` you can get with the [Homebrew](https://brew.sh/) `mariadb` package.


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

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

You’re probably missing a `-I` flag for the MySQL++ headers, and you’re certainly missing [correct link flags](#linkerrors).

The user manual has a [section](doc/html/userman/incorporating.html#inc-unix) that describes how to build a program based on MySQL++.


## <a name="linkerrors"></a>It compiles, but it won’t link! Why?

To build any program using MySQL++, at minimum you must link to the MySQL++ library and also to the MySQL C API library that MySQL++ is built upon. The MySQL++ library is `libmysqlpp.so` on Unixy systems, and `mysqlpp.lib` on Windows. The MySQL C API library is either `libmysqlclient{_r}.{a,so}` on Unixy systems and `libmysql.lib` on
Windows.
To build any program using MySQL++, at minimum you must link to the MySQL++ library and also to the database's C API library, which MySQL++ is built upon. The MySQL++ library is `libmysqlpp.so` on Unixy systems, and `mysqlpp.lib` on Windows. The C API library may be called:

* `libmysqlclient{_r}.{a,so}` on Unixy systems for MySQL++
* `libmariadb{client}.{a,so}` on Unixy systems for MariaDB
* `libmysql.lib` on Windows

**Visual C++**: An additional requirement with Visual C++ is that you must link to the same C Run-Time Library (RTL) for all modules throughout your project. The Visual C++ project files that come with MySQL++ use the multithreaded DLL version (`/MD` or `/MDd`) of the C RTL. If you link MySQL++ to a program or additional third party library
**Visual C++**: An additional requirement with Visual C++ is that you must link to the same C Run-Time Library (RTL) for all modules throughout your project. The Visual C++ project files that come with MySQL++ use the multithreaded DLL version (`/MD` or `/MDd`) of the C RTL. If you link MySQL++ to a program or additional third party library that uses a different RTL, you will get link errors. Study the example projects’ settings to see how this is done. The instructions in the `README-Visual-C++.txt` file may also be helpful.
that uses a different RTL, you will get link errors. Study the example projects’ settings to see how this is done. The instructions in the `README-Visual-C++.txt` file may also be helpful.

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 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 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
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 chapter](doc/html/userman/threads.html) of the [User Manual](doc/html/userman/). The OS automatically frees this memory when your program exits.
chapter](doc/html/userman/threads.html) of the [User 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, 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, 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.
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.

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.
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 retrieved? 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 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.


## <a name="bugreport"></a>I’m sure I’ve found a bug. How do I submit a report?

We’ll want some code that demonstrates the bug. No doubt you’d rather not send us a copy of your database to demonstrate the problem, and to be frank, we don’t want your database, either. The best thing is to modify one of the MySQL++ examples so that it reproduces the problem you’re seeing. This lets the people that can help you reproduce the problem on their machines, without needing your database.

Once you have your problem boiled down to a simple example, send the source code to the mailing list along with a detailed report. We want to know what you expect the program to do, and what it actually does on your machine. Keep in mind, programs often behave differently on different systems. As a programmer yourself, you know what it is like to
Once you have your problem boiled down to a simple example, send the source code to the mailing list along with a detailed report. We want to know what you expect the program to do, and what it actually does on your machine. Keep in mind, programs often behave differently on different systems. As a programmer yourself, you know what it is like to deal with vague user bug reports. Give us the sort of error report you’d like to receive for your own programs.
deal with vague user bug reports. Give us the sort of error report you’d like to receive for your own programs.

There's also the [ticket tracker](/ticket), but we prefer that you send the report to the mailing list for discussion first. Especially do not use the ticket tracker if you just need help *using* MySQL++.


## <a name="patches"></a>How do I submit a change to MySQL++?

This is covered in detail in the library's [hacker's guide](/doc/trunk/HACKERS.md).

But in brief: we want the patch in unified diff format, made against either the latest release of MySQL++ or (preferably) against [the trunk of the Fossil repository](/timeline?r=trunk). You can send it either to the [mailing list](http://lists.mysql.com/plusplus/), or to [the ticket tracker](/ticket). We prefer that you only use the ticket tracker for patches that are so trivial or obvious that they won’t need discussion.

When a patch is rejected, the most common reason is that it breaks the library’s binary interface (ABI), so that an old program can’t link to the changed library without recompiling. We only make such changes at major version transitions. These transitions are rare, and we can’t even promise that there will ever be another one, much less when it will occur. If you have a choice of two ways to get your desired effect and one of them doesn’t break the ABI, it will increase the chances that we accept your patch if you do it that way.

<p style="height: 50em">&nbsp;</p>