summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMike Bayer <mike_mp@zzzcomputing.com>2017-01-26 16:01:20 -0500
committerMike Bayer <mike_mp@zzzcomputing.com>2017-01-26 16:01:20 -0500
commita24801ae8de469f1e78bdb0c02b28de263c2310e (patch)
tree48e50afb4af81139d808499348b762930a1cbeed
parent0d91796bb3869654e104fdfd9bf5f465e2e1b0ec (diff)
downloadsqlalchemy-a24801ae8de469f1e78bdb0c02b28de263c2310e.tar.gz
- document that "column" and "where" are arbitrary SQL expressions
for ExcludeConstraint, if string is used then quoting must be applied manually. fixes #3899 Change-Id: I5885c90179e4056b84fc4776464bba7c8c70a80a
-rw-r--r--lib/sqlalchemy/dialects/postgresql/ext.py54
1 files changed, 51 insertions, 3 deletions
diff --git a/lib/sqlalchemy/dialects/postgresql/ext.py b/lib/sqlalchemy/dialects/postgresql/ext.py
index ec95f37b4..e3ac79f30 100644
--- a/lib/sqlalchemy/dialects/postgresql/ext.py
+++ b/lib/sqlalchemy/dialects/postgresql/ext.py
@@ -82,10 +82,51 @@ static/sql-createtable.html#SQL-CREATETABLE-EXCLUDE
def __init__(self, *elements, **kw):
r"""
+ Create an :class:`.ExcludeConstraint` object.
+
+ E.g.::
+
+ const = ExcludeConstraint(
+ (Column('period'), '&&'),
+ (Column('group'), '='),
+ where=(Column('group') != 'some group')
+ )
+
+ The constraint is normally embedded into the :class:`.Table` construct
+ directly, or added later using :meth:`.append_constraint`::
+
+ some_table = Table(
+ 'some_table', metadata,
+ Column('id', Integer, primary_key=True),
+ Column('period', TSRANGE()),
+ Column('group', String)
+ )
+
+ some_table.append_constraint(
+ ExcludeConstraint(
+ (some_table.c.period, '&&'),
+ (some_table.c.group, '='),
+ where=some_table.c.group != 'some group',
+ name='some_table_excl_const'
+ )
+ )
+
:param \*elements:
A sequence of two tuples of the form ``(column, operator)`` where
- column must be a column name or Column object and operator must
- be a string containing the operator to use.
+ "column" is a SQL expression element or a raw SQL string, most
+ typically a :class:`.Column` object,
+ and "operator" is a string containing the operator to use.
+
+ .. note::
+
+ A plain string passed for the value of "column" is interpreted
+ as an arbitrary SQL expression; when passing a plain string,
+ any necessary quoting and escaping syntaxes must be applied
+ manually. In order to specify a column name when a
+ :class:`.Column` object is not available, while ensuring that
+ any necessary quoting rules take effect, an ad-hoc
+ :class:`.Column` or :func:`.sql.expression.column` object may
+ be used.
:param name:
Optional, the in-database name of this constraint.
@@ -103,9 +144,16 @@ static/sql-createtable.html#SQL-CREATETABLE-EXCLUDE
for this constraint. Defaults to 'gist'.
:param where:
- Optional string. If set, emit WHERE <predicate> when issuing DDL
+ Optional SQL expression construct or literal SQL string.
+ If set, emit WHERE <predicate> when issuing DDL
for this constraint.
+ .. note::
+
+ A plain string passed here is interpreted as an arbitrary SQL
+ expression; when passing a plain string, any necessary quoting
+ and escaping syntaxes must be applied manually.
+
"""
columns = []
render_exprs = []