Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the clsql-helper Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:15:59 2022 GMT+0.
Next: Systems, Previous: The clsql-helper Reference Manual, Up: The clsql-helper Reference Manual [Contents][Index]
A library providing a clutch of utilities to make working with clsql easier
If you def-view-classes inherit from clsql-helper:db-object then they will never use stored database connections (from view-database slot) and instead will prefer the dynamic default-database.
Using with-database/with-a-database then become useful ways to interact with clsql in a multithreaded web environment.
While there is code in clsql to handle filling primary keys, I have never quite wrapped my head around it. Instead if you inherit from mssql-db-object or pg-db-object the db-objects will autofill single primary keys (from IDENTITY / SERIAL) Primary Key columns.
This is somewhat specific to how we design databases (most all tables have a single IDENTITY / SERIAL PK) and might not be applicable to all situations
;; Copyright (c) 2011 Russ Tyndall , Acceleration.net http://www.acceleration.net
;; All rights reserved.
;;
;; Redistribution and use in source and binary forms, with or without
;; modification, are permitted provided that the following conditions are
;; met:
;;
;; - Redistributions of source code must retain the above copyright
;; notice, this list of conditions and the following disclaimer.
;;
;; - Redistributions in binary form must reproduce the above copyright
;; notice, this list of conditions and the following disclaimer in the
;; documentation and/or other materials provided with the distribution.
;;
;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
;; A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
;; LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
;; DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
;; THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
;; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
;; OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Next: Files, Previous: Introduction, Up: The clsql-helper Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
A library providing a clutch of utilities to make working with clsql easier
BSD
0.1
Next: Packages, Previous: Systems, Up: The clsql-helper Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: clsql-helper/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
clsql-helper (system).
Next: clsql-helper/utils.lisp, Previous: clsql-helper/clsql-helper.asd, Up: Lisp [Contents][Index]
clsql-helper (system).
Next: clsql-helper/iterate-clauses.lisp, Previous: clsql-helper/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
clsql-helper (system).
Next: clsql-helper/connections.lisp, Previous: clsql-helper/utils.lisp, Up: Lisp [Contents][Index]
utils.lisp (file).
clsql-helper (system).
Next: clsql-helper/date.lisp, Previous: clsql-helper/iterate-clauses.lisp, Up: Lisp [Contents][Index]
iterate-clauses.lisp (file).
clsql-helper (system).
Next: clsql-helper/clsql.lisp, Previous: clsql-helper/connections.lisp, Up: Lisp [Contents][Index]
connections.lisp (file).
clsql-helper (system).
Next: clsql-helper/db-object.lisp, Previous: clsql-helper/date.lisp, Up: Lisp [Contents][Index]
date.lisp (file).
clsql-helper (system).
Next: clsql-helper/dirty.lisp, Previous: clsql-helper/clsql.lisp, Up: Lisp [Contents][Index]
clsql.lisp (file).
clsql-helper (system).
Next: clsql-helper/migrations.lisp, Previous: clsql-helper/db-object.lisp, Up: Lisp [Contents][Index]
db-object.lisp (file).
clsql-helper (system).
Next: clsql-helper/merge.lisp, Previous: clsql-helper/dirty.lisp, Up: Lisp [Contents][Index]
dirty.lisp (file).
clsql-helper (system).
Next: clsql-helper/recency.lisp, Previous: clsql-helper/migrations.lisp, Up: Lisp [Contents][Index]
migrations.lisp (file).
clsql-helper (system).
Previous: clsql-helper/merge.lisp, Up: Lisp [Contents][Index]
merge.lisp (file).
clsql-helper (system).
Next: Definitions, Previous: Files, Up: The clsql-helper Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: clsql-helper.system, Previous: Packages, Up: Packages [Contents][Index]
Previous: clsql-helper, Up: Packages [Contents][Index]
Next: Indexes, Previous: Packages, Up: The clsql-helper Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
a stream that we will record sql commands to in the body of
A variable that when bound to a connection-database object will look up
the table name to use for migrations
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
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)
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
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
record commands to the *command-log-stream* for the duration of body then restore its previous binding
Log the sql commands of the body to a string
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
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Are we past a specific day of the month
Are we past a specific day of the month
returns a CLSQL:SQL-AND for all non-nil clauses, no nil if there are no non-nil clauses
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
Tries to handle full datetime equality reguardless of the format (string datestamp, date, datetime, utime)
alias of get-scalar
returns a CLSQL:SQL-AND for all non-nil clauses, no nil if there are no non-nil clauses
returns a CLSQL:SQL-AND for all non-nil clauses, no nil if there are no non-nil clauses
current date
current date and time
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
Return the number of days in the month of the date passed in
Returns a value or the string null
retrieve objects of type class from the database using db-query
runs a db query
sets :flatp to t
if params are provided we build a command object
(backend better support this)
Returns a list of plists that correspond to the query results
Query a single value from the database
Runs a clsql:select
defaulting to :flatp T
unnests any lists as part of the select list
query a single row / value from the database using clsql:select
alias with db-select-scalar
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
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.
returns the first of the month for the month/year of the date passed in
returns whether or not the date passed in is the first of the month
prints a correctly sql escaped value for postgres
Returns the first of next month eg: 2/14/2012->2/29/2012
Returns T if its the last day of the month
For use in creating ‘column IN (${stuff})‘ type of clauses
Creates a plist intended to be passed to make-instance
From N rows and some column-names make N instances of class filling data from rows using make instance
From N rows and column-name make N instances of class filling data from rows by creating instances and setting through access lib
From N rows and column-name make N instances of class filling data from rows by creating instances and setting existing accessor functions
prints dates as January 3
Converts the date to the full name, January, February,etc
Generates a where clause based on all of the primary keys of the object
ex: pk1 = val1 and pk2 = val2 ...
if the date exists, prints m?m/d?d/yyyy
if the date exists, prints mm/dd/yyyy hh:mm:ss
if the date exists, prints yyyy-mm-dd hh:mm:ss.uuuuuu
based on what is passed in, tries to figure out what the table name is
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
Either establish a new transaction context (with-transaction-context) or run the body in the extisting transaction context
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
Alias of with-database-context for backwards compatability
Creates a context inside which *default-database* is bound and runs the fn
inside it
Establish a context for enlisting in transactions and run the body in a new transaction
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
The Server time this was retrieved from the database
Named this way to reduce conflict likely hood with database columns
fetchs the first row for the given class by id
Fetchs the first row for the given class by id
direct implementation of by-id, (select class). fetchs the first row for the given class by id
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
Convert your value into a clsql:date structure
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.
Makes a copy of an instance via allocate instance then copies all
slot-values and calls reinitialize-instance
Given an object that encodes a date, return the day component
Given an object that encodes a date, return the month component
Given an object that encodes a date, return the year component
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)
automatically generated reader method
automatically generated writer method
automatically generated reader method
automatically generated writer method
fill the id field on the object with the appropriate next-identifier
Given an object that encodes a date
return an iso8601-datestamp representation of it
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
run ‘sql-statements‘ on the database once and only once. ‘sql-statements‘ can be strings, pathnames, or lists.
Checks that primary keys have values and that the object with those primary key values exists in the database
fetch the next unique identifier for this obj/database, usually the value of a autoincrement field.
returns the SQL query to run to get the next identifier. Query should return 1 row with 1 column.
fetch most recent AUTOINCREMENT on this connection. https://www.sqlite.org/lang_corefunc.html#last_insert_rowid
use SCOPE_IDENTITY
pull the sequence value for this object’s table
saves the given object, then returns the saved object
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
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
clsql-sys.
Print the auto-print-items for this instance.
sb-mop.
sb-mop.
clsql-sys.
After effecting the database record, fill the identifier field
clsql-sys.
clsql-sys.
clsql-sys.
By default views shouldn’t be updatable, so specialize a method to signal an error.
clsql-sys.
After effecting the database record, if the key-slot is empty then use SCOPE_IDENTITY to fill it. If > 1 key-slot, this won’t do anything.
clsql-sys.
clsql-sys.
clsql-sys.
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
error.
The object that was saved while we were working
(quote nil)
:already-saved
(quote nil)
:old-value
(quote nil)
:saved-value
(quote nil)
:pending-value
error.
(quote nil)
:conflicts
condition.
(quote nil)
:target
(quote nil)
:value
error.
:message
Previous: Conditions, Up: Public Interface [Contents][Index]
standard-db-object.
The Server time this was retrieved from the database
Named this way to reduce conflict likely hood with database columns
(or null clsql-sys:wall-time)
:%retrieved-at
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
:%history-select-fn
Previous: Public Interface, Up: Definitions [Contents][Index]
Variable to hold conditions from internal errors, just makes for a bit cleaner code I think.
Should we record this slot as dirty?
Variable to hold the gensymed catch tag this thread’s with-a-transaction is using.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
These are migrations necessary to making the system work as it upgrades
returns non-nil if this hashed migration has been run
returns a hashed form of the query, as a string
iterates through dates from start by step
HAS NO END CHECK eg an infinite loop unless you prevent it
iterates through dates from start to end inclusively
iterates through dates from start to end exclusive of end
iterates through dates from start by step
HAS NO END CHECK eg an infinite loop unless you prevent it
iterates through dates from start to end inclusively
iterates through dates from start to end exclusive of end
if it doesn’t exist, create the migration table
From N rows and column-name make N instances of class filling data from rows by creating instances and setting slot-values
determines whether or not two connections are the same
by comparing their connection spec (eg ’(server db user pass))
handles connection-settings, connection-specs and clsql:database
convert a string to a boolean value
trims the whitespace from a string returning nil
if trimming produces an empty string or the string ’nil’
Next: Standalone methods, Previous: Ordinary functions, Up: Internals [Contents][Index]
Converts something in an iterate date iteration clause BY section to a valid clsql:duration if it can
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
Convert an object into an unquoted string that the database understands
mostly used to do the coercion in db-string
returns the primarky key-slots of the given object
from.
perform the migration, returns the number of statments executed
A mapping of names to active connections
A mapping of names to connection specs
automatically generated reader method
automatically generated writer method
obj.
automatically generated reader method
automatically generated writer method
trys to read a value we hope to be a floating point number returns nil on failure
The goal is to allow reading strings with spaces commas and dollar signs in them correctly
slot.
slot.
automatically generated reader method
automatically generated writer method
Recursively turn the input into a list of migrations to be performed
val.
Next: Conditions, Previous: Generic functions, Up: Internals [Contents][Index]
Always prefer the passed in database or the dynamic database eg: never use the view-database slot on the object because that causes thread safety issues
clsql-sys.
This setfs slot values from the database values during select, so it makes sense to reset after ward
clsql-sys.
disable dirty slot recording if the value is from the database
clsql-sys.
clsql-sys.
Next: Classes, Previous: Standalone methods, Up: Internals [Contents][Index]
condition.
condition.
Previous: Conditions, Up: Internals [Contents][Index]
:migration-done-p
This slot is read-only.
Previous: Definitions, Up: The clsql-helper Reference Manual [Contents][Index]
| Jump to: | %
(
A B C D E F G H I J L M N O P R S T U V W |
|---|
| Jump to: | %
(
A B C D E F G H I J L M N O P R S T U V W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | %
*
+
A C D F H I M N O P S T V |
|---|
| Jump to: | %
*
+
A C D F H I M N O P S T V |
|---|
| Jump to: | C D F I M P R S T U |
|---|
| Jump to: | C D F I M P R S T U |
|---|