Improve Relation Definition Error Messages

[tamurashingo]

Overview

Improved error messages when there are relation specification errors (such as incorrect relation names) in queries defined with the query macro.

Background

Currently, when a relation name is incorrect, only a simple error message is displayed:

Relation `TAGS' not found for model `<TODO>'

This message alone does not indicate which query definition caused the error, making debugging difficult.

Changes

1. Add query-source-info slot to <query> and <query-placeholder> classes

Added a slot to store the original query definition information.

(defclass <query> ()
  (...
   (query-source-info :initform nil
                      :documentation "Original query definition for error messages")))

2. Save query definition in query macro

Save the original definition information (model, as, columns, joins, where, order-by, limit, offset) only when defined via the query macro.

(defmacro query (model &key as columns joins where order-by limit offset)
  (labels ((make-source-info ()
             (list :model model
                   :as as
                   :columns columns
                   :joins joins
                   :where where
                   :order-by order-by
                   :limit limit
                   :offset offset)))
    `(let ((q (make-instance '<query> ...)))
       (setf (slot-value q 'query-source-info) ',(make-source-info))
       q)))

3. Add format-query-source-info function

Added a function to format the query definition in a readable format.

(defun format-query-source-info (query)
  "Format query source information for error messages."
  (let ((source-info (slot-value query 'query-source-info)))
    (if source-info
        (with-output-to-string (s)
          (format s "~%~%Query definition:")
          (format s "~%  (query ~A" (getf source-info :model))
          (format s "~%    :as ~A" (getf source-info :as))
          ...)
        "")))

4. Update error messages

Updated error messages in build-alias-map and generate-join-sql to include the query definition.

;; Before
(error "Relation `~A' not found for model `~A'" target-alias source-model)

;; After
(error "Relation `~A' not found for model `~A'~A"
       target-alias
       source-model
       (format-query-source-info query))

Improved Error Messages

When a relation name is incorrect, a detailed error message is now displayed:

Relation `TAGS' not found for model `<TODO>'

Query definition:
  (query <TODO>
    :as :TODO
    :columns ((TODO :ID :TITLE))
    :joins ((:INNER-JOIN :TAGS))
    :where (:= (:TODO :DONE) :DONE))

This allows developers to immediately identify which query definition caused the error.

Notes

• No impact on queries created with query-builder or direct make-instance

  • query-source-info remains nil, so no additional information is output
  • Only existing error messages are displayed

• File name output is unnecessary as it's included in the stack trace

  • Error messages do not include file names

Testing

• All 63 tests passed successfully
• No impact on existing functionality
• Verified that original query definition is displayed when relation definition errors occur