MySQL++

MySQL++ is a C++ wrapper for MySQL’s C API. It is built around STL principles, to make dealing with the database as easy as dealing with an STL container. MySQL++ relieves the programmer of dealing with cumbersome C data structures, generation of repetitive SQL statements, and manual creation of C++ data structures to mirror the database schema.

If you have any questions about this project, do not email us about it unless the question is inherently personal. Search for solutions on the MySQL++ mailing list first, and post to that list if you can’t find the answer you need. 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.2.tar.gz (1.7 MB, 2008.04.27) — Library source code. If you aren’t sure which file to download, download this.

mysql++-3.0.2-1.src.rpm (1.7 MB, 2008.04.13) — 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.2-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:

use a different distribution of Linux, or
use a different compiler than the one that came with the OS, or
use a different version of MySQL, or
need thread support

...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.2-1.el3.i386.rpm (168 KB, 2008.04.13) — the library itself (libmysqlpp.so*)
mysql++-devel-3.0.2-1.el3.i386.rpm (174 KB, 2008.04.13) — 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.2-1.el4.i386.rpm (164 KB, 2008.04.13) — the library itself (libmysqlpp.so*)
mysql++-devel-3.0.2-1.el4.i386.rpm (175 KB, 2008.04.13) — corresponding development and example files

CentOS 5

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

mysql++-3.0.2-1.el5.i386.rpm (158 KB, 2008.04.13) — the library itself (libmysqlpp.so*)
mysql++-devel-3.0.2-1.el5.i386.rpm (183 KB, 2008.04.13) — corresponding development and example files

Old Versions

mysql++-2.3.2.tar.gz (1.6 MB, 2007.07.11) — 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, 2005.05.26) — 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, 2001.05.01) — 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.01) — 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.2-1.i386.rpm (2.2 MB, 2008.04.13)), 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 software license does MySQL++ use? Is it free?

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

How do MySQL++ version numbers work?

A change in the first number denotes major changes to the library that will almost certainly require changes in your program. The user manual covers these changes in the “Incompatible Library Changes” chapter.

A change in the second number means added features that shouldn’t break your program, but you should check anyway.

A change in the final number should be transparent, as it’s only for internal bug fixes.

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 versions of GCC will it build under?

Any GCC from 3.0 onwards should be able to build current versions of MySQL++, except on MinGW, which requires 3.4.5.

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.

MySQL++ builds most easily against the official OS X build of MySQL. With it installed, the MySQL++ Makefiles and project files should find the headers and libraries automatically.

You can also use the current version of MySQL from the Fink project: say fink install mysql15-dev. If you use this version of MySQL, you need to give the --with-mysql=/sw flag to MySQL++’s configure script so that it will find the MySQL headers and libraries.

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.

Will it build under Solaris?

We’ve seen reports from people successfully building it on versions going back to Solaris 8. It may or may not work with Sun’s own C++ compiler; if you find that it doesn’t, try GCC before sending a bug report to the mailing list.

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 fixed-size per-thread memory allocated by the MySQL C API library that MySQL++ is built atop. The MySQL C API library allocates one of these blocks upon making the first connection from a thread. 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.

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