The version of sqlite supported by this library is version 3 or greater.
This library allows storing Factor tuples in a sqlite database. It provides words to create, read update and delete these entries as well as simple searching.
The library is in a very early state and is likely to change quite a bit in the near future. Its most notable omission is it cannot currently handle relationships between tuples. This feature is currently being worked on.
The Factor image must have been bootstrapped with the sqlite shared library name provided. This can be done with the following command:
./f boot.image.le32 -libraries:sqlite:name=libsqlite3.so
The quickest way to get up and running with this library is to change to the 'sqlite' directory and run Factor. Then execute the following commands:
"sqlite.factor" run-file "tuple-db.factor" run-file USE: sqlite USE: tuple-db
Some simple tests can be run to check that everything is working ok:
"tuple-db-tests.factor" run-file
This library can be used for storing simple Factor tuples in a sqlite database. In its current form the tuples must not contain references to other tuples and should not have a delegate set.
This document will use the following tuple for demonstration purposes:
TUPLE: person name surname phone ;
The sqlite database to store tuples must be created, or an existing one opened. This is done using the 'sqlite-open word. If the database does not exist then it is created. The examples in this document store the database pointer in a variable called 'db':
SYMBOL: db "example.db" sqlite-open db set
Each tuple has a 'mapping' tuple associated with it. The 'mapping' stores information about what table the tuple will be stored in, the datatypes of the tuple slots, etc. A mapping must be created before a tuple can be stored in a database. A default mapping is easily created using the 'default-mapping' word. Given the tuple class, this will use reflection to get the slots of it, assume that all slots are of database type 'text', and store the tuple objects in a table with the same name as the tuple.
The following shows how to create the default mapping for the 'person' tuple, and how to register that mapping so the 'tuple-db' system can know how to handle 'person' instances:
person default-mapping set-mapping
The table used to store tuple instances may need to be created. This can be done manually using 'sqlite' or via the 'create-tuple-table' word:
! create-tuple-table ( db class -- )
db get person create-tuple-table
The SQL used to create the table is produced by the 'create-sql' word. This is a generic word dispatched on the mapping object, and could be specialised if needed. If you wish to see the SQL used to create the table, use the following code:
! M: mapping create-sql ( mapping -- string )
person get-mapping create-sql .
=> "create table person (name text,surname text,phone text);"
The 'insert-tuple' word will store instances of a tuple into the database table defined by its mapping object. It's as simple as:
! insert-tuple ( db tuple -- )
db get "John" "Smith" "123-456-789" <person> insert-tuple
'insert-tuple' internally uses the 'insert-sql' word to produce the SQL used to store the tuple. Like 'create-sql', 'insert-sql' is a generic word specialized on the mapping object. You can call it directly to see what SQL is generated:
! M: mapping insert-sql ( mapping -- string )
person get-mapping insert-sql .
=> "insert into person values(:name,:surname,:phone);"
Notice that the SQL uses named parameters. This parameters are bound to the values stored in the tuple object when the SQL is compiled. This helps prevent SQL injection techniques.
When the 'insert-sql' word is run, it adds a delegate to the tuple being stored. The delegate is of type 'persistent' and holds the row id of the tuple in its 'key' slot. This way the exact record can be updated or retrieved later. The following demonstates this fact:
"Mandy" "Jones" "987-654-321" <person> dup .
=> << person f "Mandy" "Jones" "987-654-321" >>
db get over insert-tuple .
=> << person
<< persistent ... "2" >>
"Mandy" "Jones" "987-654-321"
>>
The '2' highlited in the above example is the row id of the record inserted. We can go into the 'sqlite' command and view this record:
$ sqlite3 example.db
SQLite version 3.0.8
Enter ".help" for instructions
sqlite> select ROWID,* from person;
1|John|Smith|123-456-789
2|Mandy|Jones|987-654-321
sqlite>
The 'find-tuples' word is used to return tuples populated with data already existing in the database. As well as the database pointer, it takes a tuple that should be populated only with the fields that should be matched in the database. All fields you do not wish to match against should be set to 'f':
! find-tuples ( db tuple -- seq )
db get f "Smith" f <person> find-tuples short.
=> [ << person # "John" "Smith" "123-456-789" >> ]
db get "Mandy" f f <person> find-tuples short.
=> [ << person # "Mandy" "Jones" "987-654-321" >> ]
db get "Joe" f f <person> find-tuples short.
=> f
Notice that if no matching tuples are found then 'f' is returned. The returned tuples also have their delegate set to 'persistent' with the correct row id set as the key. This can be used to later update the tuples with new information and store them in the database.
Given a tuple that has the 'persistent' delegate with the row id set as the key, you can update this specific record using the 'update-tuple' word:
! update-tuple ( db tuple -- )
db get f "Smith" f <person> find-tuples dup short.
=> [ << person # "John" "Smith" "123-456-789" >> ]
first [ "999-999-999" swap set-person-phone ] keep dup short.
=> << person << persistent f # "1" >> "John" "Smith" "999-999-999" ...
db get swap update-tuple
Using the 'sqlite' command from the system shell you can see the record was updated:
$ sqlite3 example.db
SQLite version 3.0.8
Enter ".help" for instructions
sqlite> select ROWID,* from person;
1|John|Smith|999-999-999
2|Mandy|Jones|987-654-321
sqlite>
The 'save-tuple' word can be used to insert a tuple if it has not already been stored in the database, or update it if it already exists. Whether to insert or update is decided by the existance of the 'persistent' delegate:
! save-tuple ( db tuple -- )
"Mary" "Smith" "111-111-111" <person> dup short.
=> << person f "Mary" "Smith" "111-111-111" >>
! This will insert the tuple
db get over save-tuple dup short.
=> << person << persistent f # "3" >> "Mary" "Smith" "111-111-111" ...
[ "222-222-222" swap set-person-phone ] keep dup short.
=> << person << persistent f # "3" >> "Mary" "Smith" "222-222-222" ...
! This will update the tuple
db get over save-tuple short.
=> << person << persistent f # "3" >> "Mary" "Smith" "222-222-222" ...
Given a tuple with the delegate set to 'persistent' (ie. One already stored in the database) you can delete it from the database with the 'delete-tuple' word:
! delete-tuple ( db tuple -- )
db get f "Smith" f <person> find-tuples [
db get swap delete-tuple
] each
It's important to close the sqlite database when you've finished using it. The word for this is 'sqlite-close':
! sqlite-close ( db -- )
db get sqlite-close
Copyright (c) 2004, Chris Double. All Rights Reserved.