[1.7.x] Fixed #3214 -- Stopped parsing SQL with regex.

Avoided introducing a new regex-based SQL splitter in the migrations
framework, before we're bound by backwards compatibility.

Adapted this change to the legacy "initial SQL data" feature, even
though it's already deprecated, in order to facilitate the transition
to migrations.

sqlparse becomes mandatory for RunSQL on some databases (all but
PostgreSQL). There's no API to provide a single statement and tell
Django not to attempt splitting. Since we have a more robust splitting
implementation, that seems like a good tradeoff. It's easier to add a
new keyword argument later if necessary than to remove one.

Many people contributed to both tickets, thank you all, and especially
Claude for the review.

Refs #22401.

Backport of 8b5b199 from master

3 files changed, 18 insertions, 9 deletions

diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index 3edc588c18..3571fb0c26 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -166,6 +166,7 @@ dependencies:
 *  memcached_, plus a :ref:`supported Python binding <memcached>`
 *  gettext_ (:ref:`gettext_on_windows`)
 *  selenium_
+*  sqlparse_
 
 You can find these dependencies in `pip requirements files`_ inside the
 ``tests/requirements`` directory of the Django source tree and install them
@@ -197,6 +198,7 @@ associated tests will be skipped.
 .. _memcached: http://memcached.org/
 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
 .. _selenium: https://pypi.python.org/pypi/selenium
+.. _sqlparse: https://pypi.python.org/pypi/sqlparse
 .. _pip requirements files: http://www.pip-installer.org/en/latest/cookbook.html#requirements-files
 
 Code coverage
diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt
index 2a5f46a93c..331ccd5c06 100644
--- a/docs/ref/migration-operations.txt
+++ b/docs/ref/migration-operations.txt
@@ -167,25 +167,23 @@ Changes a field's name (and, unless ``db_column`` is set, its column name).
 Special Operations
 ==================
 
+.. _operation-run-sql:
+
 RunSQL
 ------
 
 ::
 
-    RunSQL(sql, reverse_sql=None, state_operations=None, multiple=False)
+    RunSQL(sql, reverse_sql=None, state_operations=None)
 
 Allows running of arbitrary SQL on the database - useful for more advanced
 features of database backends that Django doesn't support directly, like
 partial indexes.
 
-``sql``, and ``reverse_sql`` if provided, should be strings of SQL to run on the
-database. They will be passed to the database as a single SQL statement unless
-``multiple`` is set to ``True``, in which case they will be split into separate
-statements manually by the operation before being passed through.
-
-In some extreme cases, the built-in statement splitter may not be able to split
-correctly, in which case you should manually split the SQL into multiple calls
-to ``RunSQL``.
+``sql``, and ``reverse_sql`` if provided, should be strings of SQL to run on
+the database. On most database backends (all but PostgreSQL), Django will
+split the SQL into individual statements prior to executing them. This
+requires installing the sqlparse_ Python library.
 
 The ``state_operations`` argument is so you can supply operations that are
 equivalent to the SQL in terms of project state; for example, if you are
@@ -194,6 +192,7 @@ operation here so that the autodetector still has an up-to-date state of the
 model (otherwise, when you next run ``makemigrations``, it won't see any
 operation that adds that field and so will try to run it again).
 
+.. _sqlparse: https://pypi.python.org/pypi/sqlparse
 
 .. _operation-run-python:
 
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index d0a0945d85..b620c1134b 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -636,6 +636,14 @@ Management Commands
 * :djadmin:`collectstatic` command with symlink option is now supported on
   Windows NT 6 (Windows Vista and newer).
 
+* :ref:`initial-sql` now works better if the sqlparse_ Python library is
+  installed.
+
+  Note that it's deprecated in favor of the :ref:`RunSQL <operation-run-sql>`
+  operation of migrations, which benefits from the improved behavior.
+
+.. _sqlparse: https://pypi.python.org/pypi/sqlparse
+
 Models
 ^^^^^^