YANPM/public/migration/doc/nginx-tables.md

Migration Tables → nginx mapping

This document explains the purpose of each migration table added under public/migration/src/migrations and how the rows map to generated nginx configuration (HTTP http {} and stream {} contexts).

Summary of tables covered:

• upstream
• upstream_target
• proxy_host
• location
• stream_service
• access_list
• access_list_entry
• audit_log

---

upstream

Purpose: A named backend pool of servers. Shared by HTTP and stream services.

Key fields:

• id: UUID primary key
• name: identifier used when generating nginx upstream <name> {}
• protocol: http | tcp | udp — determines how nginx will use the pool
• algorithm: load balancing strategy (round_robin, least_conn, ip_hash)
• sticky_session: whether to enable sticky behavior when supported
• health_check: optional JSON describing health probes

nginx mapping (HTTP):

upstream <name> {
    server 10.0.0.5:8080 weight=2;
    server 10.0.0.6:8080 backup;
    # optional LB settings generated from `algorithm` and `sticky_session`
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://<name>;
    }
}

nginx mapping (stream):

stream {
  upstream <name> {
    server 10.0.0.5:3306;
    server 10.0.0.6:3306 backup;
  }

  server {
    listen 3306;
    proxy_pass <name>;
  }
}

Notes: upstream.protocol selects which block and directive forms to generate;

---

upstream_target

Purpose: One row per backend server in an upstream pool.

Key fields:

• upstream_id: FK to upstream
• target_host, target_port
• weight, is_backup, enabled

nginx mapping: each row becomes a server line in the generated upstream block (weights and backup flags applied). Disabled targets are omitted.

Example generated line:

server 10.0.0.5:8080 weight=3;
server 10.0.0.6:8080 backup;

---

proxy_host

Purpose: Represents an HTTP(S) host (a top-level server block in nginx http context).

Key fields:

• domain: server_name value (may be a wildcard)
• listen_port: port to listen on (80/443)
• scheme: http|https (informs UI; TLS handled elsewhere)
• forward_host/forward_port or default_upstream_id: host-level forwarding fallback
• preserve_host_header: whether to forward original Host header
• enable_websocket: toggles websocket header handling
• meta: JSON for optional host-level settings (timeouts, client_max_body_size, custom snippets)

nginx mapping (host-level default):

server {
  listen <listen_port>;
  server_name <domain>;

  # host-level fallback if no matching location
  location / {
    proxy_pass http://<default_upstream_name>;
  }
}

If forward_host/forward_port is set instead of default_upstream_id, generate proxy_pass http://forward_host:forward_port;.

meta entries are injected into the server block (careful: snippets can break reloads).

---

location

Purpose: Path-level routing (location blocks inside a server). More specific than proxy_host default.

Key fields:

• host_id: FK to proxy_host
• path: location match (e.g., /api, ~^/assets/)
• match_type: prefix | exact | regex
• upstream_id or proxy_pass_host/proxy_pass_port
• allowed_methods: optional method whitelist
• custom_config: raw nginx snippet inserted inside the location

nginx mapping:

location /api {
  proxy_pass http://api_upstream;
  # optional custom_config injected here
}

Ordering and match type produce correct nginx location selection semantics; order field can break ties for equal specificity.

---

stream_service

Purpose: A TCP/UDP service in nginx stream context — corresponds to a server block inside stream {}.

Key fields:

• listen_host, listen_port
• protocol: tcp | udp
• mode: direct | upstream (direct forwards to forward_host:forward_port, upstream uses upstream_id pool)
• preserved_client_ip: whether to enable proxy_protocol or other client-ip forwarding
• meta: JSON for advanced stream options (ssl_preread, proxy_timeout, buffer sizes)

nginx mapping (stream):

stream {
  upstream <name> {
    server 10.0.0.5:3306;
  }

  server {
    listen 3306;
    proxy_pass <name>; # or proxy_pass 10.0.0.10:3306 for direct
  }
}

Notes: Stream services bypass HTTP processing. Use meta for proxy_protocol and ssl_preread toggles.

---

access_list and access_list_entry

Purpose: Nameable allow/deny lists for IP/CIDR or other entry types that can be applied to hosts/locations/stream services.

Key fields (access_list): id, name, description. Key fields (entry): access_list_id, entry_type (e.g., allow, deny, note), value (IP or CIDR), comment.

nginx mapping (HTTP example):

location /admin {
  allow 10.0.0.0/24;
  deny all;
  proxy_pass http://admin_upstream;
}

nginx mapping (stream example):

server {
  listen 3306;
  allow 10.0.0.0/24;
  deny all;
  proxy_pass backend_pool;
}