[Django] #25430: RunSQL documentation is incorrect
Django
-------------------------------+--------------------
Reporter: fcurella | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
The current documentation for the `RunSQL` operation includes the
following example:
{{{
migrations.RunSQL(["INSERT INTO musician (name) VALUES (%s);",
['Reinhardt']])
}}}
That didn't work for me. The code that actually executes the replacement,
in `django.db.migrations.operations.special.RunSQL._run_sql` is:
{{{
def _run_sql(self, schema_editor, sqls):
if isinstance(sqls, (list, tuple)):
for sql in sqls:
params = None
if isinstance(sql, (list, tuple)):
elements = len(sql)
if elements == 2:
sql, params = sql
else:
raise ValueError("Expected a 2-tuple but got %d" %
elements)
schema_editor.execute(sql, params=params)
}}}
If I'm reading the code correctly, the provided example should instead be:
{{{
migrations.RunSQL([["INSERT INTO musician (name) VALUES (%s);",
['Reinhardt']]])
}}}
Indeed, I've found this very same usage in the tests
(`tests/migrations/test_operations.py:test_run_sql_params@L1541`):
{{{
param_operation = migrations.RunSQL(
# forwards
(
"INSERT INTO i_love_ponies (id, special_thing) VALUES (1,
'Django');",
["INSERT INTO i_love_ponies (id, special_thing) VALUES (2,
%s);", ['Ponies']],
("INSERT INTO i_love_ponies (id, special_thing) VALUES
(%s, %s);", (3, 'Python',)),
),
# backwards
[
"DELETE FROM i_love_ponies WHERE special_thing =
'Django';",
["DELETE FROM i_love_ponies WHERE special_thing =
'Ponies';", None],
("DELETE FROM i_love_ponies WHERE id = %s OR special_thing
= %s;", [3, 'Python']),
]
)
}}}
Looking throughout the docs, I could not find any usage such as the one
referred in the doc. That is value replacement where the `sql` is a list
made of SQL statement + the list params. The only usage I could find are
instances of list of list of SQL + params.
--
Ticket URL: <https://code.djangoproject.com/ticket/25430>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: fcurella | Owner: fcurella
Type: Uncategorized | Status: assigned
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by fcurella):
* status: new => assigned
* needs_better_patch: => 0
* needs_tests: => 0
* owner: nobody => fcurella
* needs_docs: => 0
Old description:
New description:
The current documentation for the `RunSQL` operation
(https://docs.djangoproject.com/en/dev/ref/migration-operations/#runsql)
includes the following example:
--
--
Ticket URL: <https://code.djangoproject.com/ticket/25430#comment:1>
Django
Reporter: fcurella | Owner: fcurella
Type: Uncategorized | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Old description:
> The current documentation for the `RunSQL` operation
> (https://docs.djangoproject.com/en/dev/ref/migration-operations/#runsql)
New description:
The current documentation for the `RunSQL` operation
(https://docs.djangoproject.com/en/dev/ref/migration-operations/#runsql)
includes the following example:
--
Comment (by fcurella):
I'm filing this as a documentation fix because a) it's eaasier and b) I'm
assuming there's people out there that just dealt with it and are using
the nested tuple form.
If you think the bug is in the code, and it should behave as documented,
let me know and I can work on fixing it.
--
Ticket URL: <https://code.djangoproject.com/ticket/25430#comment:2>
Django
Reporter: fcurella | Owner: fcurella
Type: Uncategorized | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by fcurella):
PR at https://github.com/django/django/pull/5314
--
Ticket URL: <https://code.djangoproject.com/ticket/25430#comment:3>
Django
Reporter: fcurella | Owner: fcurella
Component: Documentation | Version: 1.8
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"95edabb45e016ed269f96acc03d4a2bfcecd6b71" 95edabb4]:
{{{
#!CommitTicketReference repository=""
revision="95edabb45e016ed269f96acc03d4a2bfcecd6b71"
Fixed #25430 -- Fixed incorrect RunSQL examples.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25430#comment:4>
Django
Reporter: fcurella | Owner: fcurella
Type: Uncategorized | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"63147dfa07cfed6c2aa2ad28b4a5664747650352" 63147dfa]:
{{{
#!CommitTicketReference repository=""
revision="63147dfa07cfed6c2aa2ad28b4a5664747650352"
[1.8.x] Fixed #25430 -- Fixed incorrect RunSQL examples.
Backport of 95edabb45e016ed269f96acc03d4a2bfcecd6b71 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25430#comment:5>