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.

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 in a single step. You might upgrade to an intermediate version first 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 change in the library’s major version number denotes changes that will almost certainly require source code changes in your program. 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 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, but we do document the cases where it occurs in the “Incompatible Library Changes” chapter of the user manual.

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 optionally use some C++11 and C++14 features, but their presence is either autodetected at build time, or you have to go out of your way to enable them.

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.

If your platform isn’t explicitly addressed in the FAQ items below and it’s outside the mainstream or it's older than about ten years, the chance of MySQL++ working out of the box drops. 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 or a patch to the forum. We will support any platform that gets enough interest from the users.

If you find that MySQL++ doesn't build or run on your system, and there was a working port to a prior version of that platform, a short bug report is usually sufficient to get the regression fixed.

Does it build against MariaDB?

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 OSes are shipping as the MariaDB package at the time of our release. It will no longer build against versions of MySQL older than 4.1 due to changes in their C API.

If you find a regression in a newer version of MySQL, either send the build output showing it or tell us how we can cause the examples to show the same behavior.

What software license does MySQL++ use? Is it free?

MySQL++ is free software, licensed under the GNU LGPL.

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 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 the LGPL. If you distribute those binaries outside your organization, those receiving them have a right under the LGPL to relink your program to any version of MySQL++ they wish, which in practice is best done with dynamic linkage.

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.

If you can’t accommodate the LGPL's licensing terms, 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.

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.

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

How does MySQL++ compare to MySQL’s Connector/C++?

MySQL++ has a long, complex development history. It started out as a third-party library, was maintained and enhanced by MySQL AB for several years, then got spun back out again, this time probably for good. All of this happened before Sun bought MySQL. Oracle — who later bought Sun — still hosts our old mailing list, a useful archive of answered questions, for which we thank them, but they've never been involved in the hosting or development of MySQL++ proper.

Though it is now mature, Connector/C++ was started many years after MySQL AB abandoned maintainership of MySQL++. It was initially developed under Sun, and as such, it was in part an effort to produce a more JDBC-like API for MySQL. Because they developed Connector/C++ fully under the MySQL corporate aegis, they were then able to do the same dual-licensing thing they do with the C API library.

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

Will it build under GCC?

Yes, with GCC version 3.0 and up, except on 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.

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.

Will it build on Linux?

Yes; this is MySQL++’s primary platform. See the README-Linux.txt file.

Will it build on the BSDs or other “real” Unices?

Yes. See the README-Unix.txt file.

The BSDs behave mostly the same as Linux for the purposes of building MySQL++.

If you're building on Solaris, see the README-Solaris.txt file for some platform-specific details. We have reports of people building it successfully on versions as old as Solaris 8. It gets the most testing with GCC, but we have heard occasional success reports from people using Sun CC.

Will it build under Visual C++?

Yes. See the README-Visual-C++.txt file.

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 can’t do that yet.

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

Will it build on macOS?

Yes. See the README-macOS.txt file.

It's best to build it on the command line using the typical Unix build methods (see README-Unix.txt) rather than from the included Xcode project files.

We've successfully built versions of MySQL++ on every major release of Mac OS X going back to 10.3, and we still test each release on either the most recent version of macOS, the prior major version, or both.

You can build MySQL++ on macOS against either Connector/C or against related libraries like the libmysqlclient you can get with the Homebrew mariadb package.

Will it build under Cygwin?

Yes. See the README-Cygwin.txt file.

Will it build under MinGW?

Yes. See the README-MinGW.txt file.

Occasionally a version of MinGW comes out that breaks MySQL++, but there has always been a usable workaround.

g++ simple1.cpp -o simple1?

No!

You’re probably missing a -I flag for the MySQL++ headers, and you’re certainly missing correct link flags.

The user manual has a section that describes how to build a program based on MySQL++.

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 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 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 in the MySQL++ User Manual for more on this.

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. Since MySQL++ is built atop this library, 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 to free them.

Before embarking on this quest, realize that these “leaks” are all harmless in practice for most programs. So long as you aren't abusing the APIs, these "leaks" are fixed-size, not changing as the program runs. If your program is typical in that it needs database access for its entire effective run time, the only thing you're fixing with this is to explicitly release memory that was in active use until moments before your program closed the database connection and exited. The OS was going to do that anyway; you're actually slowing your program's exit to no practical effect by taking time to explicitly free this memory first.

That said, I get it: 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.

If you’ve done all 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++ forum 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.

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

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. If the examples also fail to work, post to the forum with a detailed failure report.

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

There's also the ticket tracker, but we prefer that you send the report to the forum for discussion first. Especially do not use the ticket tracker if you just need help using MySQL++.

How do I submit a change to MySQL++?

This is covered in detail in the library's contribution guide.

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. You can send it either to the forum or to the ticket tracker. 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.