audrey 0.2 → 0.3

data/lib/audrey/engine/sqlite3.rb

@@ -0,0 +1,1609 @@
+require 'sqlite3'
+require 'json'
+
+#===============================================================================
+# Audrey::Engine::SQLite3
+#
+class Audrey::Engine::SQLite3 < Audrey::Engine
+	attr_reader :dbh
+	attr_reader :transactions
+	attr_reader :path
+	attr_reader :preps
+	attr_accessor :partition
+	extend Forwardable
+	
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_path, p_mode, opts={})
+		# default options
+		opts = {'immediate_commit'=>true}.merge(opts)
+		
+		# set some properties
+		@path = p_path
+		@immediate_commit = opts['immediate_commit'] ? true : false
+		@preps = {}
+		@mode = p_mode
+		
+		# KLUDGE: For now, default to partition 'm'
+		@partition = 'm'
+		
+		# lock file
+		set_lock()
+		
+		# if file exists
+		existed = File.exist?(@path)
+		
+		# open database handle
+		@dbh = get_dbh()
+		
+		# custom functions
+		custom_functions()
+		
+		# create and structure database if the file doesn't exist
+		if not existed
+			require 'audrey/engine/sqlite3/init'
+			Audrey::Engine::SQLite3::Init.build @dbh
+		end
+		
+		# transactions
+		@transactions = []
+		
+		# initial transaction
+		if @immediate_commit
+			@transactions.push Audrey::Engine::SQLite3::Transaction::AutoCommit.new(self)
+		else
+			@transactions.push Audrey::Engine::SQLite3::Transaction::RC.new(self)
+		end
+		
+		# create stuff just for this session
+		self.class.session_tables @dbh
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# get_dbh
+	#
+	def get_dbh
+		# get database handle
+		rv = ::SQLite3::Database.new(@path)
+		
+		# enforce referential integrity
+		rv.execute 'pragma foreign_keys=on'
+		
+		# results as hash
+		rv.results_as_hash = true
+		
+		# return
+		return rv
+	end
+	#
+	# get_dbh
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# commit, rollback
+	#
+	def commit
+		return @transactions[0].commit
+	end
+	
+	def rollback
+		return @transactions[0].rollback
+	end
+	#
+	# commit, rollback
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# in_transaction?
+	#
+	def in_transaction?
+		# loop through transactions
+		@transactions.each do |tr|
+			tr.is_a?(Audrey::Engine::SQLite3::Transaction::RC) and return true
+		end
+		
+		# else not in transaction
+		return false
+	end
+	#
+	# in_transaction?
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# transaction
+	#
+	def transaction(opts={})
+		# $tm.hrm
+		tr = Audrey::Engine::SQLite3::Transaction::RC.new(self)
+		@transactions.push tr
+		
+		# block
+		if block_given?
+			begin
+				# yield
+				yield tr
+				
+				# autocommit if necessary
+				if opts['autocommit']
+					tr.commit
+				end
+			
+			# exit transaction
+			rescue Audrey::Exception::TransactionExit => e
+				unless e.tr == tr
+					raise e
+				end
+				
+				# return out of this method
+				return nil
+			ensure
+				tr.terminate
+				@transactions.pop
+			end
+			
+			# return nil
+			return nil
+		
+		# non-block
+		else
+			return tr
+		end
+	end
+	#
+	# transaction
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# reset_savepoints
+	#
+	def reset_savepoints(ftr)
+		found = false
+		
+		@transactions.each do |tr|
+			if tr == ftr
+				found = true
+			end
+			
+			if found
+				tr.start
+			end
+		end
+	end
+	#
+	# reset_savepoints
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# close
+	#
+	def close(opts={})
+		# $tm.hrm
+		
+		# close prepared statements
+		@preps.keys.each do |key|
+			stmt = @preps[key]
+			
+			if stmt and (not stmt.closed?)
+				stmt.close
+			end
+			
+			@preps.delete key
+		end
+		
+		# purge
+		if opts['purge']
+			purge()
+		end
+		
+		# close database handle
+		if not @dbh.closed?
+			@dbh.close
+		end
+		
+		# unlock file
+		if @lock
+			@lock.flock File::LOCK_UN
+			@lock.close
+		end
+	end
+	#
+	# close
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# custom_functions
+	#
+	def custom_functions()
+		#-----------------------------------------------------------------------
+		# partition
+		#
+		@dbh.create_function('current_partition', 0) do |func|
+			func.result = @partition
+		end
+		#
+		# partition
+		#-----------------------------------------------------------------------
+		
+		
+		#-----------------------------------------------------------------------
+		# insert_object_journal
+		#
+		@dbh.create_function('insert_object_journal', 4 ) do |func, partition, root, fclass, scalar, xt|
+			# $tm.hrm
+			
+			# translate scalars to objects for storage in JSON
+			if converter = Audrey::AUDREY_SCALAR_TO_RUBY[fclass]
+				scalar = converter.call(scalar)
+			end
+			
+			# initialize
+			rv = {}
+			rv['fc'] = fclass
+			rv['pt'] = partition
+			
+			# scalar
+			if rv['s'].is_a?(String)
+				rv['s'] = scalar.force_encoding('UTF-8')
+			end
+			
+			# xt
+			if xt
+				rv['xt'] = xt
+			end
+			
+			# root
+			if root == 1
+				rv['root'] = true
+			end
+			
+			# set return result
+			func.result = JSON.generate(rv)
+		end
+		#
+		# insert_object_journal
+		#-----------------------------------------------------------------------
+		
+		
+		#-----------------------------------------------------------------------
+		# fclass_fco, fclass_isolate
+		#
+		@dbh.create_function('fclass_fco', 1) do |func, fclass|
+			func.result = Audrey::Util.fclass_fco(fclass) ? 1 : 0
+		end
+		
+		@dbh.create_function('fclass_isolate', 1) do |func, fclass|
+			func.result = Audrey::Util.fclass_isolate(fclass) ? 1 : 0
+		end
+		#
+		# fclass_fco, fclass_isolate
+		#-----------------------------------------------------------------------
+		
+		
+		#-----------------------------------------------------------------------
+		# graph_field
+		#
+		@dbh.create_function('graph_field', 2) do |func, fclass, hkey|
+			func.result = Audrey::Util.graph_field?(fclass, hkey) ? 1 : 0
+		end
+		#
+		# graph_field
+		#-----------------------------------------------------------------------
+		
+		
+		#-----------------------------------------------------------------------
+		# change_to_true
+		#
+		# @dbh.create_function('change_to_true', 1) do |func, fclass|
+		# 	func.result = 1
+		# end
+		#
+		# change_to_true
+		#-----------------------------------------------------------------------
+		
+		
+		#-----------------------------------------------------------------------
+		# custom_class
+		#
+		@dbh.create_function('custom_class', 1) do |func, fclass|
+			func.result = Audrey::Util.custom_class?(fclass) ? 1 : 0
+		end
+		#
+		# custom_class
+		#-----------------------------------------------------------------------
+		
+		
+		#-----------------------------------------------------------------------
+		# debug
+		#
+		@dbh.create_function('debug', 1) do |func, msg|
+			puts msg
+			func.result = 1
+		end
+		#
+		# debug
+		#-----------------------------------------------------------------------
+	end
+	#
+	# custom_functions
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# purge
+	#
+	def purge
+		# $tm.hrm
+		
+		if @mode.write
+			sql = 'delete from objects where pk in (select pk from fco_not_traced)'
+			@dbh.execute sql
+		end
+	end
+	#
+	# purge
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# root_pk
+	#
+	def root_pk
+		sql = 'select pk from objects where root and partition=:partition'
+		return @dbh.get_first_value(sql, 'partition'=>@partition)
+	end
+	#
+	# root_pk
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# insert_object
+	#
+	def insert_object(object, opts={})
+		# $tm.hrm
+		
+		# pk
+		pk = opts['pk'] || Audrey::Util.uuid
+		
+		# if scalar
+		if dfn = Audrey::Engine::SQLite3::RUBY_SCALAR_TO_SQLITE[object.class]
+			if not @preps['insert_scalar']
+				sql = <<~'SQL'
+				insert into objects(pk, partition, bclass, fclass, scalar)
+				values(:pk, :partition, :bclass, :fclass, :scalar)
+				SQL
+				
+				@preps['insert_scalar'] = @dbh.prepare(sql)
+			end
+			
+			# insert record
+			simple_exec(
+				@preps['insert_scalar'],
+				'pk' => pk,
+				'partition' => @partition,
+				'bclass' => dfn['fclass'].bclass.to_s,
+				'fclass' => dfn['fclass'].to_s,
+				'scalar' => dfn['to_db'].call(object)
+			);
+			
+		# if hash or array
+		elsif dfn = Audrey::RUBY_OBJECT_TO_AUDREY[object.class] and dfn['nclass']
+			simple_exec(
+				prepare_insert_collection(),
+				'pk' => pk,
+				'partition' => @partition,
+				'bclass' => dfn['fclass'].bclass.to_s,
+				'fclass' => dfn['fclass'].to_s
+			);
+			
+		# if custom object
+		elsif object.is_a?(Audrey::Object::Custom)
+			simple_exec(
+				prepare_insert_collection(),
+				'pk' => pk,
+				'partition' => @partition,
+				'bclass' => object.class.bclass.to_s,
+				'fclass' => object.class.to_s,
+			);
+			
+		# else unknown
+		else
+			raise 'unknown-object-class: ' + object.class.to_s
+		end
+		
+		# return pk
+		return pk
+	end
+	#
+	# insert_object
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# delete_object
+	#
+	def delete_object(pk)
+		# $tm.hrm
+		
+		# ensure statement handle
+		if not @preps['delete_object']
+			sql = <<~'SQL'
+			delete from objects
+			where pk=:pk and partition=:partition
+			SQL
+			
+			@preps['delete_object'] = @dbh.prepare(sql)
+		end
+		
+		# execute
+		simple_exec @preps['delete_object'], 'pk' => pk, 'partition' => @partition
+	end
+	#
+	# delete_object
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# add_xt
+	#
+	def add_xt(obj_pk, xt_pk)
+		# $tm.hrm
+		
+		# prepare insert statement if necessary
+		if not @preps['insert_xt']
+			sql = <<~SQL
+			insert into objects(pk, partition, bclass, fclass)
+			values(?, (select partition from objects where pk=?), 'Audrey::Object::Hash', 'xt')
+			SQL
+			
+			@preps['insert_xt'] ||= @dbh.prepare(sql)
+		end
+		
+		# create xt
+		simple_exec @preps['insert_xt'], xt_pk, obj_pk
+		
+		# associate record
+		@preps['add_xt'] ||= @dbh.prepare('update objects set xt=:xtpk where pk=:pk and partition=:partition')
+		simple_exec @preps['add_xt'], 'xtpk'=>xt_pk, 'pk'=>obj_pk, 'partition'=>@partition
+	end
+	#
+	# add_xt
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# get_xt
+	#
+	def get_xt(obj_pk)
+		# prepare statement if necessary
+		@preps['existing_xt'] ||= @dbh.prepare('select xt from objects where pk=:pk and partition=:partition')
+		
+		# search
+		@preps['existing_xt'].execute('pk'=>obj_pk, 'partition'=>@partition).each do |row|
+			return row['xt']
+		end
+		
+		# create
+		xt_pk = Audrey::Util.uuid
+		add_xt obj_pk, xt_pk
+		
+		# return
+		return xt_pk
+	ensure
+		@preps['existing_xt'] and @preps['existing_xt'].reset!
+	end
+	#
+	# get_xt
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# add_relationship
+	#
+	def add_relationship(parent_pk, child_pk, opts={})
+		# ensure prepared statement
+		if not @preps['add_relationship']
+			sql = <<~SQL
+			insert into relationships(pk, parent, child, ord, hkey)
+				values(
+					:pk,
+					:parent,
+					:child,
+			
+					case
+						when :ord is null then
+							coalesce((select max(ord) from relationships where parent=parent), 0) + 1
+						else :ord
+					end,
+			:hkey)
+			SQL
+			
+			@preps['add_relationship'] = @dbh.prepare(sql)
+		end
+		
+		# uuid for new relationship record
+		pk = Audrey::Util.uuid
+		
+		# execute
+		begin
+			@preps['add_relationship'].execute(
+				sql,
+				'pk'=>pk,
+				'parent'=>parent_pk,
+				'child'=>child_pk,
+				'ord'=>opts['ord'],
+				'hkey'=>opts['hkey']
+			);
+		ensure
+			@preps['add_relationship'].reset!
+		end
+		
+		# return
+		return pk
+	end
+	#
+	# add_relationship
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# hash_has_key?
+	#
+	def hash_has_key?(parent_pk, key)
+		# $tm.hrm
+		# puts "parent_pk: #{parent_pk}"
+		# puts "key: #{key}"
+		
+		# prepare
+		if not @preps['hash_has_key']
+			sql = <<~'SQL'
+			select count(*) as count
+			from relationships
+			where parent=:parent and hkey=:hkey
+			SQL
+			
+			@preps['hash_has_key'] ||= @dbh.prepare(sql)
+		end
+		
+		# get count
+		@preps['hash_has_key'].execute('parent'=>parent_pk, 'hkey'=>key).each_hash do |row|
+			return row['count'] > 0
+		end
+	ensure
+		@preps['hash_has_key'] and @preps['hash_has_key'].reset!
+	end
+	#
+	# hash_has_key?
+	#---------------------------------------------------------------------------
+	
+	
+	
+	#---------------------------------------------------------------------------
+	# row_hash_by_key
+	#
+	def row_hash_by_key(parent_pk, hkey)
+		# $tm.hrm
+		
+		# ensure statement handle
+		if not @preps['row_hash_by_key']
+			sql = <<~SQL
+			select * from objects
+			where pk =
+				(select child from relationships where parent=:parent and hkey=:hkey) and
+				partition=:partition
+			SQL
+			
+			@preps['row_hash_by_key'] = @dbh.prepare(sql)
+		end
+		
+		# params
+		params = {}
+		params['parent'] = parent_pk
+		params['hkey'] = hkey
+		params['partition'] = @partition
+		
+		# get record
+		@preps['row_hash_by_key'].execute(params).each_hash do |row|
+			return self.class.set_row_scalar(row.to_h)
+		end
+		
+	ensure
+		@preps['row_hash_by_key'] and @preps['row_hash_by_key'].reset!
+	end
+	#
+	# row_hash_by_key
+	#---------------------------------------------------------------------------
+	
+	
+	
+	#---------------------------------------------------------------------------
+	# hash_element_delete
+	#
+	def hash_element_delete(parent_pk, key)
+		# $tm.hrm
+		
+		# get record
+		record = row_hash_by_key(parent_pk, key)
+		
+		# execute
+		if record
+			if not @preps['delete_hash_key']
+				sql = <<~'SQL'
+				delete from relationships
+				where parent=:parent and hkey=:hkey
+				SQL
+				
+				@preps['delete_hash_key'] = @dbh.prepare(sql)
+			end
+			
+			simple_exec @preps['delete_hash_key'], 'parent'=>parent_pk, 'hkey'=>key
+		end
+		
+		# return
+		return record
+	end
+	#
+	# hash_element_delete
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# row_by_pk
+	#
+	def row_by_pk(pk)
+		# $tm.hrm
+		
+		# ensure prepared statement
+		@preps['row_by_pk'] ||= @dbh.prepare('select * from objects where pk=:pk and partition=:partition')
+		
+		# get record
+		@preps['row_by_pk'].execute('pk'=>pk, 'partition'=>@partition).each_hash do |row|
+			return self.class.set_row_scalar(row.to_h)
+		end
+		
+		# didn't find the object, so return nil
+		return nil
+		
+	ensure
+		@preps['row_by_pk'] and @preps['row_by_pk'].reset!
+	end
+	#
+	# row_by_pk
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# row_by_array_index
+	#
+	def row_by_array_index(parent_pk, idx)
+		# $tm.hrm
+		
+		# ensure statement handle
+		if not @preps['row_by_array_index']
+			sql = <<~SQL
+			select r.ord as ord, o.*
+			from relationships r, objects o
+			where r.parent=:parent and o.pk=r.child
+			order by r.ord
+			limit 1
+			offset :offset
+			SQL
+			
+			@preps['row_by_array_index'] = @dbh.prepare(sql)
+		end
+		
+		# get record
+		@preps['row_by_array_index'].execute('parent'=>parent_pk, 'offset'=>idx).each_hash do |row|
+			return self.class.set_row_scalar(row.to_h)
+		end
+		
+		# else return nil
+		return nil
+	ensure
+		@preps['row_by_array_index'] and @preps['row_by_array_index'].reset!
+	end
+	#
+	# row_by_array_index
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# hash_each
+	#
+	def hash_each(parent_pk)
+		# $tm.hrm
+		rv = nil
+		
+		# loop through keys
+		hash_keys(parent_pk).each do |key|
+			if block_given?
+				yield key, row_hash_by_key(parent_pk, key)
+			else
+				rv ||= []
+				rv.push [key, row_hash_by_key(parent_pk, key)]
+			end
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# hash_each
+	#---------------------------------------------------------------------------
+	
+	
+	
+	#---------------------------------------------------------------------------
+	# hash_keys
+	#
+	def hash_keys(parent_pk)
+		# $tm.hrm
+		rv = []
+		
+		# prepare
+		@preps['hash_keys'] ||= @dbh.prepare('select hkey from relationships where parent=:parent order by ord')
+		
+		# loop through records
+		@preps['hash_keys'].execute('parent'=>parent_pk).each_hash do |row|
+			rv.push row['hkey']
+		end
+		
+		# return
+		return rv
+		
+	ensure
+		@preps['hash_keys'] and @preps['hash_keys'].reset!
+	end
+	#
+	# hash_keys
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# clear_collection
+	#
+	def clear_collection(parent_pk)
+		# $tm.hrm
+		
+		# prepare
+		@preps['clear_collection'] ||= @dbh.prepare('delete from relationships where parent=:parent')
+		
+		# execute
+		simple_exec @preps['clear_collection'], 'parent'=>parent_pk
+	end
+	#
+	# clear_collection
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# changed_get
+	#
+	def changed_get(pk)
+		# $tm.hrm
+		
+		# prepare
+		@preps['changed_get'] ||= @dbh.prepare('select changed from objects where pk=:pk')
+		
+		# execute
+		@preps['changed_get'].execute('pk'=>pk).each_hash do |row|
+			return row['changed']
+		end
+	ensure
+		@preps['changed_get'] and @preps['changed_get'].reset!
+	end
+	#
+	# changed_get
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# changed_set
+	#
+	def changed_set(pk, bool)
+		# $tm.hrm
+		
+		# set to changed
+		if bool
+			@preps['changed_set_true'] ||= @dbh.prepare('update base_objects set changed=current_timestamp where pk=:pk')	
+			simple_exec @preps['changed_set_true'], 'pk'=>pk
+		else
+			@preps['changed_set_false'] ||= @dbh.prepare('update base_objects set changed=null where pk=:pk')	
+			simple_exec @preps['changed_set_false'], 'pk'=>pk
+		end
+	end
+	#
+	# changed_set
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# collection_child_pks
+	#
+	def collection_child_pks(parent_pk)
+		# $tm.hrm
+		
+		# prepare
+		if not @preps['collection_child_pks']
+			sql = <<~'SQL'
+			select child
+			from relationships
+			where parent=:parent
+			SQL
+			
+			@preps['collection_child_pks'] ||= @dbh.prepare(sql)
+		end
+		
+		# init
+		rv = []
+		
+		# get count
+		@preps['collection_child_pks'].execute(parent_pk).each_hash do |row|
+			rv.push row['child']
+		end
+		
+		# return
+		return rv
+	ensure
+		@preps['collection_child_pks'] and @preps['collection_child_pks'].reset!
+	end
+	#
+	# collection_child_pks
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# collection_length
+	#
+	def collection_length(parent_pk)
+		# $tm.hrm
+		
+		# prepare
+		if not @preps['collection_length']
+			sql = <<~'SQL'
+			select count(*) as count
+			from relationships
+			where parent=:parent
+			SQL
+			
+			@preps['collection_length'] ||= @dbh.prepare(sql)
+		end
+		
+		# get count
+		@preps['collection_length'].execute(parent_pk).each_hash do |row|
+			return row['count']
+		end
+	ensure
+		@preps['collection_length'] and @preps['collection_length'].reset!
+	end
+	#
+	# collection_length
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# array_each
+	#
+	def array_each(parent_pk)
+		# $tm.hrm
+		
+		# ensure statement handle
+		if not @preps['array_each']
+			sql = <<~SQL
+			select r.ord as ord, o.*
+			from relationships r, objects o
+			where r.parent=:parent and o.pk=r.child
+			order by r.ord
+			SQL
+			
+			@preps['array_each'] = @dbh.prepare(sql)
+		end
+		
+		# loop through records
+		@preps['array_each'].execute('parent'=>parent_pk).each_hash do |row|
+			yield row
+		end
+	ensure
+		@preps['array_each'] and @preps['array_each'].reset!
+	end
+	#
+	# array_each
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# object_exists?
+	#
+	def object_exists?(pk)
+		# $tm.hrm
+		
+		# ensure statement handle
+		if not @preps['object_exists']
+			sql = <<~'SQL'
+			select count(*) as count
+			from objects
+			where
+			pk=:pk and
+			partition=:partition
+			SQL
+			
+			@preps['object_exists'] = @dbh.prepare(sql)
+		end
+		
+		@preps['object_exists'].execute('pk'=>pk, 'partition'=>@partition).each do |row|
+			return row['count'] > 0
+		end
+	ensure
+		@preps['object_exists'] and @preps['object_exists'].reset!
+	end
+	#
+	# object_exists?
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# ancestors
+	#
+	def ancestors(child_pk)
+		# sql to add parents
+		if not @preps['ancestors']
+			sql = <<~'SQL'
+			select *
+				from objects where pk in (
+					with recursive
+						ancestors(c) as (
+							values(:child_pk)
+							union
+							select parent from relationships, ancestors
+							where relationships.child=ancestors.c
+						)
+					select parent from relationships
+						where relationships.child in ancestors
+			);
+			SQL
+			
+			@preps['ancestors'] = @dbh.prepare(sql)
+		end
+		
+		# loop through results
+		@preps['ancestors'].execute('child_pk'=>child_pk).each do |row|
+			yield row
+		end
+	ensure
+		@preps['ancestors'] and @preps['ancestors'].reset!
+	end
+	#
+	# ancestors
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# q0
+	#
+	def q0(p_fquery)
+		require 'audrey/engine/sqlite3/query/q0'
+		return Audrey::Engine::SQLite3::Query::Q0.new(self, p_fquery)
+	end
+	#
+	# q0
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# import_csv
+	#
+	def import_csv(fclass, path, opts={})
+		# $tm.hrm
+		return Audrey::Engine::SQLite3::Importer::CSV.new(self, fclass, path, opts={})
+	end
+	#
+	# import_csv
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# changed_objects
+	#
+	def changed_objects
+		# $tm.hrm
+		
+		# sql to add parents
+		if not @preps['changed_objects']
+			sql = <<~'SQL'
+			select *
+				from objects
+			where
+				changed and
+				custom_class(fclass)
+			order by
+				changed
+			SQL
+			
+			@preps['changed_objects'] = @dbh.prepare(sql)
+		end
+		
+		# loop through results
+		@preps['changed_objects'].execute().each do |row|
+			yield row
+		end
+	ensure
+		@preps['changed_objects'] and @preps['changed_objects'].reset!
+	end
+	#
+	# changed_objects
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	
+	#---------------------------------------------------------------------------
+	# simple_exec
+	#
+	def simple_exec(stmt, *opts)
+		begin
+			stmt.execute(*opts)
+		ensure
+			stmt.reset!
+		end
+	end
+	#
+	# simple_exec
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# RUBY_SCALAR_TO_SQLITE
+	#
+	RUBY_SCALAR_TO_SQLITE = {}
+	
+	RUBY_SCALAR_TO_SQLITE[::String] = {
+		'fclass' => Audrey::Object::Scalar::String,
+		'to_db' => Proc.new {|obj| obj}
+	}
+	
+	RUBY_SCALAR_TO_SQLITE[::Integer] = {
+		'fclass' => Audrey::Object::Scalar::Number,
+		'to_db' => Proc.new {|obj| obj.to_s}
+	}
+	
+	RUBY_SCALAR_TO_SQLITE[::Float] = RUBY_SCALAR_TO_SQLITE[::Integer]
+	
+	RUBY_SCALAR_TO_SQLITE[::TrueClass] = {
+		'fclass' => Audrey::Object::Scalar::Boolean,
+		'to_db' => Proc.new {|obj| obj ? 1 : 0}
+	}
+	
+	RUBY_SCALAR_TO_SQLITE[::FalseClass] = RUBY_SCALAR_TO_SQLITE[::TrueClass]
+	
+	RUBY_SCALAR_TO_SQLITE[::NilClass] = {
+		'fclass' => Audrey::Object::Scalar::Null,
+		'to_db' => Proc.new {|obj| nil}
+	}
+	
+	RUBY_SCALAR_TO_SQLITE.freeze
+	#
+	# RUBY_SCALAR_TO_SQLITE
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# prepare_insert_collection
+	#
+	def prepare_insert_collection
+		if not @preps['insert_collection']
+			sql = <<~'SQL'
+			insert into objects(pk, partition, bclass, fclass)
+			values(:pk, :partition, :bclass, :fclass)
+			SQL
+			
+			@preps['insert_collection'] = @dbh.prepare(sql)
+		end
+		
+		return @preps['insert_collection']
+	end
+	#
+	# prepare_insert_collection
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# set_row_scalar
+	#
+	def self.set_row_scalar(row)
+		# fix scalar if necessary
+		if converter = Audrey::AUDREY_SCALAR_TO_RUBY[row['fclass']]
+			row['scalar'] = converter.call(row['scalar'])
+		end
+		
+		# return
+		return row
+	end
+	#
+	# set_row_scalar
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# session_tables
+	#
+	def self.session_tables(dbh)
+		# create temp tables
+		# KLUDGE: query_rows references objects, but apparently you can't reference
+		# from a temp table to a main table. For now just not enforcing referential
+		# integrity.
+		sql = <<~"SQL"
+		create temp table connection(key varchar(5) primary key, val varchar(64));
+		insert into connection(key, val) values('partition', null);
+		
+		create temp table queries (pk varchar(5) primary key);
+		create temp table subqueries (pk varchar(5) primary key, query not null references queries(pk));
+		
+		create temp table query_rows (
+			subquery varchar(5) not null references subqueries(pk) on delete cascade,
+			parent varchar(36) not null, -- references objects(pk),
+			unique(subquery, parent)
+		);
+		SQL
+		
+		# execute
+		dbh.execute_batch sql
+	end
+	#
+	# session_tables
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# set_lock
+	#
+	def set_lock()
+		# $tm.hrm
+		
+		# open lock file
+		@lock = File.open(@path + '.lock', File::RDWR|File::CREAT)
+		
+		# exclusive
+		if @mode.write
+			@lock.flock File::LOCK_EX
+		
+		# shared
+		else
+			@lock.flock File::LOCK_SH
+		end
+	end
+	#
+	# set_lock
+	#---------------------------------------------------------------------------
+end
+#
+# Audrey::Engine::SQLite3
+#===============================================================================
+
+
+#===============================================================================
+# Audrey::Engine::SQLite3::Importer
+#
+class Audrey::Engine::SQLite3::Importer
+end
+#
+# Audrey::Engine::SQLite3::Importer
+#===============================================================================
+
+
+#===============================================================================
+# Audrey::Engine::SQLite3::Importer::CSV
+#
+class Audrey::Engine::SQLite3::Importer::CSV < Audrey::Engine::SQLite3::Importer
+	attr_reader :fields
+	attr_accessor :verbose
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(engine, fclass, path, opts={})
+		# $tm.hrm
+		require 'csv'
+		@engine = engine
+		@dbh = @engine.dbh
+		@fclass = fclass.to_s
+		@path = path
+		@partition = 'm'
+		@fields = {}
+		@verbose = false
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# run
+	#
+	def run
+		# $tm.hrm
+		converters = {}
+		count = 0
+		
+		# set fclass primary keys
+		fclass_pks()
+		
+		# prepare statements
+		prepare_statements()
+		
+		# build converters
+		@fields.each do |k, dfn|
+			converters[k] = Audrey::AUDREY_SCALAR_TO_RUBY[dfn.to_s]
+		end
+		
+		# begin transaction
+		@dbh.execute 'begin transaction'
+		
+		# TESTING
+		$tm.timer('import') do
+			# loop through CSV
+			::CSV.foreach(@path, headers: true) do |row|
+				# verbosify
+				if @verbose
+					count += 1
+					puts count.to_s + ': ' + row.to_s
+				end
+				
+				# init collection ord
+				ord = 0
+				
+				# convert
+				converters.each do |k, converter|
+					if row.has_key?(k)
+						row[k] = converter.call(row[k])
+					end
+				end
+				
+				# object pk
+				obj_pk = Audrey::Util.uuid
+				
+				# add hash object
+				@insert_hash.execute(
+					'pk'=>obj_pk,
+					'partition'=>@partition,
+					'bclass'=>@obj_bclass_pk,
+					'fclass'=>@obj_fclass_pk
+				);
+				
+				# add scalars and relationships
+				row.each do |k,v|
+					ord += 1
+					scalar_uuid = Audrey::Util.uuid
+					
+					# add scalar object
+					@insert_scalar.execute(
+						'pk'=>scalar_uuid,
+						'partition'=>@partition,
+						'bclass'=>@scalar_bclass_pk,
+						'fclass'=>@bclasses[v.class],
+						'scalar'=>v
+					);
+					
+					# add relationship
+					@insert_relationship.execute(
+						'pk'=>Audrey::Util.uuid,
+						'parent'=>obj_pk,
+						'child'=>scalar_uuid,
+						'hkey'=>k,
+						'ord'=>ord
+					);
+				end
+			end
+		end
+		
+		# commit transaction
+		$tm.timer('commit') do
+			@dbh.execute 'commit'
+		end
+		
+	# close prepared statements
+	ensure
+		$tm.puts 'close prepared statements'
+		
+		$tm.timer('close prepared statements') do
+			@insert_hash and @insert_hash.close
+			@insert_scalar and @insert_scalar.close
+			@insert_relationship and @insert_relationship.close
+		end
+	end
+	#
+	# run
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# prepare_statements
+	#
+	def prepare_statements
+		# $tm.hrm
+		
+		# hash
+		sql = <<~'SQL'
+		insert into
+			base_objects(
+				pk,
+				partition,
+				bclass_pk,
+				fclass_pk
+			)
+			
+			values(
+				:pk,
+				:partition,
+				:bclass,
+				:fclass
+			);
+		SQL
+		
+		# prepare
+		@insert_hash = @dbh.prepare(sql)
+		
+		# scalar
+		sql = <<~'SQL'
+		insert into
+			base_objects(
+				pk,
+				partition,
+				bclass_pk,
+				fclass_pk,
+				scalar
+			)
+			
+			values(
+				:pk,
+				:partition,
+				:bclass,
+				:fclass,
+				:scalar
+			);
+		SQL
+		
+		# prepare
+		@insert_scalar = @dbh.prepare(sql)
+		
+		# relationship
+		sql = <<~'SQL'
+		insert into relationships(
+			pk,
+			parent,
+			child,
+			hkey,
+			ord
+		)
+		
+		values(
+			:pk,
+			:parent,
+			:child,
+			:hkey,
+			:ord
+		)
+		SQL
+		
+		# prepare
+		@insert_relationship = @dbh.prepare(sql)
+	end
+	#
+	# prepare_statements
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# fclass_pks
+	#
+	def fclass_pks
+		@bclasses = {}
+		
+		# object bclass primary key
+		@obj_bclass_pk = set_fclass_pk('Audrey::Object::Hash')
+		
+		# object fclass primary key
+		@obj_fclass_pk = set_fclass_pk(@fclass)
+		
+		# scalar base class
+		@scalar_bclass_pk = set_fclass_pk('Audrey::Object::Scalar')
+		
+		# loop through scalar classes
+		[String, Integer, Float, NilClass].each do |clss|
+			@bclasses[clss] = set_fclass_pk(Audrey::RUBY_OBJECT_TO_AUDREY[clss]['fclass'].to_s)
+		end
+	end
+	#
+	# fclass_pks
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# set_fclass_pk
+	#
+	def set_fclass_pk(set_fclass)
+		# $tm.hrm
+		
+		# ensure fclass record
+		sql = <<~'SQL'
+		insert or ignore into
+		fclasses(name)
+		values(:fclass);
+		SQL
+		
+		# execute
+		@dbh.execute sql, 'fclass'=>set_fclass
+		
+		# get fclass pk
+		sql = 'select pk from fclasses where name=:fclass'
+		return @dbh.get_first_value(sql, 'fclass'=>set_fclass)
+	end
+	#
+	# set_fclass_pk
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# set_bclass_pks
+	#
+	# def set_bclass_pks
+	#	$tm.hrm
+	# end
+	#
+	# set_bclass_pks
+	#---------------------------------------------------------------------------
+end
+#
+# Audrey::Engine::SQLite3::Importer::CSV
+#===============================================================================
+
+
+#===============================================================================
+# Audrey::Engine::SQLite3::Query
+#
+class Audrey::Engine::SQLite3::Query
+end
+#
+# Audrey::Engine::SQLite3::Query
+#===============================================================================
+
+
+#===============================================================================
+# Audrey::Engine::SQLite3::Transaction
+#
+class Audrey::Engine::SQLite3::Transaction < Audrey::Transaction
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_engine)
+		@engine = p_engine
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+end
+#
+# Audrey::Engine::SQLite3::Transaction
+#===============================================================================
+
+
+#===============================================================================
+# Audrey::Engine::SQLite3::Transaction::AutoCommit
+#
+class Audrey::Engine::SQLite3::Transaction::AutoCommit < Audrey::Engine::SQLite3::Transaction
+	def commit
+		@engine.reset_savepoints self
+	end
+	
+	def start
+	end
+	
+	def rollback
+	end
+	
+	def release
+	end
+end
+#
+# Audrey::Engine::SQLite3::Transaction::AutoCommit
+#===============================================================================
+
+
+#===============================================================================
+# Audrey::Engine::SQLite3::Transaction::RC
+# An object of this class represents a transaction that can be rolled back or
+# committed.
+#
+class Audrey::Engine::SQLite3::Transaction::RC < Audrey::Engine::SQLite3::Transaction
+	attr_reader :savepoint
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(*opts)
+		super(*opts)
+		start()
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# start
+	#
+	def start
+		@savepoint = Audrey::Util.randstr()
+		@engine.dbh.execute "savepoint #{@savepoint}"
+	end
+	#
+	# start
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# commit
+	#
+	def commit
+		release()
+		@engine.reset_savepoints self
+	end
+	#
+	# commit
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# rollback
+	#
+	def rollback
+		@engine.dbh.execute "rollback to #{@savepoint}"
+	end
+	#
+	# rollback
+	#---------------------------------------------------------------------------
+
+	
+	#---------------------------------------------------------------------------
+	# terminate
+	#
+	def terminate
+		rollback()
+		release()
+	end
+	#
+	# terminate
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	
+	#---------------------------------------------------------------------------
+	# release
+	#
+	def release
+		@engine.dbh.execute "release #{@savepoint}"
+		@savepoint = nil
+	end
+	#
+	# release
+	#---------------------------------------------------------------------------
+end
+#
+# Audrey::Engine::SQLite3::Transaction::RC
+#===============================================================================