Client 1 - Connecting to the Server

Client 1 ”Connecting to the Server

Connecting to a database using libpgeasy is simple. libpgeasy provides a single connection function:

 PGconn * connectdb( char * options ); 

The single argument to connectdb() is a connection string in the same form expected by the libpq PQconnectdb() function. An example connection string might look like this:

 char * connectString = "dbname=movies user=sheila"; 

Let's look at a simple client that uses the connectdb() function:

 /* client1.c */ #include <stdlib.h> #include <libpq-fe.h> #include <libpgeasy.h> int main( int argc, char * argv[] ) {   connectdb( argv[1] ? argv[1] : "" );   disconnectdb();   exit( EXIT_SUCCESS ); } 

This example shows the minimum required code for a libpgeasy application. You must #include two files: libpq-fe.h and libpgeasy.h , and you must #include them in that order ^[1] .

^[1] libpqeasy refers to items in libqp-fe , so they must be #include d in that order.

In the call to connectdb() , I've passed in the first command-line argument (or an empty string if there are no command-line arguments). When you run this program, you should provide a connection string as the only argument. If you need to specify more than one connection property, enclose the list in double quotes and separate the properties with a space. Here are two examples:

 $ ./client1 dbname=movies $ ./client1 "dbname=movies user=sheila" 

After the connectdb() function returns, I call disconnectdb() . The function prototype for disconnectdb() is

 void disconnectdb( void ); 

Notice that disconnectdb() does not expect any arguments. You may have also noticed that I did not capture any return value from the call to connectdb() .

How does libpgeasy know which connection I want to terminate? In keeping with the goal of simplicity, libpgeasy remembers the database connection for me. When I call connectdb() , libpgeasy stores (in a private variable) the PGconn pointer. When I call disconnectdb() , it uses the stored connection pointer. Although libpgeasy has the capacity to remember the database connection, it will remember only one connection at a time. This is one example of the tradeoffs made when using libpgeasy versus libpq ”you have gained simplicity, but lost some flexibility.

If you want, you can capture the return value from connectdb() in a PGconn pointer variable and use it in the same ways that you could use a PGconn * through libpq.

Now let's run this client application to see what it does:

 $ ./client1 dbname=movies $ 

Exciting, don't you think? Let's try that again, feeding it an erroneous database name this time:

 $ ./client1 dbname=foofoo Connection to database using 'dbname=foofoo' failed. FATAL 1:  Database "foofoo" does not exist in the system catalog. $ 

This time, you can see that libpgeasy produced an error message. The client1.c source code doesn't include any error handling at all ”you didn't include any code to check for errors or to print error messages. Again, this is consistent with the goal of simplicity. Of course, in a sophisticated application, you probably want a little more control over the handling of error conditions.