diff options
author | Daniele Varrazzo <daniele.varrazzo@gmail.com> | 2020-01-20 21:00:58 +0000 |
---|---|---|
committer | Daniele Varrazzo <daniele.varrazzo@gmail.com> | 2020-01-20 21:00:58 +0000 |
commit | e9dc1df889df54c54bf798af1cf630bb2b45e495 (patch) | |
tree | fcd39f484603c3812fdbb381b3c9c61aed4010fb /doc | |
parent | dbd6577d91c6dcdafcc543f8f3c7c230597c1f62 (diff) | |
download | psycopg2-e9dc1df889df54c54bf798af1cf630bb2b45e495.tar.gz |
Added sql module basic usage section and classes hierarchy
Diffstat (limited to 'doc')
-rw-r--r-- | doc/src/sql.rst | 51 |
1 files changed, 47 insertions, 4 deletions
diff --git a/doc/src/sql.rst b/doc/src/sql.rst index 9cd18e7..c6507e0 100644 --- a/doc/src/sql.rst +++ b/doc/src/sql.rst @@ -55,10 +55,53 @@ from the query parameters:: .format(sql.Identifier('my_table')), [10, 20]) -The objects exposed by the `!sql` module can be used to compose a query as a -Python string (using the `~Composable.as_string()` method) or passed directly -to cursor methods such as `~cursor.execute()`, `~cursor.executemany()`, -`~cursor.copy_expert()`. + +Module usage +------------ + +Usually you should express the template of your query as an `SQL` instance +with `{}`\-style placeholders and use `~SQL.format()` to merge the variable +parts into them, all of which must be `Composable` subclasses. You can still +have `%s`\ -style placeholders in your query and pass values to +`~cursor.execute()`: such value placeholders will be untouched by +`!format()`:: + + query = sql.SQL("select {field} from {table} where {pkey} = %s").format( + field=sql.Identifier('my_name'), + table=sql.Identifier('some_table'), + pkey=sql.Identifier('id')) + +The resulting object is meant to be passed directly to cursor methods such as +`~cursor.execute()`, `~cursor.executemany()`, `~cursor.copy_expert()`, but can +also be used to compose a query as a Python string, using the +`~Composable.as_string()` method:: + + cur.execute(query, (42,)) + +If part of your query is a variable sequence of arguments, such as a +comma-separated list of field names, you can use the `SQL.join()` method to +pass them to the query:: + + query = sql.SQL("select {fields} from {table}").format( + fields=sql.SQL(',').join([ + sql.Identifier('field1'), + sql.Identifier('field2'), + sql.Identifier('field3'), + ]), + table=sql.Identifier('some_table')) + + +`!sql` objects +-------------- + +The `!sql` objects are in the following inheritance hierarchy: + +| `Composable`: the base class exposing the common interface +| ``|__`` `SQL`: a literal snippet of an SQL query +| ``|__`` `Identifier`: a PostgreSQL identifier or dot-separated sequence of identifiers +| ``|__`` `Literal`: a value hardcoded into a query +| ``|__`` `Placeholder`: a `%s`\ -style placeholder whose value will be added later e.g. by `~cursor.execute()` +| ``|__`` `Composed`: a sequence of `!Composable` instances. .. autoclass:: Composable |