MySQL++ v3.2.0 User Manual

Kevin Atkinson

Sinisa Milivojevic

Monty Widenius

Warren Young

June 20, 2013

Table of Contents

1. Introduction
1.1. A Brief History of MySQL++
1.2. If You Have Questions...
2. Overview
2.1. The Connection Object
2.2. The Query Object
2.3. Result Sets
2.4. Exceptions
3. Tutorial
3.1. Running the Examples
3.2. A Simple Example
3.3. A More Complicated Example
3.4. Exceptions
3.5. Quoting and Escaping
3.6. C++ vs. SQL Data Types
3.7. Handling SQL Nulls
3.8. MySQL++’s Special String Types
3.9. Dealing with Binary Data
3.10. Using Transactions
3.11. Which Query Type to Use?
3.12. Conditional Result Row Handling
3.13. Executing Code for Each Row In a Result Set
3.14. Connection Options
3.15. Dealing with Connection Timeouts
3.16. Concurrent Queries on a Connection
3.17. Getting Field Meta-Information
4. Template Queries
4.1. Setting up Template Queries
4.2. Setting the Parameters at Execution Time
4.3. Default Parameters
4.4. Error Handling
5. Specialized SQL Structures
5.1. sql_create
5.2. SSQLS Comparison and Initialization
5.3. Retrieving data
5.4. Adding data
5.5. Modifying data
5.6. Storing SSQLSes in Associative Containers
5.7. Changing the Table Name
5.8. Using an SSQLS in Multiple Modules
5.9. Harnessing SSQLS Internals
5.10. Having Different Field Names in C++ and SQL
5.11. Expanding SSQLS Macros
5.12. Customizing the SSQLS Mechanism
5.13. Deriving from an SSQLS
5.14. SSQLS and BLOB Columns
5.15. SSQLS and Visual C++ 2003
6. Using Unicode with MySQL++
6.1. A Short History of Unicode
6.2. Unicode on Unixy Systems
6.3. Unicode on Windows
6.4. For More Information
7. Using MySQL++ in a Multithreaded Program
7.1. Build Issues
7.2. Connection Management
7.3. Helper Functions
7.4. Sharing MySQL++ Data Structures
8. Configuring MySQL++
8.1. The Location of the MySQL Development Files
8.2. The Maximum Number of Fields Allowed
8.3. Buried MySQL C API Headers
8.4. Building MySQL++ on Systems Without Complete C99 Support
9. Using MySQL++ in Your Own Project
9.1. Visual C++
9.2. Unixy Platforms: Linux, *BSD, OS X, Cygwin, Solaris...
9.3. OS X
9.4. MinGW
9.5. Eclipse
10. Incompatible Library Changes
10.1. API Changes
10.2. ABI Changes
11. Licensing
11.1. GNU Lesser General Public License
11.2. MySQL++ User Manual License

1. Introduction

MySQL++ is a powerful C++ wrapper for MySQL’s C API[1]. Its purpose is to make working with queries as easy as working with STL containers.

The latest version of MySQL++ can be found at the official web site.

Support for MySQL++ can be had on the mailing list. That page hosts the mailing list archives, and tells you how you can subscribe.

1.1. A Brief History of MySQL++

MySQL++ was created in 1998 by Kevin Atkinson. It started out MySQL-specific, but there were early efforts to try and make it database-independent, and call it SQL++. This is where the old library name “sqlplus” came from. This is also why the old versions prefixed some class names with “Mysql” but not others: the others were supposed to be the database-independent parts. All of Kevin’s releases had pre-1.0 version numbers.

Then in 1999, MySQL AB took over development of the library. In the beginning, Monty Widenius himself did some of the work, but later gave it over to another MySQL employee, Sinisa Milivojevic. MySQL released versions 1.0 and 1.1, and then Kevin gave over maintenance to Sinisa officially with 1.2, and ceased to have any involvement with the library’s maintenance. Sinisa went on to maintain the library through 1.7.9, released in mid-2001. It seems to be during this time that the dream of multiple-database compatibility died, for obvious reasons.

With version 1.7.9, MySQL++ went into a period of stasis, lasting over three years. (Perhaps it was the ennui and retrenchment following the collapse of the bubble that caused them to lose interest.) During this time, Sinisa ran the MySQL++ mailing list and supported its users, but made no new releases. Contributed patches were either ignored or put up on the MySQL++ web site for users to try, without any official blessing.

The biggest barrier to using MySQL++ during this period is that the popular C++ compilers of 2001 weren’t all that compatible with the C++ Standard. As a result, MySQL++ used many nonstandard constructs, to allow for compatibility with older compilers. Each new compiler released in the following years increased compliance, either warning about or rejecting code using pre-Standard constructs. In particular, GCC was emerging from the mess following the EGCS fork during this time. The fork was healed officially in 1999, but there’s always a delay of a few years between the release of a new GCC and widespread adoption. The post-EGCS versions of GCC were only beginning to become popular by 2001, when development on MySQL++ halted. As a result, it became increasingly difficult to get MySQL++ to build cleanly as newer compilers came out. Since MySQL++ uses templates heavily, this affected end user programs as well: MySQL++ code got included directly in your program, so any warnings or errors it caused became your program’s problem.

As a result, most of the patches contributed to the MySQL++ project during this period were to fix up standards compliance issues. Because no one was bothering to officially test and bless these patches, you ended up with the worst aspects of a bazaar development model: complete freedom of development, but no guiding hand to select from the good stuff and reject the rest. Many of the patches were mutually incompatible. Some would build upon other patches, so you had to apply them in the proper sequence. Others did useful things, but didn’t give a fully functional copy of MySQL++. Figuring out which patch(es) to use was an increasingly frustrating exercise as the years wore on, and newer GCCs became popular.

In early August of 2004, Warren Young got fed up with this situation and took over. He released 1.7.10 later that month, which did little more than make the code build with GCC 3.3 without warnings. Since then, with a little help from his friends on the Net, MySQL++ has lost a lot of bugs, gained a lot of features, gained a few more bugs, lost them again... MySQL++ is alive and healthy now.

1.2. If You Have Questions...

If you want to email someone to ask questions about this library, we greatly prefer that you send mail to the MySQL++ mailing list. The mailing list is archived, so if you have questions, do a search to see if the question has been asked before.

You may find people’s individual email addresses in various files within the MySQL++ distribution. Please do not send mail to them unless you are sending something that is inherently personal. Not all of the principal developers of MySQL++ are still active in its development; those who have dropped out have no wish to be bugged about MySQL++. Those of us still active in MySQL++ development monitor the mailing list, so you aren’t getting any extra “coverage” by sending messages to additional email addresses.

[1] The MySQL C API is also known as Connector/C.