Home > Quick start > Build an application >

Build a C application

The following tutorial shows a small C application that connects to a YugabyteDB cluster using the libpq driver and performs basic SQL operations. Use the application as a template to get started with Yugabyte Cloud in C.

Prerequisites

32-bit (x86) or 64-bit (x64) architecture machine. (Use Rosetta to build and run on Apple silicon.)
gcc 4.1.2 or later, or clang 3.4 or later installed.
OpenSSL 1.1.1 or later (used by libpq to establish secure SSL connections).
libpq. Homebrew users on macOS can install using brew install libpq. You can download the PostgreSQL binaries and source from PostgreSQL Downloads.

Yugabyte Cloud

You have a cluster deployed in Yugabyte Cloud. To get started, use the Quick start.
You downloaded the cluster CA certificate. Refer to Download your cluster certificate.
You have added your computer to the cluster IP allow list. Refer to Assign IP Allow Lists.

Clone the application from GitHub

Clone the sample application to your computer:

git clone https://github.com/yugabyte/yugabyte-simple-c-app && cd yugabyte-simple-c-app

Provide connection parameters

The application needs to establish a connection to the YugabyteDB cluster. To do this:

Open the sample-app.c file.
Set the following configuration-related macros:
- HOST - the host name of your YugabyteDB cluster. To obtain a Yugabyte Cloud cluster host name, sign in to Yugabyte Cloud, select your cluster on the Clusters page, and click Settings. The host is displayed under Network Access.
- PORT - the port number that will be used by the driver (the default YugabyteDB YSQL port is 5433).
- DB_NAME - the name of the database you are connecting to (the default database is named yugabyte).
- USER and PASSWORD - the username and password for the YugabyteDB database. If you are using the credentials you created when deploying a cluster in Yugabyte Cloud, these can be found in the credentials file you downloaded.
- SSL_MODE - the SSL mode to use. Yugabyte Cloud requires SSL connections; use verify-full.
- SSL_ROOT_CERT - the full path to the Yugabyte Cloud cluster CA certificate.
Save the file.

Build and run the application

Build the application with gcc or clang.

gcc sample-app.c -o sample-app -I<path-to-libpq>/libpq/include -L<path-to-libpq>/libpq/lib -lpq

Replace <path-to-libpq> with the path to the libpq installation; for example, /usr/local/opt.

Start the application.

$ ./sample-app

You should see output similar to the following:

>>>> Successfully connected to YugabyteDB!
>>>> Successfully created table DemoAccount.
>>>> Selecting accounts:
name = Jessica, age = 28, country = USA, balance = 10000
name = John, age = 28, country = Canada, balance = 9000
>>>> Transferred 800 between accounts.
>>>> Selecting accounts:
name = Jessica, age = 28, country = USA, balance = 9200
name = John, age = 28, country = Canada, balance = 9800

You have successfully executed a basic C application that works with Yugabyte Cloud.

Explore the application logic

Open the sample-app.c file in the yugabyte-simple-c-app folder to review the methods.

connect

The connect method establishes a connection with your cluster via the libpq driver.

PQinitSSL(1);

conn = PQconnectdb(CONN_STR);

if (PQstatus(conn) != CONNECTION_OK) {
    printErrorAndExit(conn, NULL);
}

printf(">>>> Successfully connected to YugabyteDB!\n");

return conn;

createDatabase

The createDatabase method uses PostgreSQL-compliant DDL commands to create a sample database.

res = PQexec(conn, "DROP TABLE IF EXISTS DemoAccount");

if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

res = PQexec(conn, "CREATE TABLE DemoAccount ( \
                    id int PRIMARY KEY, \
                    name varchar, \
                    age int, \
                    country varchar, \
                    balance int)");

if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

res = PQexec(conn, "INSERT INTO DemoAccount VALUES \
                    (1, 'Jessica', 28, 'USA', 10000), \
                    (2, 'John', 28, 'Canada', 9000)");

if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

selectAccounts

The selectAccounts method queries your distributed data using the SQL SELECT statement.

res = PQexec(conn, "SELECT name, age, country, balance FROM DemoAccount");

if (PQresultStatus(res) != PGRES_TUPLES_OK) {
    printErrorAndExit(conn, res);
}

for (i = 0; i < PQntuples(res); i++) {
    printf("name = %s, age = %s, country = %s, balance = %s\n",
        PQgetvalue(res, i, 0), PQgetvalue(res, i, 1), PQgetvalue(res, i, 2), PQgetvalue(res, i, 3));
}

transferMoneyBetweenAccounts

The transferMoneyBetweenAccounts method updates your data consistently with distributed transactions.

res = PQexec(conn, "BEGIN TRANSACTION");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

res = PQexec(conn, "UPDATE DemoAccount SET balance = balance - 800 WHERE name = \'Jessica\'");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

res = PQexec(conn, "UPDATE DemoAccount SET balance = balance + 800 WHERE name = \'John\'");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

res = PQexec(conn, "COMMIT");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
    printErrorAndExit(conn, res);
}

Learn more

libpq driver

Explore more applications

Deploy clusters in Yugabyte Cloud

Connect to applications in Yugabyte Cloud