Database Operations Using C Driver

In a NuoDB C client application, the common database operations you will want to perform are:

Connecting to a database
Closing a database connection
Creating statements and prepared statements
Executing SQL statements
Committing or rolling back transactions

Connecting to a Database

To persist data, a connection to a NuoDB database must be established. To obtain a connection handle, see the following example:

NuoDB_Connection* connectDB(const char* dbName)
{
    NuoDB_Connection* connection = NULL;
    NuoDB_Options* options = NULL;

    connection = NuoDB_Connection_create();
    options = NuoDB_Options_create();
    options->add(options, "schema", "hello");
    CHECK_SUCCESS(connection->openDatabase(connection,
                                           dbName,
                                           "dba", /* username */
                                           "goalie",  /* password */
                                           options));
    NuoDB_Options_Free(options);

    /* disable auto-commit mode */
    connection->setAutoCommit(connection, NUODB_FALSE);

    return connection;
}

The NuoDB_Connection type is the client’s handle that represents a connection to a NuoDB database.

The NuoDB_Options type represents a set of connection options.

The openDatabase() function takes the following arguments:

The first argument is a pointer to the NuoDB database connection.
The dbName argument is a string in the following format:
```
[.var]__database_name__++[++@[.var]__host__++[++:[.var]__port__++]++++]++
```
Where database_name is the name of the database.
host is the name or IP Address of the machine on which the NuoDB broker is running.
port is the port on which the NuoDB broker is listening.
IPv4 literal addresses are specified as a.b.c.d:port
IPv6 literal addresses are specified as [a:b:…]:port

You might want to specify more than one value for dbName, perhaps by varying the host and port. If you specify more than one value, the driver tries the dbName specified first. If the connection succeeds then the other specifications are not tried. If the first specification fails then the driver tries the second specification and so on. Use a comma to separate multiple specifications. For example:`test,test@localhost,test@localhost:48004`
The third argument is a string for the user name for accessing the database.
The fourth argument is a string for the password for accessing the database.
The last argument contains the options for connecting to the database.

Closing a Database Connection

When you are finished with the database connection, you should release the database connection resources by calling:

NuoDB_Connection_Free(connection);

Creating Statements and Prepared Statements

The NuoDB_Statement type lets you create parameterized and non-parameterized statements. The following code uses the NuoDB_Statement type to create a statement that creates the names table.

void createTable(NuoDB_Connection* connection)
{
    int status = 0;
    NuoDB_Statement* stmt = NULL;
    stmt = NuoDB_Statement_Create(connection);
    status = stmt->executeSQL(stmt,
       "create table names \
        (id bigint generated always as identity primary key, \
        name string)", NUODB_NO_FLAGS);
    if (status != NUODB_SUCCESS) {
        CHECK_SUCCESS(connection->rollback(connection));
        printf("The table 'NAMES' already exists, re-using it.\n");
    } else {
        CHECK_SUCCESS(connection->commit(connection));
        printf("The table 'NAMES' was created.\n");
    }
    NuoDB_Statement_Free(stmt);
}

Executing SQL Statements

There are two NuoDB_Statement functions for executing SQL statements:

Function	Description
executeSQL()	Executes a non-parameterized SQL statement in a single request. It returns 0 if successful or an error code if not successful.
execute()	Executes a parameterized SQL statement that has been prepared and whose parameters have been bound. It returns 0 if successful or an error code if not successful.

Function

Description

executeSQL()

Executes a non-parameterized SQL statement in a single request. It returns 0 if successful or an error code if not successful.

execute()

Executes a parameterized SQL statement that has been prepared and whose parameters have been bound. It returns 0 if successful or an error code if not successful.

Committing or Rolling Back Transactions

To commit persistent work, you should call the commit() function on the connection type:

connection->commit(connection)

To roll back persistent work, you should call the rollback() function on the connection type:

connection->rollback(connection)