gloo-db 1.2 → 1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5f869d21a951e0e316359c444255d44fdae07b64bf9991eb1739ba9df90431c
-  data.tar.gz: 64f9bc0c6aeb28f99779a9addacbf3fbc4bcb3265c3b096d93c9db8d19b5c40e
+  metadata.gz: 3ad932a978b3c8ba5733dcd79d4188748ccbeae4077da55dfe096ced7bcc5fd0
+  data.tar.gz: 878fed77aa72d68a826043ac53026753b8cd50817efcf428d2df13b34998b729
 SHA512:
-  metadata.gz: e7af37a53fdc0b250306bf723ae92181cca7958aa7dedbf78c61e1f9c660bcc3ee1f46ac52082df6647a3f55ea077ac05ebf659dd309f7c5900348521d71b035
-  data.tar.gz: 25b3ec859468892ac5ed7572790b6400259e52241eca8ef18e0170f6db0cc0fa3a683bb6c27903efbd2513cd0ea4a18a2653ad0e011ccbb3a7e87c3e76641193
+  metadata.gz: 7fd86d6a95af8d73e481d8f6a589fb7bb7e4adf2708351e434fd2c28a677f3f804d01c2c75cd5f43d427829bccc8d1afcce455956cff2db692e2ddb97818f4c6
+  data.tar.gz: 6d166a12139e3e9cf9796c9e9cf49ff05df66ee13f17c80c3daebf25aebc7b48502d33346e65b069763de6bb617baa3b5dfc229db77a9396e37e72e403e80c45

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
 
   #
@@ -282,8 +323,13 @@ class Query < Gloo::Core::Obj
         'params (container) — Optional list of parameters for the query.'
       ],
       :messages => [
-        'run — Run the query and get back the data.'
+        '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

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.
@@ -285,8 +307,12 @@ class Table < Gloo::Core::Obj
         '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.'
+        '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] :

metadata

@@ -1,14 +1,82 @@
 --- !ruby/object:Gem::Specification
 name: gloo-db
 version: !ruby/object:Gem::Version
-  version: '1.2'
+  version: '1.3'
 platform: ruby
 authors:
 - Eric Crane
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+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,6 +85,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- lib/db_connection.rb
 - lib/gloo-db.rb
 - lib/query.rb
 - lib/query_result.rb