Skip to content

Publication Update Endpoint Has Confusing Semantics #459

@aleksandarskrbic

Description

@aleksandarskrbic

Problem

The current publication update endpoint uses POST with full replacement semantics, which is confusing and inconsistent with REST conventions:

POST /sources/{source_id}/publications/{publication_name}

Current behavior: If a publication has table_a and you want to add table_b, you must send a request with both tables in the request body. This is full replacement semantics, not incremental updates.

Why this is confusing:

  1. POST typically means "create" or "append", not "replace"
  2. Users must track the current state and send the full list
  3. Race conditions if multiple clients try to update simultaneously
  4. Doesn't match PostgreSQL's native granular operations

PostgreSQL's Native Operations

PostgreSQL supports three distinct operations for publications:

  1. ADD TABLE - Add tables to existing publication
    ALTER PUBLICATION pub_name ADD TABLE schema.table_name;

  2. DROP TABLE - Remove tables from publication
    ALTER PUBLICATION pub_name DROP TABLE schema.table_name;

  3. SET TABLE - Replace all tables (current implementation)
    ALTER PUBLICATION pub_name SET TABLE schema.table_1, schema.table_2;

Current implementation only exposes operation #3 (SET TABLE).

Proposed Solutions:

Option 1: Fix HTTP Method (Short-term)

Change POST → PUT to correctly indicate replacement semantics:
PUT /sources/{source_id}/publications/{publication_name}

Pros: Minimal code change, semantically correct
Cons: Still requires full state in request body

Option 2: Add Granular Endpoints (Medium-term)

Add dedicated endpoints for each operation:
POST /sources/{source_id}/publications/{publication_name}/tables # ADD TABLE
DELETE /sources/{source_id}/publications/{publication_name}/tables # DROP TABLE
PUT /sources/{source_id}/publications/{publication_name}/tables # SET TABLE

Pros: Matches PostgreSQL semantics, better UX
Cons: More endpoints to maintain

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions