django-mssql / docs / usage.txt

Usage
=====

``Django-mssql`` is a Django database backend and supports the interface 
for the paired Django version. It should behave the same as the core 
backends.

Executing Custom SQL
--------------------

Please refer to the Django documentation for `Executing custom SQL directly`_.

.. _`Executing custom SQL directly`: https://docs.djangoproject.com/en/dev/topics/db/sql/#executing-custom-sql-directly

Stored Procedures
-----------------

``Django-mssql`` provides support for executing stored procedures, with and 
without parameters. The main function that should be used to execute a 
stored procedure is ``callproc``. ``callproc`` will allow executing stored 
procedures with both input and output parameters, integer return values, and
result sets.

    .. code-block:: python
    
        def callproc(self, procname, parameters=None):
            """Call a stored database procedure with the given name.
    
            The sequence of parameters must contain one entry for each
            argument that the sproc expects. The result of the
            call is returned as modified copy of the input
            sequence. Input parameters are left untouched, output and
            input/output parameters replaced with possibly new values.
    
            The sproc may also provide a result set as output,
            which is available through the standard .fetch*() methods.
    
            Extension: A "return_value" property may be set on the
            cursor if the sproc defines an integer return value.
            """

Example:

This example assumes that there exists a stored procedure named ``uspDoesSomething`` 
that expects two parameters (int and varchar), and returns ``1`` when there 
is a result set.
        
    .. code-block:: python
    
        from django.db import connection
        
        cursor = connection.cursor()
        try:
            cursor.callproc('[dbo].[uspDoesSomething]', [5, 'blah'])
            
            if cursor.return_value == 1:
                result_set = cursor.fetchall()
        finally:
            cursor.close()


It is also possible to use the cursor's ``execute`` method to call a stored 
procedure, but ``return_value`` will not be set on the cursor and output
parameters are not supported. This usage is intended for calling a stored
procedure that returns a result set or nothing at all.

Example:

    .. code-block:: python
    
        from django.db import connection
        
        cursor = connection.cursor()
        try:
            cursor.execute('EXEC [dbo].[uspFetchSomeData]')
            result_set = cursor.fetchall()
        finally:
            cursor.close()

.. _rawstoredproceduremanager:

RawStoredProcedureManager
-------------------------

The ``RawStoredProcedureManager`` provides the ``raw_callproc`` method that will take the name
of a stored procedure and use the result set that it returns to create instances of the model.

Example:

    .. code-block:: python
    
        from sqlserver_ado.models import RawStoredProcedureManager
        
        class MyModel(models.Model):
            ...
            
            objects = RawStoredProcedureManager()

        sproc_params = [1, 2, 3]
        MyModel.objects.raw_callproc('uspGetMyModels', sproc_params)

.. versionadded:: 1.2
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.