Skip to content

Alpha gate: audit docs/limitations.md against the gap list, and state release status #215

Description

@jdatcmd

Alpha gate 2 of 4, from the pre-alpha review note. @ChronicallyJD for review.

What is true today

The review note asks for an honest "known limitations / not for production"
list. Most of that list already exists. docs/limitations.md has 20 sections
and already documents the largest item the note names:

  • Row locking: a "Row locking" section already states that SELECT ... FOR UPDATE, FOR SHARE and FOR KEY SHARE are not implemented, which matches
    columnar_tuple_lock raising in src/columnar_tableam.c:1347.
  • Logical decoding: mentioned, and docs/user-guide.md documents the row
    trigger workaround from Document what a decoding slot actually does with a columnar table #190.

So this is an audit and fill, not a write from scratch. What is actually absent,
by grep over docs/limitations.md:

term hits
bulk load 0
untrusted 0
security 0
alpha 0
production 0

The gaps are therefore: bulk load performance is not characterized anywhere in
the user-facing docs, there is no statement of the untrusted-input boundary
(that is #216 and belongs there), and nothing in the tree states
the project's release status. VERSION reads 1.0-dev and no document says
what that means for a reader deciding whether to run this.

One correction to carry into the text

The note cites "bulk load ~4.9x slower than heap" from #155. That number is one
point on a curve and should not be published as the headline. #213 re-measured
at 6,000,000 rows on PG17.10 non-assert as ratios against a heap insert:

shape full fast
1 text col, low cardinality 3.83x 3.01x
1 text col, high entropy 6.48x 1.94x
5-col mixed, low-cardinality text 5.59x 5.55x
5-col mixed, high-entropy text 8.83x 4.13x
1 bigint col 0.67x -

The honest statement is a range of 0.67x to 8.83x, shape dependent, with the
encode_effort setting named as the knob. A single figure would be wrong in
both directions depending on the reader's schema.

The rule this must not break

docs/testing.md:81 already states that docs/limitations.md is for what is
genuinely out of scope or blocked, and records a case where planner statistics
sat there as a limitation after the implementation had landed. Documenting a
defect is not fixing it. Every line added here must be a real constraint, not a
known defect being reclassified. Anything on this list that is a defect gets an
issue instead.

Plan

Audit the existing file against the tree rather than appending to it, then add
the missing sections, then state release status in one place that the other
documents link to.

Todo

  • Read docs/limitations.md against the current tree section by section and
    correct anything that has been implemented since it was written. The
    planner-statistics case in docs/testing.md is the precedent for why this
    comes first.
  • Add a bulk load and import performance section, stating the range by shape
    with the Re-scope #155 after encode_effort, with measurements #213 measurements and naming encode_effort. Do not publish a
    single multiplier.
  • Add the per-column insert cost from Re-scope #155 after encode_effort, with measurements #213 (roughly 1 to 2 seconds per extra
    column per 6M rows) if it survives the ablation that issue is waiting on.
    Hold this item until then rather than publishing an unattributed number.
  • Add a release status statement covering what 1.0-dev means, what is
    gated on what, and who this is currently appropriate for. Link it from
    README.md and docs/index.md.
  • Confirm every gap the note names is either in the file or has an open
    issue, and cross-reference the issue from the file where one exists.
  • Check the result against the project documentation style: professional,
    no em-dashes, no decorative adjectives.

What closes this

A reader can determine, from the documentation alone and without reading the
issue tracker, what this does not do and what state it is in.

The set

Alpha gates from the pre-alpha review note, ranked cheapest-highest-value first:
#214 fuzz the parsers, #215 limitations and release status, #216 untrusted-input
boundary, #217 backend-crash blast radius.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions