Opened 8 years ago

Closed 8 years ago

Last modified 8 years ago

#27355 closed Cleanup/optimization (fixed)

Add PostgreSQL Extension operation example to reference page

Reported by: Maxime Lorant Owned by: ntuckovic
Component: Documentation Version: 1.10
Severity: Normal Keywords: postgres unaccent trigram
Cc: reinout@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes UI/UX: no

Description

TrigramExtension and UnaccentExtension have been introduced in django.contrib.postgres in Django 1.10 to help developpers to activate the pg_trim and unaccent extension of postgres when they are using the corresponding ORM lookup.

Even though I feel pretty comfortable with the Django doc usually, this time, I did not find UnaccentExtension in few minutes. In local, I did the extension activation by myself (since I did not read the relevant part of the doc) but get stuck when trying to execute my unit tests. I think these migration operations are not stressed enough in the doc. I believe it is [referenced only here](https://docs.djangoproject.com/en/1.10/ref/contrib/postgres/lookups/), each time in a sentence which barely says when to use it.

I think there should be an introduction at the top of the page linked above saying something like: "The lookups above need the activation of extensions in Postgres. To enable them, you are advised to create a Django migration which will apply the relevant operation", where the "relevant operation" is referring to either TrigramExtension or UnaccentExtension, but I don't know how to transcribe it :/

Change History (13)

comment:1 by Tim Graham, 8 years ago

It's not entirely clear to me why you want the instructions repeated twice, once at the top of the page and once within the docs for each extension -- or did I misunderstand the suggestion? Another consideration is that future lookups might not require activation of an extension.

in reply to:  1 comment:2 by Maxime Lorant, 8 years ago

Replying to Tim Graham:

It's not entirely clear to me why you want the instructions repeated twice, once at the top of the page and once within the docs for each extension -- or did I misunderstand the suggestion? Another consideration is that future lookups might not require activation of an extension.

I don't think it should be write twice, but I guess it would not hurt if the usefulness of these two classes was more explicit so it can be easier to find it.

(It is marked as cleanup, we can live with the current wording, but I think it could be better :) )

comment:3 by Tim Graham, 8 years ago

Maybe moving the HStoreExtension example from https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField to https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/ and explaining that the same usage principles apply for all extensions would be help?

comment:4 by Maxime Lorant, 8 years ago

That would be great, yes, and it does involve a lot of changes.

comment:5 by Tim Graham, 8 years ago

Summary: Emphasizes the role of TrigramExtension and UnaccentExtension in the documentationAdd PostgreSQL Extension operation example to reference page
Triage Stage: UnreviewedAccepted

comment:6 by Levi Velázquez, 8 years ago

What Maxime suggested sounds good, I think we can add an section on https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/ named "Create extension using migrations" and add the example from ​https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#django.contrib.postgres.fields.HStoreField.


About Tom reply, why it does involve a lot of changes ?

I'm interesting to take this cleanup, It would be my first contribution to Django.

in reply to:  6 comment:7 by Maxime Lorant, 8 years ago

Replying to Levi Velázquez:

About Tom reply, why it does involve a lot of changes ?

I'm interesting to take this cleanup, It would be my first contribution to Django.

I forgot a "not", you should read: "it does NOT involve [...] " :-) It's merely copy-pasting in another page with some adjustments.

comment:8 by ntuckovic, 8 years ago

Owner: changed from nobody to ntuckovic
Status: newassigned

comment:9 by ntuckovic, 8 years ago

Has patch: set

comment:10 by Reinout van Rees, 8 years ago

Patch needs improvement: set

Looks fine, apart from some spelling/formatting corrections. These have been noted as comments on the PR.

For clarity, I've set the "patch needs improvement" checkbox as there are two sets of suggested fixes on the PR.

comment:11 by Reinout van Rees, 8 years ago

Cc: reinout@… added

comment:12 by Tim Graham <timograham@…>, 8 years ago

Resolution: fixed
Status: assignedclosed

In 4de8aaf:

Fixed #27355 -- Added “Creating extension using migrations” docs.

comment:13 by Tim Graham <timograham@…>, 8 years ago

In 1b6649c6:

[1.10.x] Fixed #27355 -- Added “Creating extension using migrations” docs.

Backport of 4de8aaf7ffc91b91cbb70e9db406abe9b160575a from master

Note: See TracTickets for help on using tickets.
Back to Top