Add lookup_choice transformer

[kvch]

Description

This PR adds a transformer named lookup_choice. It replaces a column value with one read from a column of another table, loaded from the source database once when the pipeline starts. This is the live-table counterpart of greenmask_choice, which chooses from a list written into the configuration. The main issue was that greenmask_choice and greenmask_integer force users to regenerate their YAML whenever the lookup table's contents change.

The name is not foreign_key_choice, as the issue proposes, because nothing here queries pg_constraint or checks that a foreign key exists.

Name	Description
lookup_table	The schema-qualified table to read the replacement values from, quoted as written, so public.countries means lowercase countries.
lookup_column	The column of that table whose values become the pool to choose from, read once at startup with IS NOT NULL and an ORDER BY.
generator: deterministic	Picks the value from a hash of the incoming value, so equal originals stay equal afterwards; random picks independently per row and destroys that grouping.
ignore_values: [0, -1]	Drops those values from the pool after it is read.
postgres_url	The database to read the lookup table from; omitted here because the PostgreSQL parser fills in the source URL, and only needed when the source is not PostgreSQL.

Example configuration

 transformations:
    table_transformers:
      - schema: public
        table: addresses
        column_transformers:
          country_id:
            name: lookup_choice
            parameters:
              lookup_table: public.countries
              lookup_column: id
              generator: deterministic
              ignore_values: [0, -1]

Related Issue(s)

• Closes column transformer randomise foreign key #1137

Type of Change

Please select the relevant option(s):

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test coverage improvement
• 🔨 Build/CI changes
• 🧹 Code cleanup

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• All existing tests pass

Checklist

• Code follows project style guidelines
• Self-review completed
• Code is well-commented
• Documentation updated where necessary

[xata-bot]

⚠️ The pgstream review agent is deferring to a human reviewer.

• 535 substantive lines exceeds the 300-line ceiling for auto-review

_{tier T1-agent. Address the above (or get a human review) and re-add the ai-review label to re-run.}

[github-actions]

Coverage

Total: 61.4% (+0.2% vs main)

Coverage in packages changed by this PR:

Package	Coverage	Δ
pkg/transformers	85.8%	+0.5%
pkg/transformers/builder	90.9%	+0.2%
pkg/transformers/internal/lookup	0.0%	new
pkg/wal/processor/transformer	85.8%	+0.4%

[thorfi]

@kvch FYI this will need to ensure that lookup table stream is fully updated first (in snapshot mode - replication mode should be OK), if that's not already taken care of, otherwise the lookup will try to add ids that don't yet exist in the target. Particularly bad if there are parallel table workers going on.

Alternately the lookup could be done in the target, but that's not as nice.