[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

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

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:
 

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
 ^^^^^^