MySQL++

MySQL++ rocks

MySQL++ is a C++ wrapper for MySQL’s C API. It is built around the same principles as the Standard C++ Library, to make dealing with the database as easy as dealing with STL containers. In addition, MySQL++ provides facilities that let you avoid the most repetitive sorts of SQL within your own code, providing native C++ interfaces for these common tasks.

If you have any questions about this project, do not email us about it unless the question is inherently personal. The documentation answers most questions, and the mail list archives are a treasure trove of information:

If you can’t find an answer in the documentation or the list archives, ask on the list. Everyone active in MySQL++’s development monitors that mailing list, and the library’s primary maintainer responds to almost every question posted there. By posting to the mailing list, your question and any answers are archived for future developers to find, and you reach a wider audience than is possible with personal email.

Latest Stable Version

Before upgrading an existing version of MySQL++, please scan through the change log first. If you’re coming from a much older version, better read through the “Incompatible Library Changes” chapter in the user manual instead.

Source Code

mysql++-3.2.1.tar.gz (2.2 MB, 2013.12.10) — Library source code. If you aren’t sure which file to download, download this.

mysql++-3.2.1-1.src.rpm (2.1 MB, 2013.12.10) — Source RPM, for those that need to build their own binary RPMs. To do this, run this command as root:

# rpmbuild --rebuild /wherever/it/is/mysql++-3.2.1-1.src.rpm

The resulting mysql++, mysql++-devel and mysql++-manuals RPMs will be in a distribution-dependent directory, typically somewhere under /usr/src.

Linux Binary Packages

MySQL++ has been picked up by many package distros. It’s been spotted in the Debian, Fedora, FreeBSD, Gentoo, Homebrew, RHEL (EPEL), and Ubuntu package systems.

You can find old CentOS RPMs here. I stopped publishing new ones after EPEL picked the package up, since theirs are better integrated into the stock CentOS/RHEL system than mine.

RPMs are fairly closely tied to the system they were built on. You can use someone else’s binary RPMs freely as long as you:

  1. use the same distribution of Linux, and
  2. use the same compiler that built the MySQL++ RPM, and
  3. use the same version of MySQL, and
  4. build your program with the same threading options as was chosen when building that RPM

If any of these things differ, you must build MySQL++ from source, or else you will have problems.

Old Versions

These old versions are provided for people who cannot or will not upgrade their source code to work with the current version. MySQL++ has had assorted API and ABI breakages over the years, so there can be good reasons for sticking with an old version.

mysql++-3.1.0.tar.gz (1.9 MB, 2010.06.03) — This was the only version in the 3.1.x line. It is remarkable only in that it was the current release for a 3-year span. MySQL++ 3.2.x is both ABI and API-compatible with 3.1.0, so there is little reason to insist on using this particular version.

mysql++-3.0.9.tar.gz (2.6 MB, 2009.02.04) — This is the last version in the 3.0.x line. It has a slightly different ABI from 3.1.0.

mysql++-2.3.2.tar.gz (1.6 MB, 2007.07.11) — This is the last version in the 2.x line. The change to 3.x was fairly traumatic for some code bases, so it is understandable if you still must use this version.

mysql++-1.7.40.tar.gz (1.7 MB, 2005.05.26) — This is the last version in the 1.x line. This is really old, and known to be really broken in some ways. If your code can’t be upgraded any further than this, you might want to reexamine your priorities. :)

mysql++-1.7.9.tar.gz (731 KB, 2001.05.01) — This is the last version Sinisa Milivojevic maintained. This version is significant because it was the only “official” version for over three years. As a result, there are many patches floating around on the Internet that apply to this version of the library. Also, it is the last version of the library known to work on GCC 2.95.x without changes.

mysql++-1.7.1-win32-vc++.zip (786 KB, 2000.05.17) — Ancient version for Visual C++ 6.0. Use this only if you absolutely, positively cannot upgrade to Visual C++ 2003 or newer. It is known to have bugs, and there is almost no chance they will ever be fixed. The path forward is to switch to a newer compiler; see below for information on obtaining a free version of Visual C++ 2013!

All files — This is simply a link to the raw directory view. There are old versions of the source code going back to 0.64, old binaries, etc.

Documentation

The user and reference manuals are shipped in the source code tarball above. They are also available online.

Contributing to the Effort

The easiest thing to do if you want to help out with the MySQL++ development effort is to participate on the mailing list. We could use help answering questions, and it’s frequently helpful to have different voices contributing to discussions about the library’s future.

If you want to participate in the coding effort, the MySQL++ development project is hosted here, courtesy of Gna! They host the MySQL++ Subversion repository, which holds the version history going back to version 1.7.9. The HACKERS.txt file included with the MySQL++ sources contains further instructions; please read it before making changes to the library. For a great source of projects to tackle, see the Wishlist file. There’s a copy distributed with MySQL++, but the repository version may be more current. You wouldn’t want to go to the effort of creating a patch, only to find that someone had already checked in a change for that item!

If you just want to keep up on the in-progress developments, you can sign up for the mysqlpp-commits mailing list on our Gna! project page. This mails you all of the Subversion commit messages. Between that and the regular mailing list traffic, you will know as much about MySQL++’s development as anyone save the people actually working on it. :)

FAQs

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, at least not in a single step. You might want to upgrade to an intermediate version 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 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” 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 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 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 early in the 3.x series before settling down.

What platforms does it work on?

MySQL++ should work on any platform that has a Standard C++ compiler and the MySQL C API development files. The code does use some C99/TR1 features that are widely supported in advance of full standardization, but these are optional.

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 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 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 is the oldest version that it’s regularly tested against during development.

We do most of the development against MySQL 5.1, since this is the version we still 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, 5.6 as of this writing. 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 is usually sufficient to get it fixed.

It probably builds fine 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, or give you features like UTF-8 aware sorting.

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_*. (It’s a fairly invasive change, which is the only reason the library doesn’t come with this change already.) Also, the UTF-8 comments above apply equally to older versions of MySQL.

Does it build against MariaDB?

Sorry, no idea. We haven’t tried it yet.

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

There’s no practical way of avoiding this. 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. 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 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.

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, MySQL, Inc. will happily sell you a commercial distribution license 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 MySQL, Inc. Having settled that, the previous FAQ item applies.

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

Connector/C++ is a new C++ wrapper for the MySQL C API library, fully developed under the MySQL corporate aegis. By contrast, MySQL++ has a long, complex development 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. MySQL does still host our mailing list, 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 style API for that support.

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.

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

Will it build under Visual C++?

Yes, it works out of the box with Visual C++ 2005 and 2008.

MySQL++ also works fine with Visual C++ 2010, 2012, and 2013, 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.

MySQL++ mostly works with Visual C++ 2003. The main exception is the Specialized SQL Structures 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 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 of MySQL++. This is a third-party contribution which is known to have bugs. You might be better off using Connector/C instead.

The library’s primary maintainer only uses MySQL++ seriously on Linux, OS X and FreeBSD systems, and let his MSDN membership lapse years ago. Consequently, he only tests MySQL++ occasionally under the current version of Visual C++ Express. 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 consider upgrading as the compliance of the compiler has improved greatly. Microsoft is giving away a limited but functional version of Visual C++ 2013 which works just fine with MySQL++. (You want the Express 2013 for Windows Desktop version.)

The main practical limitation of VC++ Express — relative to the Professional edition — is that the Express version doesn’t include MFC. If you need to build GUI programs using only Standard C++, we recommend the free wxWidgets library as a capable MFC substitute. If you don’t mind stepping into the .NET world, there is explicit support for C++/CLI in MySQL++ now, including a Windows Forms based example program.

(Microsoft attemted to kill the VC++-for-Desktop product with the 2012 release, but relented when the community yelled that it wasn’t going to tolerate a Metro-only Express version of Visual C++. Here’s hoping they continue offering this.)

Will it build on Mac OS X?

Yes, it builds just fine, both from within the Xcode environment and at the command line. We currently test only on OS X 10.8 and up. The Xcode project files should 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 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 for OS X, which MySQL++ builds against.

Will it build under Cygwin?

Yes, but beware of Cygwin’s licensing: any program linked to cygwin1.dll is subject to the GPL, unless you’ve purchased ($$) a commercial license for Cygwin from Red Hat. If that’s not a problem for you, see the README-Cygwin.txt file.

If you are making a closed-source program, we recommend using Visual C++ or MinGW instead.

Will it build under MinGW?

Yes. You want to be using the current version, because there are important bugs fixed in recent versions that prevent the current version of MySQL++ from building or working correctly.

Will it build under Solaris?

Yes, 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. I’ve personally only built it with GCC under OpenSolaris 2008.05 and 2008.11.

Just use the built-in package manager to install MySQL 5.0 and GCC, and you’re set. Beware, 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.

Will it build under Borland C++ Builder?

It can be made to work, mostly.

The only major feature that doesn’t work out of the box is the Specialized SQL Structures. It can’t work as-is due to a compiler limitation. A full discussion of the problem and possible workarounds is in this mailing list message.

Fixes and further support are unlikely, as it seems that this is a dead product now.

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

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. 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 chapter of the User Manual. 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.

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.

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 someone else’s binary RPMs, try rebuilding the RPMs from the source RPM. A binary RPM 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 mailing list 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 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 programs.

How do I submit a change to MySQL++?

This is covered in detail in the HACKERS.txt file that accompanied MySQL++.

But in brief: we want the patch in unified diff format, made against either the latest release of MySQL++ or (preferrably) against the svn repository. You can send it either to the mailing list, or to the bug tracker. We prefer that you only use the bug 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.

This space intentionally left blank. :)


  Go to my home page