Skip to content

Adding UUIDs for rows - #3253

Closed
rjzondervan wants to merge 13 commits into
mainfrom
feat/3093/row-uuid
Closed

rjzondervan wants to merge 13 commits into
mainfrom
feat/3093/row-uuid

Conversation

@rjzondervan

@rjzondervan rjzondervan commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Closes issue #3093

Adds UUIDs to Rows as described in issue #3093.

A small summary:

  • Rows get a UUIDv7 in a new column on tables_row_sleeves
  • Every mapper assigns a uuid. Exported uuids are kept on import if the uuid does not conflict with existing rows
  • Existing rows are backfilled
  • Added support for using a uuid in api/2/{tables|views}/{nodeId}/rows/{rowId}. On PUT and DELETE methods this does not yet work for federated tables and federated views.

This PR does not set the UUID column to NOT NULL as these are added by a backfill.

To help the reviewers, we did a number of internal reviews before posting the PR here, that we did on our reviewing-fork, and the results can be found in this draft PR.

This PR is larger than I would like it with just over 2000 LoC. However, of those 2000 lines only ~500 lines are actual production code. ~500 more lines are generated API docs and the remaining ~1000 lines are added unit tests.

🏁 Checklist

  • ⛑️ Tests (unit and/or integration) are included or not needed
  • 🔙 Backport requests are created or not needed: /backport to stableX.X
  • 📅 Milestone is set
  • 🌸 PR title is meaningful (if it should be in the changelog: is it meaningful to users?)

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI

Rows get a UUIDv7 in tables_row_sleeves with a global unique index.
Every mapper insert assigns one, and a user migration import keeps
the exported uuid when no other row uses it yet. Existing rows are
backfilled in batches by a queued background job, so the column stays
nullable until the backfill has finished.

GET, PUT and DELETE on /api/2/{tables|views}/{nodeId}/rows/{rowId}
accept an integer id or a uuid. A uuid is only looked up within the
table, or the table of the view, so a uuid of another table is not
found. Federated tables and views keep using the integer id and
reject a uuid with a 400.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Drop an unused catch variable in RowService::findViewOrFail and pass
uuidOf as a first-class callable in BackfillRowUuidsTest, as the
rector check asks.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
The row identifier methods were inserted between create() and its
docblock, which left create() without its $data shape and @throws list
and gave resolveRowId() two docblocks.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
resolveRowId() looked a uuid up in all tables when it got neither a
table nor a view. The api/2 routes always pass one, but the method is
public and promises a lookup within the table, so it now throws an
InternalError instead, as findInNode() does.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
The uuid index is unique across all tables, so an exported uuid may only
be kept when no row in any table uses it. The existing tests mocked the
lookup and checked only its first argument. A new test stores the uuid
in another table and resolves it through the real mapper, and the mocks
now also expect no table id.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
The migration docblock said the column stays nullable until the
backfill has finished, which suggested a step in this change that
makes it NOT NULL. There is none: a migration that runs in the same
upgrade would have to fill every uuid during that upgrade, which is
what the background job avoids. Making the column NOT NULL is left to
a migration in a later release, after the backfill has had a release
to run.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Each batch selected the rows without a uuid ordered by id. On
PostgreSQL that walks the primary key and skips every row already
filled in, so each batch got slower as the backfill went on: with half
of 1M rows filled, one batch query took 138 ms after a vacuum and
425 ms before one, against 0.2 to 2 ms without the ordering. The
backfill only needs some rows without a uuid, so the ordering is
dropped. A full backfill of 1M rows on PostgreSQL 16 now takes 103
runs of about 1.75 s each, the same at the start and at the end.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
PUT and DELETE on /api/2/public/{token}/rows/{rowId} accept an integer
id or a uuid, like the authenticated row routes. A uuid is only looked
up within the shared table, or the table of the shared view. The rows
these routes return already carried their uuid; TablesPublicRow now
declares it, and DELETE documents its 400 for a malformed identifier.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>
RowService gained a RowVisibilityService constructor argument on main
(#3250), so the row identifier and import tests construct it with a
mock as well.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Robert Zondervan <robert@conduction.nl>

@enjeck enjeck left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems to conflict with #3229 . Please check that. If it's doing same thing, we can close this and review that instead

@rjzondervan

Copy link
Copy Markdown
Contributor Author

Both PRs indeed conflict. This PR contains one feature (public routes with uuid) that is missing in #3229, but when that merges I could reimplement that shortly. Closing this PR for now.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants