How to Connect Cloud ETL to a Local Database Behind NAT

Why a cloud ETL service cannot directly reach a local database

A managed extract, transform, and load service runs outside the network that contains a local database. The service may know the database software, username, and schema, but it still needs a routable network destination. An address such as 127.0.0.1, 192.168.x.x, or another private address has meaning only inside the relevant machine or private network. It cannot be used as a destination from an unrelated cloud environment.

Conventional NAT makes this separation intentional. A router permits devices on the private network to initiate outbound connections while rejecting unsolicited inbound traffic unless an explicit forwarding rule exists. CGNAT adds another translation layer controlled by the internet service provider. In that situation, configuring the local router alone may not create a usable inbound route because the customer does not control the provider-facing address.

A Localtonet tunnel changes the connection path. Our client runs on a device that can reach the database and establishes an outbound connection to a Localtonet relay server. A TCP tunnel then supplies a public host and port that can forward compatible TCP traffic to the configured local IP address and port. This does not require an inbound router port-forwarding rule, firewall changes for unsolicited internet traffic, a public IP address, or VPN setup.

The resulting data path has several distinct segments. The managed ETL connector opens a connection to the assigned public host and port. The Localtonet relay accepts the tunnel traffic. The already-connected Localtonet client carries it toward the local target. Finally, the database handles authentication, authorization, queries, and any database-native transport security.

Compare TCP tunneling, an HTTPS data API, and private mesh access

The safest design is not always the design with the fewest components. Start with the interface the ETL platform can consume, how much of the database must be available, and whether software can run inside the ETL environment. These factors usually determine whether a native TCP connection, a purpose-built HTTPS API, or a private network is appropriate.

When a TCP tunnel is the direct solution

Choose the TCP pattern when the cloud connector expects to speak the database's native wire protocol and accepts a user-supplied host and port. This is often the least disruptive approach because the ETL tool continues to use its existing database connector. Features such as metadata discovery, incremental reads, or change data capture remain connector and database concerns rather than tunnel features.

The direct design is also useful when the database is temporary, the pipeline is being evaluated, or the source exists on a network where inbound forwarding cannot be configured. However, convenience is not a reason to use broad administrator credentials or leave the tunnel running indefinitely. A native database endpoint deserves the same care as any other internet-reachable infrastructure.

When an HTTPS API is safer or more flexible

An API is preferable when the ETL job needs a narrow dataset rather than general database access. The application can enforce approved queries, omit confidential columns, aggregate records, validate filters, and present a stable contract even if the underlying schema changes. It can also implement API-specific authorization and auditing.

This approach introduces engineering work. A reliable extraction API needs pagination, deterministic ordering, error responses, timeout handling, and an incremental cursor or timestamp strategy where repeated full exports are impractical. It must define how deletions and updates are represented. The ETL tool must also support the API's authentication method and response format. If these requirements are not implemented carefully, an API may be narrower than a database tunnel but less reliable as a data source.

If the API runs locally, an HTTP/s tunnel can publish it through Localtonet. HTTP tunnel process types can use a random subdomain, a custom subdomain where supported, or a custom domain. Exact domain and DNS requirements should be checked against current Localtonet documentation before deployment.

When VPN Manager fits

Our VPN Manager provides a private mesh VPN with granular firewall rules and can bridge local LANs. It is conceptually appropriate when both ends can join the mesh or when a participating network can route the required resource. This is different from a standard TCP tunnel and should not be treated as the same feature under another name.

A fully managed ETL connector often gives the customer no operating-system access, so there may be nowhere to install or run the required private-network participant. In that case, private mesh access is not viable unless the ETL vendor supports a customer-managed worker, gateway, or agent. Review the Localtonet VPN Manager workflow alongside the deployment model of the selected ETL service before choosing this architecture.

Confirm the prerequisites before creating a tunnel

A few checks performed in advance prevent most failed deployments. Record the results as part of the pipeline design so operators know which system owns each control.

ETL connector requirements

• Supported source: Confirm that the ETL platform supports the exact database engine and version.
• Custom network destination: Verify that the connector accepts a custom public hostname and port. A connector that only supports vendor-managed instances or fixed cloud endpoints cannot use an arbitrary TCP tunnel.
• Authentication compatibility: Confirm support for the database authentication method you intend to use. Do not assume every connector supports client certificates, integrated identity, or every password mechanism.
• TLS controls: Determine whether the connector can require TLS, validate the server certificate, supply a trusted certificate authority, and verify the hostname where applicable.
• Extraction behavior: Identify whether the job performs full reads, incremental queries, log-based change capture, or another method. Each mode can require different database privileges and configuration.
• Network controls: If source IP allowlisting is part of the design, obtain the ETL service's documented egress addresses and confirm that the enforcement point can actually apply them.
• Connection behavior: Understand connection concurrency, query timeouts, retry policy, and scheduling. These affect database load and recovery after a temporary interruption.

Local environment requirements

• A running database that accepts TCP connections from the machine where the Localtonet client will run, or from another address reachable by that machine.
• A Localtonet-supported client installation on a device that can remain powered on for the required extraction window.
• Outbound network access from that device so the Localtonet client can establish and maintain its relay connection.
• A device-specific Localtonet authentication token handled as a secret. Never place the token in an article, shared ticket, pipeline log, or ETL hostname field.
• An available Localtonet relay server or region selected from the current dashboard. Availability can vary, so this guide does not hardcode a server code.
• A dedicated database account with only the schema, table, view, and operational privileges needed by the extraction method.
• A documented maintenance owner for the client, tunnel, database credentials, and ETL job.

Prepare the local database for controlled ETL access

Database configuration varies by engine, version, operating system, and connector. For that reason, this guide does not guess service names, configuration file paths, default ports, or vendor-specific commands. Use the database's official administration procedure for the controls below, then test from the same device that will run the Localtonet client.

Choose the Localtonet client location

Running the client on the database host can minimize the local network path. If the database accepts connections only on its loopback interface, a client on that same host may be able to target the loopback address. A client on another LAN machine cannot reach the database through the database host's loopback interface.

Running the client on a separate gateway or utility server can reduce software installed on the database host, but the database must then listen on an appropriate LAN interface and permit connections from that client device. The network between the client and database becomes another dependency. Choose one topology intentionally and avoid broad listening rules that make the database available to the entire LAN without need.

Create a dedicated extraction identity

Give the ETL process its own account rather than sharing an application or human administrator identity. For a basic snapshot extraction, read-only access to selected views or tables may be sufficient. Incremental replication and change data capture can require metadata, logging, replication, or other specialized permissions. Grant only requirements documented for the exact connector mode.

Curated database views are useful when the pipeline needs only a subset of fields. They can hide sensitive columns, normalize names, and provide a stable extraction surface. Row-level policies may provide additional separation where the database supports them and where the connector behaves correctly with those policies.

Plan transport security end to end

A TCP tunnel transports the database protocol but does not replace database authentication or automatically establish that the database connector is using its own TLS mode. Configure database-native TLS when supported, require it on the extraction identity where the database allows that policy, and configure the ETL connector to validate certificates rather than silently accepting any certificate.

Certificate hostname validation deserves special attention. The ETL connector connects to the public tunnel hostname, while the database certificate may have been issued for an internal database name. Whether a connector permits a separate TLS server name, custom trust material, or another supported configuration is product-specific. Do not disable certificate verification merely to make the first test pass. Resolve the name and trust design according to the database and ETL vendor documentation.

Test local reachability first

Before creating the public path, use an approved database client from the intended Localtonet device to connect to the exact local target address and port. Authenticate with the dedicated ETL identity and run a small read against an approved table or view. This proves that the database listener, local firewall, account, grants, and TLS settings work independently of the tunnel.

If this local test fails, adding a tunnel will not repair it. Troubleshoot the listener address, local routing, firewall policy, credentials, certificate trust, and database logs before continuing.

Create the Localtonet TCP tunnel

Use a TCP tunnel for a connector that communicates through the database's native TCP protocol. The workflow below follows the Localtonet lifecycle: install and run the client, identify the device, select an available relay, create the local target, start the tunnel, and then use the assigned endpoint.

The Localtonet documentation provides the current product navigation for supported tunnel categories. Dashboard values should remain the authority for relay selection and the endpoint assigned to a particular tunnel.

Verify the complete connection in layers

A successful dashboard status is necessary, but it does not prove that the ETL job can authenticate, validate TLS, discover schemas, or complete a query. Verify each layer separately so a failure can be assigned to the correct system.

Distinguish connectivity from data correctness

Network success says only that a session can reach the database. It does not prove that the extraction is complete. Validate expected row counts, update and deletion handling, timezone conversion, numeric precision, character encoding, and the incremental cursor. For change data capture, confirm that the connector progresses through changes without gaps and that required database logs are retained long enough for realistic outages.

Use a non-sensitive sentinel dataset for recurring checks when practical. A small table or view with known values can prove that the scheduled job reads from the intended database and writes to the intended destination without exposing confidential data in monitoring output.

Harden a database tunnel for ETL use

Direct database connectivity can be appropriate, but it creates a high-value access path. Security should be applied at the database, transport, connector, operating system, and lifecycle layers instead of relying on one control.

Use source IP restrictions only where they are enforceable

Some managed ETL providers publish stable egress addresses, while others use changing ranges or do not promise a fixed source. Source IP filtering is useful only if the provider documents the addresses and an actual enforcement point in the chosen architecture can apply them.

Do not assume which source address the local database will observe through a relayed tunnel. That behavior can depend on the tunnel implementation and protocol path. Test the observed database connection metadata in your environment. If source-based policy is mandatory, verify the full behavior before approving the architecture or place a controlled database proxy or API in front of the database where the required policy can be enforced.

Protect every credential independently

The Localtonet device token and database password serve different purposes. The device token identifies the client that runs the tunnel. The database credential authenticates the ETL session to the database. Neither should appear in the public endpoint, screenshots, source control, query text, or general logs.

Rotate credentials according to organizational policy and after suspected exposure. Test rotation with a limited extraction before revoking the old database secret if continuity is required. Remove obsolete accounts and device tokens when a host or integration is retired.

Control database workload

Least privilege does not prevent an authorized query from consuming excessive CPU, memory, I/O, or locks. Begin with a limited schedule and dataset. Use database-supported workload controls, statement timeouts, read replicas, or reporting views where appropriate. Exact controls differ by database and should be configured according to its official documentation.

Coordinate full refreshes with backup windows and application peaks. Incremental extraction can reduce repeated reads, but it may require more database privileges and operational preparation. Do not enable change data capture based only on a connector checkbox without reviewing the database-side consequences.

Operate the tunnel as part of the data pipeline

The tunnel is an infrastructure dependency, not a one-time setup task. Assign ownership and include it in monitoring, maintenance, incident response, and decommissioning.

Align the tunnel lifecycle with the ETL schedule

A Localtonet tunnel is available only while the selected client is connected and the tunnel is running. If extraction occurs continuously, the client host must be maintained as an always-available component. If extraction occurs in defined windows, operators can reduce unnecessary exposure by starting the tunnel before the job and stopping it afterward using an approved operational process.

Do not assume an endpoint, option, or relay choice will remain suitable forever. Record the assigned host and port in the integration inventory, but confirm current dashboard state before migrations or disaster-recovery tests. Plan and feature availability can vary, so validate required behavior against the current product rather than relying on old screenshots.

Monitor connection state

Localtonet platform-wide Token/Tunnel webhooks can report when a token or tunnel in a selected Token Group changes to Connected or Disconnected. The webhook sends a WebHookRequest JSON body containing Id, ActionDate, Type, and Status. The type identifies a token or tunnel, and the status is Connected or Disconnected.

These lifecycle webhooks should not be confused with File Server file-event webhooks. File Server webhooks concern upload, delete, rename, and move events and are unrelated to database query activity. A tunnel connection webhook also does not prove that the database is healthy, so combine it with ETL job monitoring and database-side checks.

Document a recovery sequence

1. Confirm that the database service is healthy and that the local target still accepts the dedicated account.
2. Confirm that the Localtonet client device is powered on, connected to its network, and authenticated.
3. Confirm that the intended TCP tunnel is started.
4. Verify the public host and port recorded in the ETL connector against the current tunnel assignment.
5. Run the connector's connection test and classify the result as network, TLS, authentication, authorization, or query related.
6. Run a limited extraction before resuming the normal schedule.

Decommission cleanly

When the pipeline is retired, disable its schedule, stop and delete the tunnel if it has no other approved purpose, revoke the dedicated database account, remove unnecessary database grants, and remove obsolete Localtonet device access. Preserve only the audit records required by organizational policy. Leaving an unused tunnel or credential available creates avoidable risk.

Troubleshoot common connection failures

Troubleshooting is fastest when each error is mapped to a layer. Avoid changing the database listener, firewall, tunnel, TLS settings, and credentials simultaneously because that makes the eventual fix difficult to identify and review.

Frequently asked questions