Koodit: C: SQLite3-kirjaston käyttäminen

Vinkki esittelee kuinka C:llä otetaan yhtyes SQLite -tietokantaan ja suoritetaan haku sieltä. Lopuksi suljetaan tietokantayhteys. Vinkin on tarkoitus olla ihan perustasoa.

Luonnollisestkin vinkin toimimiseen tarvitse SQLite:n kehityskirjastot. Linuxilla ne löytyvät todennäköisesti pakettien hallinasta. Niiden asentamisesta windows -ympäristöön en osaa sanoa, kun en kyseistä käyttöjärjestelmää paljoa käytä. Jos joku tietää enemmän, niin saa kommentoida. Uusin versio kirjoitushetkellä on 3.5.6.

Mikä ihmeen SQLite? SQLite on kevyt kirjasto, joka sisältää serverittömän tietokantamoottorin, näin lyhyikäisyydessään ilmaistuna. Tietokantaa hyödyntääksesi sinun ei siis tarvitsee ajaa erillistä serveriprosessia. SQLite ei myöskään vaadi mitään lisäkirjastoja ohjelmasi käyttäjältä. Se on siis juuri sopiva pieniin ja jopa isompiinkin tietokantaa tarvitseviin ohjelmistoihin.

Käyn seuraavaksi läpi esimerkki koodin, toivottavasti tarpeeksi selittävästi ja yksinkertaisesti. Esimerkkikoodi avaa ensin tietokantayhteyden. Osoitin database osoittaa avatuun yhteyteen ja sitä tarvitaan myöhemmin.

Avattava tiedosto on nimeltään database.db. Se sisältää taulun ja muutamia esimerkkirivejä. Voit helposti luoda vastaavan tiedoston komentamalla:

sqlite3 database.db

Tämän jälkeen voit luoda uusia tauluja ja syöttää arvoja seuraavaan tapaan:

sqlite> CREATE TABLE dinot(Dinosaurus varchar(64), Ääntely varchar(64));
sqlite> insert into dinot values('Tyrannosaurus Rex','Grraaauuuhh!');
sqlite> insert into dinot values('Velociraptor','Grrr Grr!');
sqlite> insert into dinot values('Stegosaurus','Mmrrrh!');
sqlite> .quit

Nyt meillä on siis tietokannassamme taulu nimeltä dinot. Taulumme sisältää kaksi saraketta, Dinosaurus ja Ääntely. Kumpaankin voidaan sijoittaa maksimissaan 64 merkin pituinen merkkijono. Sijoitimme kantaamme kolme dinosaurusta ääntelyineen. Syntyneen database.db -tiedoston tulee olla samassa hakemistossa, kuin ajettava ohjelma.

HUOM! Kirjoittaja ei ota vastuuta ääntelyiden oikeellisuudesta.

sqlite3_open -funktion tulisi palauttaa arvo nolla, jos tietokantayhteys saatiin avatuksi onnistuneesti.

Kun olemme saaneet yhteyden avatuksi, niin on aika suorittaa haku kantaan. Haku tehdään käyttäen sqlite3_exec -funktiota. Funktio on muotoa:

int sqlite3_exec(
  sqlite*,
  const char *sql,
  int(*callback)(void*,int,char**,char**),
  void *,
  char **errmsg
);

Ensinmäinen parametri on osoitin avattuun tietokantaan. Toinen parametri on suoritettava SQL-kysely. Kolmas parametri on osoitin funktioon, joka käsittelee kyselyn tulokset. Se voi olla myös NULL. Neljäs parametri on kolmantena parametrina annetulle funktiolle välitettävä arvo. Viides parametri kertoo minne mahdolliset virhesanomat tulisi sijoittaa.

Kolmantena parametrina annettaa funktiota kutsutaan jokaista riviä kohden, jotka noudetaan kyselyn seurauksena tietokannasta. Esimerkissäni handler -funktiota kutsutaan siis kolme kertaa.

Funktio saa ensimmäisenä parametrinaan sqlite3_exec -funktiolle välitetyn neljännen parametrin. Kolmas parametri on taulukollinen osoittimia, kuin myös on neljäs. Kolmannesta taulukosta löytyy tietokannasta haetut arvot, kun taas neljäs sisältää sarakkeiden nimet. "Hetkinen! Entäs se toinen parametri!", saatat miettiä tässä vaiheessa. Se sisältää yksinkertaisesti vain noiden taulukoiden alkioiden määrän. Voit havaita samankaltaisuuden main -funktion kanssa.

Jos funktio palauttaa nollasta poikkeavan arvon, niin keskeytyy funktion sqlite3_exec -function suoritus ja sqlite_exec palauttaa arvon SQLITE_ABORT.

Jos halutaan esimerkiksi tulostaa kaikki se tieto mitä kysely tuotti, niin yksinkertaisinta se on for -silmukalla. Näin koodiesimerkissä tehdään.

Jos kuitenkin sqlite3_exec ei palauta arvoa SQLITE_OK (eli kysely onnistui), niin silloin voimme tulostaa virheen, joka löytyy sqlite_exec -funktiolle annetun viidennen paremetrin osoittamasta paikasta. sqlite3_exec varaa muistia virhesanomalle ja käyttäjän täytyy vapauttaa se funktiolla sqlite_free.

Lopuksi erimerkissämme suljetaan tietokantayhteys sqlite3_close -funktiota kutsumalla.

Jotta saisimme koodin käännetyksi, niin tarvitsee kääntäjälle kertoa mistä SQLite3 -kirjasto löytyy. Gcc:llä se tapahtuu vivulla -lsqlite3. Seuraava rivi siis kääntäisi esimerkin

gcc -o main main.c -lsqlite3

Ohjelman tulisi tulostaa seuraavat rivit:

Näin eri dinosaurukset puhuvat:
Dinosaurus: Tyrannosaurus Rex
Ääntely: Grraaauuuhh!

Dinosaurus: Velociraptor
Ääntely: Grrr Grrr!

Dinosaurus: Stegosaurus
Ääntely: Mmrrrh!

Lisää tietoa SQLite3:sta löytyy sen virallisita kotisivuilta osoitteesta http://sqlite.org/. Sieltä löytyy esimerkiksi C/C++ API:n kuvaus. Mainittakoon vielä, että sqlite löytyy muillekin kielille, kuten vaikkapa pythonille.

/*
 * main.c
 * Kääntäminen:
 * gcc -o main main.c -lsqlite3
 */

#include <stdio.h>
/*Sqlite3:n tarvitsema otsikkotiedosto*/
#include <sqlite3.h>

/*Funktio, joka käsittelee haun tulokset*/
int handler(void *data, int argc, char **argv, char **colName)
{
	int i;
	for(i=0;i<argc;i++)
	{
		printf("%s: %s\n", colName[i], argv[i]);
	}
	printf("\n");
	return 0;
}

int main(int argc, char **argv)
{
	/* Tarvitsemamme muuttujat */
	sqlite3 *database;
	char *errMsg;
	int retVal;

	/* Avataan yhteys tietokantaan */
	retVal = sqlite3_open("database.db", &database);
	if(retVal)
	{
		/* sqlite3_errmsg onkii esille virhesanoma */
		printf("Virhe tietokantaa avatessa!\n%s", sqlite3_errmsg(database) );
		sqlite3_close(database);
		return -1;
	}

	printf("Näin eri dinosaurukset puhuvat:\n");
	/* Suoritetaan haku tietokannasta, haetaan dinot -taulun kaikki rivit */
	retVal = sqlite3_exec(database, "select * from dinot", handler, NULL, &errMsg);
	if(retVal != SQLITE_OK)
	{
		printf("Virhe hakua suoritettaessa:\n%s\n",errMsg);
		sqlite3_free(errMsg);
		return -1;
	}

	/* Suljetaan yhteys */
	sqlite3_close(database);
	return 0;
}