*vital-database-sqlite.txt*		sqlite utilities library.

Maintainer: ujihisa <ujihisa at gmail com>

==============================================================================
CONTENTS				*Vital.Database.SQLite-contents*

INTRODUCTION			|Vital.Database.SQLite-introduction|
PRINCIPLE			|Vital.Database.SQLite-principle|
EXAMPLES			|Vital.Database.SQLite-examples|
FUNCTIONS			|Vital.Database.SQLite-functions|

==============================================================================
INTRODUCTION				*Vital.Database.SQLite-introduction*

*Vital.Database.SQLite* is SQLite Utilities Library.
It provides some functions to manipulate |SQLite|.

==============================================================================
PRINCIPLE				*Vital.Database.SQLite-principle*

|Vital.Database.SQLite| won't provide ORM but provides safe query and result
parser. ORM is a wrong way of abstracting relational database.

|Vital.Database.SQLite| is
* not an object that wraps something fancy.
* not sqlite itself but a bridge to use a sqlite implementation.
* encouraging you to write a good SQL query.
* helping you to investigate what's going on by debug functions.

==============================================================================
EXAMPLES				*Vital.Database.SQLite-examples*

>
	let s:S = s:V.import('Database.SQLite')
	if !s:S.is_available()
	  return 'failed'
	endif
	echo s:S.query_rawdata(
	      \ 'a.db',
	      \ 'CREATE TABLE cities (name varchar(80), country_name text);')
	echo s:S.query_rawdata(
	      \ 'a.db',
	      \ 'INSERT INTO cities VALUES (?, ?);',
	      \ ['Vancouver', 'Canada'])
	echo s:S.query(
	      \ 'a.db',
	      \ 'SELECT * FROM cities WHERE name = ?;',
	      \ ['Vancouver'])
<

==============================================================================
FUNCTIONS				*Vital.Database.SQLite-functions*

is_available()		*Vital.Database.SQLite.is_available()*
	1 if you can use this sqlite integration feature by checking if you
	have sqlite3 command.
>
	:echo S.is_available()
	1
<

query({dbfile}, {query/placeholders}, {list})	*Vital.Database.SQLite.query()*
	Sends an SQL query to sqlite with specifying the db file to store is
	{dbfile}, and returns its result in list. If {query/placeholders}
	(query with placeholders) contains placeholders "?", {list} has to
	have same amount of string elements.  e.g.
>
	query(d, 'A', [])
	query(d, 'A ?', [x])
	query(d, 'A ? ?', [x, y])
<
	You don't have to give {list} if {query/placeholders} has no
	placeholders. e.g.
>
	query(d, 'A', []) == query(d, 'A')
<

	This function returns a list which has multiple dictionaries. e.g.
>
	query('a.db', 'SELECT * FROM cities WHERE name = Vancouver;')
	is
	[{'country': 'Canada', 'name': 'Vancouver'},
	 {'country': 'US', 'name': 'Vancouver'}]
<

build_line_from_query_with_placeholders({query/placeholders}, {list})
	*Vital.Database.SQLite.build_line_from_query_with_placeholders()*
	Returns internal value that |Vital.Database.SQLite.query()| uses. This
	function doesn't have side effects.

	This function name is long on purpose to discourage people to use that
	frequently. Use this only for your understanding and for debugging
	this library itself.

	Examples
>
	build_line_from_query_with_placeholders(
	      \ 'SELECT * FROM cities WHERE name = ?;',
	      \ ['Vancouver'])
	"=> 'SELECT * FROM cities WHERE name = "Vancouver";'

	echo s:S.build_line_from_query_with_placeholders(
	      \ 'SELECT * FROM cities WHERE name = ?;',
	      \ ["Vancouver\"; ujihisa\""])
	"=> 'SELECT * FROM cities WHERE name = "Vancouver\"; ujihisa\"";'
<

==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl