Embedded InnoDB 1.0 (Early Adopter Release) User’s Guide and Reference

In comparison to other compact or embedded database systems you might be familiar with:

Examples are given throughout this book that are designed to illustrate API usage. These examples build upon each other; for brevity, the later examples omit some of the repetitive initialization code such as starting a transaction. The sample programs, including all the required initialization, are available in the Embedded InnoDB software distribution. You can find them in:

share/innodb-release-version/examples

Being familiar with the InnoDB storage engine, and in particular the latest InnoDB technology available through the InnoDB Plugin, can give you a head start in developing Embedded InnoDB applications. For information about the Plugin or to download it, see:

http://www.innodb.com/products/innodb_plugin/

For InnoDB terminology that applies to Embedded InnoDB development, see Embedded InnoDB Glossary.

The version number of the Embedded InnoDB product reflects the version number of the underlying InnoDB Plugin. For example, Embedded InnoDB version 1.0.3.5325 was based on InnoDB Plugin version 1.0.3.

These features in particular are inherited from the InnoDB Plugin:

Some InnoDB Plugin features are not available:

If you like, you can develop and deploy Embedded InnoDB applications without using MySQL at all.

You might find it helpful to be familiar with the capabilities of MySQL and the InnoDB storage engine to help design your application logic, tune your data-manipulation code, and debug any problems. For example, if you have existing MySQL table definitions, you can see how the types are mapped to Embedded InnoDB constant values, as explained in Section 6.2.4, “Column Types”.

For even faster prototyping and debugging, you can transfer data directories back and forth between a MySQL installation and an Embedded InnoDB application. For example, you could create a set of InnoDB tables using SQL in MySQL, then perform all the data manipulation through an Embedded InnoDB program. Or you could set up data through an Embedded InnoDB program, then verify the data by running queries from MySQL. For details about this process, see Chapter 10, Transferring Databases between MySQL and Embedded InnoDB.

Features from MySQL that require higher-level interfaces are not available in Embedded InnoDB programs, for example:

Embedded InnoDB, being based on the underlying InnoDB storage engine, keeps track of tables, indexes, and table columns. This information is stored in a set of system tables called the data dictionary. Embedded InnoDB applications are not prevented from writing to these tables as in regular MySQL usage; however, you must treat these tables as read-only.

The system tables are:

For efficiency in setting up multiple data structures, Embedded InnoDB does not wrap each table or index creation operation within a transaction. You must wrap these operations within calls to lock and unlock the data dictionary, and to start and commit transactions. You will see examples of the proper sequences of function calls later on.

Each separate program using the Embedded InnoDB library must use its own data dictionary and data files.

Data files are stored by default underneath the current working directory of the application. You can specify a different location by calling the configuration APIs.

The system tablespace, which holds the tables of the data dictionary and by default all the tables used by your application, is a single large file. If you change the configuration settings to use the file-per-table option, each table created afterwards is stored in a separate file.

Cursors provide a mechanism to iterate over the records in a table. Using cursors, you can read, write, and delete database records. You perform all cursor operations by passing a handle (an opaque type) to the relevant functions. As each cursor is created, it is attached to a transaction. All changes to the database using the cursor are part of that same transaction; you must make sure that you are finished using the cursor before the transaction ends. Once a transaction is committed or rolled back, the cursor handle is considered invalid. All subsequent results from using the stale cursor handle are undefined. You receive a cursor handle by opening an existing table or index, using the ID or the name of the applicable table or index. (The relevant API calls are ib_cursor_open_table, ib_cursor_open_table_using_id, ib_cursor_open_index_using_name, and ib_cursor_open_index_using_id.)

You can reuse a cursor by calling ib_cursor_reset on the cursor handle and attaching it to a running transaction. You close a cursor by calling ib_cursor_close.

Tuples are memory structures that represent different sets of columns, You use them for all kinds of DML operations. In a DML operation, they represent the columns of a record being inserted or updated. In a query, they represent columns from a record pointed to be a cursor.

There are different kinds of tuples derived from the clustered index or a secondary index. There is also a distinction between tuples used for simply searching for a record, and for reading back the columns of the record. In all, you work with four different kinds of tuples based on the above combinations.

Each transaction has a property called the isolation level that controls how strictly the InnoDB engine protects different transactions from “seeing” uncommitted changes made by other transactions. For maximum correctness and reliability, you should typically choose the IB_REPEATABLE_READ isolation level. For maximum performance in advanced applications, where you can ensure that this level of strictness is not required, you might choose a different isolation level, as explained in Section 5.3, “Setting the Transaction Isolation Level”.

Savepoints help to implement nested transactions. They can be used to provide scope to operations on tables that are part of a larger transaction. For example, scheduling a trip in a reservation system might involve booking several different flights; if a desired flight is unavailable, you might roll back the changes involved in booking that one leg, without rolling back the earlier flights that were successfully booked. Embedded InnoDB provides these functions for savepoints:

In this example, we set the InnoDB buffer pool size to 128 megabytes.

ib_err_t	err;

err = ib_cfg_set_int("buffer_pool_size", 134217728)

if (err != DB_SUCCESS) {
	fprintf(stderr, "Error setting InnoDB buffer pool size: %s\n",
		ib_strerror(err));
}

In this example we enable the file-per-table setting:

err = ib_cfg_set_bool_on("file_per_table");
/* Check whether we were successful in enabling the setting or not. */

In this example we disable the file per table setting:

err = ib_cfg_set_bool_off("file_per_table");
/* Check whether we were successful in disabling the setting or not. */

In this example we set the InnoDB data file path:

err = ib_cfg_set_text("data_file_path", "ibdata1:32M:autoextend");
/* Check whether we were successful in setting the data file path. */

If file_per_table configuration variable is set, InnoDB uses one data file per table. Otherwise, all user tables and indexes are stored in one data tablespace. The underlying directory must exist, or it can be created by the ib_database_create function:

ib_err_t err = ib_database_create("test");

This name must be a simple database name, not a path.

Dropping a database drops all tables in the database and then deletes the underlying directory.

ib_err_t err = ib_database_drop("test"); 

Creating a table involves a sequence of API calls to set up the table and its related objects:

When all the structures are set up and connected together, a final API call actually creates the table.

For example, imagine that you want to create a table with the following structure:

CREATE TABLE T(c1 VARCHAR(32), c2 VARCHAR(32), c3 INT UNSIGNED, PRIMARY KEY (c1, c2));

The steps involved are:

ib_trx_t        ib_trx;
ib_id_t         table_id = 0;
ib_tbl_sch_t    ib_tbl_sch = NULL;
ib_idx_sch_t    ib_idx_sch = NULL;
char            table_name[IB_MAX_TABLE_NAME_LEN];

snprintf(table_name, sizeof(table_name), "%s/%s", database_name, name);

/* Pass a table page size of 0, ie., use default page size. */
ib_table_schema_create(table_name, &ib_tbl_sch, IB_TBL_COMPACT, 0);

/* The fifth argument is currently not used. */
ib_table_schema_add_col(ib_tbl_sch, "c1", IB_VARCHAR, IB_COL_NONE, 0, 32);
ib_table_schema_add_col(ib_tbl_sch, "c2", IB_VARCHAR, IB_COL_NONE, 0, 32);
ib_table_schema_add_col(ib_tbl_sch, "c3", IB_INT, IB_COL_UNSIGNED, 0, 4);

/* Index schema handle is "owned" by the table schema handle in this
case and will be deleted when the table schema handle is deleted. */

ib_table_schema_add_index(ib_tbl_sch, "PRIMARY_KEY", &ib_idx_sch);

/* Set prefix length to 0. */
ib_index_schema_add_col(ib_idx_sch, "c1", 0);

/* Set prefix length to 0. */
ib_index_schema_add_col(ib_idx_sch, "c2", 0);

ib_index_schema_set_clustered(ib_idx_sch);

/* Create the transaction that will cover data dictionary update. */
ib_trx = ib_trx_begin(IB_TRX_SERIALIZABLE);

/* Lock the data dictionary in exclusive mode */
ib_schema_lock_exclusive(ib_trx);

/* Create the actual table from the schema. The table id of the new
table will be returned in table_id. */
ib_table_create(ib_trx, ib_tbl_sch, &table_id);

/* Commit the transaction */
ib_trx_commit(ib_trx);

ib_table_schema_delete(ib_tbl_sch);

Before you can search, read, or write records, you need to open either a table or an index. Because every table has a primary key (either one you specified, or a default one supplied by the Embedded InnoDB engine), “opening a table” is shorthand for opening the table’s primary key index, also known as the clustered index.

The open operation creates a cursor handle that is then used to position, search, read, write, and delete records. All table and index operations require one of these cursor handles. (Subsequent sections explain the considerations for exactly which index to use, depending on the columns involved in the operation.)

To open a table, you specify its name. You must have an active transaction. The cursor is attached to this transaction, to prevent any further read, write, or retrieve operations using the cursor after the transaction is committed or rolled back.

ib_trx_t   ib_trx;
ib_crsr_t  ib_crsr;

ib_trx = ib_trx_begin(IB_TRX_REPEATABLE_READ);
ib_cursor_open_table(table_name, ib_trx, &ib_crsr);

Opening an index is very similar to opening a table. Instead of the table name, you specify the index name:

/* Open the secondary index "SEC_1" which is defined on the
table to which the cursor is attached. */
err = ib_cursor_open_index_using_name(crsr, "SEC_1", &index_crsr);

Or you can specify the index ID:

ib_trx_t   ib_trx;
ib_crsr_t  ib_crsr;

ib_trx = ib_trx_begin(IB_TRX_REPEATABLE_READ);
ib_cursor_open_index_using_id(index_id, ib_trx, &ib_crsr);

While performing operations on a table or index, you pass a cursor handle to each function. When finished with the operations, close the cursor by calling the ib_cursor_close() function. Once the cursor is closed, its memory is freed and it is unusable. There is no garbage collection of open cursors when transactions are committed or rolled back; you must explicitly close each cursor.

ib_cursor_close(ib_crsr); 

You can call the function ib_cursor_reset to use the same cursor handle again. (Remember to attach the cursor to a running transaction after calling the reset function.)

When you want to keep a table, but delete all the data in the table, you can truncate the table by calling the ib_cursor_truncate or ib_table_truncate function. This operation is faster and more convenient than deleting all the records. If the operation is successful it will close the cursor and set it to NULL.

ib_cursor_truncate(&ib_crsr, &table_id); 

ib_table_truncate(table_name, &table_id); 

There are two ways to create an index within InnoDB:

This operation is covered in Section 3.2.2, “Opening a Table or Index”.

Currently, there are two basic types of tuples:

The operations are a little different depending on whether you are working through a clustered index or a secondary index. Thus, you might create and work with each of these kinds of tuples:

         ib_tpl_t   ib_tpl;

When doing substantial data processing, you will probably work with several tuples at a time. For example, to update a record, you read the original values into one tuple, then write updated values back to the table using another tuple.

/* Create a tuple for searching a clustered index. */
ib_tpl = ib_clust_search_tuple_create(crsr);

/* Create a tuple for searching a secondary index. */
ib_tpl = ib_sec_search_tuple_create(crsr);

/* Create a tuple for reading/writing a row from/to a clustered index. */
ib_tpl = ib_clust_read_tuple_create(crsr);

/* Create a tuple for reading a row from a secondary index. */
ib_tpl = ib_sec_read_tuple_create(crsr);

There is a single call to delete all four tuple types from above:

ib_tuple_delete(ib_tpl); 

All the metadata about a column is contained in each tuple. You can read the values of columns in the tuples by using either of these techniques, either copying the values or accessing the contents via a pointer:

Whenever you would use a query or any kind of WHERE clause in SQL, with Embedded InnoDB you will position a cursor and scan forward or backward through the records.

ib_err_t err;
ib_tpl_t ib_tpl;

/* Assuming we are iterating over the table, we would create
a tuple to read the data like so: */

ib_tpl = ib_clust_read_tuple_create(ib_crsr);
if (ib_tpl == NULL) {
	/* Handle out of memory error. */
} else {
	err = ib_cursor_first(ib_crsr);

	while (err == DB_SUCCESS) {
		/* Read the record and process it. */
		err = ib_cursor_read_row(ib_crsr, ib_tpl);

		/* Check for errors from the read ignored for brevity. */
		/* Do something with the tuple here. */

		err = ib_cursor_next(ib_crsr);
		/* Check for errors from the next ignored for brevity. */

		…
		/* Remember to reset the tuple that was used to
		read the record from the cursor. */
		ib_tpl = ib_tuple_clear(ib_tpl);
	}

	ib_tuple_delete(ib_tpl);
}

int       res;
ib_tpl_t  key;
ib_err_t  err;

key = ib_sec_search_tuple_create(crsr);
ib_col_set_value(key, 0, "a", strlen("a"));
ib_col_set_value(key, 1, "x", strlen("x"));

/* res will contain the result from comparing key and the user
record that the cursor is positioned on. The result is undefined
if the function returns DB_END_OF_INDEX or error. */
err = ib_cursor_moveto(crsr, key, IB_CUR_GE, &res);

...
ib_tuple_delete(key);

Once the cursor is positioned on a particular record, you can read the columns from that record. What you do after reading the columns depends on the type of operation:

Here is an example to read values from a tuple, that also handles NULL values in columns. It assumes that you have already created a tuple holding a set of column values.

int             i;
int             n_cols = ib_tuple_get_n_cols(tpl);

for (i = 0; i < n_cols; ++i) {
	ib_ulint_t      data_len;
	ib_col_meta_t   ib_col_meta;

	/* Get the meta data for the ith column. */
	data_len = ib_col_get_meta(tpl, i, &ib_col_meta);

	/* Skip system columns. */
	if (ib_col_meta.type == IB_SYS) {
		continue;
	/* Nothing to print. Check for NULL values. */
	} else if (data_len == IB_SQL_NULL) {
		fprintf(stream, "|");
		continue;
	} else {
		switch (ib_col_meta.type) {
		case IB_INT: {
			/* You can either read the raw bytes and do the
			conversion yourself by twiddling the bits or use
			the typed interface of the InnoDB API to read the
			int values.  

			The general strategy will be to determine the INT
			size from the column meta data size (type_len)
			along with the sign flag. Then call the appropriate
			API function to read the int type. */
			...

			switch (ib_col_meta.type_len) {
			case 1:
			case 2:
			...
			case 4: {
				ib_u32_t	v;

				ib_tuple_read_i32(tpl, i, &v);
				fprintf(stream, "%d\n", v);
			}
			...
			case 8:
			...
			default:
				/* Data dictionary is corrupt! */
				assert(IB_FALSE);
			}
			break;
		}
		case IB_FLOAT: {
			float   v;

			ib_tuple_read_float(tpl, i, &v);
			fprintf(stream, "%f", v);
			break;
		}
		case IB_DOUBLE: {
			double  v;

			ib_tuple_read_double(tpl, i, &v);
			fprintf(stream, "%lf", v);
			break;
		}
		case IB_CHAR:
		case IB_BLOB:
		case IB_DECIMAL:
		case IB_VARCHAR: {
			const char*     ptr;

			/* Get access to the raw data via a pointer. */
			ptr = ib_col_get_value(tpl, i);
			fprintf(stream, "%.*s", (int) data_len, ptr);
			break;
		}
		default:
			assert(IB_FALSE);
			break;
		}
	}
	fprintf(stream, "|");
}

fprintf(stream, "\n");

The API function for setting a column value is ib_col_set_value(). You specify a target tuple, the column number to set, a pointer to the data bytes, and the length of the raw data bytes. InnoDB does no type checking when setting the value of a column.

The column values are only stored in a table when you call a function to perform an insert or update using this tuple.

char*   c = "some value";

ib_col_set_value(tpl, col_no, c, strlen(c));

ib_col_set_value(tpl, col_no, NULL, IB_SQL_NULL);

You can copy the contents of one tuple to another, as long as the tuple types are the same type (search or read), and are defined on the same table or index.

ib_tpl_t  src_tpl;
ib_tpl_t  dst_tpl;

Create the two tuples
…
Read or set column values of src tpl from somewhere
…

/* Copy the old contents to the new tuple. */
err = ib_tuple_copy(dst_tpl, src_tpl);

There are two ways to test for SQL NULL values: one using the column metadata, and the other by accessing the value directly. The recommended method is to check the column metadata. The destination tuple is first “cleared” and then the data is copied.

ib_col_meta_t   ib_col_meta;

/* Get the meta data for the ith column. */
data_len = ib_col_get_meta(tpl, i, &ib_col_meta);

/* Skip system columns. */
if (ib_col_meta.type == IB_SYS) {
	continue;
/* Nothing to print. Check for NULL values. */
} else if (data_len == IB_SQL_NULL) {
	/* Do something. */
}

The function ib_col_get_value returns NULL if the column value is IB_SQL_NULL. The function ib_col_copy_value returns IB_SQL_NULL if the column value is NULL .

To read a record from the clustered index, create a cursor handle for that table, then position the cursor on the record to read.

Example code:

ib_err_t        err;
ib_tpl_t        tpl;

tpl = ib_clust_read_tuple_create(crsr);

/* Scan the entire table and print all rows. */
err = ib_cursor_first(crsr);

while (err == DB_SUCCESS) {
	err = ib_cursor_read_row(crsr, tpl);

	/* Possible handle locking and timeout errors too
	in multi-threaded applications. */
	if (err == DB_RECORD_NOT_FOUND || err == DB_END_OF_INDEX) {
		break;
	}

	…
	/* Do something with the tuple */
	…

	err = ib_cursor_next(crsr);

	/* Possible handle locking and timeout errors too
	in multi-threaded applications. */
	if (err == DB_RECORD_NOT_FOUND || err == DB_END_OF_INDEX) {
		break;
	}

	tpl = ib_tuple_clear(tpl);
}

ib_tuple_delete(tpl);

To insert a record, perform the following steps:

Example code:

ib_err_t        err;
ib_tpl_t        tpl;

tpl = ib_clust_read_tuple_create(crsr);

ib_col_set_value(tpl, 0, "a", strlen("a"));
ib_col_set_value(tpl, 1, "b", strlen("b"));
ib_tuple_write_i32(tpl, 2, 100);

err = ib_cursor_insert_row(crsr, tpl);

/* Check err and handle potential errors here ... */

ib_tuple_delete(tpl);

To update a record, perform the following steps:

Example code, from the sample program ib_test1.c:

char*           c1;
int             c1_len;
int             c3_len;
ib_col_meta_t   col_meta;
ib_tpl_t        old_tpl = NULL;
ib_tpl_t        new_tpl = NULL;

/* Create the tuple instance that we will use to update the
table. old_tpl is used for reading the existing row and
new_tpl will contain the update row data. */

old_tpl = ib_clust_read_tuple_create(crsr);
new_tpl = ib_clust_read_tuple_create(crsr);

ib_cursor_read_row(crsr, old_tpl);

/* Get the first column value. c1 will be NULL if
the column value is SQL_NULL. */
c1 = ib_col_get_value(old_tpl, 0);
c1_len = ib_col_get_meta(old_tpl, 0, &col_meta);

/* Copy the old contents to the new tuple. */
ib_tuple_copy(new_tpl, old_tpl);

/* Set the new value of column c3 in the new tuple. */
ib_tuple_write_i32(new_tpl, 2, 10);

err = ib_cursor_update_row(crsr, old_tpl, new_tpl);
/* Check err status etc. */

ib_tuple_delete(old_tpl);
ib_tuple_delete(new_tpl);

To delete a record, perform the following steps:

Below is an example of searching for the record to delete, from the sample program ib_test1.c:

ib_err_t        err;
int             res = ~0;
ib_tpl_t        key = NULL;

/* Create a tuple for searching an index. */
key_tpl = ib_sec_search_tuple_create(crsr);

/* Set the value to delete. */
ib_col_set_value(key, 0, "b", strlen("b"));
ib_col_set_value(key, 1, "z", strlen("z"));

/* Search for the key using the clustered index (PK) */
err = ib_cursor_moveto(crsr, key, IB_CUR_GE, &res);

/* Must be positioned on the record to delete, since
we've specified an exact match. */
/* res will tell us whether there was an exact
match found or not, res == 0 means cursor positioned
on a record that matches exactly. */

ib_tuple_delete(key);

/* InnoDB handles the updating of all secondary indexes. */
if (res == 0) {
	err = ib_cursor_delete_row(crsr);
}

/* Check err status etc. */ 

To emulate a WHERE clause, which lets you operate on multiple rows with a single INSERT, UPDATE, or DELETE statement, use the techniques from Section 4.2.4, “Scanning and Positioning” to loop through all the relevant records from your result set, and perform the appropriate operation on each one as demonstrated in the preceding sections.

To take a savepoint, you must already have an active transaction. If there is already a savepoint of the same name, this call erases that old savepoint and replaces it with a new one.

ib_trx_t  ib_trx;

ib_trx = ib_trx_begin(IB_REPEATABLE_READ);
...
/* Make some changes. */
ib_savepoint_take(ib_trx, savepoint_tag, savepoint_tag_len);

Releases only the named savepoint. Any savepoints that were set after this savepoint are left as-is. This does not undo any changes but only deletes the internal housekeeping data of the savepoint. If the savepoint does not exist, the function returns DB_NO_SAVEPOINT.

 ib_savepoint_release(ib_trx, savepoint_tag, savepoint_tag_len); 

You can either roll back to a specific named savepoint to undo the changes made after a certain point, or roll back all the savepoints to undo all changes made in that transaction. The savepoints are deleted once they are rolled back. Modifications after the savepoint are undone, but InnoDB does not release the corresponding locks that are stored in memory. If a lock is “implicit”, that is, a new inserted row holds a lock where the lock information is carried by the transaction ID stored in the row, these locks are naturally released in the rollback. Any savepoints that were set after this savepoint are deleted. If name equals NULL (that is, a C null pointer), all the savepoints are rolled back.

For example, the following call rolls back all the savepoints and deletes them.

ib_savepoint_rollback(ib_trx, NULL, 0); 

and this call rolls back the named savepoint and all the savepoints taken after the named savepoint and deletes them.

 ib_savepoint_rollback(ib_trx, savepoint_tag, savepoint_tag_len); 

InnoDB supports various configuration variables. The types of these variables are listed below:

InnoDB supports various table format types. You must specify the appropriate type when creating the table. All the supported types are listed below:

The column type ib_col_type_t can have the following possible values. Typically, you read columns one by one out of a tuple, and use a switch construct to decide how to process each column based on its type.

The column type ib_col_attr_t can have the following attributes:

Every column definition is represented by the data structure ib_col_meta_t:

typedef struct ib_col_meta_t {
  ib_col_type_t   type;        /* Type of the column */
  ib_col_attr_t   attr;        /* Column attributes */
  ib_ulint_t      type_len;    /* Length of type in bytes, can
                               be IB_SQL_NULL */
  ib_u16_t        client_type; /* 16 bits of data relevant only to the
                               client. InnoDB ignores this attribute */
  ib_charset_t*   charset;     /* Column charset */
} ib_col_meta_t;

There are several modes for shutdown, that control what actions InnoDB should perform when a shutdown of the storage engine is requested.

InnoDB supports the following lock modes. You specify the degree to which you need exclusive access to a resource (for example, while writing) or shared access (for example, while reading). Embedded InnoDB controls access to the appropriate tables, rows, and so on based on the locks you acquire, and returns error codes if a deadlock or timeout condition occurs. (Thus, it is important to always check return codes.)

Some lock modes can only be used to lock tables; for example, the lock modes IB_LOCK_IS and IB_LOCK_IX.

The cursor search modes represent conditional tests that you would specify in a SQL WHERE clause, for example to position the cursor on a row that is greater or less than some value. The search mode setting is used by ib_cursor_moveto() to position the cursor when searching for a key.

Embedded InnoDB currently supports the following search modes:

These cursor match modes affect the state of the cursor. The match modes control these things: the positioning of the cursor; whether or not its state needs to be made persistent; whether the next N records need to be fetched into the row cache, on the assumption that the program will do cursor next/prev operations. Storing the cursor state is an expensive operation and should be minimized and for that reason. Embedded InnoDB fetches the next N records to avoid unnecessary persistent cursor operations. Embedded InnoDB currently supports the following match modes:

You can specify the following values when starting a transaction. Each value represents an isolation level. The values are listed here in descending order of frequency of use in typical applications. (In fact, the only design decision needed for most applications is whether to use IB_REPEATABLE_READ, which is the default for regular MySQL and InnoDB applications, or switch to IB_READ_COMMITTED.

A transaction can be in one of the following states, which you can check by using the ib_trx_state() function. The InnoDB deadlock monitor can roll back a transaction, and you should be prepared for this, especially where there is high contention.

These APIs are typically the first and last functions that you call within a Embedded InnoDB program. (You might also call some of the functions in Section 6.7.4, “API Functions - Configuration” prior to starting the database engine.) To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_u64_t ib_api_version(void);
   

int release, revision, age;

release = version >> 32;
revision = (version >> 16) & 0xffff;
age = version & 0xffff

    ib_err_t ib_init(void);
   

    ib_err_t ib_startup(const char* format);
   

    ib_err_t ib_shutdown(ib_shutdown_t flag);
   

To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_err_t ib_cursor_open_table(const char* name, ib_trx_t ib_trx,
                                  ib_crsr_t* ib_crsr);
   

    ib_err_t ib_cursor_open_table_using_id(
             ib_id_t        table_id,
             ib_trx_t       ib_trx,
             ib_crsr_t*     ib_crsr);
   

    ib_err_t ib_cursor_open_index_using_name(
             ib_crsr_t       ib_open_crsr,
             const char*     index_name,
             ib_crsr_t*      ib_crsr);
   

    ib_err_t ib_cursor_open_index_using_id(
             ib_id_t         index_id,
             ib_trx_t        ib_trx,
             ib_crsr_t*      ib_crsr);
   

    ib_err_t ib_cursor_first(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_next(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_last(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_prev(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_attach_trx(ib_crsr_t ib_crsr, ib_trx_t ib_trx);
   

    ib_err_t ib_cursor_set_cluster_access(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_is_positioned(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_set_lock_mode(ib_crsr_t ib_crsr, ib_lck_mode_t ib_lck_mode);
   

    void ib_cursor_set_match_mode(ib_crsr_t ib_crsr, ib_match_mode_t match_mode);
   

    void ib_cursor_simple_select(ib_crsr_t ib_crsr);
   

    void ib_cursor_stmt_begin(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_lock(ib_crsr_t ib_crsr, ib_lck_mode_t ib_lck_mode);
   

    ib_err_t ib_cursor_reset(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_close(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_insert_row(ib_crsr_t ib_crsr, const ib_tpl_t ib_tpl);
   

    ib_err_t ib_cursor_update_row(
             ib_crsr_t       ib_crsr,
             const ib_tpl_t  ib_old_tpl,
             const ib_tpl_t  ib_new_tpl);
   

    ib_err_t ib_cursor_delete_row(ib_crsr_t ib_crsr);
   

    ib_err_t ib_cursor_read_row(ib_crsr_t ib_crsr, ib_tpl_t ib_tpl);
   

    ib_err_t ib_cursor_moveto(
             ib_crsr_t       ib_crsr,
             ib_tpl_t        ib_tpl,
             ib_srch_mode_t  ib_srch_mode,
	     int*            result);
   

These functions deal with transactions. For usage instructions, see Chapter 5, Managing Transactions with Embedded InnoDB. To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_trx_t ib_trx_begin(ib_trx_level_t ib_trx_level);
   

        ib_trx_t    ib_trx;
        ib_err_t    ib_err;
        ib_crsr_t   ib_crsr;

        ib_trx = ib_trx_begin(IB_TRX_REPEATABLE_READ);
        ib_err = ib_cursor_open_table("db/t", ib_trx, &ib_crsr);
        ... Do some DML operations ...
        ib_err = ib_cursor_close(ib_crsr);
        ib_trx_commit(ib_trx);
    

    ib_err_t ib_trx_commit(ib_trx_t ib_trx);
   

    ib_trx_state_t ib_trx_state(ib_trx_t ib_trx);
   

    ib_err_t ib_trx_start(ib_trx_t ib_trx, ib_trx_level_t ib_trx_level);
   

    ib_err_t ib_trx_release(ib_trx_t ib_trx);
   

        ib_trx_t    ib_trx;
        ib_err_t    ib_err;

        ib_trx = ib_trx_begin(IB_TRX_REPEATABLE_READ);
        ... Do some DML operations ...
        /* If the transaction is rolled back by InnoDB then the
        transaction handle ib_trx is still valid and has to be
        destroyed using ib_trx_release() explicitly. */
        if (ib_err == DB_DEADLOCK || ib_err == DB_LOCK_WAIT_TIMEOUT) {
                ib_err = ib_trx_release(ib_trx);
                /* Check return value. */
        } else {
                /* Assuming everything went OK. */
                ib_trx_commit(ib_trx);
        }
    

    ib_err_t ib_trx_rollback(ib_trx_t ib_trx);
   

    ib_err_t ib_savepoint_take(ib_trx_t ib_trx, const void* name,
                               ib_ulint_t name_len);
   

    ib_err_t ib_savepoint_release(
             ib_trx_t        ib_trx,
             const void*     name,
             ib_ulint_t      name_len);
   

    ib_err_t ib_savepoint_rollback(
             ib_trx_t        ib_trx,
             const char*     name,
             ib_ulint_t      name_len);
   

These APIs deal with the configuration variables listed in Chapter 8, Embedded InnoDB Configuration Variables. For usage information, see Section 2.5, “Configuration”. To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_err_t ib_cfg_var_get_type(const char* name, ib_cfg_var_type_t* type);
   

    ib_err_t ib_cfg_set_int(const char* name, ib_ulint_t value);
   

    ib_err_t ib_cfg_set_text(const char* name, const char* value);
   

    ib_err_t ib_cfg_set_bool_on(const char* name);
   

    ib_err_t ib_cfg_set_bool_off(const char* name);
   

    ib_err_t ib_cfg_set_callback(const char* name, ib_cb_t func);
   

    ib_err_t ib_cfg_get(const char* name, void* value);
   

      ib_err_t ib_cfg_get_all(const char*** names, ib_u32_t* names_num);
    

These APIs deal with the create and drop operations, which are categorized as Data Definition Language, known as DDL. For usage information, see Chapter 3, Performing CREATE and DROP Operations (DDL) with Embedded InnoDB. To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_err_t ib_table_schema_create(
             const char*     name,
             ib_table_sch_t* ib_tbl_sch,
             ib_tbl_fmt_t    ib_tbl_fmt,
             ib_ulint_t      page_size);
   

    ib_err_t ib_table_schema_delete(ib_tbl_sch_t ib_tbl_sch);
   

    ib_err_t ib_table_schema_add_col(
	      ib_tbl_sch_t    ib_tbl_sch,
	      const char*     name,
	      ib_col_type_t   ib_col_type,
	      ib_col_attr_t   ib_col_attr,
	      ib_u16_t        client_type,
	      ib_ulint_t      len);
   

    ib_err_t ib_table_schema_add_index(
             ib_tbl_sch_t    ib_tbl_sch,
             const char*     name,
             ib_idx_sch_t*   ib_idx_sch);
   

    ib_err_t ib_index_schema_create(
             ib_trx_t        ib_usr_trx,
             const char*     name,
             const char*     table_name,
             ib_idx_sch_t*   ib_idx_sch);
   

    ib_err_t ib_index_schema_set_clustered(ib_idx_sch_t ib_idx_sch);
   

    ib_err_t ib_index_set_unique(ib_idx_sch_t ib_idx_sch);
   

    ib_err_t ib_index_schema_delete(
             ib_idx_sch_t    ib_idx_sch);
   

    ib_err_t ib_index_schema_add_col(
             ib_idx_sch_t    ib_idx_sch,
             const char*     name,
             ib_ulint_t      prefix_len);
   

    ib_err_t ib_table_create(ib_trx_t ib_trx, ib_tbl_sch_t ib_tbl_sch, ib_id_t* id);
   

    ib_err_t ib_index_create(ib_idx_sch_t ib_idx_sch, ib_id_t id);
   

    ib_err_t ib_table_drop(ib_trx_t trx, const char* name);
   

    ib_err_t ib_index_drop(ib_trx_ti ib_trx, ib_id_t index_id);
   

    ib_err_t ib_table_lock(
             ib_trx_t        ib_trx,
             ib_id_t         table_id,
             ib_lck_mode_t   ib_lck_mode);
   

    ib_err_t ib_table_rename(
             ib_trx_t        ib_trx,
             const char*     old_name,
             const char*     new_name);
   

    ib_bool_t ib_database_create(const char* dbname);
   

    ib_err_t ib_database_drop(const char* dbname);
   

To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_err_t ib_status_get_i64(const char* name, ib_i64_t* dst);
   

    void ib_set_client_compare(ib_client_cmp_t client_cmp_func);
   

    ib_err_t ib_schema_tables_iterate(
             ib_trx_t        ib_trx,
             ib_schema_visitor_table_all_t visitor,
             void*           arg);
   

visitor.tables(arg, const char* tablename, int tablename_len)

   ib_err_t ib_table_schema_visit(
             ib_trx_t        ib_trx,
             const char*     name,
             const ib_schema_visitor_t*  visitor,
             void*           arg);
   

             visitor->table()
             visitor->table_col() for each user column
             visitor->index() for each user index
             visitor->index_col() for each column in user index
   

    ib_err_t ib_schema_lock_exclusive(ib_trx_t ib_trx);
   

    ib_err_t ib_schema_lock_shared(ib_trx_t ib_trx);
   

    ib_bool_t ib_schema_lock_is_exclusive(const ib_trx_t ib_trx);
   

    ib_bool_t ib_schema_lock_is_shared(const ib_trx_t ib_trx);
   

    ib_err_t ib_schema_unlock(ib_trx_t ib_trx);
   

    ib_err_t ib_cursor_truncate(ib_crsr_t* ib_crsr, ib_id_t* id);
   

    ib_err_t ib_table_truncate(const const* name, ib_id_t* table_id);
   

    ib_err_t ib_table_get_id(const char* table_name, ib_id_t* table_id);
   

    ib_err_t ib_index_get_id(
             const char*     table_name,
             const char*     index_name,
             ib_id_t*        index_id);
   

    void ib_logger_set(ib_msg_log_t ib_msg_log, ib_msg_stream_t ib_msg_stream);
   

    const char* ib_strerror(ib_err_t db_errno);
   

These functions work with tuples. To understand how tuples relate to queries and other operations using a WHERE clause, see Section 1.4, “Overview of Queries and WHERE Clauses”. For usage information, see Section 4.3.5, “Emulating a WHERE Clause”. To see these APIs in action, look in the sample programs listed in Appendix B, Code Examples Supplied with Embedded InnoDB.

    ib_tpl_t ib_sec_read_tuple_create(ib_crsr_t ib_crsr);
   

    ib_tpl_t ib_sec_search_tuple_create(ib_crsr_t ib_crsr);
   

    ib_tpl_t ib_clust_read_tuple_create(ib_tpl_t ib_tpl);
   

    ib_tpl_t ib_clust_search_tuple_create(ib_crsr_t ib_crsr);
   

    ib_err_t ib_tuple_get_cluster_key(
             ib_crsr_t       ib_crsr,
             ib_tpl_t*       ib_dst_tpl,
             const ib_tpl_t  ib_src_tpl);
   

    void ib_tuple_delete(ib_tpl_t ib_tpl);
   

    ib_ulint_t ib_tuple_get_n_cols(const ib_tpl_t ib_tpl);
   

    ib_ulint_t ib_tuple_get_n_user_cols(const ib_tpl_t ib_tpl);
   

    ib_err_t ib_tuple_copy(ib_tpl_t ib_dst_tpl, const ib_tpl_t ib_src_tpl);
   

    ib_tpl_t ib_tuple_clear(ib_tpl_t ib_tpl);
   

    ib_ulint_t ib_col_get_meta(
             ib_tpl_t        ib_tpl,
             ib_ulint_t      col_no,
             ib_col_meta_t   ib_col_meta);
   

    const void* ib_col_get_value(ib_tpl_t ib_tpl, ib_ulint_t col_no);
   

    ib_ulint_t ib_col_copy_value(
             ib_tpl_t        ib_tpl,
             ib_ulint_t      col_no,
             void*           dst,
             ib_ulint_t      max_len);
   

    ib_ulint_t ib_col_get_len(ib_tpl_t ib_tpl, ib_ulint_t col_no);
   

    ib_err_t ib_col_set_value(
             ib_tpl_t        ib_tpl,
             ib_ulint_t      col_no,
             const void*     src,
             ib_ulint_t      len);
   

    ib_err_t ib_tuple_read_i8(ib_tpl_t ib_tpl, int col_no, ib_i8_t* val);
    ib_err_t ib_tuple_read_u8(ib_tpl_t ib_tpl, int col_no, ib_i8_t* val);
    ib_err_t ib_tuple_read_i16(ib_tpl_t ib_tpl, int col_no, ib_i16_t* val);
    ib_err_t ib_tuple_read_u16(ib_tpl_t ib_tpl, int col_no, ib_u16_t* val);
    ib_err_t ib_tuple_read_i32(ib_tpl_t ib_tpl, int col_no, ib_i32_t* val);
    ib_err_t ib_tuple_read_u32(ib_tpl_t ib_tpl, int col_no, ib_i32_t* val);
    ib_err_t ib_tuple_read_i64(ib_tpl_t ib_tpl, int col_no, ib_i64_t* val);
    ib_err_t ib_tuple_read_u64(ib_tpl_t ib_tpl, int col_no, ib_u64_t* val);
    ib_err_t ib_tuple_read_float(ib_tpl_t ib_tpl, int col_no, float* val);
    ib_err_t ib_tuple_read_double(ib_tpl_t ib_tpl, int col_no, double* val);
   

    ib_err_t ib_tuple_write_i8(ib_tpl_t ib_tpl, int col_no, ib_i8_t val);
    ib_err_t ib_tuple_write_u8(ib_tpl_t ib_tpl, int col_no, ib_i8_t val);
    ib_err_t ib_tuple_write_i16(ib_tpl_t ib_tpl, int col_no, ib_i16_t val);
    ib_err_t ib_tuple_write_u16(ib_tpl_t ib_tpl, int col_no, ib_u16_t val);
    ib_err_t ib_tuple_write_i32(ib_tpl_t ib_tpl, int col_no, ib_i32_t val);
    ib_err_t ib_tuple_write_u32(ib_tpl_t ib_tpl, int col_no, ib_i32_t val);
    ib_err_t ib_tuple_write_i64(ib_tpl_t ib_tpl, int col_no, ib_i64_t val);
    ib_err_t ib_tuple_write_u64(ib_tpl_t ib_tpl, int col_no, ib_u64_t val);
    ib_err_t ib_tuple_write_float(ib_tpl_t ib_tpl, int col_no, float val);
    ib_err_t ib_tuple_write_double(ib_tpl_t ib_tpl, int col_no, double val);