gloo-db 1.1 → 1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 778e0ec24cdb55d18047a73c5d5b125b1c9e079b378b7e8611a90890cf66ba8b
-  data.tar.gz: 30d8e53743f29cd3aa24f58e93fcd475c29ad8150f3c6377500a8c48eaae0c4e
+  metadata.gz: 3ad932a978b3c8ba5733dcd79d4188748ccbeae4077da55dfe096ced7bcc5fd0
+  data.tar.gz: 878fed77aa72d68a826043ac53026753b8cd50817efcf428d2df13b34998b729
 SHA512:
-  metadata.gz: 8922b35f3b17002743dfd0d8366ccda1ebff342e78adcd5a1d60cb37cd3723a16ff4f0c6db4227f342a3067c57ee97aa1efc1a94f447c906909a8eeb6e45f1b2
-  data.tar.gz: 10e12ef81de0fa63e309bff21257c3f9f66ffb66dc62f9b4001d2cc275ef402676aac3e88806a0da9a8a069561bc75bdc7f30349023e5aeaf30b1281c89f8b01
+  metadata.gz: 7fd86d6a95af8d73e481d8f6a589fb7bb7e4adf2708351e434fd2c28a677f3f804d01c2c75cd5f43d427829bccc8d1afcce455956cff2db692e2ddb97818f4c6
+  data.tar.gz: 6d166a12139e3e9cf9796c9e9cf49ff05df66ee13f17c80c3daebf25aebc7b48502d33346e65b069763de6bb617baa3b5dfc229db77a9396e37e72e403e80c45

data/README.md

@@ -0,0 +1,23 @@
+# gloo-db
+
+A core gloo library for database operations.
+
+Use this library and one of the database-specific driver libraries (`gloo-pg`, `gloo-mysql`, `gloo-sqlite`) to interact with databases.
+
+## Usage
+
+Load this library, plus a driver, in a gloo script:
+
+```gloo
+> load lib db
+> load lib sqlite
+```
+
+## Objects
+
+- `query` — a SQL query (SELECT, INSERT, UPDATE, or other statement)
+- `table` — a data table
+
+## Full Reference
+
+Every object's children and messages are documented in-app once the library is loaded — e.g. `help> object query`.

data/lib/db_connection.rb

@@ -0,0 +1,60 @@
+# Author::    Eric Crane  (mailto:eric.crane@mac.com)
+# Copyright:: Copyright (c) 2026 Eric Crane.  All rights reserved.
+#
+# Shared behaviour for database connection objects (gloo-sqlite,
+# gloo-mysql, gloo-pg). A connection class includes this module so
+# every driver reports problems the same way:
+#
+#   - Database errors (bad SQL, a missing table, a lost connection)
+#     come out of the driver's query as exceptions; Query reports them
+#     as one readable error. database_errors says which exception
+#     classes those are.
+#   - Setup problems the driver can see (eg. no database name) are
+#     reported with setup_err, and the query returns no result.
+#   - verify puts true in it, or reports a readable error and puts
+#     false (verify_connection).
+#
+module DbConnection
+
+  #
+  # The exception classes that are database errors for this driver.
+  # Query reports these as 'Query failed: …'; anything else is an
+  # unexpected error. Drivers override this with their library's
+  # error classes.
+  #
+  def database_errors
+    return [ StandardError ]
+  end
+
+  #
+  # Verify the connection: run the block, which connects (and raises
+  # if it can't). It is true when it connects, false otherwise, with
+  # a readable error and no backtrace.
+  #
+  def verify_connection
+    yield
+    @engine.heap.it.set_to true
+    return true
+  rescue *database_errors, SystemCallError => e
+    @engine.err "Could not connect to #{connection_label}: #{e.message}"
+    @engine.heap.it.set_to false
+    return false
+  end
+
+  #
+  # Report a setup problem (eg. no database name) and return nil,
+  # meaning no result.
+  #
+  def setup_err( msg )
+    @engine.err msg
+    return nil
+  end
+
+  #
+  # How the connection is named in messages, eg. sqlite 'db'.
+  #
+  def connection_label
+    return "#{self.class.typename} '#{name}'"
+  end
+
+end

data/lib/gloo-db.rb

@@ -1,8 +1,9 @@
-# 
-# Shim to allow `require 'gloo-mysql'`
-# 
+#
+# Shim to allow `require 'gloo-db'`
+#
 # This file is loaded when someone does `require 'gloo-mysql'`
 # 
+require 'db_connection'
 require 'query'
 require 'query_result'
 require 'table'

data/lib/query.rb

@@ -17,6 +17,7 @@ class Query < Gloo::Core::Obj
   SIMPLE_LIST = 'simple_list'.freeze
 
   DB_MISSING_ERR = 'The database connection is missing!'.freeze
+  QUERY_FAILED = 'Query failed: '.freeze
 
   #
   # The name of the object type.
@@ -79,45 +80,43 @@ class Query < Gloo::Core::Obj
 
   #
   # Run the query and process the results.
+  # It is true when the query ran, false if it failed.
   #
   def msg_run
     db = db_obj
-    return unless db
+    return @engine.heap.it.set_to( false ) unless db
 
-    begin
-      clear_results
+    sql = sql_value
+    return @engine.heap.it.set_to( false ) unless sql
 
-      log_query sql_value, param_array
-      result = db.query( sql_value, param_array )
-      process_result( result, db )
-    rescue => e
-      @engine.log_exception e
-      return
-    end
+    # Clear first, so a failed query doesn't leave the last results.
+    clear_results
+    result = execute( db, sql )
+    return @engine.heap.it.set_to( false ) unless result
+
+    process_result( result, db )
+    @engine.heap.it.set_to true
   end
 
   #
-  # Run the query and return the results.
+  # Run the query and return the results (used by table).
+  # Returns nil if the query failed; the failure is reported.
   #
   def run_query
     db = db_obj
-    return unless db
-
-    begin
-      log_query sql_value, param_array
-
-      db_start = ::Time.now
-      result = db.query( sql_value, param_array )
-      db_done = ::Time.now
-      elapsed = ( ( db_done - db_start ) * 1000.0 ).round(2)
-
-      app = @engine.running_app
-      app.add_db_time elapsed if app
-      return result
-    rescue => e
-      @engine.log_exception e
-      return
-    end
+    return nil unless db
+
+    sql = sql_value
+    return nil unless sql
+
+    db_start = ::Time.now
+    result = execute( db, sql )
+    db_done = ::Time.now
+    elapsed = ( ( db_done - db_start ) * 1000.0 ).round(2)
+
+    app = @engine.running_app
+    app.add_db_time elapsed if app
+    return result
   end
 
   # 
@@ -151,29 +150,71 @@ class Query < Gloo::Core::Obj
   private
 
   #
-  # Get the database connection.
+  # Run the SQL on the database connection. A database error (one of
+  # the driver's database_errors) is reported as one readable error,
+  # with no backtrace. Returns the result, or nil if the query failed
+  # or the driver reported a setup problem.
+  #
+  def execute( db, sql )
+    params = param_array
+    log_query sql, params
+    return db.query( sql, params )
+  rescue *database_errors_for( db ) => e
+    @engine.err "#{QUERY_FAILED}#{e.message}"
+    return nil
+  end
+
+  #
+  # The exception classes that are database errors for the driver.
+  # A driver that doesn't say (an older one) counts every
+  # StandardError.
+  #
+  def database_errors_for( db )
+    return db.database_errors if db.respond_to?( :database_errors )
+
+    return [ StandardError ]
+  end
+
+  #
+  # Get the database connection. Reports an error and returns nil if
+  # there's no database child, its alias points at nothing, or it
+  # isn't a database connection.
   #
   def db_obj
     o = find_child DB
 
-    unless o
+    # No database child, or an alias that doesn't point anywhere yet.
+    if o.nil? || o.value.to_s.strip.empty?
       @engine.err DB_MISSING_ERR
       return nil
     end
 
-    return Gloo::Objs::Alias.resolve_alias( @engine, o )
+    db = Gloo::Objs::Alias.resolve_alias( @engine, o )
+    unless db
+      @engine.err Gloo::Core::NotFound.object( o.value )
+      return nil
+    end
+
+    unless db.respond_to?( :query )
+      @engine.err "'#{o.value}' is not a database connection."
+      return nil
+    end
+
+    return db
   end
 
   #
   # Get the SQL from the child object.
-  # Returns nil if there is none.
+  # Reports an error and returns nil if there is none.
   #
   def sql_value
     o = find_child SQL
-    return nil unless o
-
     o = Gloo::Objs::Alias.resolve_alias( @engine, o )
-    return o.value
+    sql = o&.value.to_s
+    return sql unless sql.strip.empty?
+
+    @engine.err "query '#{name}' has no SQL; put a SQL statement into #{name}.sql first."
+    return nil
   end
 
   #
@@ -262,4 +303,43 @@ class Query < Gloo::Core::Obj
     end
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'A SQL Query — a SELECT, INSERT, UPDATE or other ' \
+        'SQL statement. The query requires a valid database connection.',
+      :children => [
+        'database (alias) — Reference to the database we\'re going to query.',
+        'sql (string) — The SQL query to execute.',
+        'result (container) — Optional. The result of the query will be a container for each row, with an object for each column. If not present, results are displayed in the console instead.',
+        'params (container) — Optional list of parameters for the query.'
+      ],
+      :messages => [
+        'run — Run the query and get back the data. It is true when the query ran, false if it failed (with or without a result container).'
+      ],
+      :notes => 'Errors (and it is false): no database, a database ' \
+        'alias that points at nothing or at something that is not a ' \
+        'database connection, no SQL, and a database error such as bad ' \
+        "SQL or a missing table, reported as 'Query failed: ' and the " \
+        "database's message. A failed query clears the result container.",
+      :examples => <<~EXAMPLES.strip
+        sqlite [can] :
+          on_load [script] : run sqlite.sql
+          db [sqlite] :
+            database : test.db
+          sql [query] :
+            database [alias] : sqlite.db
+            sql : SELECT id, key, value FROM key_values
+      EXAMPLES
+    }
+  end
+
 end

data/lib/table.rb

@@ -73,17 +73,15 @@ class Table < Gloo::Core::Obj
     
     if o.is_a? Query
       @engine.log.debug "Table getting data from query."
-      begin
-        result = o.run_query
-        return result
-      rescue => e
-        @engine.log_exception e
-        return nil
-      end
+      # Nil if the query failed (Query has reported it).
+      return o.run_query
     else
       cols = self.columns
 
-      if o.children&.first.children.empty?
+      # No rows yet.
+      return [ cols, [] ] if o.children.empty?
+
+      if o.children.first.children.empty?
         # It is a simgle row table.
         rows = [ cols.map { |h| o.find_child( h )&.value } ]
       else
@@ -166,14 +164,24 @@ class Table < Gloo::Core::Obj
 
   #
   # Show the table in the CLI.
+  # Shows nothing if its query failed (the query reports the error).
   #
   def msg_show
+    result = data
+    return unless result
+
     title = self.value
-    @engine.platform.table.show headers, data[1], title
+    @engine.platform.table.show headers, result[1], title
   end
 
+  #
+  # Render the table as HTML, inside a web app.
+  # It has the HTML, or false if the table couldn't be rendered.
+  #
   def msg_render
-    return render
+    html = render
+    @engine.heap.it.set_to( html.nil? ? false : html )
+    return html
   end
 
 
@@ -185,9 +193,19 @@ class Table < Gloo::Core::Obj
   # Render the table.
   # The render_ƒ is 'render_html', 'render_text', 'render_json', etc.
   # 
-  def render render_ƒ
+  def render render_ƒ = :render_html
+    # Outside a web app (or without gloo-web) there's no renderer.
+    helper = table_renderer
+    unless helper
+      @engine.err "table '#{name}' can only render inside a web app (gloo-web); use show to see it in the console."
+      return nil
+    end
+
     begin
       result = self.data
+      # The query failed and has reported it.
+      return nil unless result
+
       head = self.headers 
       head = result[0] if head.empty?
       rows = result[1]
@@ -207,20 +225,24 @@ class Table < Gloo::Core::Obj
         params[ :always_rows ] = true
       end
 
-      # helper = Gloo::WebSvr::TableRenderer.new( @engine )
-      helper = @engine.running_app&.create_table_renderer
-      if helper
-        return helper.data_to_table params
-      else
-        @engine.log.error "Table renderer not found."
-        return nil
-      end
+      return helper.data_to_table params
     rescue => e
       @engine.log_exception e
       return nil
     end
   end
 
+  #
+  # The web app's table renderer, or nil outside a web app or when
+  # gloo-web isn't loaded.
+  #
+  def table_renderer
+    return nil unless @engine.running_app
+    return nil unless defined?( WebSvr::TableRenderer )
+
+    return @engine.running_app.create_table_renderer
+  end
+
   # 
   # Build the column list based on the result data and
   # the headers defined in the table object.
@@ -266,4 +288,55 @@ class Table < Gloo::Core::Obj
     return columns.sort_by { |hsh| hsh[ :display_index ] }
   end
 
+  # ---------------------------------------------------------------------
+  #    Object Documentation
+  # ---------------------------------------------------------------------
+
+  #
+  # Get the object's documentation data.
+  #
+  def self.doc_data
+    {
+      :name => KEYWORD,
+      :shortcut => KEYWORD_SHORT,
+      :description => 'A data table.',
+      :children => [
+        'headers (container) — A list of headers. The name of each header object must match the name of the object in the data container; the value of the header is what will be displayed.',
+        'data (container) — The table\'s data. Contains one or more containers, each representing one row of data.',
+        'cells (container) — Optional. If present, cells can be formatted with a child per column you want to format; you don\'t need to specify a child for every column.',
+        'always_rows (boolean) — Optional. By default, if a table\'s data is only 1 row, it shows that row in a vertical table. Marking this true means a horizontal table is shown even if only one row is returned.'
+      ],
+      :messages => [
+        'show — Show the contents of the table in the CLI.',
+        'render — Render the table as HTML, inside a web app (gloo-web). It has the HTML. Outside a web app this is an error, and it is false; use show instead.'
+      ],
+      :notes => 'If data is a query and the query fails, the query ' \
+        'reports the error and show and render stop without showing ' \
+        'anything.',
+      :examples => <<~EXAMPLES.strip
+        t [tbl] :
+          on_load [script] :
+            tell t to show
+          headers [can] :
+            name : Name
+            phone : Tel
+            notes : Notes
+          data [alias] : table_data
+        table_data [can] :
+          1 [can] :
+            name : Joe
+            phone : 312-555-1212
+            notes : Play golf with Joe
+          2 [can] :
+            name : Sally
+            phone : 708-555-1212
+            notes : met Sally at the meetup last week
+          3 [can] :
+            name : Frank
+            phone : 312-555-1213
+            notes : Frank Lee Speaking
+      EXAMPLES
+    }
+  end
+
 end

metadata

@@ -1,15 +1,82 @@
 --- !ruby/object:Gem::Specification
 name: gloo-db
 version: !ruby/object:Gem::Version
-  version: '1.1'
+  version: '1.3'
 platform: ruby
 authors:
 - Eric Crane
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-06 00:00:00.000000000 Z
-dependencies: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gloo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.14.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 13.0.1
 description: Adds database support to Gloo.
 email:
 - eric.crane@mac.com
@@ -17,16 +84,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- lib/db_connection.rb
 - lib/gloo-db.rb
 - lib/query.rb
 - lib/query_result.rb
 - lib/table.rb
-homepage: https://gloo.ecrane.us/
+homepage: https://github.com/ecrane/gloo
 licenses:
 - MIT
 metadata:
   gloo.type: core-library
-post_install_message:
+  documentation_uri: https://github.com/ecrane/gloo
 rdoc_options: []
 require_paths:
 - lib
@@ -41,8 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Gloo core library. Database support.
 test_files: []