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.
Code like this will have to change:
Query q = con.query(); q << "delete from mytable where myfield=%0:myvalue"; q.parse(); q.def["myvalue"] = some_value; q.execute();
...to something more like this:
Query q = con.query(); q << "delete from mytable where myfield=%0"; q.parse(); q.execute(some_value);
The first code snippet abuses the default template
query parameter mechanism (Query::def)
to fill out the template instead of using one of the
overloaded forms of execute(),
store() or
use() taking one or more
SQLString parameters. The purpose
of Query::def is to allow for default
template parameters over multiple queries. In the first
snippet above, there is only one parameter, so in order
to justify the use of template queries in the first
place, it must be changing with each query. Therefore,
it isn't really a "default" parameter at all. We did not
make this change maliciously, but you can understand why
we are not in any hurry to restore this "feature".
(Incidentally, this change was made to allow better support for BLOB columns.)
Connection::set_option()
calls now set the connection option immediately, instead
of waiting until just before the connnection is actually
established. Code that relied on the old behavior could see
unhandled exceptions, since option setting errors are now
thrown from a different part of the code. You want to wrap
the actual set_option() call now,
not Connection::connect()
FieldNames and
FieldTypes are no longer exported
from the library. If you are using these classes directly
from Visual C++ or MinGW, your code won't be able to
dynamically link to a DLL version of the library any
more. These are internal classes, however, so no one
should be using them directly.
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.