From b1c277932e3dd56345f7e277d7e6ecd034ee109c Mon Sep 17 00:00:00 2001 From: jonathan vanasco Date: Thu, 23 Sep 2021 11:22:37 -0400 Subject: [PATCH] Fixes: #7051 Update documentation regarding callproc and functions/stored procedures. Change-Id: I47bc6ec648d11604a1b1a8e4ad4581cc7612b953 --- doc/build/core/connections.rst | 36 ++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 52197a7958..979969c08c 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -1753,12 +1753,18 @@ Some recipes for DBAPI connection use follow. .. _stored_procedures: -Calling Stored Procedures -------------------------- +Calling Stored Procedures and User Defined Functions +------------------------------------------------------ -For stored procedures with special syntactical or parameter concerns, +SQLAlchemy supports calling stored procedures and user defined functions +several ways. Please note that all DBAPIs have different practices, so you must +consult your underlying DBAPI's documentation for specifics in relation to your +particular usage. The following examples are hypothetical and may not work with +your underlying DBAPI. + +For stored procedures or functions with special syntactical or parameter concerns, DBAPI-level `callproc `_ -may be used:: +may potentially be used with your DBAPI. An example of this pattern is:: connection = engine.raw_connection() try: @@ -1770,6 +1776,28 @@ may be used:: finally: connection.close() +.. note:: + + Not all DBAPIs use `callproc` and overall usage details will vary. The above + example is only an illustration of how it might look to use a particular DBAPI + function. + +Your DBAPI may not have a ``callproc`` requirement *or* may require a stored +procedure or user defined function to be invoked with another pattern, such as +normal SQLAlchemy connection usage. One example of this usage pattern is, +*at the time of this documentation's writing*, executing a stored procedure in +the PostgreSQL database with the psycopg2 DBAPI, which should be invoked +with normal connection usage:: + + connection.execute("CALL my_procedure();") + +This above example is hypothetical. The underlying database is not guaranteed to +support "CALL" or "SELECT" in these situations, and the keyword may vary +dependent on the function being a stored procedure or a user defined function. +You should consult your underlying DBAPI and database documentation in these +situations to determine the correct syntax and patterns to use. + + Multiple Result Sets -------------------- -- 2.47.3