1192 lines
53 KiB
XML
1192 lines
53 KiB
XML
<?xml version="1.0" encoding='UTF-8'?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<sect1 id="breakages">
|
|
<title>Incompatible Library Changes</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Since pure additions do not break programs, those changes are
|
|
still documented only in the ChangeLog.</para>
|
|
|
|
|
|
<sect2 id="api-changes">
|
|
<title>API Changes</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<sect3 id="api-1.7.10">
|
|
<title>v1.7.10</title>
|
|
|
|
<para>Removed <methodname>Row::operator[]()</methodname> overloads
|
|
except the one for <type>size_type</type>, and added
|
|
<methodname>Row::lookup_by_name()</methodname> to provide the
|
|
“subscript by string” functionality. In practical
|
|
terms, this change means that the <varname>row["field"]</varname>
|
|
syntax no longer works; you must use the new
|
|
<methodname>lookup_by_name</methodname> method instead.</para>
|
|
|
|
<para>Renamed the generated library on POSIX systems from
|
|
<filename>libsqlplus</filename> to
|
|
<filename>libmysqlpp</filename>.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="api-1.7.19">
|
|
<title>v1.7.19</title>
|
|
|
|
<para>Removed <methodname>SQLQuery::operator=()</methodname>, and
|
|
the same for its <classname>Query</classname> subclass. Use the
|
|
copy constructor instead, if you need to copy one query to another
|
|
query object.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="api-1.7.20">
|
|
<title>v1.7.20</title>
|
|
|
|
<para>The library used to have two names for many core classes: a
|
|
short one, such as <classname>Row</classname> and a longer one,
|
|
<classname>MysqlRow</classname>. The library now uses the shorter
|
|
names exclusively.</para>
|
|
|
|
<para>All symbols within MySQL++ are in the
|
|
<filename>mysqlpp</filename> namespace now if you use the new
|
|
<filename>mysql++.h</filename> header. If you use the older
|
|
<filename>sqlplus.hh</filename> or <filename>mysql++.hh</filename>
|
|
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.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="api-2.0.0">
|
|
<title>v2.0.0</title>
|
|
|
|
<sect4 id="api-2.0.0-Connection">
|
|
<title>Connection class changes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><methodname>Connection::create_db()</methodname>
|
|
and <methodname>drop_db()</methodname> return
|
|
<symbol>true</symbol> on success. They returned
|
|
<symbol>false</symbol> in v1.7.<emphasis>x</emphasis>! This
|
|
change will only affect your code if you have exceptions
|
|
disabled.</para></listitem>
|
|
|
|
<listitem><para>Renamed
|
|
<methodname>Connection::real_connect()</methodname>
|
|
to <methodname>connect()</methodname>, made several
|
|
more of its parameters default, and removed the
|
|
old <methodname>connect()</methodname> method, as
|
|
it’s now a strict subset of the new one. The
|
|
only practical consequence is that if your program
|
|
was using <methodname>real_connect()</methodname>,
|
|
you will have to change it to
|
|
<methodname>connect()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Replaced
|
|
<methodname>Connection::read_option()</methodname> with new
|
|
<methodname>set_option()</methodname> mechanism. In addition
|
|
to changing the name, programs using this function will have
|
|
to use the new <classname>Connection::Option</classname>
|
|
enumerated values, accept a <symbol>true</symbol>
|
|
return value as meaning success instead of 0, and
|
|
use the proper argument type. Regarding the latter,
|
|
<methodname>read_option()</methodname> took a <type>const
|
|
char*</type> argument, but because it was just a thin wrapper
|
|
over the MySQL C API function <ulink url="mysql-options"
|
|
type="mysqlapi"/>, the actual value being pointed to could
|
|
be any of several types. This new mechanism is properly
|
|
type-safe.</para></listitem>
|
|
</itemizedlist>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-2.0.0-Exception">
|
|
<title>Exception-related changes</title>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>Classes <classname>Connection</classname>,
|
|
<classname>Query</classname>, <classname>Result</classname>,
|
|
<classname>ResUse</classname>, and <classname>Row</classname>
|
|
now derive from <ulink type="classref"
|
|
url="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 <ulink type="classref"
|
|
url="NoExceptions"/> class on the stack, which disables
|
|
exceptions on an <classname>OptionalExceptions</classname>
|
|
subclass as long as the <classname>NoExceptions</classname>
|
|
instance is in scope. You can instead call
|
|
<methodname>disable_exceptions()</methodname> on any
|
|
of these objects, but if you only want them disabled
|
|
temporarily, it’s easy to forget to re-enable them
|
|
later.</para></listitem>
|
|
|
|
<listitem><para>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 <classname>Connection</classname>
|
|
object with exceptions enabled, and then asked it to
|
|
create a <classname>Query</classname> object, the
|
|
<classname>Query</classname> 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 <classname>NoExceptions</classname> 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.</para></listitem>
|
|
|
|
<listitem><para>All custom MySQL++ exceptions now derive from
|
|
the new <ulink type="classref" url="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 <classname>BadQuery</classname>
|
|
exception had a string member called <varname>error</varname>
|
|
plus a method called <methodname>what()</methodname>. Both
|
|
did the same thing, and the <methodname>what()</methodname>
|
|
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.</para></listitem>
|
|
|
|
<listitem><para>Renamed
|
|
<classname>SQLQueryNEParams</classname> exception to
|
|
<classname>BadParamCount</classname> to match style of other
|
|
exception names.</para></listitem>
|
|
|
|
<listitem><para>Added <ulink type="classref"
|
|
url="BadOption"/>, <ulink type="classref"
|
|
url="ConnectionFailed"/>, <ulink type="classref"
|
|
url="DBSelectionFailed"/>, <ulink type="classref"
|
|
url="EndOfResults"/>, <ulink type="classref"
|
|
url="EndOfResultSets"/>, <ulink type="classref"
|
|
url="LockFailed"/>, and <ulink type="classref"
|
|
url="ObjectNotInitialized"/> exception types, to fix
|
|
overuse of <classname>BadQuery</classname>. Now the
|
|
latter is used only for errors on query execution. If
|
|
your program has a “catch-all” block taking a
|
|
<classname>std::exception</classname> 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.</para></listitem>
|
|
</itemizedlist>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-2.0.0-Query">
|
|
<title>Query class changes</title>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>In previous versions,
|
|
<classname>Connection</classname> had
|
|
a querying interface similar to class
|
|
<classname>Query</classname>’s. These methods were
|
|
intended only for <classname>Query</classname>’s use; no
|
|
example ever used this interface directly, so no end-user code
|
|
is likely to be affected by this change.</para></listitem>
|
|
|
|
<listitem><para>A more likely problem arising from
|
|
the above change is code that tests for query success
|
|
by calling the <classname>Connection</classname>
|
|
object’s <methodname>success()</methodname> method
|
|
or by casting it to <type>bool</type>. This will now give
|
|
misleading results, because queries no longer go through
|
|
the <classname>Connection</classname> object. Class
|
|
<classname>Query</classname> has the same success-testing
|
|
interface, so use it instead.</para></listitem>
|
|
|
|
<listitem><para><classname>Query</classname> now derives
|
|
from <classname>std::ostream</classname> instead of
|
|
<classname>std::stringstream</classname>.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-2.0.0-Result">
|
|
<title>Result/ResUse class changes</title>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Renamed
|
|
<methodname>ResUse::mysql_result()</methodname> to
|
|
<methodname>raw_result()</methodname> so it’s database
|
|
server neutral.</para></listitem>
|
|
|
|
<listitem><para>Removed
|
|
<methodname>ResUse::eof()</methodname>, as it wrapped
|
|
the deprecated and unnecessary MySQL C API function
|
|
<ulink url="mysql-eof" type="mysqlapi"/>. See the
|
|
<filename>simple3</filename> and <filename>usequery</filename>
|
|
examples to see the proper way to test for the end of a result
|
|
set.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-2.0.0-Row">
|
|
<title>Row class changes</title>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Removed “field name” form
|
|
of <methodname>Row::field_list()</methodname>. It was
|
|
pointless.</para></listitem>
|
|
|
|
<listitem><para><classname>Row</classname> subscripting
|
|
works more like v1.7.9: one can subscript a
|
|
<classname>Row</classname> with a string (e.g.
|
|
<methodname>row["myfield"]</methodname>), or with
|
|
an integer (e.g. <methodname>row[5]</methodname>).
|
|
<methodname>lookup_by_name()</methodname> was
|
|
removed. Because <methodname>row[0]</methodname> is
|
|
ambiguous (0 could mean the first field, or be a null
|
|
pointer to <type>const char*</type>), there is now
|
|
<methodname>Row::at()</methodname>, which can look up any
|
|
field by index.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-2.0.0-misc">
|
|
<title>Miscellaneous changes</title>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>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.</para></listitem>
|
|
|
|
<listitem><para>Removed the backwards-compatibility
|
|
headers <filename>sqlplus.hh</filename> and
|
|
<filename>mysql++.hh</filename>. If you were
|
|
still using these, you will have to change to
|
|
<filename>mysql++.h</filename>, which will put all symbols in
|
|
<symbol>namespace mysqlpp</symbol>.</para></listitem>
|
|
|
|
<listitem><para>Can no longer use arrow operator
|
|
(<symbol>-></symbol>) on the iterators into the
|
|
<classname>Fields</classname>, <classname>Result</classname>
|
|
and <classname>Row</classname> containers.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
<sect3 id="api-2.2.0">
|
|
<title>v2.2.0</title>
|
|
|
|
<para>Code like this will have to change:</para>
|
|
|
|
<programlisting>
|
|
query << "delete from mytable where myfield=%0:myvalue";
|
|
query.parse();
|
|
query.def["myvalue"] = some_value;
|
|
query.execute();</programlisting>
|
|
|
|
<para>...to something more like this:</para>
|
|
|
|
<programlisting>
|
|
query << "delete from mytable where myfield=%0";
|
|
query.parse();
|
|
query.execute(some_value);</programlisting>
|
|
|
|
<para>The first code snippet abuses the default template query
|
|
parameter mechanism (<varname>Query::def</varname>) to fill out
|
|
the template instead of using one of the overloaded forms of
|
|
<methodname>execute()</methodname>,
|
|
<methodname>store()</methodname> or <methodname>use()</methodname>
|
|
taking one or more <classname>SQLString</classname> parameters.
|
|
The purpose of <varname>Query::def</varname> 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”.</para>
|
|
|
|
<para>(Incidentally, this change was made to allow better support
|
|
for BLOB columns.)</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="api-2.3.0">
|
|
<title>v2.3.0</title>
|
|
|
|
<para><methodname>Connection::set_option()</methodname> 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
|
|
<methodname>set_option()</methodname> call now, not
|
|
<methodname>Connection::connect()</methodname></para>
|
|
|
|
<para><classname>FieldNames</classname> and
|
|
<classname>FieldTypes</classname> 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.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="api-3.0.0">
|
|
<title>v3.0.0</title>
|
|
|
|
<sect4 id="api-3.0.0-names">
|
|
<title>Class name changes</title>
|
|
|
|
<para>Several classes changed names in this
|
|
release:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><classname>ColData</classname> is now
|
|
<classname>String</classname>.</para></listitem>
|
|
|
|
<listitem><para><classname>NullisBlank</classname>
|
|
is now <classname>NullIsBlank</classname>. (Note
|
|
the capital <emphasis>I</emphasis>.) Similar
|
|
changes for <classname>NullisNull</classname> and
|
|
<classname>NullisZero</classname>.</para></listitem>
|
|
|
|
<listitem><para><classname>ResNSel</classname> is now
|
|
<classname>SimpleResult</classname>.</para></listitem>
|
|
|
|
<listitem><para><classname>Result</classname> is now
|
|
<classname>StoreQueryResult</classname>.</para></listitem>
|
|
|
|
<listitem><para><classname>ResUse</classname> is now
|
|
<classname>UseQueryResult</classname>.</para></listitem>
|
|
|
|
<listitem><para><classname>SQLString</classname> is now
|
|
<classname>SQLTypeAdapter</classname>.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>When first building existing code against this version,
|
|
you may find it helpful to define the macro
|
|
<varname>MYSQLPP_OLD_CLASS_NAMES</varname> in your
|
|
program’s build options. This will turn on some macros
|
|
that set up aliases for the new class names matching their
|
|
corresponding old names. Then, when you’ve fixed up any
|
|
other issues that may prevent your program from building with
|
|
the new MySQL++, you can turn it back off and fix up any class
|
|
name differences.</para>
|
|
|
|
<para>If you were only using <classname>ColData</classname> in a
|
|
BLOB context, you should use <classname>sql_blob</classname> or
|
|
one of the related typedefs defined in
|
|
<filename>lib/sql_types.h</filename> instead, to insulate your
|
|
code from changes like these.</para>
|
|
|
|
<para>The <classname>SQLString</classname> change
|
|
shouldn’t affect you, as this class was not designed to be
|
|
used by end user code. But, due to the old name and the fact
|
|
that it used to derive from <classname>std::string</classname>,
|
|
some might have been tempted to use it as an enhanced
|
|
<classname>std::string</classname>. Such code will undoubtedly
|
|
break, but can probably be fixed by just changing it to use
|
|
<classname>std::string</classname> instead.</para>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-Connection">
|
|
<title>Connection class changes</title>
|
|
|
|
<para>The option setting mechanism has been redesigned. (Yes,
|
|
again.) There used to be an enum in
|
|
<classname>Connection</classname> with a value for each option
|
|
we understood, and an overload of
|
|
<methodname>Connection::set_option()</methodname> for each
|
|
argument type we understood. It was possible to pass any option
|
|
value to any <methodname>set_option()</methodname> overload, and
|
|
the problem would only be detected at run time. Now each option
|
|
is represented by a class derived from the new
|
|
<classname>Option</classname> abstract base class, and
|
|
<methodname>set_option()</methodname> simply takes a pointer to
|
|
one of these objects. See
|
|
<filename>examples/multiquery.cpp</filename> for the syntax.
|
|
Since each <classname>Option</classname> subclass takes only the
|
|
parameter types it actually understands, it’s now
|
|
completely type-safe at compile time.</para>
|
|
|
|
<para>The new option setting mechanism also has the virtue of
|
|
being more powerful so it let us replace several existing things
|
|
within <classname>Connection</classname> with new
|
|
options:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>Replaced
|
|
<methodname>enable_ssl()</methodname> with
|
|
<classname>SslOption</classname>.</para></listitem>
|
|
|
|
<listitem><para>Replaced the <varname>compress</varname>
|
|
parameter to the <classname>Connection</classname>
|
|
create-and-connect constructor and
|
|
<methodname>Connection::connect()</methodname> method with
|
|
<classname>CompressOption</classname>.</para></listitem>
|
|
|
|
<listitem><para>Replaced the
|
|
<varname>connect_timeout</varname> parameter with
|
|
<classname>ConnectTimeoutOption</classname>.</para></listitem>
|
|
|
|
<listitem><para>Defined <classname>Option</classname>
|
|
subclasses for each of the flags you would previously set
|
|
using the <varname>client_flag</varname> parameter. There
|
|
are about a dozen of these, so instead of listing them,
|
|
look in <filename>lib/options.h</filename> for something
|
|
with a similar name.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Collapsed <classname>Connection</classname>’s
|
|
<varname>host</varname>, <varname>port</varname>, and
|
|
<varname>socket_name</varname> parameters down into a new
|
|
combined <varname>server</varname> parameter which is parsed to
|
|
determine what kind of connection you mean. These interfaces are
|
|
still compatible with v2.3 and earlier up through the port
|
|
parameter.</para>
|
|
|
|
<para>Moved
|
|
<methodname>Connection::affected_rows()</methodname>,
|
|
<methodname>info()</methodname> and
|
|
<methodname>insert_id()</methodname> methods to class
|
|
<classname>Query</classname>, as they relate to the most
|
|
recently-executed query.</para>
|
|
|
|
<para>Changed the return type of
|
|
<methodname>Connection::ping()</methodname> from
|
|
<type>int</type> to <type>bool</type>. If you were calling
|
|
<methodname>ping()</methodname> in <type>bool</type> context
|
|
or using its return value in <type>bool</type> context,
|
|
you will need to reverse the sense of the test because the
|
|
previous return code used zero to mean success. Now it returns
|
|
<type>true</type> to indicate success.</para>
|
|
|
|
<para>Renamed several methods:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>Use <methodname>client_version()</methodname>
|
|
instead of <methodname>api_version()</methodname> or
|
|
<methodname>client_info()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>ipc_version()</methodname> instead of
|
|
<methodname>host_info()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>protocol_version()</methodname> instead of
|
|
<methodname>proto_info()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>server_version()</methodname> instead of
|
|
<methodname>server_info()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>status()</methodname> instead of
|
|
<methodname>stat()</methodname>.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Also, removed <methodname>close()</methodname> in favor
|
|
of <methodname>disconnect()</methodname>, which has always
|
|
done the same thing.</para>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-DateTime">
|
|
<title>Date and Time class changes</title>
|
|
|
|
<para>The <type>sql_timestamp</type> typedef is now
|
|
an alias for <classname>DateTime</classname>, not
|
|
<classname>Time</classname>.</para>
|
|
|
|
<para>There used to be implicit conversion constructors from
|
|
<classname>ColData</classname> (now
|
|
<classname>String</classname>),
|
|
<classname>std::string</classname> and <type>const char*</type>
|
|
for the <classname>Date</classname>,
|
|
<classname>DateTime</classname>, and <classname>Time</classname>
|
|
classes. It’s still possible to do these conversions, but
|
|
only explicitly. (This had to be done to make
|
|
<classname>Null<T></classname> work in SSQLSes.)</para>
|
|
|
|
<para>The most likely place to run into problems as a result
|
|
of this change is in code like this:</para>
|
|
|
|
<programlisting>
|
|
void some_function(const mysqlpp::DateTime& dt);
|
|
|
|
some_function("2007-12-22");</programlisting>
|
|
|
|
<para>The function call needs to be changed to:</para>
|
|
|
|
<programlisting>
|
|
some_function(mysqlpp::DateTime("2007-12-22"));</programlisting>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-Exception">
|
|
<title>Exception changes</title>
|
|
|
|
<para>If an error occurs during the processing of a
|
|
“use” query (as opposed to the initial execution) we
|
|
throw the new <classname>UseQueryError</classname> exception
|
|
instead of <classname>BadQuery</classname>.</para>
|
|
|
|
<para>If you pass bad values to the <classname>Row</classname>
|
|
ctor so that it can’t initialize itself properly, it
|
|
throws the <classname>ObjectNotInitialized </classname>
|
|
exception instead of <classname>BadQuery</classname>.</para>
|
|
|
|
<para>Together, these two changes mean that
|
|
<classname>BadQuery</classname> is now used solely to indicate
|
|
a problem executing the actual SQL query statement.</para>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-Field">
|
|
<title>Field and Fields class changes</title>
|
|
|
|
<para><classname>Field</classname> is now a real C++ class,
|
|
not just a typedef for the corresponding C API class. Major
|
|
portability impacts are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>It has no public data members. Where
|
|
sensible, there is a public accessor function of the
|
|
same name as the corresponding field in the C API
|
|
structure.</para></listitem>
|
|
|
|
<listitem><para>The main exception to this is the
|
|
<varname>flags</varname> data member. This is a bitfield in
|
|
the C API data structure and you had to use MySQL-specific
|
|
constants to break values out of it. MySQL++’s new
|
|
<classname>Field</classname> class provides a public member
|
|
function returning <type>bool</type> for each of these
|
|
flags.</para></listitem>
|
|
|
|
<listitem><para>The new class doesn’t include all of the
|
|
data members from the C API version. We left out those that
|
|
aren’t used within MySQL++ or its examples, or whose
|
|
function we couldn’t understand. Basically, if we
|
|
couldn’t document a reason to use it, we left it
|
|
out.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para><classname>Fields</classname> used to be a
|
|
<classname>std::vector</classname> work-alike which
|
|
worked with the C API to access fields and return them
|
|
as though they were simply contained directly within the
|
|
<classname>Fields</classname> object. Now that we have a
|
|
real MySQL++ class to hold information about each field
|
|
without reference to the C API, we were able to replace the
|
|
<classname>Fields</classname> class with:</para>
|
|
|
|
<programlisting>
|
|
typedef std::vector<Field> Fields;</programlisting>
|
|
|
|
<para>If anything, this should give a pure superset of the old
|
|
functionality, but it’s possible it could break end user
|
|
code.</para>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-Query">
|
|
<title>Query class changes</title>
|
|
|
|
<para>If you were using <type>char</type> as an 8-bit integer
|
|
in query building, there are several places in MySQL++ v3 where
|
|
it will now be treated as a single-character string. MySQL++
|
|
has had the <classname>tiny_int</classname> class for many
|
|
years now specifically to provide a true 8-bit integer without
|
|
the semantic confusion surrounding the old C <type>char</type>
|
|
type. Either use <classname>tiny_int</classname>, or
|
|
use the SQL type aliases <type>sql_tinyint</type> and
|
|
<type>sql_tinyint_unsigned</type> instead.</para>
|
|
|
|
<para>The ‘r’ and ‘R’ template query
|
|
parameter modifiers were removed. They made the library do
|
|
quoting and both quoting and escaping (respectively) regardless
|
|
of the data type of the parameter. There are no corresponding
|
|
<classname>Query</classname> stream manipulators, so for
|
|
symmetery we had to decide whether to add such manipulators or
|
|
remove the tquery modifiers. There should never be a reason to
|
|
force quoting or escaping other than to work around a MySQL++
|
|
bug, and it’s better to just fix the bug than work around
|
|
it, so removed the tquery modifiers.</para>
|
|
|
|
<para><methodname>Query::store_next()</methodname>
|
|
and <methodname>Result::fetch_row()</methodname> no
|
|
longer throw the <classname>EndOfResults</classname> and
|
|
<classname>EndOfResultSets</classname> exceptions; these
|
|
are not exceptional conditions! These methods simply return
|
|
<type>false</type> when you hit the end of the result set
|
|
now.</para>
|
|
|
|
<para>Renamed <varname>Query::def</varname> to
|
|
<varname>Query::template_defaults</varname> to make its
|
|
purpose clearer.</para>
|
|
|
|
<para>Removed <methodname>Query::preview()</methodname>. The
|
|
most direct replacement for this set of overloaded methods is
|
|
the parallel set of <methodname>str()</methodname> methods,
|
|
which were just aliases before. (Chose
|
|
<methodname>str()</methodname> over
|
|
<methodname>preview()</methodname> because it’s standard
|
|
C++ nomenclature.) But if you’re just looking to get a
|
|
copy of a built query string and you aren’t using template
|
|
queries, you can now insert the <classname>Query</classname>
|
|
into a stream and get the same result.</para>
|
|
|
|
<para>For example, a lot of code in the examples that used to
|
|
say things like:</para>
|
|
|
|
<programlisting>
|
|
cout << query.preview() << endl;</programlisting>
|
|
|
|
<para>now looks like this:</para>
|
|
|
|
<programlisting>
|
|
cout << query << endl;</programlisting>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-Result">
|
|
<title>Result, ResUse, and ResNSel class changes</title>
|
|
|
|
<para>In addition to the class name changes described above,
|
|
<classname>UseQueryResult</classname> is no longer
|
|
<classname>StoreQueryResult</classname>’s base class.
|
|
There is a new abstract class called
|
|
<classname>ResultBase</classname> containing much of what used
|
|
to be in <classname>ResUse</classname>, and it is the base of
|
|
both of these concrete result set types. This should only affect
|
|
your code if you were using <classname>ResUse</classname>
|
|
references to refer to <classname>Result</classname>
|
|
objects.</para>
|
|
|
|
<para>Removed a bunch of duplicate methods:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>Use
|
|
<methodname>num_fields()</methodname> instead of
|
|
<methodname>columns()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>field_names()</methodname> instead of
|
|
<methodname>names()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>num_rows()</methodname> instead of
|
|
<methodname>rows()</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>field_types()</methodname> instead of
|
|
<methodname>types()</methodname>.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Renamed several methods for “grammar” reasons.
|
|
For example, some methods returned a single object but had a
|
|
“plural” name, implying that it returned a container
|
|
of objects. In cases like this, we changed the name to agree
|
|
with the return value. Some of these also fall into the
|
|
duplicate method category above:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para>Use
|
|
<methodname>field(unsigned int)</methodname>
|
|
instead of <methodname>fields(unsigned
|
|
int)</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use <methodname>field_num(const
|
|
std::string&)</methodname>
|
|
instead of <methodname>names(const
|
|
std::string&)</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>field_name(int)</methodname> instead of
|
|
<methodname>names(int)</methodname>.</para></listitem>
|
|
|
|
<listitem><para>Use
|
|
<methodname>field_type(int)</methodname> instead of
|
|
<methodname>types(int)</methodname>.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Removed several “smelly” methods:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><methodname>purge()</methodname>: was an
|
|
internal implementation detail, not something for end user
|
|
code to call</para></listitem>
|
|
|
|
<listitem><para><methodname>raw_result()</methodname>: end
|
|
user code shouldn’t be digging down to the C API data
|
|
structures, but if you really need something like this, look
|
|
at the implementation of
|
|
<methodname>Query::storein()</methodname>. Its workings will
|
|
probably be educational.</para></listitem>
|
|
|
|
<listitem><para><methodname>reset_names()</methodname>:
|
|
no reason to call this, especially now that the field
|
|
name list is initialized once at startup and then never
|
|
changed</para></listitem>
|
|
|
|
<listitem><para><methodname>reset_field_names()</methodname>:
|
|
just an alias for previous</para></listitem>
|
|
|
|
<listitem><para><methodname>reset_types()</methodname>:
|
|
same argument as for
|
|
<methodname>reset_names()</methodname></para></listitem>
|
|
|
|
<listitem><para><methodname>reset_field_types()</methodname>:
|
|
just an alias for previous</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para><methodname>ResUse::field_num()</methodname> would
|
|
unconditionally throw a <classname>BadFieldName</classname>
|
|
exception when you asked for a field that doesn’t exist.
|
|
Now, if exceptions are disabled on the object, it just returns
|
|
-1.</para>
|
|
|
|
<para><classname>SimpleResult</classname>’s member
|
|
variables are all now private, and have read-only accessor
|
|
functions of the same name.</para>
|
|
|
|
<para>Code like this used to work:</para>
|
|
|
|
<programlisting>
|
|
mysqlpp::Row row;
|
|
mysqlpp::Result::size_type i;
|
|
for (i = 0; row = res[i]; ++i) {
|
|
// Do something with row here
|
|
}</programlisting>
|
|
|
|
<para>That is, indexing past the end of a “store”
|
|
result set would just return an empty row object, which tests as
|
|
false in <type>bool</type> context, so it ends the loop. Now
|
|
that <classname>StoreQueryResult</classname> is a
|
|
<classname>std::vector</classname> derivative, this either
|
|
crashes your program or causes the standard library to throw an
|
|
exception, depending on what debugging features your version of
|
|
STL has. The proper technique is:</para>
|
|
|
|
<programlisting>
|
|
mysqlpp::Row row;
|
|
mysqlpp::StoreQueryResult::size_type i;
|
|
for (i = 0; i < res.num_rows(); ++i) {
|
|
row = res[i];
|
|
// Do something with row here
|
|
}</programlisting>
|
|
|
|
<para>...or, in a more C++ish idiom:</para>
|
|
|
|
<programlisting>
|
|
mysqlpp::Row row;
|
|
mysqlpp::StoreQueryResult::const_iterator it;
|
|
for (it = res.begin(); it != res.end(); ++it) {
|
|
row = *it;
|
|
// Do something with row here
|
|
}</programlisting>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-Row">
|
|
<title>Row class changes</title>
|
|
|
|
<para>Removed <methodname>Row::raw_data()</methodname>,
|
|
<methodname>raw_size()</methodname> and
|
|
<methodname>raw_string()</methodname>. These were useful with
|
|
BLOB data back when MySQL++ didn’t handle embedded null
|
|
characters very well, and when copies of
|
|
<classname>ColData</classname> objects were expensive. Neither
|
|
is true now, so they have no value any more. Equivalent calls
|
|
are:</para>
|
|
|
|
<programlisting>
|
|
mysqlpp::String s = row[0];
|
|
s.data(); // raw_data() equivalent
|
|
s.length(); // raw_size() equivalent
|
|
std::string(s.data(), s.length()); // raw_string() equivalent</programlisting>
|
|
|
|
<para><methodname>Row::operator[](const char*)</methodname>
|
|
would unconditionally throw a
|
|
<classname>BadFieldName</classname> exception when you asked for
|
|
a field that doesn’t exist. Now, if exceptions are
|
|
disabled on the <classname>Row</classname> object, it just
|
|
returns a reference to an empty <classname>String</classname>
|
|
object. You can tell when this happens because such an object
|
|
tests as false in <type>bool</type> context.</para>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-SSQLS">
|
|
<title>Specialized SQL Structure (SSQLS) changes</title>
|
|
|
|
<para>Renamed <filename>custom*</filename> to
|
|
<filename>ssqls*</filename>. There is a backwards-compatibility
|
|
header <filename>custom.h</filename> which includes
|
|
<filename>ssqls.h</filename> for you, but it will go away in a
|
|
future version of MySQL++.</para>
|
|
|
|
<para>SSQLSes get populated by field name now, not by
|
|
field order. In v2, it was absolutely required that your
|
|
SSQLS had its fields declared in exactly the same order
|
|
as the fields in the database server, and there could be
|
|
no gaps. An <command>ALTER TABLE</command> command would
|
|
almost always necessitate redefining the corresponding SSQLS
|
|
and rebuilding your program. Some alterations actually made
|
|
using SSQLS impossible. For the most part, this change just
|
|
gives your program additional flexibility in the face of
|
|
future changes. However, code that was taking advantage of
|
|
this low-level fact will break when moving to v3. Before I
|
|
explain how, let’s go over the high-level functional
|
|
changes you’ll find in v3’s SSQLS mechanism.</para>
|
|
|
|
<para>Because MySQL++ no longer needs the
|
|
SSQLS field order to match the SQL field order,
|
|
the <function>sql_create_c_order_*</function>
|
|
SSQLS creation macro was dropped in v3. We were
|
|
also able to drop the ordering parameters from
|
|
<function>sql_create_complete_*</function>. That in turn
|
|
means there is no longer a difference between the way it and
|
|
<function>sql_create_c_names_*</function> work, so the latter
|
|
was also dropped. Thus, there are now only two groups of SSQLS
|
|
creation macros left: <function>sql_create_*</function>,
|
|
which works pretty much as it always has, and
|
|
<function>sql_create_complete_*</function>, which is the same
|
|
except for the lack of ordering parameters.</para>
|
|
|
|
<para>In general, you should be using
|
|
<function>sql_create_*</function> for all SSQLSes unless
|
|
you need to use different names for data members in C++ than
|
|
you use for the corresponding columns in SQL. In that case,
|
|
use <function>sql_create_complete_*</function> instead.</para>
|
|
|
|
<para>In v2, it was possible to have different SQL column
|
|
names than SSQLS data member names while still using
|
|
<function>sql_create_*</function> if you only used SSQLS
|
|
for data retrieval.<footnote><para>In MySQL++ v2, data
|
|
retreival (<methodname>Query::storein()</methodname>,
|
|
<methodname>SSQLS(const Row& other)</methodname>,
|
|
etc.) worked fine regardless of whether your SSQLS field names
|
|
matched those in the corresponding SQL table, because the
|
|
SSQLS was populated by position, not by field name. Thus,
|
|
if all you used SSQLS for was data retrieval, you could
|
|
define your structures with <function>sql_create_*</function>
|
|
in v2. This was never recommended, because such an SSQLS
|
|
wouldn’t work with other features of MySQL++ like
|
|
<methodname>Query::insert()</methodname> because they depend
|
|
on being able to map names from C++ to SQL and back. You
|
|
needed to use <function>sql_create_c_names_*</function>
|
|
to make these features work in v2 in the face of a naming
|
|
scheme difference between C++ and SQL.</para></footnote> In
|
|
v3, you must use <function>sql_create_complete_*</function>
|
|
for absolutely all uses of SSQLS when you want the C++ field
|
|
names to differ from the SQL column names.</para>
|
|
|
|
<para>The new <classname>Null<T></classname> support in
|
|
SSQLSes causes an internal compiler error in Visual C++ 2003.
|
|
(VC++ 2005 and newer have no trobule with it.) A poll on the
|
|
mailing list says there aren’t many people still stuck on
|
|
this version, so we just ifdef’d out the SSQLS mechanism
|
|
and all the examples that use it when built with VC++ 2003. If
|
|
this affects you, see <xref linkend="ssqls-vc2003"/> for
|
|
suggestions on ways to cope.</para>
|
|
|
|
<para>If you are using types other than MySQL++’s
|
|
<type>sql_*</type> ones <footnote><para>These typedefs
|
|
have been available since MySQL++ v2.1.</para></footnote>
|
|
in your SSQLSes, code that previously worked may now see
|
|
<classname>TypeLookupFailed</classname> exceptions. (This
|
|
can be thrown even if exceptions are otherwise disabled in
|
|
MySQL++.) This version of MySQL++ is stricter about mapping
|
|
SQL to C++ type information, and vice versa. If the library
|
|
can’t find a suitable mapping from one type system
|
|
to the other, it throws this exception, because its only
|
|
other option would be to crash or raise an assertion. This
|
|
typically happens when building SQL queries, so you can
|
|
probably handle it the same way as if the subsequent
|
|
query excecution failed. If you’re catching the
|
|
generic <classname>mysqlpp::Exception</classname>, your
|
|
error handling code might not need to change. If you see
|
|
this exception, it does mean you need to look into your
|
|
use of data types, though. The table that controls this is
|
|
<varname>mysql_type_info::types</varname>, defined at the top
|
|
of <filename>lib/type_info.cpp</filename>. Every data type in
|
|
<filename>lib/sql_types.h</filename> has a corresponding record
|
|
in this table, so if you stick to those types, you’ll
|
|
be fine. It’s also okay to use types your C++ compiler
|
|
can convert directly to these predefined types.</para>
|
|
|
|
<para>The <varname>_table</varname> static member variable
|
|
for each SSQLS is now private. The recommended way to access
|
|
this remains unchanged: the <function>table()</function>
|
|
static member function.</para>
|
|
|
|
<para><function>table()</function> used to return a modifiable
|
|
reference to the table name. Now there are two overloads,
|
|
one which returns an unmodifiable pointer to the table name,
|
|
and the other which takes <type>const char*</type> so you
|
|
can override the default table name. So, the code we used to
|
|
recommend for changing the SSQLS’s table name:</para>
|
|
|
|
<programlisting>
|
|
my_ssqls_type::table() = "MyTableName";</programlisting>
|
|
|
|
<para>now needs to be:</para>
|
|
|
|
<programlisting>
|
|
my_ssqls_type::table("MyTableName");</programlisting>
|
|
</sect4>
|
|
|
|
|
|
<sect4 id="api-3.0.0-misc">
|
|
<title>Miscellaneous changes</title>
|
|
|
|
<para>MySQL++ does quoting and escaping much more selectively
|
|
now. Basically, if the library can tell you’re not
|
|
building a SQL query using one of the standard methods, it
|
|
assumes you’re outputting values for human consumption, so
|
|
it disables quoting and SQL escaping. If you need to build your
|
|
own mechanism to replace this, quoting is easy to do, and
|
|
<methodname>Query::escape_string()</methodname> can do SQL
|
|
escaping for you.</para>
|
|
|
|
<para>Removed <methodname>success()</methodname> in
|
|
<classname>Connection</classname>, <classname>Query</classname>
|
|
and <classname>SimpleResult</classname> (neé
|
|
<classname>ResNSel</classname>) and simply made these classes
|
|
testable in <type>bool</type> context to get the same
|
|
information. An additional change in
|
|
<classname>Connection</classname> is that it used to be
|
|
considered “unsuccessful” when the connection was
|
|
down. Since the sense of this test is now whether the object is
|
|
in a good state, it only returns <type>false</type> when the
|
|
connection attempt fails. Call
|
|
<methodname>Connection::is_connected()</methodname> if you just
|
|
want to test whether the connection is up.</para>
|
|
|
|
<para>The debug mode build of the library now has a "_d" suffix
|
|
for Visual C++, and Xcode. This lets you have both versions
|
|
installed without conflict. The release build uses the current
|
|
naming scheme. If you have an existing program building against
|
|
MySQL++ on these platforms, you’ll need to change your
|
|
build options to use the new name in debug mode.</para>
|
|
|
|
<para>Renamed <varname>NO_LONG_LONGS</varname> to
|
|
<varname>MYSQLPP_NO_LONG_LONGS</varname> to avoid a risk of
|
|
collision in the global macro namespace.</para>
|
|
</sect4>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="api-3.0.7">
|
|
<title>v3.0.7</title>
|
|
|
|
<para>Most MySQL++ classes with <methodname>at()</methodname>
|
|
or <methodname>operator []()</methodname> methods now
|
|
throw the new <ulink type="structref" url="BadIndex"/>
|
|
exception when you pass an out-of-range index. These
|
|
methods variously either did not check their indices,
|
|
or threw <classname>std::out_of_range</classname> when
|
|
passed a bad index. The one exception that comes to mind is
|
|
<classname>Fields</classname>, which is just a typedef for a
|
|
specialization of <classname>std::vector</classname>, and the
|
|
Standard has its own rules for index checking.</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="abi-changes">
|
|
<title>ABI Changes</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>If you were going to rebuild your program after
|
|
installing the new library anyway, you can probably ignore this
|
|
section.</para>
|
|
|
|
|
|
<sect3 id="abi-1.7.18">
|
|
<title>v1.7.18</title>
|
|
|
|
<para>The <classname>Query</classname> classes now subclass from
|
|
<classname>stringstream</classname> instead of the deprecated
|
|
<classname>strstream</classname>.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-1.7.19">
|
|
<title>v1.7.19</title>
|
|
|
|
<para>Fixed several <type>const</type>-incorrectnesses in the
|
|
<classname>Query</classname> classes.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-1.7.22">
|
|
<title>v1.7.22</title>
|
|
|
|
<para>Removed “reset query” parameters from several
|
|
<classname>Query</classname> 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.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-1.7.24">
|
|
<title>v1.7.24</title>
|
|
|
|
<para>Some freestanding functions didn’t get moved into
|
|
<symbol>namespace mysqlpp</symbol> when that namespace was
|
|
created. This release fixed that. It doesn’t affect the API
|
|
if your program’s C++ source files say <symbol>using
|
|
namespace mysqlpp</symbol> within them.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-2.0.0">
|
|
<title>v2.0.0</title>
|
|
|
|
<para>Removed <methodname>Connection::infoo()</methodname>.
|
|
(I’d call this an API change if I thought there were any
|
|
programs out there actually using this...)</para>
|
|
|
|
<para>Collapsed the <classname>Connection</classname> constructor
|
|
taking a bool (for setting the throw_exceptions flag) and the
|
|
default constructor into a single constructor using a default for
|
|
the parameter.</para>
|
|
|
|
<para>Classes <classname>Connection</classname> and
|
|
<classname>Query</classname> are now derived from the
|
|
<classname>Lockable</classname> interface, instead of implementing
|
|
their own lock/unlock functions.</para>
|
|
|
|
<para>In several instances, functions that took objects by
|
|
value now take them by const reference, for efficiency.</para>
|
|
|
|
<para>Merged <classname>SQLQuery</classname> class’s members
|
|
into class <classname>Query</classname>.</para>
|
|
|
|
<para>Merged <classname>RowTemplate</classname> class’s
|
|
members into class <classname>Row</classname>.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Simplified the date and time class hierarchy.
|
|
<ulink type="structref" url="Date"/> used to
|
|
derive from <classname>mysql_date</classname>,
|
|
<ulink type="structref" url="Time"/> used to derive
|
|
from <classname>mysql_time</classname>, and <ulink
|
|
type="structref" url="DateTime"/> used to derive from
|
|
both of those. All three of these classes used to derive
|
|
from <classname>mysql_dt_base</classname>. All of the
|
|
<classname>mysql_*</classname> classes’ functionality
|
|
and data has been folded into the leaf classes, and now the
|
|
only thing shared between them is their dependence on the
|
|
<ulink type="structref" url="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.</para>
|
|
|
|
<para><classname>mysql_type_info</classname> now always
|
|
initializes its private <varname>num</varname> 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 <varname>num</varname>) has a default.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-3.0.0">
|
|
<title>v3.0.0</title>
|
|
|
|
<para>Removed <varname>reset_query</varname> parameters from
|
|
<classname>Query</classname> member functions. None of these have
|
|
been honored at least going back to v1.7.9, so this is not an API
|
|
change. As of this version, <classname>Query</classname> now
|
|
automatically detects when it can safely reset itself after
|
|
executing a query, so it’s not necessary to ask for a reset
|
|
except when using template queries.</para>
|
|
|
|
<para>Removed overloads of
|
|
<methodname>Query::execute()</methodname>,
|
|
<methodname>store()</methodname>, and
|
|
<methodname>use()</methodname> that take only a <type>const
|
|
char*</type>. This is not an API change because there was an
|
|
equivalent call chain for this already. This change just snaps
|
|
a layer of indirection.</para>
|
|
|
|
<para><methodname>Query::error()</methodname> is now
|
|
<type>const</type> and returns <type>const char*</type> instead
|
|
of a <classname>std::string</classname> by value.</para>
|
|
|
|
<para>Removed <classname>Lockable</classname> mechanism as it was
|
|
conceptually flawed. <classname>Connection</classname> and
|
|
<classname>Query</classname> consequently no longer derive from
|
|
<classname>Lockable</classname>. Since it was basically useless in
|
|
prior versions, it can’t be construed as an API
|
|
change.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-3.0.1">
|
|
<title>v3.0.1</title>
|
|
|
|
<para><methodname>Connection::thread_aware()</methodname>,
|
|
<methodname>thread_start()</methodname> and
|
|
<methodname>thread_end()</methodname> are now static methods, so
|
|
a program can call them before creating a connection. Ditto for
|
|
<classname>DBDriver</classname> methods of the same name.</para>
|
|
|
|
<para><methodname>ConnectionPool::release()</methodname> is now
|
|
virtual, so a subclass can override it.</para>
|
|
</sect3>
|
|
|
|
|
|
<sect3 id="abi-3.0.2">
|
|
<title>v3.0.2</title>
|
|
|
|
<para><methodname>ConnectionPool::grab()</methodname> is now
|
|
virtual; same reason as above.</para>
|
|
|
|
<para><classname>Query</classname> can now be tested in
|
|
<type>bool</type> context, as was intended for v3.0.0. Had to
|
|
change the “safe bool” method signature to make it
|
|
happen, so technically it’s an API change, but it’s
|
|
still used the same way.</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|