WiredTiger(3) Getting Started with the API

Connecting to a database

To access a database, first open a connection and create a session handle for the single thread accessing the database:

        WT_CONNECTION *conn;
        WT_CURSOR *cursor;
        WT_SESSION *session;
        const char *key, *value;
        int ret;
         * Create a clean test directory for this run of the test program if the
         * environment variable isn't already set (as is done by make check).
        if (getenv("WIREDTIGER_HOME") == NULL) {
                home = "WT_HOME";
                ret = system("rm -rf WT_HOME && mkdir WT_HOME");
        } else
                home = NULL;
        /* Open a connection to the database, creating it if necessary. */
        if ((ret = wiredtiger_open(home, NULL, "create", &conn)) != 0 ||
            (ret = conn->open_session(conn, NULL, NULL, &session)) != 0) {
                fprintf(stderr, "Error connecting to %s: %s,
                    home, wiredtiger_strerror(ret));
                return (ret);

 The configuration string 'create' is passed to wiredtiger_open to indicate the database should be created if it does not already exist.

The code block above also shows simple error handling with wiredtiger_strerror (a function that returns a string describing an error code passed as its argument). More complex error handling can be configured by passing an implementation of WT_EVENT_HANDLER to wiredtiger_open or WT_CONNECTION::open_session.

Creating a table

Create a table we can use to store data:

        ret = session->create(session,
            "table:access", "key_format=S,value_format=S");

 This call creates a table called 'access', configured to use strings for its key and value columns. (See Schema, Columns, Column Groups, Indices and Projections for more information on tables with other types of key and value columns.)

Accessing data with cursors

Now that we have a table, we open a cursor to perform some operations on it:

        ret = session->open_cursor(session,
            "table:access", NULL, NULL, &cursor);

 Here, the string 'table:access' specifies that we are opening the cursor on the table named 'access'.

Then we insert a new row into the table. The WT_CURSOR::set_key and WT_CURSOR::set_value calls put the application's key and value into the cursor, respectively. The WT_CURSOR::insert call creates a record containing that value and inserts it into the table.

        cursor->set_key(cursor, "key1");        /* Insert a record. */
        cursor->set_value(cursor, "value1");
        ret = cursor->insert(cursor);

 Now we iterate through all of the records in the table, printing them out as we go:

        ret = cursor->reset(cursor);            /* Restart the scan. */
        while ((ret = cursor->next(cursor)) == 0) {
                ret = cursor->get_key(cursor, &key);
                ret = cursor->get_value(cursor, &value);
                printf("Got record: %s : %s, key, value);

 Note that the key and value parts of the records are returned as C strings because the table was created that way (even if it was created by a previous run of the example). No data extraction or conversion is required in the application.

Because the cursor was positioned in the table after the WT_CURSOR::insert call, we had to re-position it using the WT_CURSOR::first call; if we weren't using the cursor for the call to WT_CURSOR::insert above, this loop would simplify to:

while ((ret = cursor->next(cursor)) == 0) {

Closing handles

Lastly, we close the connection, which implicitly closes the cursor and session handles:

        ret = conn->close(conn, NULL);