This chapter documents those library changes since the epochal 1.7.9 release that break end-user programs. You can dig this stuff out of the ChangeLog, but the ChangeLog focuses more on explaining and justifying the facets of each change, while this section focuses on how to migrate your code between these library versions.
Since pure additions do not break programs, those changes are still documented only in the ChangeLog.
This section documents files, functions, methods and classes that were removed or changed in an incompatible way. If your program uses the changed item, you will have to change something in your program to get it to compile after upgrading to each of these versions.
Removed Row::operator[]() overloads except the one for size_type, and added Row::lookup_by_name() to provide the "subscript by string" functionality. In practical terms, this change means that the row["field"] syntax no longer works; you must use the new lookup_by_name method instead.
Renamed the generated library on POSIX systems from libsqlplus to libmysqlpp.
Removed SQLQuery::operator=(), and the same for its Query subclass. Use the copy constructor instead, if you need to copy one query to another query object.
The library used to have two names for many core classes: a short one, such as Row and a longer one, MysqlRow. The library now uses the shorter names exclusively.
All symbols within MySQL++ are in the mysqlpp namespace now if you use the new mysql++.h header. If you use the older sqlplus.hh or mysql++.hh headers, these symbols are hoist up into the global namespace. The older headers cause the compiler to emit warnings if you use them, and they will go away someday.
Connection::create_db() and drop_db() return true on success. They returned false in v1.7.x! This change will only affect your code if you have exceptions disabled.
Renamed Connection::real_connect() to connect(), made several more of its parameters default, and removed the old connect() method, as it's now a strict subset of the new one. The only practical consequence is that if your program was using real_connect(), you will have to change it to connect().
Replaced Connection::read_option() with new set_option() mechanism. In addition to changing the name, programs using this function will have to use the new Connection::Option enumerated values, accept a true return value as meaning success instead of 0, and use the proper argument type. Regarding the latter, read_option() took a const char* argument, but because it was just a thin wrapper over the MySQL C API function mysql_options(), the actual value being pointed to could be any of several types. This new mechanism is properly type-safe.
Classes Connection, Query, Result, ResUse, and Row now derive from OptionalExceptions which gives these classes a common interface for disabling exceptions. In addition, almost all of the per-method exception-disabling flags were removed. The preferred method for disabling exceptions on these objects is to create an instance of the new NoExceptions class on the stack, which disables exceptions on an OptionalExceptions subclass as long as the NoExceptions instance is in scope. You can instead call disable_exceptions() on any of these objects, but if you only want them disabled temporarily, it's easy to forget to re-enable them later.
In the previous version of MySQL++, those classes that supported optional exceptions that could create instances of other such classes were supposed to pass this flag on to their children. That is, if you created a Connection object with exceptions enabled, and then asked it to create a Query object, the Query object also had exceptions disabled. The problem is, this didn't happen in all cases where it should have in v1.7. This bug is fixed in v2.0. If your program begins crashing due to uncaught exceptions after upgrading to v2.0, this is the most likely cause. The most expeditious fix in this situation is to use the new NoExceptions feature to return these code paths to the v1.7 behavior. A better fix is to rework your program to avoid or deal with the new exceptions.
All custom MySQL++ exceptions now derive from the new Exception interface. The practical upshot of this is that the variability between the various exception types has been eliminated. For instance, to get the error string, the BadQuery exception had a string member called error plus a method called what(). Both did the same thing, and the what() method is more common, so the error string was dropped from the interface. None of the example programs had to be changed to work with the new exceptions, so if your program handles MySQL++ exceptions the same way they do, your program won't need to change, either.
Renamed SQLQueryNEParams exception to BadParamCount to match style of other exception names.
Added BadOption, ConnectionFailed, DBSelectionFailed, EndOfResults, EndOfResultSets, LockFailed, and ObjectNotInitialized exception types, to fix overuse of BadQuery. Now the latter is used only for errors on query execution. If your program has a "catch-all" block taking a std::exception for each try block containing MySQL++ statements, you probably won't need to change your program. Otherwise, the new exceptions will likely show up as program crashes due to unhandled exceptions.
In previous versions, Connection had a querying interface similar to class Query's. These methods were intended only for Query's use; no example ever used this interface directly, so no end-user code is likely to be affected by this change.
A more likely problem arising from the above change is code that tests for query success by calling the Connection object's success() method or by casting it to bool. This will now give misleading results, because queries no longer go through the Connection object. Class Query has the same success-testing interface, so use it instead.
Query now derives from std::ostream instead of std::stringstream.
Renamed ResUse::mysql_result() to raw_result() so it's database server neutral.
Removed ResUse::eof(), as it wrapped the deprecated and unnecessary MySQL C API function mysql_eof(). See the simple3 and usequery examples to see the proper way to test for the end of a result set.
Removed "field name" form of Row::field_list(). It was pointless.
Row subscripting works more like v1.7.9: one can subscript a Row with a string (e.g. row["myfield"]), or with an integer (e.g. row[5]). lookup_by_name() was removed. Because row[0] is ambiguous (0 could mean the first field, or be a null pointer to const char*), there is now Row::at(), which can look up any field by index.
Where possible, all distributed Makefiles only build dynamic libraries. (Shared objects on most Unices, DLLs on Windows, etc.) Unless your program is licensed under the GPL or LGPL, you shouldn't have been using the static libraries from previous versions anyway.
Removed the backwards-compatibility headers sqlplus.hh and mysql++.hh. If you were still using these, you will have to change to mysql++.h, which will put all symbols in namespace mysqlpp.
Can no longer use arrow operator (->) on the iterators into the Fields, Result and Row containers.
This section documents those library changes that require you to rebuild your program so that it will link with the new library. Most of the items in the previous section are also ABI changes, but this section is only for those items that shouldn't require any code changes in your program.
If you were going to rebuild your program after installing the new library anyway, you can probably ignore this section.
Removed "reset query" parameters from several Query class members. This is not an API change, because the parameters were given default values, and the library would ignore any value other than the default. So, any program that tried to make them take another value wouldn't have worked anyway.
Some freestanding functions didn't get moved into namespace mysqlpp when that namespace was created. This release fixed that. It doesn't affect the API if your program's C++ source files say using namespace mysqlpp within them.
Removed Connection::infoo(). (I'd call this an API change if I thought there were any programs out there actually using this...)
Collapsed the Connection constructor taking a bool (for setting the throw_exceptions flag) and the default constructor into a single constructor using a default for the parameter.
Classes Connection and Query are now derived from the Lockable interface, instead of implementing their own lock/unlock functions.
In several instances, functions that took objects by value now take them by const reference, for efficiency.
Merged SQLQuery class's members into class Query.
Merged RowTemplate class's members into class Row.
Reordered member variable declarations in some classes. The most common instance is when the private section was declared before the public section; it is now the opposite way. This can change the object's layout in memory, so a program linking to the library must be rebuilt.
Simplified the date and time class hierarchy. Date used to derive from mysql_date, Time used to derive from mysql_time, and DateTime used to derive from both of those. All three of these classes used to derive from mysql_dt_base. All of the mysql_* classes' functionality and data has been folded into the leaf classes, and now the only thing shared between them is their dependence on the DTbase template. Since the leaf classes' interface has not changed and end-user code shouldn't have been using the other classes, this shouldn't affect the API in any practical way.
mysql_type_info now always initializes its private num member. Previously, this would go uninitialized if you used the default constructor. Now there is no default ctor, but the ctor taking one argument (which sets num) has a default.