Tables

Every table is pithy_<capability>_<table>, and that prefix is the same segment that is the pithy add argument, the migration namespace, the error-code domain, the audit-action domain and the catalog key.

One rule, five places — so one capability’s tables cannot collide with another’s, or with yours.

Your own tables carry no pithy_ prefix. That is what keeps them yours.

Every table here is created by migrations, reached through the data layer, and lives in whichever database its binding resolves to — which is how two Workers come to share one.

auth

pithy_auth_users · pithy_auth_accounts · pithy_auth_sessions · pithy_auth_verifications · pithy_auth_jwks · pithy_auth_rate_limit · pithy_auth_devices · pithy_auth_rotated_tokens · pithy_auth_user_lifecycle · pithy_auth_verification_outcomes · pithy_auth_attestation_challenges · pithy_auth_app_attest_keys

The first six are Better Auth’s, created from its own schema. The last six are the kit’s — the device registry, the refresh-token reuse ledger, every suspension and deletion with its actor and reason, which outlives the purge of the account it describes, the verification ledger, one row per sign-in link or code issued, stamped when it is used, the outstanding native app attestation challenges, each kept only as its SHA-256 and deleted when it is presented, and the registered App Attest keys, one row per key with its public key, App ID, Apple environment and the counter each assertion must rise above. A key belongs to an install of the app, not to a person. Nothing writes to the last two unless an environment has an attestation block.

pithy_auth_users.locale is the one home for a person’s language, and it is nullable: null means nobody chose, which is a different fact from en.

mcp

pithy_mcp_clients · pithy_mcp_resources · pithy_mcp_client_resources · pithy_mcp_consents · pithy_mcp_access_tokens · pithy_mcp_refresh_tokens · pithy_mcp_client_assertions

Better Auth’s OAuth provider’s tables, renamed under this capability’s prefix and created in the same database as auth’s, from the plugin’s own schema. A client is the application that registered itself; a consent is a person’s approval of one. A person’s purge erases their consents and the tokens minted under them, and leaves the client, which is the application’s. Letting your users’ agents in is what composes them.

organization

pithy_organization_organizations · pithy_organization_memberships · pithy_organization_invitations · pithy_organization_ownership_nominations · pithy_organization_acting · pithy_organization_lifecycle · pithy_organization_foundings

The first five are tenancy: the organization, the memberships that grant access to it, the outstanding invitations, the standing ownership offer, and each session’s acting selection. UNIQUE (organization_id, user_id) is one membership per person per organization, and a partial unique index on pending invitations is one live offer per address, so withdrawing the offer a pane shows is a revoke that revokes. user_id names pithy_auth_users as plain text, never a foreign key across a capability boundary.

pithy_organization_lifecycle is every transition of an organization, from a suspension to the end of its purge, with its actor and reason. It has no foreign key to the organization, because a purge erases that row and this is the record that must outlive it. The state itself is four columns on the organization row, the same four auth puts on a user.

pithy_organization_foundings is which organization each founder’s idempotency key founded, with the name and short name the request asked for, so a repeated POST /organizations answers the organization it already founded. Its primary key is (founder_user_id, idempotency_key), which is what decides between two concurrent foundings carrying one key, so each person’s keys are their own. It has no foreign key to the organization: the batch that deletes the organization deletes its founding record, which frees the key.

payments

pithy_payments_purchases · pithy_payments_entitlements · pithy_payments_provider_accounts · pithy_payments_webhook_events · pithy_payments_reconcile_runs · pithy_payments_sync_cursors · pithy_payments_overrides · pithy_payments_meter_counters · pithy_payments_usage_reports · pithy_payments_usage_runs

Two constraints carry the design. UNIQUE (rail, providerTransactionId) on purchases is the idempotency anchor all three write paths rely on; UNIQUE (rail, providerEventId) on webhook events is what makes a redelivery recognized rather than reprocessed.

storage

pithy_storage_objects · pithy_storage_shares

A share is a row rather than a presigned URL, because a presigned URL cannot be revoked.

media

pithy_media_assets · pithy_media_hashes

email

pithy_email_jobs · pithy_email_events · pithy_email_suppressions

The suppression table lives in its own binding, shared across a project’s environments. The other two are per environment.

vector

pithy_vector_documents — the corpus. The embeddings live in Vectorize; long source text belongs here, which is why this capability has a table at all.

artifacts

pithy_artifacts_repos · pithy_artifacts_grants · pithy_artifacts_tokens · pithy_artifacts_revocations

A repository’s key is its physical name, and UNIQUE (owner_kind, owner_id, display_name) is what lets two owners both hold a repository called docs while one owner cannot hold two. A grant is keyed on (repo, user_id): one per person per repository.

A token record names who a token was minted for, which Cloudflare’s own token metadata never does. It is keyed on the token id Cloudflare assigns, and has no column for the token itself, so there is nowhere to write one. A revocation record is a spent idempotency key, keyed on (connection_id, idempotency_key), so two management clients can never spend each other’s, and a replay answers what the first call did.

secrets

pithy_secrets_system_secrets · pithy_secrets_rotations · pithy_secrets_tables · pithy_secrets_reencryptions

In their own database, because the master key that opens the rows is per environment.

pithy_secrets_tables is the registry of declared tables, one row per table an app declared with defineSecretTable. Each declared table is pithy_secrets_<name>_secrets in the same database — the system table’s row plus a column per owner key — and its migration registers it here, which is how the at-rest rotation finds it without a redeploy.

pithy_secrets_reencryptions is what lets a rotation retire a version safely. One row per secret, per value sealed under it at rest and per database holding that value, saying which version it was last re-encrypted under — the auth Worker writes one for its JWKS keys. The manager reads it before it retires a previous version. It holds version keys and fingerprints, never a value.

support

pithy_support_threads · pithy_support_messages · pithy_support_classifications · pithy_support_attachments · pithy_support_thread_flags · pithy_support_assignments · pithy_support_embeddings

pithy_support_assignments is a thread’s handover history, one row per change of assignee, written in the same batch as the change on the thread. The thread holds only who has it now.

pithy_support_embeddings is the model stamp for search by meaning: one row per message in the semantic index, naming the model that embedded it and when. The vectors live in Vectorize and carry only the message id; the text stays in pithy_support_messages. A model change is found by this stamp, which is what pithy vector reprocess --index support-messages re-embeds by.

testers

pithy_testers_cohorts · pithy_testers_members · pithy_testers_events · pithy_testers_cohort_snapshots

The events table is append-only, and the streak is replayed from it — never stored as a counter, because a counter can only be overwritten, which destroys both the old value and the evidence that it changed.

One snapshot per cohort per UTC day is what makes the trend chartable: the opt-in figures could always be replayed, activity could not.

audit

pithy_audit_events — append-only. No route deletes, edits or prunes. The one way a row leaves is the retention prune your own Worker runs, when its retention block sets a window, and it leaves a tombstone in the checkpoint bucket for every run it removes.

pithy_consent_records · pithy_consent_documents · pithy_consent_merges

Append-only by schema. Triggers abort an update of any fact column and every delete on all three, so the database itself refuses to change the record. The one write allowed is the field-key rotator re-sealing the typed and representative names, which are encrypted fields. A document is keyed on the SHA-256 of its text and kept once. All three are retained: a person’s purge keeps them, and a down migration is refused while they hold rows.

ledger

pithy_ledger_accounts · pithy_ledger_transactions · pithy_ledger_holds

CHECK (balance >= 0 AND held >= 0 AND held <= balance) on accounts is the overdraft guard, and ref is UNIQUE across the whole ledger.

leaderboard

pithy_leaderboard_boards · pithy_leaderboard_entries · pithy_leaderboard_locks · pithy_leaderboard_contributions · pithy_leaderboard_moderations · pithy_leaderboard_stale_windows

The lock table is the advisory lock that keeps at most one rank refresh running.

A contribution row records what one result put on one entry, written in the same batch as the score, so the entry names the result that wrote it and a retried publish folds nothing twice; a plain submission writes none. The moderation table is the board’s history of management acts — what each found, what it left, the reason, the connection and the operator — written in the same batch as the change. A stale window is a closed window an act moved, waiting for the next refresh pass to renumber it.

rating

pithy_rating_ratings · pithy_rating_outcomes · pithy_rating_outcome_players · pithy_rating_adjustments

A rating row is one (pool, player), and its skill column is indexed, because bucketing a matchmaking queue is a range read over it. The outcome log is append-only, written in the same batch that moves the ratings, so a recalculation replays it and a void marks an outcome rather than deleting it. An adjustment row is one control-plane act, with the rating before and after.

matchmaking

pithy_matchmaking_invites · pithy_matchmaking_friends

The friend graph is indexed both ways, so a lookup from either side is one read.

multiplayer

pithy_multiplayer_results · pithy_multiplayer_sessions · pithy_multiplayer_void_keys

A result row is one terminal session, and it records whether the result was voided, under which key, and what each consumer did. The sessions table is the index of sessions in flight: a session writes its row when it opens and deletes it when it ends, so a management client can list what no id-addressed Durable Object could. The void-key table keeps every key a void was sent with, each unique, so a replayed key stays a replay and one key never voids two results. Session and game state live in the Durable Object’s own storage, not here.

the control plane

pithy_controlplane_connections · pithy_controlplane_replays · pithy_controlplane_holds

pithy_controlplane_holds is every legal hold, standing or released. Nothing deletes a row, and a person’s purge keeps the holds that named them.

The replay table is keyed on the token id alone, never the pair of token and connection — a composite would let a token captured from one connection be spent against another.

bookkeeping

pithy_migrations_owner — the ownership stamp.

An unstamped database is adopted on first migrate; your own is a no-op, and somebody else’s is caught rather than migrated into.

pithy_migrations_groups — which run applied each migration. Every pithy migrate run is a group, and a rollback reverses one group by name. Like the ownership stamp, it is not a migration, so a rollback and a full reset leave it standing; reversing a migration removes its row.

ESC