1# Configuration
2 
3Setup and configuration for TCP Sockets in Cloudflare Workers.
4 
5## Wrangler Configuration
6 
7### Basic Setup
8 
9TCP Sockets are available by default in Workers runtime. No special configuration required in `wrangler.jsonc`:
10 
11```jsonc
12{
13  "name": "private-network-worker",
14  "main": "src/index.ts",
15  "compatibility_date": "2025-01-01"
16}
17```
18 
19### Environment Variables
20 
21Store connection details as env vars:
22 
23```jsonc
24{
25  "vars": { "DB_HOST": "10.0.1.50", "DB_PORT": "5432" }
26}
27```
28 
29```typescript
30interface Env { DB_HOST: string; DB_PORT: string; }
31 
32export default {
33  async fetch(req: Request, env: Env): Promise<Response> {
34    const socket = connect({ hostname: env.DB_HOST, port: parseInt(env.DB_PORT) });
35  }
36};
37```
38 
39### Per-Environment Configuration
40 
41```jsonc
42{
43  "vars": { "DB_HOST": "localhost" },
44  "env": {
45    "staging": { "vars": { "DB_HOST": "staging-db.internal.net" } },
46    "production": { "vars": { "DB_HOST": "prod-db.internal.net" } }
47  }
48}
49```
50 
51Deploy: `wrangler deploy --env staging` or `wrangler deploy --env production`
52 
53## Integration with Cloudflare Tunnel
54 
55To connect Workers to private networks, combine TCP Sockets with Cloudflare Tunnel:
56 
57```
58Worker (TCP Socket) → Tunnel hostname → cloudflared → Private Network
59```
60 
61### Quick Setup
62 
631. **Install cloudflared** on a server inside your private network
642. **Create tunnel**: `cloudflared tunnel create my-private-network`
653. **Configure routing** in `config.yml`:
66 
67```yaml
68tunnel: <TUNNEL_ID>
69credentials-file: /path/to/<TUNNEL_ID>.json
70ingress:
71  - hostname: db.internal.example.com
72    service: tcp://10.0.1.50:5432
73  - service: http_status:404  # Required catch-all
74```
75 
764. **Run tunnel**: `cloudflared tunnel run my-private-network`
775. **Connect from Worker**:
78 
79```typescript
80const socket = connect(
81  { hostname: "db.internal.example.com", port: 5432 },  // Tunnel hostname
82  { secureTransport: "on" }
83);
84```
85 
86For detailed Tunnel setup, see [Tunnel configuration reference](../tunnel/configuration.md).
87 
88## Smart Placement Integration
89 
90Reduce latency by auto-placing Workers near backends:
91 
92```jsonc
93{ "placement": { "mode": "smart" } }
94```
95 
96Workers automatically relocate closer to TCP socket destinations after observing connection latency. See [Smart Placement reference](../smart-placement/).
97 
98## Secrets Management
99 
100Store sensitive credentials as secrets (not in wrangler.jsonc):
101 
102```bash
103wrangler secret put DB_PASSWORD  # Enter value when prompted
104```
105 
106Access in Worker via `env.DB_PASSWORD`. Use in protocol handshake or authentication.
107 
108## Local Development
109 
110Test with `wrangler dev`. Note: Local mode may not access private networks. Use public endpoints or mock servers for development:
111 
112```typescript
113const config = process.env.NODE_ENV === 'dev' 
114  ? { hostname: 'localhost', port: 5432 }  // Mock
115  : { hostname: 'db.internal.example.com', port: 5432 };  // Production
116```
117 
118## Connection String Patterns
119 
120Parse connection strings to extract host and port:
121 
122```typescript
123function parseConnectionString(connStr: string): SocketAddress {
124  const url = new URL(connStr); // e.g., "postgres://10.0.1.50:5432/mydb"
125  return { hostname: url.hostname, port: parseInt(url.port) || 5432 };
126}
127```
128 
129## Hyperdrive Integration
130 
131For PostgreSQL/MySQL, prefer Hyperdrive over raw TCP sockets (includes connection pooling):
132 
133```jsonc
134{ "hyperdrive": [{ "binding": "DB", "id": "<HYPERDRIVE_ID>" }] }
135```
136 
137See [Hyperdrive reference](../hyperdrive/) for complete setup.
138 
139## Compatibility
140 
141TCP Sockets available in all modern Workers. Use current date: `"compatibility_date": "2025-01-01"`. No special flags required.
142 
143## Related Configuration
144 
145- **[Tunnel Configuration](../tunnel/configuration.md)** - Detailed cloudflared setup
146- **[Smart Placement](../smart-placement/configuration.md)** - Placement mode options
147- **[Hyperdrive](../hyperdrive/configuration.md)** - Database connection pooling setup
148