feat(sqlite): make opts.lazy false by default and add opts.keep_open

Before lazy was default and there was no way of changing that. I've
decided to make it optional because it seems that:

1. People expects sqlite {} or sqlite:extend {} to create all the
   defined table in advance.
2. Performance impact of initializing db object is only 1.0 slower in
   microseconds, so it seems to not be as important as I thought it
   would:

   ```lua
   -- test/lazy.lua
    Benchmark #1: 'Logical Component'
      Time(mean ± σ):     23.7 μs ±  18.7 μs
      Range(min … max):   17.4 μs … 102.3 μs  20 runs
    Benchmark #2: 'Full Initialization'
      Time(mean ± σ):     28.7 μs ±  12.9 μs
      Range(min … max):   24.1 μs …  83.1 μs  20 runs
    Summary
      'Logical Component' ran
      1.2 ± 1.1 times faster than 'Full Initialization'
   ```

Author: kkharji

lua/sqlite/db.lua

@@ -26,9 +26,9 @@ local tbl = require "sqlite.tbl"
 
 ---Creates a new sqlite.lua object, without creating a connection to uri.
 ---|sqlite.new| is identical to |sqlite.db:open| but it without opening sqlite db
----connection. Thus its most suited for cases where the database might be
----acccess from multiple places. For neovim use cases, this mean from different
----neovim instances.
+---connection (unless opts.keep_open). Its most suited for cases where the
+---database might be -acccess from multiple places. For neovim use cases, this
+---mean from different -neovim instances.
 ---
 ---<pre>
 ---```lua
@@ -39,16 +39,26 @@ local tbl = require "sqlite.tbl"
 ---@param opts sqlite_opts: (optional) see |sqlite_opts|
 ---@return sqlite_db
 function sqlite.db.new(uri, opts)
+  opts = opts or {}
+  local keep_open = opts.keep_open
+  opts.keep_open = nil
   uri = type(uri) == "string" and u.expand(uri) or ":memory:"
-  return setmetatable({
+
+  local o = setmetatable({
     uri = uri,
     conn = nil,
     closed = true,
-    opts = opts or {},
+    opts = opts,
     modified = false,
     created = nil,
     tbl_schemas = {},
   }, sqlite.db)
+
+  if keep_open then
+    o:open()
+  end
+
+  return o
 end
 
 ---Extend |sqlite_db| object with extra sugar syntax and api. This is recommended
@@ -61,27 +71,40 @@ end
 ---
 ---Like |sqlite_tbl| original methods can be access through pre-appending "__"
 ---when user overwrites it.
+---
+---if { conf.opts.lazy } then only return a logical object with self-dependent
+--tables, e.g. a table exists and other not because the one that
+---exists, it's method was called. (default false).
+---if { conf.opts.keep_open } then the sqlite extend db object will be returned
+---with an open connection (default false)
+
 ---<pre>
 ---```lua
 --- local db = sqlite { -- or sqlite_db:extend
 ---   uri = "path/to/db", -- path to db file
 ---   entries = require'entries',  -- a pre-made |sqlite_tbl| object.
 ---   category = { title = { "text", unique = true, primary = true}  },
 ---   opts = {} or nil -- custom sqlite3 options, see |sqlite_opts|
+---   --- if opts.keep_open, make connection and keep it open.
+---   --- if opts.lazy, then just provide logical object
 --- }
 --- --- Overwrite method and access it using through pre-appending "__"
 --- db.select = function(...) db:__select(...) end
 ---```
 ---</pre>
----@param opts table: see 'Fields'
+---@param conf table: see 'Fields'
 ---@field uri string: path to db file.
----@field opts sqlite_opts: (optional) see |sqlite_opts|
+---@field opts sqlite_opts: (optional) see |sqlite_opts| + lazy (default false), open (default false)
 ---@field tname1 string: pointing to |sqlite_etbl| or |sqlite_schema_dict|
 ---@field tnameN string: pointing to |sqlite_etbl| or |sqlite_schema_dict|
 ---@see sqlite_tbl:extend
 ---@return sqlite_db
-function sqlite.db:extend(opts)
-  local db = self.new(opts.uri, opts.opts)
+function sqlite.db:extend(conf)
+  conf.opts = conf.opts or {}
+  local lazy = conf.opts.lazy
+  conf.opts.lazy = nil
+
+  local db = self.new(conf.uri, conf.opts)
   local cls = setmetatable({ db = db }, {
     __index = function(_, key, ...)
       if type(key) == "string" then
@@ -93,15 +116,16 @@ function sqlite.db:extend(opts)
     end,
   })
 
-  for tbl_name, schema in pairs(opts) do
-    if tbl_name ~= "uri" and tbl_name ~= "opts" and u.is_tbl(schema) then
+  for tbl_name, schema in pairs(conf) do
+    if tbl_name ~= "uri" and tbl_name ~= "opts" and tbl_name ~= "lazy" and u.is_tbl(schema) then
       local name = schema._name and schema._name or tbl_name
-      cls[tbl_name] = schema.set_db and schema or require("sqlite.tbl").new(name, schema)
+      cls[tbl_name] = schema.set_db and schema or require("sqlite.tbl").new(name, schema, not lazy and db or nil)
       if not cls[tbl_name].db then
         (cls[tbl_name]):set_db(db)
       end
     end
   end
+
   return cls
 end
 

test/auto/db_spec.lua

@@ -802,12 +802,13 @@ describe("sqlite.db", function()
   describe(":extend", function()
     local testrui = "/tmp/extend_db_new"
     local testrui2 = "/tmp/extend_db_new5"
+    local testrui3 = "/tmp/extend_db_new5"
     local ok, manager
 
     it("Initialize manager", function()
-      ---@class Manager:sqldb
-      ---@field projects sqltable
-      ---@field todos sqltable
+      ---@class ManagerLazy:sqlite_db
+      ---@field projects sqlite_tbl
+      ---@field todos sqlite_tbl
       ok, manager = pcall(sql, {
         uri = testrui,
         projects = {
@@ -825,6 +826,7 @@ describe("sqlite.db", function()
         },
         opts = {
           foreign_keys = true,
+          lazy = true,
         },
       })
       eq(true, ok, manager)
@@ -914,7 +916,38 @@ describe("sqlite.db", function()
       eq(3, db.st:count(), "should have inserted.")
     end)
 
+    it("Initialize manager", function()
+      ---@class ManagerFull:sqlite_db
+      ---@field projects sqlite_tbl
+      ---@field todos sqlite_tbl
+      ok, manager = pcall(sql, {
+        uri = testrui,
+        projects = {
+          id = true,
+          title = "text",
+          objectives = "luatable",
+        },
+        todos = {
+          id = true,
+          title = "text",
+          client = "integer",
+          status = "text",
+          completed = "boolean",
+          details = "text",
+        },
+        opts = {
+          foreign_keys = true,
+          keep_open = true
+        }
+      })
+      eq(true, ok, manager)
+    end)
+    it("should exists", function()
+      eq(true, manager:exists("projects"))
+    end)
+
     luv.fs_unlink(testrui)
     luv.fs_unlink(testrui2)
+    luv.fs_unlink(testrui3)
   end)
 end)

test/lazy.lua

@@ -0,0 +1,71 @@
+local bunch = require'plenary.benchmark'
+R('sqlite')
+local sqlite = require('sqlite')
+local remove_db = function ()
+  vim.loop.fs_unlink("/tmp/uri")
+end
+
+bunch("Logical Component vs Full initialization", {
+  runs = 20,
+  fun = {
+    {
+      "Logical Component",
+      function ()
+        ---@class __ManagerA:sqlite_db
+        ---@field projects sqlite_tbl
+        ---@field todos sqlite_tbl
+        local db = sqlite {
+          uri = "/tmp/uri",
+          projects = {
+            id = true,
+            title = "text",
+            objectives = "luatable",
+          },
+          todos = {
+            id = true,
+            title = "text",
+            client = "integer",
+            status = "text",
+            completed = "boolean",
+            details = "text",
+          },
+          clients = { name = "text" },
+          opts = {
+            foreign_keys = true,
+          },
+          lazy = true
+        }
+        remove_db()
+      end
+    },
+    {
+      "Full Initialization",
+      function ()
+        ---@class __ManagerB:sqlite_db
+        ---@field projects sqlite_tbl
+        ---@field todos sqlite_tbl
+        local db = sqlite {
+          uri = "/tmp/uri",
+          projects = {
+            id = true,
+            title = "text",
+            objectives = "luatable",
+          },
+          todos = {
+            id = true,
+            title = "text",
+            client = "integer",
+            status = "text",
+            completed = "boolean",
+            details = "text",
+          },
+          clients = { name = "text" },
+          opts = {
+            foreign_keys = true,
+          },
+        }
+        remove_db()
+      end
+    }
+  }
+})