sqlite: add sync and journal funcs, docs (#14970)

Author: chipnetics

vlib/sqlite/README.md

@@ -26,10 +26,11 @@ library installed on your system.
 
 # Performance Tips
 
-When performing a large amount of database calls (i.e. INSERTS), significant performance increase
-can be obtained by issuing to sqlite the following pragma commands.
+When performing a large amount of database calls (i.e. INSERTS), significant performance increase can be obtained by controlling the synchronization and journal modes.
 
-```
-db.exec('pragma synchronous = off;')
-db.exec('pragma journal_mode = MEMORY;')
+For instance,
+```v
+db := sqlite.connect('foo.db') or {panic(err)}
+db.synchronization_mode(sqlite.SyncMode.off)
+db.journal_mode(sqlite.JournalMode.memory)
 ```

vlib/sqlite/sqlite.v

@@ -21,6 +21,20 @@ pub const (
 	sqlite_done  = 101
 )
 
+pub enum SyncMode {
+	off
+	normal
+	full
+}
+
+pub enum JournalMode {
+	off
+	delete
+	truncate
+	persist
+	memory
+}
+
 struct C.sqlite3 {
 }
 
@@ -219,7 +233,8 @@ pub fn (db DB) error_message(code int, query string) IError {
 	})
 }
 
-// In case you don't expect any result, but still want an error code
+// Execute a query returning only the result code.
+// In case you don't expect any row results, but still want a result code.
 // e.g. INSERT INTO ... VALUES (...)
 pub fn (db DB) exec_none(query string) int {
 	stmt := &C.sqlite3_stmt(0)
@@ -235,11 +250,54 @@ pub fn (db DB) exec_param(query string, param string) []Row {
 }
 */
 
+// Issue a "create table if not exists" command to the db.
+// Creates table named 'table_name', with columns generated from 'columns' array.
+// Default columns type will be TEXT.
 pub fn (db DB) create_table(table_name string, columns []string) {
 	db.exec('create table if not exists $table_name (' + columns.join(',\n') + ')')
 }
 
-// Set a busy timeout in milliseconds https://www.sqlite.org/c3ref/busy_timeout.html
+// Set a busy timeout in milliseconds.
+// Sleeps for a specified amount of time when a table is locked. The handler
+// will sleep multiple times until at least "ms" milliseconds of sleeping have accumulated.
+// (see https://www.sqlite.org/c3ref/busy_timeout.html)
 pub fn (db DB) busy_timeout(ms int) int {
 	return C.sqlite3_busy_timeout(db.conn, ms)
 }
+
+// Sets disk synchronization mode,
+// which controls how aggressively SQLite will write data to physical storage.
+// off: No syncs at all. (fastest)
+// normal: Sync after each sequence of critical disk operations.
+// full: Sync after each critical disk operation (slowest).
+pub fn (db DB) synchronization_mode(sync_mode SyncMode) {
+	if sync_mode == .off {
+		db.exec('pragma synchronous = OFF;')
+	} else if sync_mode == .full {
+		db.exec('pragma synchronous = FULL;')
+	} else {
+		db.exec('pragma synchronous = NORMAL;')
+	}
+}
+
+// Controls how the journal file is stored and processed.
+// off: No journal record is kept. (fastest)
+// memory: Journal record is held in memory, rather than on disk.
+// delete: At the conclusion of a transaction, journal file is deleted.
+// truncate: Journal file is truncated to a length of zero bytes.
+// persist: Journal file is left in place, but the header is overwritten to indicate journal is no longer valid.
+pub fn (db DB) journal_mode(journal_mode JournalMode) {
+	if journal_mode == .off {
+		db.exec('pragma journal_mode = OFF;')
+	} else if journal_mode == .delete {
+		db.exec('pragma journal_mode = DELETE;')
+	} else if journal_mode == .truncate {
+		db.exec('pragma journal_mode = TRUNCATE;')
+	} else if journal_mode == .persist {
+		db.exec('pragma journal_mode = PERSIST;')
+	} else if journal_mode == .memory {
+		db.exec('pragma journal_mode = MEMORY;')
+	} else {
+		db.exec('pragma journal_mode = MEMORY;')
+	}
+}