clsql-helper

API Reference

clsql-helper

A library providing a clutch of utilities to make working with clsql easier

CLSQL-HELPER

  • Variable *CONNECTION-SETTINGS*
    nil
  • Variable *COMMAND-LOG-STREAM*
    nil
    a stream that we will record sql commands to in the body of
  • Variable +A-NEGATIVE-SECOND+
    (clsql-sys:make-duration :second -1)
  • Variable +A-NEGATIVE-MINUTE+
    (clsql-sys:make-duration :minute -1)
  • Variable +A-NEGATIVE-HOUR+
    (clsql-sys:make-duration :hour -1)
  • Variable +A-NEGATIVE-DAY+
    (clsql-sys:make-duration :day -1)
  • Variable +A-NEGATIVE-MONTH+
    (clsql-sys:make-duration :month -1)
  • Variable +A-NEGATIVE-YEAR+
    (clsql-sys:make-duration :year -1)
  • Variable +A-SECOND+
    (clsql-sys:make-duration :second 1)
  • Variable +A-MINUTE+
    (clsql-sys:make-duration :minute 1)
  • Variable +AN-HOUR+
    (clsql-sys:make-duration :hour 1)
  • Variable +A-DAY+
    (clsql-sys:make-duration :day 1)
  • Variable +A-MONTH+
    (clsql-sys:make-duration :month 1)
  • Variable +A-YEAR+
    (clsql-sys:make-duration :year 1)
  • Variable *CONNECTION-DATABASE*
    (make-instance 'clsql-helper::connection-database)
    A variable that when bound to a connection-database object will look up
  • Function NEW-CONNECTION-DATABASE (&key (db *connection-database*) name new-connection)
  • Function ADD-CONNECTION-SPEC (name spec &key (db *connection-database*))
  • Function REMOVE-CONNECTION-SPEC (name &key (db *connection-database*))
  • Function GET-CONNECTION-SPEC (name-or-spec &key (db *connection-database*))
  • Function FIND-CONNECTION (name &key ((db *connection-database*) *connection-database*))
  • Function FIND-ANY-CONNECTION (names &key ((db *connection-database*) *connection-database*))
  • Function FIND-ACTIVE-CONNECTION-NAME (name &key ((db *connection-database*) *connection-database*))
  • Function FIND-ANY-ACTIVE-CONNECTION-NAME (names &key ((db *connection-database*) *connection-database*))
  • Function WITH-DATABASE-FUNCTION (fn connect-settings &key post-connect-fn log)
    Alias of with-database-context for backwards compatability Creates a context inside which *default-database* is bound and runs the fn inside it
  • Function WITH-DATABASE-CONTEXT (body-fn &key (connection-settings *connection-settings*) (db *connection-database*) post-connect-fn log &aux (*connection-settings* (or connection-settings *connection-settings*)) (*connection-database* (or db *connection-database*)))
    opens a database connection with the given settings, and runs the function. connect-settings: a plist of connection info for clsql, also supports :post-connect-fn, a function to run after opening the connection post-connect-fn: a function of no arguments to run after opening the connection
  • Function WITH-A-DATABASE-CONTEXT (body-fn &key (connection-settings *connection-settings*) (db *connection-database*) post-connect-fn log &aux existing-connection (*connection-settings* (or connection-settings *connection-settings*)) (*connection-database* (or db *connection-database*)))
    If a database connection exists and it matches the passed in settings or the passed in settings are null, use it!, otherwise aquire a new database connection
  • Macro WITH-DATABASE ((&optional (connection-settings *connection-settings*) &key post-connect-fn log) &body body)
    opens a database connection and executes the body connect-settings: a plist of connection info for clsql, also supports :post-connect-fn, a function to run after opening the connection post-connect-fn: a function of no arguments to run after opening the connection
  • Macro WITH-A-DATABASE ((&optional (connection-settings '*connection-settings*) &key post-connect-fn log) &body body)
    If a database connection exists and it matches the passed in settings or the passed in settings are null, use it!, otherwise aquire a new database connection
  • Function WITH-TRANSACTION-CONTEXT (body-fn database)
    Establish a context for enlisting in transactions and run the body in a new transaction
  • Function WITH-A-TRANSACTION-CONTEXT (body-fn database)
    Either establish a new transaction context (with-transaction-context) or run the body in the extisting transaction context
  • Macro WITH-A-TRANSACTION ((&key (database 'clsql-sys:*default-database*)) &body body)
    Wrapper around clsql:with-transaction, when a rollback is issued the code escapes (throw) to the outermost with-a-transaction. without the catch, its possible for an error handler in an intermediate function
  • Function CURRENT-SQL-DATE
    current date
  • Function CURRENT-SQL-TIME
    current date and time
  • Function PRINT-NULLABLE-DATE (field)
    if the date exists, prints m?m/d?d/yyyy
  • Generic-Function DATE-DAY (d)
    Given an object that encodes a date, return the day component
  • Method DATE-DAY (d)
  • Method DATE-DAY (d)
  • Method DATE-DAY (d)
  • Generic-Function DATE-YEAR (d)
    Given an object that encodes a date, return the year component
  • Method DATE-YEAR (d)
  • Method DATE-YEAR (d)
  • Method DATE-YEAR (d)
  • Generic-Function DATE-MONTH (d)
    Given an object that encodes a date, return the month component
  • Method DATE-MONTH (d)
  • Method DATE-MONTH (d)
  • Method DATE-MONTH (d)
  • Function MONTH-STRING (d)
    Converts the date to the full name, January, February,etc
  • Function MONTH-DAY-STRING (d)
    prints dates as January 3
  • Function PRINT-NULLABLE-DATETIME (field)
    if the date exists, prints mm/dd/yyyy hh:mm:ss
  • Function PRINT-TIMESTAMP (field)
    if the date exists, prints yyyy-mm-dd hh:mm:ss.uuuuuu
  • Function CLSQL-DATETIME-EQUAL (x y)
    Tries to handle full datetime equality reguardless of the format (string datestamp, date, datetime, utime)
  • Generic-Function ISO8601-DATESTAMP (d)
    Given an object that encodes a date return an iso8601-datestamp representation of it
  • Method ISO8601-DATESTAMP (d)
  • Method ISO8601-DATESTAMP (d)
  • Method ISO8601-DATESTAMP (d)
  • Generic-Function ISO8601-TIMESTAMP (d)
    CLSQL has a function (I wrote) to do this, but I wanted more flexibility in output so that I could use this in more situations clsql:iso-timestamp is used only to write to database backends, so a very strict ISO is fine
  • Method ISO8601-TIMESTAMP (d)
  • Method ISO8601-TIMESTAMP (d)
  • Method ISO8601-TIMESTAMP (d)
  • Generic-Function CONVERT-TO-CLSQL-DATETIME (val)
    Converts a string timestamp into a clsql date time object Makes every possible effort to understand your date that will invariably be in some format it wont understand.
  • Method CONVERT-TO-CLSQL-DATETIME (val)
  • Method CONVERT-TO-CLSQL-DATETIME (val)
  • Method CONVERT-TO-CLSQL-DATETIME (val)
  • Macro CONVERT-TO-CLSQL-DATETIME! (&rest places)
  • Generic-Function CONVERT-TO-CLSQL-DATE (val)
    Convert your value into a clsql:date structure
  • Method CONVERT-TO-CLSQL-DATE (val)
  • Method CONVERT-TO-CLSQL-DATE (val)
  • Method CONVERT-TO-CLSQL-DATE (val)
  • Macro CONVERT-TO-CLSQL-DATE! (&rest places)
  • Function CLSQL-DATE/TIMES->UTIME (obj &optional (timezone 0))
    obj is either a wall-time or a date in local time. Converts to UTC and returns a utime. pass timezone nil to skip UTC conversion. if you are looking for the other it is clsql-sys:utime->time
  • Function LAST-OF-THE-MONTH (start-date &aux (month (date-month start-date)))
    Returns the first of next month eg: 2/14/2012->2/29/2012
  • Function LAST-OF-THE-MONTH? (start-date)
    Returns T if its the last day of the month
  • Function FIRST-OF-THE-MONTH (&optional (date (current-sql-date)))
    returns the first of the month for the month/year of the date passed in
  • Function FIRST-OF-THE-MONTH? (&optional (date (current-sql-date)))
    returns whether or not the date passed in is the first of the month
  • Function DAYS-IN-MONTH (&optional (date (current-sql-date)))
    Return the number of days in the month of the date passed in
  • Function DAY-BEFORE (&optional (date (current-sql-date)))
  • Function DAY-AFTER (&optional (date (current-sql-date)))
  • Function NEXT-MONTH (&optional (date (current-sql-date)) &aux orig)
  • Function LAST-MONTH (&optional (date (current-sql-date)) &aux orig)
  • Function FIRST-OF-NEXT-MONTH (&optional (date (current-sql-date)))
  • Function AFTER-DAY-OF-MONTH (date day)
    Are we past a specific day of the month
  • Function BEFORE-DAY-OF-MONTH (date day)
    Are we past a specific day of the month
  • Function DATE-DIFF (d1 d2)
    Gets the difference in days between two dates returns a negative number to indicate that d1 is after d2 returns a positive number to indicate that d2 is after d1
  • Function DATE-ADD (d dur)
  • Function DT< (&rest d)
  • Function DT<= (&rest d)
  • Function DT> (&rest d)
  • Function DT>= (&rest d)
  • Condition SAVE-FAILED  (ERROR)
  • Macro WITH-COMMAND-LOGGING ((&key (database 'clsql-sys:*default-database*)) &body body)
    record commands to the *command-log-stream* for the duration of body then restore its previous binding
  • Macro WITH-COMMAND-LOGGING-TO-STRING ((&key string (database 'clsql-sys:*default-database*)) &body body)
    Log the sql commands of the body to a string
  • Macro LOG-DATABASE-COMMAND ((&optional log-fn-name (database 'clsql-sys:*default-database*)) &body body)
    MUST BE Inside a database connection, creates a lexical scope in which all sql commands executed on this connection are logged to a specific logger tries to format such that it will be readable in the log log-fn-name is a function/macro name that will be called with a string/array as (log-fn-name stuff)
  • Function CLSQL-EXP (s)
  • Function CLSQL-COLUMN-NAME (column &optional table)
  • Function DB-STRING (s &key (prefix "") (postfix "") (wrapper ""))
    trims, nullifies, escapes and wraps in single quotes so that the string is ready to be spliced into a query (eg: with cl-interpol). returns 'foo' or NIL.
  • Function DB-NULL (it)
    Returns a value or the string null
  • Macro DB-NULL! (&rest places)
  • Function LIST-OF-DB-STRINGS (list)
    For use in creating `column IN (${stuff})` type of clauses
  • Function CLSQL-ANDS (clauses)
  • Function CLSQL-AND (&rest clauses)
    returns a CLSQL:SQL-AND for all non-nil clauses, no nil if there are no non-nil clauses
  • Function CLSQL-ORS (clauses)
    returns a CLSQL:SQL-AND for all non-nil clauses, no nil if there are no non-nil clauses
  • Function CLSQL-OR (&rest clauses)
    returns a CLSQL:SQL-AND for all non-nil clauses, no nil if there are no non-nil clauses
  • Function TABLE-NAME-EXP (table-name)
    based on what is passed in, tries to figure out what the table name is
  • Function TABLE-NAME-STRING (table-name)
  • Function COLUMN-NAME-STRING (column)
  • Generic-Function BY-ID (class id &optional colname)
    Fetchs the first row for the given class by id
  • Method BY-ID (class id &optional (colname #<clsql-sys:sql-ident-attribute id>))
    direct implementation of by-id, (select class). fetchs the first row for the given class by id
  • Method BY-ID (class id &optional (colname #<clsql-sys:sql-ident-attribute id>))
    direct implementation of by-id, (select class). fetchs the first row for the given class by id
  • Method BY-ID (class id &optional (colname #<clsql-sys:sql-ident-attribute id>))
    direct implementation of by-id, (select class). fetchs the first row for the given class by id
  • Generic-Function BY-COL (class column colvalue)
    fetchs the first row for the given class by id
  • Method BY-COL (class column colvalue)
  • Method BY-COL (class column colvalue)
  • Method BY-COL (class column colvalue)
  • Function PRIMARY-KEY-SLOTS (obj)
  • Function PRIMARY-KEY-SLOT (obj)
  • Function PRIMARY-KEY-VALUE (obj)
  • Function PRIMARY-KEY-COLUMN-NAMES (obj)
  • Function PRIMARY-KEY-SLOT-NAMES (obj)
  • Function PRIMARY-KEY-WHERE-CLAUSES (obj &aux (slots (primary-key-slots obj)))
    Generates a where clause based on all of the primary keys of the object ex: pk1 = val1 and pk2 = val2 ...
  • Generic-Function NEW-OBJECT-P (obj)
    Checks that primary keys have values and that the object with those primary key values exists in the database
  • Method NEW-OBJECT-P (obj)
  • Method NEW-OBJECT-P (obj)
  • Method NEW-OBJECT-P (obj)
  • Generic-Function DB-EQL (x y &key test)
    Tries to determine if the objects are of the same type and have the same primary key values Many times objects which pass new-objectp are db-eql ,but once saved are no longer db-eql (due to using serial pkey)
  • Method DB-EQL (x y &key (test #'equalp))
  • Method DB-EQL (x y &key (test #'equalp))
  • Method DB-EQL (x y &key (test #'equalp))
  • Function PRETTY-PRINT-SQL (sql-command)
  • Function DB-TYPE-FROM-LISP-TYPE (type &key (length 64) (scale 4) (pg-default-int-type "int8"))
  • Condition TYPE-COERCION-ERROR  (ERROR)
  • Function TYPE-COERCION-ERROR (val to-type)
  • Method COERCE-VALUE-TO-DB-TYPE (val db-type)
    Coerces a value to the correct db-type if the conversion fails signals a continueable type-coercion-error (use-value is also available) returns (values val coerced?) the coerced value and whether or not a coersion took place
  • Function FORMAT-VALUE-FOR-DATABASE (d &optional stream)
    prints a correctly sql escaped value for postgres
  • Function MAKE-INSTANCE-PLIST (columns row)
    Creates a plist intended to be passed to make-instance
  • Function MAKE-INSTANCES (class columns rows)
    From N rows and some column-names make N instances of class filling data from rows using make instance
  • Function MAKE-INSTANCES-SETTING-ACCESSORS (class columns rows)
    From N rows and column-name make N instances of class filling data from rows by creating instances and setting existing accessor functions
  • Function MAKE-INSTANCES-SETTING-ACCESS (class columns rows)
    From N rows and column-name make N instances of class filling data from rows by creating instances and setting through access lib
  • Function DB-EXEC (cmd &key params log)
  • Function DB-SELECT (&rest select-args &aux log)
    Runs a clsql:select defaulting to :flatp T unnests any lists as part of the select list
  • Function DB-QUERY (cmd &rest keys &key params log &allow-other-keys)
    runs a db query sets :flatp to t if params are provided we build a command object (backend better support this)
  • Function CLSQL-GET-VAL (sql &key log)
    alias of get-scalar
  • Function DB-SCALAR (cmd &rest keys &key params log)
    Query a single value from the database
  • Function DB-SELECT-SCALAR (&rest select-args)
    query a single row / value from the database using clsql:select alias with db-select-first which was deemed more aptly named when selecting a row
  • Function DB-SELECT-FIRST (&rest select-args)
    query a single row / value from the database using clsql:select alias with db-select-scalar
  • Function DB-QUERY-PLISTS (cmd &rest keys &key params log)
    Returns a list of plists that correspond to the query results
  • Function DB-OBJS (class cmd &key params (make-instances-fn #'make-instances) log (coerce-rows? t) (column-munger #'symbol-munger:underscores->lisp-symbol))
    retrieve objects of type class from the database using db-query
  • Function DB-OBJS-SELECT (class columns &key select-args (make-instances-fn #'make-instances))
  • Function JOIN-SLOT? (slot-def)
  • Method IDENTITY-SLOT? (slot-def)
  • Generic-Function SAVE! (db-obj &key log orignal &allow-other-keys)
    saves the given object, then returns the saved object
  • Method SAVE! (db-obj &key log &allow-other-keys)
  • Method SAVE! (db-obj &key log &allow-other-keys)
  • Method SAVE! (db-obj &key log &allow-other-keys)
  • Class DB-OBJECT  (STANDARD-DB-OBJECT)
    No slots.
  • Generic-Function NEXT-IDENTIFIER-SQL (obj &key database)
    returns the SQL query to run to get the next identifier. Query should return 1 row with 1 column.
  • Method NEXT-IDENTIFIER (obj &key database)
    fetch the next unique identifier for this obj/database, usually the value of a autoincrement field.
  • Method FILL-IDENTIFIER! (obj &key database &aux (key-slots (clsql-sys::key-slots (class-of obj))))
    fill the id field on the object with the appropriate next-identifier
  • Function SLOT-DB-STORED? (slot-def &key (kinds '(:base :key)))
  • Function HAS-DB-DATA-TO-STORE? (it &key exclude)
  • Class PG-DB-OBJECT  (DB-OBJECT)
    No slots.
  • Method NEXT-IDENTIFIER-SQL ((obj pg-db-object) &key database)
    pull the sequence value for this object's table
  • Class MSSQL-DB-OBJECT  (DB-OBJECT)
    No slots.
  • Method NEXT-IDENTIFIER-SQL ((obj mssql-db-object) &key database)
    use SCOPE_IDENTITY
  • Class SQLITE3-DB-OBJECT  (DB-OBJECT)
    No slots.
  • Method NEXT-IDENTIFIER-SQL ((obj sqlite3-db-object) &key database)
    fetch most recent AUTOINCREMENT on this connection. https://www.sqlite.org/lang_corefunc.html#last_insert_rowid
  • Class DIRTY-DB-SLOTS-MIXIN
    DIRTY-SLOTS   Accessor: DIRTY-SLOTS
    DIRTY-TEST   Accessor: DIRTY-TEST
  • Function FIND-DIRTY-TEST (o slot-name)
  • Generic-Function SLOT-DIRTY? (object slot-name &key all?)
    determines whether or not a slot on a given object is dirty slot-name can be a list and all? determines if we want to not if all of them or dirty or if any of them are dirty
  • Method SLOT-DIRTY? ((o dirty-db-slots-mixin) slot-name &key (all? nil))
  • Method SLOT-DIRTY? ((o dirty-db-slots-mixin) slot-name &key (all? nil))
  • Method SLOT-DIRTY? ((o dirty-db-slots-mixin) slot-name &key (all? nil))
  • Method FILL-IDENTIFIER! ((o dirty-db-slots-mixin) &key database)
  • Variable *MIGRATION-TABLE-NAME*
    "clsql_helper_migrations"
    the table name to use for migrations
  • Method MIGRATIONS (&rest sql-statements)
    run `sql-statements` on the database once and only once. `sql-statements` can be strings, pathnames, or lists.
  • Generic-Function COPY-INSTANCE (i)
    Makes a copy of an instance via allocate instance then copies all slot-values and calls reinitialize-instance
  • Method COPY-INSTANCE (i)
  • Method COPY-INSTANCE (i)
  • Method COPY-INSTANCE (i)
  • Condition MERGING-VALUES
  • Condition MERGE-CONFLICT  (ERROR)
  • Condition MERGE-CONFLICTS  (ERROR)
  • Method MERGE-CHANGES (original already-saved pending)
  • Class RECENCY-MIXIN  (DB-OBJECT)
    %RETRIEVED-AT   Accessor: %RETRIEVED-AT
    The Server time this was retrieved from the database Named this way to reduce conflict likely hood with database columns
    %HISTORY-SELECT-FN   Accessor: %HISTORY-SELECT-FN
    a function that returns history data about an object the first returned value MUST be the most recent time the object was saved in the database
  • Condition RECENCY-ERROR  (ERROR)
  • Function CURRENT-TIMESTAMP
  • Method SAVE! ((o recency-mixin) &key original &allow-other-keys)

clsql-helper-slot-coercer

A library providing a single overwritde of (setf slot-value-using-class) so that obvious type coercions occur when setting slots on clsql:standard-db-objects USE CAUTION, LOADING SYSTEM WILL CHANGE THE SEMANTICS OF CLSQL:VIEW-CLASS (slightly, and probably in a good way)

No packages.