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.0.9.tar.gz (2.6 MB, 2009.02.04) — Library source code. If you aren’t sure which file to download, download this.

mysql++-3.0.9-1.src.rpm (2.6 MB, 2009.02.04) — 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.0.9-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 RPMs

These RPMs are fairly closely tied to the system they were built on. This means that if you:

...then you must build from source, or else you will have problems.

CentOS 3

These are built on CentOS 3.9 with GCC 3.2.3, against the official MySQL 4.1 RPMs.

mysql++-3.0.9-1.el3.i386.rpm (171 KB, 2009.02.04) — the library itself (libmysqlpp.so*)
mysql++-devel-3.0.9-1.el3.i386.rpm (174 KB, 2009.02.04) — corresponding development and example files

CentOS 4

These are built on CentOS 4.6 with GCC 3.4.6, against the official MySQL 4.1 RPMs.

mysql++-3.0.9-1.el4.i386.rpm (168 KB, 2009.02.04) — the library itself (libmysqlpp.so*)
mysql++-devel-3.0.9-1.el4.i386.rpm (174 KB, 2009.02.04) — corresponding development and example files

CentOS 5

These are built on CentOS 5.2 with GCC 4.1.2, against the official MySQL 5.0 RPMs.

mysql++-3.0.9-1.el5.i386.rpm (163 KB, 2009.02.04) — the library itself (libmysqlpp.so*)
mysql++-devel-3.0.9-1.el5.i386.rpm (182 KB, 2009.02.04) — corresponding development and example files

Old Versions

mysql++-2.3.2.tar.gz (1.6 MB, 2008.09.22) — Last version in the 2.x line. Use this only if you have existing code that you don’t want to upgrade to the current version.

mysql++-1.7.40.tar.gz (1.7 MB, 2008.09.22) — Last version in the 1.x line. Use this only if you have existing code that you don’t want to upgrade to the current version.

mysql++-1.7.9.tar.gz (731 KB, 2008.09.22) — 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, 2008.09.22) — 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++ 2008!

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 can be downloaded either in RPM form (mysql++-manuals-3.0.9-1.i386.rpm (2.0 MB, 2009.02.04)), or as part of the source code tarball above.

The documentation is 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++ version numbers have three parts: major, minor, and bug-fix. 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 the version number discipline described above 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 the current “GA” release of MySQL, 5.0 as of this writing. Because MySQL++ is intended for use in production environments, we don’t test it against bleeding-edge versions of MySQL; we wait for the GA release. 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.

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 consideration is that Connector/C++ is new and therefore perhaps less crufty, while MySQL++ is mature and perhaps showing some age.

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

It also works with Visual C++ 2003, with the exception of the Specialized SQL Structures feature. 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 the MySQL C API instead.

If you’re not using the current version of Visual C++, you should really consider upgrading as the compliance of the compiler has improved a lot. Microsoft is giving away a limited but functional version of Visual C++ 2008 which works just fine with MySQL++. Microsoft says they’re going to continue offering this indefinitely, so as long as the limitations don’t impact you, there’s no reason not to use this version. The main limitation is that this 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.

Will it build on Mac OS X?

Yes, it builds just fine with the command line tools from the current version of Xcode for OS X 10.4 and 10.5. In the past, we successfully built it on 10.3, but since the Xcode tools are no longer available for download for this version of the OS, we can’t say whether it still builds.

As of MySQL++ 3.0, we also ship Xcode project files. No one has tested these so far — they’re output automatically by the same tool that generates all the other MySQL++ project files and Makefiles, so they may work, or they may not. If you try them, please send a message to the mailing list to say how it worked, good or bad.

Naturally, it builds without fuss against the official distribution of MySQL for OS X. It also builds easily against the Fink version of MySQL; say fink install mysql15-dev to install the development files. If you also want a local copy of the MySQL server on the system, make the command fink install mysql mysql15-dev. Unlike with past versions of MySQL++, the configure script finds either version of the library without any help from you. If you have both installed, it will find the official MySQL version first.

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. It does require at least GCC 3.4.5, however. Older versions don’t build MySQL++ correctly. Also, as of this writing, GCC 4 is still considered experimental on MinGW. We’ve had reports of GCC 4.x not handling MySQL++ exceptions properly on MinGW, for instance.
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! See the next item.

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.

For building the examples, it’s simplest to just use the Makefiles or project files appropriate to your platform. The standard Makefiles are a little too complex for learning, so if you’re on a Unixy platform and just want to learn how to build programs using MySQL++, study Makefile.simple. It’s a fairly bare-bones Makefile that should work out of the box on a standard GCC-based system, and can probably be ported to other toolchains without a whole lot of work.
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 the memory that the MySQL C API library allocates for housekeeping purposes. MySQL++ is built atop this library, so it can look like it’s MySQL++ leaking the memory. This underlying C library automatically allocates one block per thread using the database, plus one for the overall use of the library. There is no corresponding automatic memory cleanup (this is C++, after all), so a memory debugger naïvely calls it a “leak.” I characterize it like that because if your program is typical in that it keeps the database connection open for its entire run time, failing to free this overhead memory is harmless: the OS will release this memory when your program exits.

That said, it’s annoying to see these reports of leaked memory, particularly if you’re regularly running your program under a memory debugger. (Recent versions of Visual Studio do this for any program run in Debug mode, for example.) 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() to free the per-application block. 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 one of the binary RPMs above, try rebuilding the RPMs from the source RPM. The resulting 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 mine.

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