Libtabula v3.9.9 User Manual

Kevin Atkinson

Sinisa Milivojevic

Monty Widenius

Warren Young

May 26, 2014


Table of Contents

1. Introduction
1.1. A Brief History of Libtabula
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. Libtabula’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 Libtabula
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 Libtabula in a Multithreaded Program
7.1. Build Issues
7.2. Connection Management
7.3. Helper Functions
7.4. Sharing Libtabula Data Structures
8. Configuring Libtabula
8.1. The Location of the C API Development Files
8.2. The Maximum Number of Fields Allowed
8.3. Buried MySQL C API Headers
8.4. Building on Systems Without Complete C99 Support
9. Using Libtabula 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. Libtabula User Manual License

1. Introduction

Libtabula is a powerful C++ wrapper for multiple C database access libraries. The initial version supports MySQL, MariaDB, and SQLite. Its purpose is to make working with SQL queries as easy as working with STL containers.

The latest version of libtabula can be found at libtabula.org.

Support for libtabula 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 Libtabula

libtabula is a fork of MySQL++ 3.2.1. (More on this at the end of this section.)

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. You can see echoes of this in the old library name libsqlplus.* and in the naming of many of the classes. 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. During this time, the library’s database-independent parts were left undeveloped, for obvious reasons.

With version 1.7.9, MySQL++ went into a period of stasis, lasting over three years. 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.

In early August of 2004, Warren Young of Educational Technology Resources got fed up with this lack of movement and took over maintenance of MySQL++. He released 1.7.10 later that month, which did little more than make the code build with GCC 3.3 without warnings. MySQL++ grew and improved greatly via prototypical spurts-and-lulls open source development, culminating in MySQL++ 3.2.1 in December 2013.

In May 2014, Warren forked libtabula from MySQL++ in order to reignite the old dream of DBMS independence, reasoning that it would be awkward and confusing to continue calling it “MySQL++” when it works with more than just MySQL and its compatible forks. The initial version of libtabula adds support for SQLite, with the only barrier to additional DBMSes being the desire of people to write the code to add that support.

This is a benign fork, not an angry fork. In a very real sense, libtabula is “MySQL++ 4.0.” It is a fork rather than just a new name since it moved to a new code repository and web site, and there is a chance that MySQL++ will continue to get some bug fixes and enhancements as libtabula stabilizes. At some point, however, libtabula should entirely replace MySQL++.

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 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 libtabula distribution. Please do not send mail to them unless you are sending something that is inherently personal. Not all of the principal developers of libtabula are still active in its development; those who have dropped out have no wish to be bugged about libtabula. Those of us still active in libtabula development monitor the mailing list, so you aren’t getting any extra “coverage” by sending messages to additional email addresses.