Skip to main content
Returns the IP address of the client making the current HTTP request.

​
Signature

sqlpage.client_ip() -> TEXT

​
Parameters

This function takes no parameters.

​
Return Value

​
return
TEXT
The IP address of the client as a string (IPv4 or IPv6), or NULL if the IP cannot be determined

​
Description

The client_ip() function returns the IP address of the client making the request. This is useful for logging, rate limiting, geolocation, and security purposes. Important: When running behind a reverse proxy, this function returns the proxy’s IP address, not the actual client IP. See the Reverse Proxy section below.

​
Examples

​
Log Connection Attempts

Record client IP addresses when users log in: 
INSERT INTO login_attempts (username, ip_address, success, attempted_at)
VALUES (
    :username,
    sqlpage.client_ip(),
    FALSE,
    CURRENT_TIMESTAMP
);

​
Rate Limiting

Limit requests per IP address: 
SET client_ip = sqlpage.client_ip();

-- Count recent requests from this IP
SET request_count = (
    SELECT COUNT(*)
    FROM requests
    WHERE ip_address = $client_ip
      AND created_at > datetime('now', '-1 hour')
);

SELECT 'redirect' as component,
    '/error.sql?msg=rate_limit' as link
WHERE $request_count > 100;

-- Log this request
INSERT INTO requests (ip_address) VALUES ($client_ip);

​
IP-Based Access Control

Restrict access to specific IP ranges: 
SET client_ip = sqlpage.client_ip();

-- Allow only internal network
SELECT 'redirect' as component,
    '/unauthorized.sql' as link
WHERE NOT ($client_ip LIKE '192.168.%' OR $client_ip LIKE '10.%');

​
Audit Trail

Maintain an audit log with IP addresses: 
INSERT INTO audit_log (user_id, action, ip_address, created_at)
SELECT 
    $user_id,
    'deleted_record',
    sqlpage.client_ip(),
    CURRENT_TIMESTAMP;

DELETE FROM records WHERE id = :record_id;

​
Reverse Proxy Configuration

When running behind a reverse proxy (Nginx, Apache, Cloudflare, etc.), you need to read forwarding headers to get the real client IP:

​
Get Real Client IP

-- Try headers in order of preference
SET real_ip = COALESCE(
    sqlpage.header('x-forwarded-for'),
    sqlpage.header('x-real-ip'),
    sqlpage.header('cf-connecting-ip'),  -- Cloudflare
    sqlpage.client_ip()
);

INSERT INTO access_log (ip_address) VALUES ($real_ip);

​
Handle X-Forwarded-For

The X-Forwarded-For header can contain multiple IPs (client, proxy1, proxy2, …): 
SET forwarded_for = sqlpage.header('x-forwarded-for');

-- Take the first IP (leftmost = original client)
SET client_ip = CASE
    WHEN $forwarded_for IS NOT NULL
        THEN SUBSTR($forwarded_for, 1, INSTR($forwarded_for || ',', ',') - 1)
    ELSE sqlpage.client_ip()
END;

​
Common Proxy Headers

HeaderUsed ByDescription
X-Forwarded-ForNginx, ApacheComma-separated list of IPs
X-Real-IPNginxSingle client IP
CF-Connecting-IPCloudflareOriginal client IP
True-Client-IPAkamai, CloudflareOriginal client IP
X-Client-IPVariousClient IP

​
Security Considerations

​
Validating Proxy Headers

Warning: Proxy headers can be spoofed if not properly configured. Only trust these headers if:
  1. Your reverse proxy is properly configured to set them
  2. The proxy strips any existing headers from the client
  3. Direct client connections are blocked (only proxy can reach SQLPage)

​
Example: Trust Proxy Headers Safely

-- Only use proxy headers if request came through trusted proxy
SET direct_ip = sqlpage.client_ip();
SET is_trusted_proxy = $direct_ip IN ('127.0.0.1', '::1', '10.0.0.1');

SET real_client_ip = CASE
    WHEN $is_trusted_proxy THEN COALESCE(
        sqlpage.header('x-forwarded-for'),
        sqlpage.header('x-real-ip')
    )
    ELSE $direct_ip
END;

​
Return Value Details

​
IPv4 Address

192.168.1.100

​
IPv6 Address

2001:0db8:85a3:0000:0000:8a2e:0370:7334

​
NULL Value

Returns NULL when:
  • Connection is through a Unix socket
  • IP address cannot be determined
  • No network connection info is available

​
Common Use Cases

  1. Security Logging - Track who accessed what
  2. Rate Limiting - Prevent abuse from single IPs
  3. Geolocation - Show region-specific content
  4. Access Control - IP whitelist/blacklist
  5. Fraud Detection - Identify suspicious patterns
  6. Analytics - Track visitor locations
  7. Session Management - Bind sessions to IP addresses

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us