This is the reference manual for the S-SQL component of the postmodern library.
S-SQL provides a lispy syntax for SQL queries, and knows how to convert various lisp types to their textual SQL representation. It takes care to do as much of the work as possible at compile-time, so that at runtime a string concatenation is all that is needed to produce the final SQL query.
Convert the given form (a list starting with a keyword) to an SQL query string at compile time, according to the rules described here.
function
sql-compile (form)
→ string
This is the run-time variant of the sql
macro. It converts the given list
to an SQL query, with the same rules except that symbols in this
list do not have to be quoted to be interpreted as
identifiers.
In cases where you do need to build the query at
run time, yet you do not want to re-compile it all the time, this
function can be used to compile it once and store the result. It
takes an S-SQL form, which may contain $$
placeholder
symbols, and returns a function that takes one argument for every
$$
. When called, this returned function produces an
SQL string in which the placeholders have been replaced by the
values of the arguments.
macro enable-sql-syntax (&optional (char #\Q))
Modifies the current readtable to add a #Q syntax
that is read as (sql ...)
. The character to use can
be overridden by passing an argument.
function
sql-escape-string (string)
→ string
Escapes a string for inclusion in a PostgreSQL query.
variable *standard-sql-strings*
Used to configure whether S-SQL will use standard
SQL strings (just replace #\' with ''), or backslash-style
escaping. Setting this to NIL
is always safe, but
when the server is configured to allow standard strings
(compile-time parameter 'standard_conforming_strings
'
is 'on
', which will become the default in future
versions of PostgreSQL), the noise in queries can be reduced by
setting this to T
.
Determines whether double quotes are added around
column, table, and function names in queries. May be
T
, in which case every name is escaped,
NIL
, in which case none is, or :auto
,
which causes only reserved
words to be escaped.. The default value is :auto
.
Be careful when binding this with let
and such
― since a lot of SQL compilation tends to happen at
compile-time, the result might not be what you expect.
function
sql-type-name (type)
→ string
Create the SQL equivalent of the given Lisp type, if one is known. See types.
function
to-sql-name (symbol &optional (escape-p *escape-sql-names-p*))
→ string
Convert a symbol to a name that can be used as an
SQL identifier by converting all non-alphanumeric characters to
underscores. Also lowercases the name to make queries look a bit
less hideous. When a second argument is given, this overrides the
current value of *escape-sql-names-p*
.
function
from-sql-name (string)
→ keyword
Convert a string that represents an SQL identifier to a keyword by uppercasing it and converting the underscores to dashes.
macro register-sql-operators (arity &rest names)
Define simple SQL operators. Arity is one of
:unary
(like 'not
'),
:unary-postfix
(the operator comes after the
operand), :n-ary
(like '+
': the operator
falls away when there is only one operand), :2+-ary
(like '=
', which is meaningless for one operand), or
:n-or-unary
(like '-
', where the
operator is kept in the unary case). After the arity may follow
any number of operators, either just a keyword, in which case the
downcased symbol name is used as the SQL operator, or a
two-element list containing a keyword and a name string.
S-SQL knows the SQL equivalents to a number of Lisp types, and defines some extra types that can be used to denote other SQL types. The following table shows the correspondence:
Lisp type | SQL type |
---|---|
smallint | smallint |
integer | integer |
bigint | bigint |
(numeric X Y) | numeric(X, Y) |
float, real | real |
double-float, double-precision | double-precision |
string, text | text |
(string X) | char(X) |
(varchar X) | varchar(X) |
boolean | boolean |
bytea | bytea |
date | date |
timestamp | timestamp |
interval | interval |
This is a type of which only the keyword
:null
is a member. It is used to represent NULL
values from the database.
An S-SQL form is converted to a query through the following rules:
operator(arguments,
...)
to-sql-name
.The following operators are defined:
sql-op :+, :*, :&, :|, :||, :and, :or, :=, :/, :!=, :<, :>, :<=, :>=, :^, :union, :union-all, :intersect, :intersect-all, :except, :except-all (&rest args)
These are expanded as infix operators. When
meaningful, they allow more than two arguments. :-
can also be used as a unary operator to negate a value. Note that
the arguments to :union
, :union-all
,
:intersect
, and :except
should be
queries (:select
forms).
Unary operators for bitwise and logical negation.
sql-op :~, :~*, :!~, :!~* (string pattern)
Regular expression matching operators. The exclamation mark means 'does not match', the asteriks makes the match case-insensitive.
sql-op :like, :ilike (string pattern)
Simple SQL string matching operators
(:ilike
is case-insensitive).
Used to invert the meaning of an operator in an :order-by
clause.
sql-op :as (form name &rest fields)
Assigns a name to a column or table in a :select
form. When fields are
given, they are added after the name, in parentheses. For example,
(:as 'table1 't1 'foo 'bar)
becomes table1 AS
t1(foo, bar)
. When you need to specify types for the
fields, you can do something like (:as 'table2 't2 ('foo
integer))
. Note that names are quoted, types are not (when
using sql-compile
or
sql-template
, you can
leave out the quotes entirely).
The EXISTS operator. Takes a query as an argument, and returns true or false depending on whether that query returns any rows.
Test whether a value is null.
Test whether a value is in a set of values.
Inverse of the above.
Denote a set of values. This one has two interfaces. When the elements are known at compile-time, they can be given as multiple arguments to the operator. When they are not, a single argument that evaulates to a list should be used.
Extract
a field from a date/time value. For example, (:extract
:month (:now))
.
Can be used to combine multiple names into a name of the form A.B to refer to a column in a table, or a table in a schema. Note that you calso just use a symbol with a dot in it.
Add a type declaration to a value, as in in
"4.3::real". The second argument is not evaluated normally, but
put through sql-type-name
to get a type
identifier.
Insert a string as-is into the query. This can be useful for doing things that the syntax does not support, or to re-use parts of a query across multiple queries:
(let* ((test (sql (:and (:= 'foo 22) (:not-null 'bar)))) (rows (query (:select '* :from 'baz :where (:raw test))))) (query (:delete-from 'baz :where (:raw test))) (do-stuff rows))
Creates a select query. The arguments are split on
the keywords found among them. The group of arguments immediately
after :select
is interpreted as the expressions that
should be selected. After this an optional :distinct
may follow, which will cause the query to only select distinct
rows, or alternatively :distinct-on
followed by a
group of row names. Next comes the optional keyword
:from
, followed by at least one table name and then
any numer of join statements. Join statements start with one of
:left-join
, :right-join
,
:inner-join
, or :outer-join
, then a
table name, then the keyword :on
, and then a form.
After that an optional :where
followed by a single
form may follow. And finally :group-by
and
:having
can optionally be specified. The first takes
any number of arguments, and the second only one. An example:
(:select (:+ 'field-1 100) 'field-5 :from (:as 'my-table 'x) :left-join 'your-table :on (:= 'x.field-2 'your-table.field-1) :where (:not-null 'a.field-3))
sql-op :limit (query amount &optional offset)
In S-SQL limit is not part of the select operator, but an extra operator that is applied to a query (this works out better when limiting the union or intersection of multiple queries, same for sorting). It limits the number of results to the amount given as the second argument, and optionally offsets the result by the amount given as the third argument.
sql-op :order-by (query &rest exprs)
Order the results of a query by the given
expressions. See :desc
for when
you want to invert an ordering.
sql-op :function (name (&rest arg-types) return-type stability body)
Create a stored procedure. The argument and return
types are interpreted as type names and not evaluated. Stability
should be one of :immutable
, :stable
, or
:volatile
(see the
Postgres manual). For example, a function that gets foobars by
id:
(:function 'get-foobar (integer) foobar :stable (:select '* :from 'foobar :where (:= 'id '$1)))
sql-op :insert-into (table &rest rest)
Insert a row into a table. When the second
argument is :set
, the other arguments should be
alternating field names and values, otherwise it should be a :select
form that will produce the
values to be inserted. Example:
(:insert-into 'my-table :set 'field-1 42 'field-2 "foobar")
It is possible to add :returning
,
followed by a list of field names or expressions, at the end of
the :insert-into
form. This will cause the query to
return the values of these expressions as a single row.
sql-op :update (table &rest rest)
Update values in a table. After the table name
there should follow a number of alternating field names and
values, like for :insert-into
, and then an
optional :where
keyword followed by the
condition.
sql-op :delete-from (table &key where)
Delete rows from the named table where the given condition holds.
sql-op :create-table (name (&rest columns) &rest options)
Create a new table. After the table name a list of column definitions follows, which are lists that start with a name, followed by one or more of the following keyword arguments:
:type
(or db-null integer)
to specify a
column that may have NULL values.:default
:unique
:primary-key
:check
:references
(target &optional
on-delete on-update)
. When target is a symbol, it names
the table to whose primary key this constraint refers. When it
is a list, its first element is the table, and its second
element the column within that table that the key refers to.
on-delete
and on-update
can be used to
specify the actions that must be taken when the row that this
key refers to is deleted or changed. Allowed values are
:restrict
, :set-null
,
:set-default
, :cascade
, and
:no-action
.After the list of columns, zero or more extra options can be specified. These are lists starting with one of the following keywords:
:check
:primary-key
:unique
:foreign-key
(columns target &optional on-delete on-update)
,
where columns
is a list of columns that are used by
this key, while the rest of the arguments have the same meaning
as they have in the :references
option for
columns.Note that, unlike most other operators,
:create-table
expects most of its arguments to be
unquoted symbols. The exception to this is the value of
:check
constraints: These must be normal S-SQL
expressions, which means that any column names they contain should
be quoted. When programatically generating table definitions,
sql-compile
is usually
more practical than the sql
macro.
Here is an example of a :create-table
form:
(:create-table enemy ((name :type string :primary-key t) (age :type integer :check (:> 'age 12)) (address :type (or db-null string) :references (important-addresses :cascade :cascade)) (fatal-weakness :type text :default "None") (identifying-color :type (string 20) :unique t)) (:foreign-key (identifying-color) (colors name)))
Drops the named table.
sql-op :create-index (name &rest args)
Create an index on a table. After the name of the
index the keyword :on
should follow, with the table
name after it. Then the keyword :fields
, followed by
one or more column names. Optionally, a :where
clause
with a condition can be added at the end to make a partial
index.
sql-op :create-unique-index (name &rest args)
Works like :create-index
, except that
the index created is unique.
Drop an index.
sql-op :create-sequence (name &key increment min-value max-value start cache cycle)
Create a sequence with the given name. The rest of the arguments control the way the sequence selects values.
Drop a sequence.
Drop a view.