Sync bucket priorities

[benitav]

Mostly from this doc: https://paper.dropbox.com/doc/2024-10-Bucket-Priorities-PowerSync-Proposal--CgTUkogvSRhCpmq2FOwMuMOiAg-DsdphMZ0JVN6mkEmY8cbh
And this PR: powersync-ja/powersync-service#192

[simolus3]

LGTM, I've found two minor things that stood out to me. Maybe we also want to mention bucket priorities on the page introducing buckets in the future, so that it can serve as a complete reference on bucket definitions.

[simolus3]

We probably don't have to do that now, but maybe it's helpful to also expand the "Organize Data Into Buckets" page to mention that buckets can have metadata attached to them (like the priority YAML key or the _priority parameter of a parameter query).

[benitav]

That's a great catch, thanks - I'll work on that next 👍

[simolus3]

I realize that it says the same thing in the paper doc, but I think this may be confusing for users.

When multiple parameter queries are involved, we would create multiple internal buckets for that. These internal buckets will have independent priorities based on the parameter row defining them. Considering something like this:

bucket_definitions:
  projects:
    parameters:
      - SELECT id AS project_id, 2 AS _priority FROM projects WHERE NOT important AND ...;
      - SELECT id AS project_id, 1 AS _priority FROM projects WHERE important AND ...;

Then, if there are 2 projects with important = TRUE and 3 projects with important = FALSE, we'll create 5 buckets of which 2 have the higher priority.

[benitav]

Oh, so that would behave as expected then - i.e. both priorities are considered and data is synced accordingly. So is the paper doc outdated on this note or is there a different nuance here that I'm missing?

[simolus3]

I think the doc is just outdated, I don't see any nuance here either.