Extending PostgreSQL with own C functions

Power of open source, if you are not happy with what PostgreSQL currently offers, you write own extension in C. Compile code with your functions into shared library, install it and they will become available from PostgreSQL. OK there are some rules and procedures. Once we are inside PostgreSQL we are using its types, interfaces and utilities. Let us do Hello World example. To build example you will need postgresql-server-dev-9.1 or whatever version you are using, installed on your Linux box.

#include "postgres.h" #include <string.h> #include "fmgr.h" #include "utils/builtins.h" #ifdef PG_MODULE_MAGIC PG_MODULE_MAGIC; #endif PG_FUNCTION_INFO_V1(say_hello_n); Datum say_hello_n(PG_FUNCTION_ARGS) { text *arg1 = cstring_to_text("Hello "); text *arg2 = PG_GETARG_TEXT_P(0); int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ; text *new_text = (text *) palloc(new_text_size); SET_VARSIZE(new_text, new_text_size); memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1) - VARHDRSZ); memcpy(VARDATA(new_text) + (VARSIZE(arg1) - VARHDRSZ), VARDATA(arg2), VARSIZE(arg2) - VARHDRSZ); PG_RETURN_TEXT_P(new_text); }

As we can see we are using new V1 spec. That is modified concat_text example from PostgreSQL documentation, look for 35.9.4. Version 1 Calling Conventions. We have load of different VAR macros. For example:

VARHDRSZ is the same as sizeof(int4), but it's considered good style to use the macro VARHDRSZ to refer to the size of the overhead for a variable-length type.

That is from PostgreSQL documentation. SET_VARSIZE we can find in includes postgres.h

#define SET_VARSIZE_4B(PTR,len) \ (((varattrib_4b *) (PTR))->va_4byte.va_header = (((uint32) (len)) << 2))

Unless you are on big endian. Going through header file one also can read in comments more about Datum and varlena datatypes. Then we got palloc which corresponds to malloc, memcpy you already know and GET and RETURN macros. It is obvious that for writing extensions one needs to familiarize himself with PostgreSQL internals. Power without knowledge and responsibility exists only in fery tails told by “software evangelists” at annual developers developers developers meetings.
Variables passed around by PostgreSQL may be on the disc, do not change them.
To build shared library I used the following Makefile:

MODULES = say_hello PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS)

Rather long story to get location of pgxs. That pgxs is location of makefiles for building extensions. It is not trivial build and using provided mk files is right way to do it. After that we can copy say_hello.so to some reasonable location or give full path to it in create function declaration.

CREATE FUNCTION say_hello(text) RETURNS text AS '/opt/pg/ext/say_hello', 'say_hello_n' LANGUAGE C STRICT; ------- select say_hello('Filip');

PostgreSQL already allows Python through untrusted language PL/Python. One can utilize power of Python for functions or triggers without learning much about PostgreSQL internals. But again if you need power and speed, you can use what PostgreSQL speaks internally and that is C.

SQLite parameterized query in C

Still very angry at Discovery Health but that is not reason to stop using C. To execute parameterized query we prepare SQL statement with one or more placeholders. Placeholder could be question mark, alone or followed by number, column, dollar sign or at sign followed by alphanumeric. For example:

select title, full_name from jane where id = @id;

We prepare such statement using sqlite3_prepare_v2, later we bind our parameter and finally execute query. To do binding we will use appropriate function, there is few of them:

int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); int sqlite3_bind_null(sqlite3_stmt*, int); int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

All bind functions will return SQLITE_OK if binding is successful or error code if it fails. The first argument is handle to prepared statement. The second argument is index of parameter. The third argument is value to be set. For blob, text we have the fourth argument, size in bytes and the fifth – destructor function. Instead of destructor function we can pass constants SQLITE_STATIC - do nothing or SQLITE_TRANSIENT – make local copy and free it when done. To find out what is index of parameter we are using this function:

int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

We pass prepared statement and parameter name it returns zero if there is no such parameter or parameter index if it exists. Even if we know that our parameter must have index one, we will still look for it to demonstrate how it is done. Here is the code:

#include <sqlite3.h> #include <stdio.h> #include <string.h> int main(int argc, char **argv) { int rc, i, v, col; sqlite3 *db; sqlite3_stmt *stmt; char *sql; rc = sqlite3_open_v2("surogat.db", &db, SQLITE_OPEN_READWRITE, NULL); if(rc != SQLITE_OK) { printf("Can't open database: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); return 1; } sql = "select title, full_name from jane where id = @id"; rc = sqlite3_prepare_v2(db, sql, strlen(sql), &stmt, 0); if(rc != SQLITE_OK) { printf("SQL error: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); return 1; } i = sqlite3_bind_parameter_index(stmt, "@id"); v = 3; rc = sqlite3_bind_int(stmt, i, v); if(rc != SQLITE_OK) { printf("SQL error: %s\n", sqlite3_errmsg(db)); sqlite3_finalize(stmt); sqlite3_close(db); return 1; } rc = sqlite3_step(stmt); col = sqlite3_column_count(stmt); for(i=0; i < col; i++) { printf("%s\t",sqlite3_column_name(stmt, i)); } printf("\n-----------------\n"); while(rc == SQLITE_ROW) { for(i=0; i < col; i++) { printf("%s\t", sqlite3_column_text(stmt, i)); } printf("\n"); rc = sqlite3_step(stmt); } sqlite3_finalize(stmt); sqlite3_close(db); return 0; }

Database should be loaded with required values in previous examples, if not here is sql to create it:

CREATE TABLE jane ( id INTEGER PRIMARY KEY NOT NULL, title TEXT, full_name TEXT NOT NULL )
INSERT INTO jane VALUES(1,'Mr','Smith');
INSERT INTO jane VALUES(2,'Mrs','Doe');
INSERT INTO jane VALUES(3,'Mr','Doe');

After we build it using:

gcc -g test.c -lsqlite3 -o test

We execute test and see the following output:

title full_name ----------------- Mr Doe

We could also misspell parameter name and rebuild to check is error handling working.

PostgreSQL, libpqxx and prepared statement example

As I promised, if people are finding interesting introductory article,  I will write more about PostgreSQL and libpqxx. But before I start with programming – rant.
I am still looking for work and finding none. Today went to Discovery Health, had very pleasant 45 minutes chat with their architect and BA and promise that we will talk again. Later guy from employment agency, who arranged meeting, calls and says that they do not want me since I do not have ANSI C in CV?! Like somebody from management decided to override decision of interviewers. If ANSI C in CV is precondition, why they wasted my time and invited me for interview? I wish them the same from their customers. BTW I am usually employed as senior developer and not as C developer or, Perl developer.
Back to programming, this time C++, had enough of ANSI C for today. Environment is Linux, I am using the same PostgreSQL and libpqxx as last time and to compile example we will use:

g++ hello_prep.cxx -o hello_prep -I/usr/local/include/ -lpqxx -lpq

This time I used test092.cxx, run dpkg with -L switch on libpqxx3-doc to see where is it. It tests passing binary parameter to prepared statement. Test macros are replaced with printing of tested values to standard output and setup of connection/transaction is included. Here is the code:

#include <iostream> #include <pqxx/pqxx> using namespace std; using namespace pqxx; int main(int argc, char** argv) { connection C("dbname=testpgdb user=testuser password=testpass hostaddr=127.0.0.1 port=5432"); if (C.is_open()) { cout << "We are connected to" << C.dbname() << endl; } else { cout << "We are not connected!" << endl; return 0; } work T(C); const char databuf[] = "Test\0data"; const string data(databuf, sizeof(databuf)); cout << "data.size() = " << data.size() << endl; cout << "databuf size = " << sizeof(databuf) << endl; const string Table = "pqxxbin", Field = "binfield", Stat = "nully"; T.exec("CREATE TEMP TABLE " + Table + " (" + Field + " BYTEA)"); if (!T.conn().supports(connection_base::cap_prepared_statements)) { cout << "Backend version does not support prepared statements. Skipping." << endl; return 0; } T.conn().prepare(Stat, "INSERT INTO " + Table + " VALUES ($1)") ("BYTEA", pqxx::prepare::treat_binary); T.prepared(Stat)(data).exec(); const result L( T.exec("SELECT length("+Field+") FROM " + Table) ); cout << "data.size() = " << data.size() << endl; cout << "L[0][0].as<size_t>() = " << L[0][0].as<size_t>() << endl; const result R( T.exec("SELECT " + Field + " FROM " + Table) ); const binarystring roundtrip(R[0][0]); cout << "roundtrip.str() = " << roundtrip.str() << endl; cout << "data = " << data << endl; cout << "roundtrip.size() = " << roundtrip.size() << endl; cout << "data.size() = " << data.size() << endl; T.exec("CREATE TEMP TABLE tuple (one INTEGER, two VARCHAR)"); pqxx::prepare::declaration d( T.conn().prepare("maketuple", "INSERT INTO tuple VALUES ($1, $2)") ); d("INTEGER", pqxx::prepare::treat_direct); d("VARCHAR", pqxx::prepare::treat_string); pqxx::prepare::invocation i( T.prepared("maketuple") ); const string f = "frobnalicious"; i(6); i(f); i.exec(); const result t( T.exec("SELECT * FROM tuple") ); cout << "t.size()= " << t.size() << endl; cout << "sz = " << 1u << endl; cout << "t[0][0].as<string>() = " << t[0][0].as<string>() << endl; cout << "l = " << 6 << endl; cout << "t[0][1].c_str() = " << t[0][1].c_str() << endl; cout << "f = " << f << endl; return 0; }

After connection is successfully obtained, transaction T is constructed. Temp table is created and after confirmation that prepared statements are supported, testing goes on. We have prepare::declaration and prepare::invocation, available in reference generated with doxygen. Adding parameters is in iterative fashion and feels natural, as they say in documentation like varargs from C. Library is well designed and easy to use, documentation, tutorial and tests are supplied. Lengths and contents should match and test succeeds.

SQLite C API another convenience routine example

Last time we presented sqlite3_exec example. Beside sqlite3_exec we can use wrapper around  sqlite3_exec and that is sqlite3_get_table. We will get, if call is successful, array of UTF-8 zero terminated strings and we have to free that array at the end. Here is interface for sqlite3_get_table and sqlite3_free_table:

int sqlite3_get_table( sqlite3 *db, /* An open database */ const char *zSql, /* SQL to be evaluated */ char ***pazResult, /* Results of the query */ int *pnRow, /* Number of result rows written here */ int *pnColumn, /* Number of result columns written here */ char **pzErrmsg /* Error msg written here */ ); void sqlite3_free_table(char **result);

It is quite self-explanatory. Number of rows doesn't count column names and we need to add one to it. Cleanup is required in the any case, if all is ОК we need to call sqlite3_free_table, if there is failure we need to do cleanup of error message, like with  sqlite3_exec. We will retrieve content of that jane table from sqlite3_exec example, then we inserted three rows into table. Here is the code:

#include <sqlite3.h> #include <stdio.h> int main(void) { sqlite3 *db; char *err_msg = NULL, *sql = NULL, **pazResult = NULL; int row, col,i,j; int rc = sqlite3_open_v2("test.db", &db, SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE, NULL); if (rc != SQLITE_OK) { printf("Failure to open database: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); return 1; } sql = "select * from jane;"; rc = sqlite3_get_table(db, sql, &pazResult, &row, &col, &err_msg); if (rc != SQLITE_OK ) { printf("Get table failure: %s\n", err_msg); sqlite3_free(err_msg); sqlite3_close(db); return 1; } for(i=0;i<row+1;i++){ for(j=0;j<col;j++) printf("%s\t",*(pazResult+i*col+j)); printf("\n"); } sqlite3_free_table(pazResult); sqlite3_close(db); return 0; }

Very simple and very user friendly API. If we build and execute binary, we should get error:

Get table failure: no such table: jane

Our table is in surogat.db, we repair example, recompile and we should see table printout:

id title full_name 1 Mr Smith 2 Mrs Doe 3 Mr Doe

That is legacy interface and usage is not recommended, though it is very user friendly and that is the reason I supplied example.
As usual, example is built on Linux using gcc and successfully tested. Didn't try on different OS or compiler.

Tests, pointers, arrays and GDB

While I was looking for work, actually I am still looking for work, they sent me to do some tests. Those are some “tech check” rubbish tests which are testing how much of man pages you know by hart. Not do you have logic of programmer and real working knowledge but how well have you memorized help files. So let me explain how you are going to deal with those test and real life problems in sensible way. While agile approach is very desirable in project management, memorizing help files is what industry expects from programmers. Everything further happens on Linux and we will do some debugging to find out answers.
About every book teaching C contains story how one can declare array and access array elements via pointer arithmetic. Something like this:

int arr1d[] = {1, 2, 3, 4, 5}, i; for(i=0;i<5;i++) printf("i = %d; %d = %d = %d\n", i, *arr1d+i, *(arr1d+i), arr1d[i]);

Expression *arr1d+i is not really pointer arithmetic since dereferencing will happen before addition, and everybody who worked in C longer than two weeks knows it, but it will also produce desired result. I also omitted array length and gcc managed to read it from initializer. Now we can declare some pointers and assign address of our array to them.

int *p1d = arr1d; for(i=0;i<5;i++) printf("i = %d; %d = %d\n", i, *(p1d+i), p1d[i]);

Array is just pointer to its first element, we got type and everything right. If we now take address of array we will have double pointer? Not really.

int **p1d12 = &arr1d;

Produces this warning:

warning: initialization from incompatible pointer type [enabled by default]

Since we do not know what is wrong, what type for pointer to array we are getting instead double pointer to integer, we will ask GDB. This is the code:

#include <stdio.h> int main(){ int arr1d[] = {1, 2, 3, 4, 5}, i; for(i=0;i<5;i++) printf("i = %d; %d = %d = %d\n", i, *arr1d+i, *(arr1d+i), arr1d[i]); int *p1d = arr1d; for(i=0;i<5;i++) printf("i = %d; %d = %d\n", i, *(p1d+i), p1d[i]); int **p1d12 = &arr1d; /* not really */ int *p1d11 = &arr1d[0]; return 0; }

and we will save it as untitled.c and build using

gcc -g -Wall -o untitled untitled.c
untitled.c: In function ‘main’:
untitled.c:12:16: warning: initialization from incompatible pointer type [enabled by default]
untitled.c:13:7: warning: unused variable ‘p1d11’ [-Wunused-variable]
untitled.c:12:8: warning: unused variable ‘p1d12’ [-Wunused-variable]

This is together with output. Switch -g means that we want debugg info and -Wall that we want all warnings. Now we start interactive session and ask GDB what we want to know:

gdb untitled GNU gdb (Ubuntu/Linaro 7.4-2012.04-0ubuntu2.1) 7.4-2012.04 Copyright (C) 2012 Free Software Foundation, Inc. … more advertising stuff … Reading symbols from ~/workshop/lrhw/untitled...done. (gdb) start Temporary breakpoint 1 at 0x4004fc: file untitled.c, line 4. Starting program: ~/workshop/lrhw/untitled Temporary breakpoint 1, main () at untitled.c:4 4 int arr1d[] = {1, 2, 3, 4, 5}, i; (gdb) info locals arr1d = {-6136, 32767, 4195877, 0, 1} i = 0 p1d = 0x0 p1d12 = 0x400410 p1d11 = 0x7fffffffe7f0 (gdb) next 5 for(i=0;i<5;i++) (gdb) info locals arr1d = {1, 2, 3, 4, 5} i = 0 p1d = 0x0 p1d12 = 0x400410 p1d11 = 0x7fffffffe7f0 (gdb) print arr1d $1 = {1, 2, 3, 4, 5} (gdb) print &arr1d $2 = (int (*)[5]) 0x7fffffffe6d0

It printed few lines of messages about license, where to report bugs and similar and loaded symbols for untitled. On prompt (gdb) we type in start and it starts and breaks on the first possible line. We try info locals and see that array is not initialized yet, so we execute next. Now array is initialized and we print it. Finally we ask it to print &arr1d and we learn what is the type of our “double pointer”.

int (*p1d12)[] = &arr1d;

This is what address of array returns and how “double pointer” should be declared, really ugly question on some idiotic test.
Things are becoming more interesting with multidimensional arrays. For example:

int arr2d[][4] = {{1, 2, 3, 4}, {5, 6, 7, 8}};

We can not omit everything even if we are supplying initializer, just the first square bracket may be empty. How about asking some questions? Start GDB session and ask all what you need to know:

(gdb) print &arr2d $1 = (int (*)[2][4]) 0x7fffffffe630 (gdb) print &arr2d[0] $2 = (int (*)[4]) 0x7fffffffe630 (gdb) print &arr2d[1] $3 = (int (*)[4]) 0x7fffffffe640 (gdb) print *arr2d $4 = {1, 2, 3, 4} (gdb) x 0x7fffffffe640 0x7fffffffe640: 0x00000005 (gdb) print **arr2d $5 = 1 (gdb) print **arr2d+1 $6 = 2 (gdb) print **(arr2d+1) $7 = 5 (gdb) print *(*arr2d+1) $8 = 2

Simple as that. There is one more question left, what will happen with double pointer initialized to address of array, why it not working? Again we are agile and write code:

int arr2d[][4] = {{1, 2, 3, 4}, {5, 6, 7, 8}}; int **p = arr2d; printf("*p = %d \n", *p);

That will execute and print *p = 1?! Start GDB session and check what is happening:

(gdb) p **p Cannot access memory at address 0x200000001 (gdb) p *p $1 = (int *) 0x200000001 (gdb) p sizeof(*p) $2 = 8 (gdb) p p $3 = (int **) 0x7fffffffe6e0 (gdb) x 0x7fffffffe6e0 0x7fffffffe6e0: 0x00000001 (gdb) x 0x7fffffffe6e4 0x7fffffffe6e4: 0x00000002 (gdb) x 0x7fffffffe6e8 0x7fffffffe6e8: 0x00000003 (gdb) p **arr2d $4 = 1 (gdb) p *arr2d $5 = {1, 2, 3, 4} (gdb) p sizeof(*arr2d) $6 = 16

Abbreviated print is p and x will print content of memory at some address. Array is not just pointer, there is size of it what counts. If we have used ld format in printf, we would see slightly bigger output than just one ;-)
That would be such lovely question for test, what would be output if we replace %d with %ld? Naturally it will be *p = 8589934593!
Ask yourself stupid questions for fun and for profit.

More SQLite C API

In previous instalment we used sqlite3_open and sqlite3_prepare to connect to db file and execute select statement. Let us take a better look at it again. Those functions are legacy interface, we could use new sqlite3_open_v2 and sqlite3_prepare_v2 which are allowing us more control over execution and they are also recommended by SQLite development team. Let us look at sqlite3_open. This is from SQLite documentation:

int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); int sqlite3_open16( const void *filename, /* Database filename (UTF-16) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); int sqlite3_open_v2( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb, /* OUT: SQLite db handle */ int flags, /* Flags */ const char *zVfs /* Name of VFS module to use */ );

In all three cases, the first argument is name of database file to be opened and the second one is handle:

typedef struct sqlite3 sqlite3;

We will need that handle to manipulate db and close it at the end. From comment we see that string with name of db file could be UTF-8 or UTF-16 encoded. What are flags? Here are definitions:

#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */ #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */

I will wisely skip last four, for now. If we specify SQLITE_OPEN_READWRITE we should be able to read and write, unless OS have marked file as read only, file must exist or error is returned. In order to simulate behavior of sqlite3_open we should use  SQLITE_OPEN_READWRITE |  SQLITE_OPEN_CREATE. The fourth argument of sqlite3_open_v2 function is name of the sqlit3_vfs object that defines the operating system interface that the new database connection should use. If we pass NULL as the fourth argument we get default sqlit3_vfs object.
If  sqlite3_open_v2 doesn't return SQLITE_OK, we have error and we should exit. We still may have proper db handle or NULL handle, calling sqlite3_close with NULL pointer is not problem.
So, we have something like this as template:

#include <sqlite3.h> #include <stdio.h> int main(int argc, char **argv) { char *file = "some.db"; sqlite3 *db = NULL; int rc = 0; rc = sqlite3_open_v2( file, &db, SQLITE_OPEN_READWRITE, NULL ); if ( rc != SQLITE_OK) { printf("Failure to open database: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); return 1; } /* do something with connection */ sqlite3_close(db); return 0; }

Call to sqlite3_errmsg should return string with description of message. We want to do resource management and to match  sqlite3_open with sqlite3_close. If we compile this and we do not have some.db file, after execution we should see descriptive error message.

./test
Failure to open database: unable to open database file

While passing to sqlite3_close NULL pointer is not problem, passing to it handle of already closed connection is problem.
Situation with sqlite3_prepare_v2 is similar to  sqlite3_open_v2, new API is preferable to legacy one and it should be used. Here both new and legacy functions are accepting the same number of arguments but behavior is different. Please check in documentation how they differ.

int sqlite3_prepare_v2( sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ );

There is also UTF-16 version with about the same arguments. It prepares statement, compiles it to bytecode  and if successful returns pointer to compiled  sqlite3_stmt.

sql = "select * from sqlite_master"; rc = sqlite3_prepare_v2(db, sql, strlen(sql), &stmt, 0); if(rc != SQLITE_OK) { printf("SQL error: %s\n", sqlite3_errmsg(db)); return 1; } rc = sqlite3_step(stmt); col = sqlite3_column_count(stmt); for(i=0; i < col; i++) { printf("%s\t",sqlite3_column_name(stmt, i)); } printf("\n------------------------------------------------------\n"); while(rc == SQLITE_ROW) { for(i=0; i < col; i++) { printf("%s\t", sqlite3_column_text(stmt, i)); } printf("\n"); rc = sqlite3_step(stmt); } sqlite3_finalize(stmt);

After statement is successfully prepared we iterate using sqlite3_step and at the end we finalize statement. In the case of sqlite3_prepare  returning error, we in general want to check is statement handle points to something and do cleanup if it does.
There is convenience wrapper around  prepare_v2-step-finalize, it is sqlite3_exec.

int sqlite3_exec( sqlite3*, /* An open database */ const char *sql, /* SQL to be evaluated */ int (*callback)(void*,int,char**,char**), /* Callback function */ void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ );

If we are doing insert, we do not really need callback, so we pass NULL pointer as the third and fourth argument.

#include <sqlite3.h> #include <stdio.h> int main(void) { sqlite3 *db; char *err_msg = NULL, *sql = NULL; int rc = sqlite3_open_v2("test.db", &db, SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE, NULL); if (rc != SQLITE_OK) { printf("Failure to open database: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); return 1; } sql = "INSERT INTO jane VALUES(1,'Mr','Smith');" "INSERT INTO jane VALUES(2,'Mrs','Doe');" "INSERT INTO jane VALUES(3,'Mr','Doe');"; rc = sqlite3_exec(db, sql, NULL, NULL, &err_msg); if (rc != SQLITE_OK ) { printf("Exec failure: %s\n", err_msg); sqlite3_free(err_msg); sqlite3_close(db); return 1; } sqlite3_close(db); return 0; }

If we don't have table jane in test.db exec will return error.

Exec failure: no such table: jane

or if we execute it more than once:

Exec failure: PRIMARY KEY must be unique

Error message is allocated using sqlite3_malloc and we have to free it using sqlite3_free.

SQLite C API introduction

I guess you are already using some kind of Linux if you are reading this. Install SQLite libraries and dev libraries, on my box they are called libsqlite3-0 and libsqlite3-dev. On your Linux packages may be called slightly differently. For example if your distro is Debian based you will check for packages executing in terminal:

apt-cache search sqlite

You do not need elevated privileges to execute that.
Also install sqlite3 command line interface for SQLite 3.
SQLite is embedded relational database engine. It was popular before but then Android made it part of OS and now it is like totally popular. There is no server and consequently no SQLite database administrator.
In order to build examples we need to specify linker switch, like this:

gcc testme.c -lsqlite3 -o test

Everything should be in path. Also we need to include appropriate header file in example:

#include <sqlite3.h> #include <stdio.h> int main(int argc, char **argv) { int rc, i, col; sqlite3 *db; sqlite3_stmt *stmt; char *sql; rc = sqlite3_open("surogat.db", &db); if(rc != SQLITE_OK) { printf("Can't open database: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); exit(1); } sql = "select * from sqlite_master"; rc = sqlite3_prepare(db, sql, strlen(sql), &stmt, 0); if(rc != SQLITE_OK) { printf("SQL error: %s\n", sqlite3_errmsg(db)); } rc = sqlite3_step(stmt); col = sqlite3_column_count(stmt); for(i=0; i < col; i++) { printf("%s\t",sqlite3_column_name(stmt, i)); } printf("\n------------------------------------------------------\n"); while(rc == SQLITE_ROW) { for(i=0; i < col; i++) { printf("%s\t", sqlite3_column_text(stmt, i)); } printf("\n"); rc = sqlite3_step(stmt); } sqlite3_finalize(stmt); sqlite3_close(db); return 0; }

We open database file, if it doesn't exist it will create it, if it can't we report error and exit. Next, we prepare statement, using legacy interface, and again check for error. Function sqlite3_step evaluates prepared statement, similarly we retrieve some metadata and print that to standard output.
Before we run example we will create table so that we can show some kind of output from our program. All that in the same folder where is binary, so that we don't have to fiddle with full path.

sqlite3 surogat.db SQLite version 3.7.9 2011-11-01 00:52:41 Enter ".help" for instructions Enter SQL statements terminated with a ";" sqlite> CREATE TABLE jane ( id INTEGER PRIMARY KEY NOT NULL, title TEXT, full_name TEXT NOT NULL ); sqlite> .exit

Now we can run our test program and see output like this.

type    name    tbl_name    rootpage    sql   
------------------------------------------------------
table    jane    jane    2    CREATE TABLE jane ( id INTEGER PRIMARY KEY NOT NULL, title TEXT, full_name TEXT NOT NULL )   

That was simple connect to database and select, there will be more in next instalment.