Skip to content

Add a more interesting README - #54

Open
sgrif wants to merge 2 commits into
mainfrom
sg-moar-readme
Open

sgrif wants to merge 2 commits into
mainfrom
sg-moar-readme

Conversation

@sgrif

@sgrif sgrif commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

This adds some more details about the design and reasoning behind the library, along with some cleanup of contribution guidelines.

Due to the nature of embedding images within the repo, the embedded images will only show up when the pull request is merged, but will appear broken in the pull request.

This adds some more details about the design and reasoning behind the
library, along with some cleanup of contribution guidelines.

Due to the nature of embedding images within the repo, the embedded
images will only show up when the pull request is merged, but will
appear broken in the pull request.
@sgrif
sgrif requested a review from levkk September 15, 2026 18:50
@levkk

levkk commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

A lot of good info here. I would restructure to highlight:

  1. Why we built this, i.e., 8x faster than pg_query.rs & uses 90% less memory
  2. How to use it, with inline Rust examples (pretend you're publishing this for someone to actually play with)
  3. Benchmarks (with details)
  4. Design and internals (highlight our use of comments to generate types, Postgres memory arena allocator and how useful it is, our ability to mutate it and generate our own statements)

The current structure loses me pretty quickly because of the wall of text. I would refactor it by adding a bunch of headings that make it flow a bit better.

A few great examples:

  1. https://github.com/NikolayS/pgque (I love the animated graph on top)
  2. https://github.com/pytorch/pytorch (not a bad structure overall, kinda explains from the top whats going on)
  3. Your own https://github.com/rust-lang/crates.io (super clean, easy to read)

@levkk

levkk commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Btw, feel free to merge this and iterate. Maybe it looks a bit cleaner with images loaded.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants