Re: Documentation improvements for partitioning

On 2017/02/27 20:44, Simon Riggs wrote:
> On 27 February 2017 at 10:12, Amit Langote
> <Langote_Amit_f8(at)lab(dot)ntt(dot)co(dot)jp> wrote:
>
>> I agree that my patch failed to de-emphasize the old partitioning method
>> enough. The examples in 5.11 Partitioning chapter also did not highlight
>> the new partitioning feature as much as it should have been, so it indeed
>> reads like a description of how to avoid using the new partitioning
>> feature.
>
> Your patch was incredibly useful; I just wanted it earlier.

Thanks. Anyway, we agree that there is room for improvement.

> I think we're probably all agreed that we should highlight benefits of
> the new approach more, though the list of caveats should stay
> somewhere, just as we did for the original inheritance feature, and
> other things such as replication.

Yes.

>> Should we completely remove details about the older partitioning
>> methods?
>
> No, because there is much code out there using it for last 12 years
> that needs to be explained and there are still some use cases where it
> is useful that aren't on the roadmap for partitioning.

Sure, it's a matter of where we place it in the rewritten section about
partitioning.

>> I like the idea of merging what are now two chapters into one and call it
>> Partitioned Tables, retaining the text that describes concepts
>
> +1
>
> ...but how?
>
> 5.10 Partitioned Tables and Related Solutions

Presumably, this is where we put the "why" of using partitioning as part
of database design, that is, some of the text at the beginning of the 5.11
Partitioning section.

> 5.10.1 Declarative Partitioning (this new feature)
> 5.10.2 Managing Partitions using Inheritance
> 5.10.3 Managing Partitions using Union All Views
> 5.10.4 Accessing tables using BRIN indexes

Each of these sub-sections explain the "how", using that method.

We point out here when it's better to use one method over another,
limitations when using a particular method, etc.

> So first and foremost we highlight the new feature and explain all its
> strengths with examples.
>
> We then explain the other possible ways of implementing something
> similar. This allows us to explain how to handle cases such as when
> partitions have different set of columns etc..

Yeah, we don't allow that with declarative partitioned tables. A user
reading this section should be able to choose the best solution for their
needs.

> I'm happy to put my name down to write the sections on Union All
> Views, which is useful but only mentioned in passing, and the section
> on BRIN indexes, all of which would have their own independent sets of
> caveats.

OK. So, I will start writing the patch with above general skeleton and
hopefully post it within this week and you can improve it as fit.

Thanks,
Amit