Documentation
¶
Overview ¶
Package pgid derives the PostgreSQL primary key that mongo2pg mints for a MongoDB row, without consulting the database.
It exists so a service can resolve a pre-cutover identifier — and so one service can name a row in ANOTHER service's database — by computing the uuid rather than looking it up. That is what lets `legacy_mongo_id` be dropped once the last pre-cutover credential has expired: nothing needs the column if every id can be derived.
This is a byte-for-byte contract, not an approximation ¶
The derivation is mongo2pg's, reproduced here because its own implementation lives in an internal package that cannot be imported. A difference of one bit produces a valid-looking uuid that names no row, so the implementation is pinned against vectors generated from mongo2pg itself (testdata/derivation_vectors.json). If those tests fail, this file is wrong — do not adjust the vectors to match it.
serviceName is a permanent contract ¶
The namespace is uuidv5(RootNS, serviceName + "/" + collection). The service name is therefore part of every id it has ever minted: renaming a service, or migrating it under a different mapping, re-mints every primary key. The per-service mappings in backend/docker/mongo2pg/services/ are the source of truth for these names, and a cross-service reference must use the same string the target service is mapped under.
Index ¶
- Constants
- Variables
- func Derive(serviceName, collection string, objectID primitive.ObjectID) uuid.UUID
- func DeriveID(serviceName, collection string, i id.ID) (uuid.UUID, error)
- func Namespace(serviceName, collection string) uuid.UUID
- func ServiceName(perServiceDefault string) string
- func ValidateServiceNameEnv() error
- func VerifyDerivation(ctx context.Context, pool *pgxpool.Pool, serviceName, collection, table string) error
Constants ¶
const ServiceNameEnvVar = "MONGO2PG_SERVICE_NAME"
ServiceNameEnvVar overrides the mongo2pg service name every derived id is keyed under.
Two topologies ship, and they do NOT agree on this string:
per-service (cloud): one database and one mongo2pg instance per service, each mapped under its own name — "auth", "calendar", "mail", "productivity". This is the default.
single-database (self-hosted): ONE mapping covering every service's collections, all under serviceName "atomic-blend" — users, sessions, tasks, notes, calendars, events, mails and the rest. See backend/docker/mongo2pg/mapping.yaml.
Because the second topology migrates EVERY collection under one name, this variable overrides the cross-service names too: a service resolving another service's rows must use the name those rows were actually minted under, and in that topology it is the same single name.
const SingleDatabaseServiceName = "atomic-blend"
SingleDatabaseServiceName is the one non-empty value ServiceNameEnvVar may take: the name the single-database self-hosted mapping mints every id under.
Variables ¶
var ErrDerivationMismatch = errors.New("pgid: derived id does not match the stored row")
ErrDerivationMismatch reports that the configured service name does not match the one the rows in this database were replicated under.
var RootNS = uuid.MustParse("7f3a1c88-4c1e-4a2d-9d0b-6b1f2e9a5c40")
RootNS is mongo2pg's fixed root namespace, compiled into its binary. Changing it would re-mint every derived primary key in existence.
Functions ¶
func Derive ¶
Derive returns the uuid mongo2pg assigns to the row whose MongoDB _id is objectID, in the given service's collection.
The timestamp comes from the ObjectID itself, which is why no database and no extra field are needed. Note it is SECOND-granularity: several rows created in the same second share a millisecond prefix and differ only in the hashed bits, so the derived order does not match the ObjectID order. Anything that sorts by id must account for that — see shared/syncquery's cursor rules.
func DeriveID ¶
DeriveID is Derive for a neutral id.
A uuid-kind id is already the PostgreSQL key and is returned unchanged, so callers can pass whatever they were handed — a token minted before the cutover or after it — without branching.
The zero id derives the NIL uuid, the counterpart of the nil ObjectID it stands for: it is well-formed, no row has it as a key, and so a lookup bound to it matches nothing and answers not-found, exactly as a lookup by primitive.NilObjectID did on MongoDB. It is deliberately not NULL (which a careless IS NOT DISTINCT FROM could match against NULL columns) and not an error (which would turn an unknown id into a 500). A caller that must refuse the zero id, such as an authenticated identity, checks IsZero first.
func Namespace ¶
Namespace derives the per-collection namespace a service's primary keys are minted under. Including the collection is what stops two collections minting the same uuid from the same source id.
func ServiceName ¶
ServiceName returns the mongo2pg service name to derive under.
perServiceDefault is the name this service is mapped under in the per-service topology, which is what an unset variable means.
Getting this wrong is silent and total: the namespace is uuidv5(RootNS, serviceName+"/"+collection), so a mismatched name derives well-formed uuids that name no row. Reads come back empty and writes land unreferenced, with nothing logged — which is why VerifyDerivation exists and why services should call it at boot.
It never panics: on MongoDB the variable is irrelevant, and services evaluate this into package vars at init. An invalid value is rejected on the PostgreSQL boot path only, by ValidateServiceNameEnv (called from db.Open under DATASOURCE=postgres, and by VerifyDerivation).
func ValidateServiceNameEnv ¶
func ValidateServiceNameEnv() error
ValidateServiceNameEnv fails closed on a ServiceNameEnvVar that is neither unset/blank (per-service default) nor SingleDatabaseServiceName. The value is free-form text, and a typo would otherwise derive well-formed uuids that name no row: empty reads, no error.
func VerifyDerivation ¶
func VerifyDerivation(ctx context.Context, pool *pgxpool.Pool, serviceName, collection, table string) error
VerifyDerivation proves the configured service name agrees with the data.
It takes one replicated row — the first of a bounded, index-backed probe whose legacy_mongo_id is a 24-hex ObjectID, so a non-ObjectID row can never mask the check — derives the uuid that row's original Mongo _id should produce under serviceName, and compares it with the id the replicator actually stored. If they differ, the service is configured for a different topology than the database was migrated with, and every id resolution it performs will silently miss.
A table with no such rows, or without the legacy_mongo_id column at all (SQLSTATE 42703, once it has been dropped), returns nil: either nothing has been replicated or the column has already been dropped, and in both cases there is no pre-cutover id for this service to resolve. Derivation only matters for rows that came from MongoDB.
collection is the MONGO collection name the rows were migrated FROM, which is what the namespace is built from — not necessarily today's table name.
Types ¶
This section is empty.