sorm/README.md

# SORM

## Description
SORM stands for SQL ORM. I made this because I have a love/hate relationship with both. I combined them together to have the best of both worlds!

The naming of my functions and variables are something to get used to. They are all abbreviations, kinda like C stdlib style. It looks weird, but you get used to it quickly and in reality, you just use a few of them.

Examples of common used functions are:
 - `sormc(char *path)` connect to database. Returns `int`.
 - `sormq(int conn, char *sql, ...)` execute query. Variadic arguments. Works like `printf`. Returns result in CSV format in case of `SELECT`.
 - `sorm_csvd(char *csv_data)` dumps your CSV result data to a nice fixed content width table in the terminal.

## Design choices
I use mainly native types and not custom structs. For example, the db parameter is an int. This is so it can easily communicate with other languages using a shared object file.
Same argument is for the result set of `sormq` (the query function) resulting in a `char *` containing CSV data. 
While the performance is nice, it's not written with performance in mind at all. 

## Thread safety
I wonder if I have configured sqlite3 the right way for thread safety. It maybe requires a manual compilation of the shared object file. Will look into that. SORM is written with thread safety in mind.

## Building

It has only one build command for the shared object file and the REPL/CLI.
It has not been compiled with optimizations / warnings enabled. Don't recommend for now.
```bash
make build
```
### Requirements
This project has the following dependencies:
 - sqlite3-dev (`apt install sqlite3-dev`)
 - readline(-dev?) (no idea how to install)
 - gcc 
 - make

The project probably works from C99 to C2X.

### Caution
This project won't compile on your local PC because `rlib.h` is missing. This is my bundle of libraries that I regularely use. I will add this later as 3rd party lib. Maybe I will cherry pick only the functions that SORM uses out of it to keep the source clean, else I will have thousands of lines nothing to do with this project in the source. 


## Python support
The Python library is low quality. I made it just for fun and test. This is not a defitive version. But it show very well how to communicate with a shared object file. I'm sure someone will be happy with examples how to use variadic functions trough Python to C. See `sorm.py`

## C API examples:

### Connecting
```c
int db = sormc("db.sqlite3");
```
### Create table
This one should return true if executed.
```c
sormq(db, "CREATE TABLE IF NOT EXISTS pony (id INTEGER  PRIMARY KEY AUTOINCREMENT,name,age);",NULL);
```
### Inserting
```c
sorm_pk iid = sormq(db, "INSERT INTO pony (id, name, age) VALUES (NULL, %s, %d);",
    "Retoorded retoor",
    42
);
```
Using `?` is also possible for arguments like this (comfy for Python usage):
```c
sorm_pk iid = sormq(db, "INSERT INTO pony (id, name, age) VALUES (NULL, ?s, ?d);",
    "Retoorded retoor",
    42
);
```
### Selecting
IN query
```c
sorm_str csv = sormq(db, "SELECT * FROM pony WHERE id in (?d,?d,?d)",1,2,3);
free(sorm_str);
```
LIKE query
```c
sorm_str csv2 = sormq(db, "SELECT * FROM pony WHERE id > %d and age = %d AND name LIKE ?s", 1, 34, "%toor%"));
free(sorm_str);
```
Yes, you did see that right, you can use the default native free!
### Disconnecting
```c
sormd(db);
```