Developer Handbook

HTTP & REST API Reference

Connect external laptops, web services, microservices, and scripts to your PocketSQL database over the local network.

Getting Started with the Background Server

To allow other devices (such as your development computer or another phone) to send queries to PocketSQL, you must start the embedded HTTP API server:

Ensure Same Wi-Fi Network: Make sure both your Android phone and the querying device are on the same local Wi-Fi router (or connect your PC to your phone's Wi-Fi Hotspot).
Start the Server in App: Open PocketSQL on your device, navigate to the Server tab, and tap Start API Server. A persistent notification will appear in your Android status bar.
Note the IP & Port: The active IP address and port will be displayed clearly (e.g., http://192.168.1.100:8080).
Generate an API Key: Under API Keys, tap Generate Token, select your target database (or all databases), and choose Read/Write or Read-Only permissions.

Step 2

HTTP API Specification

POST /api/query Auth Required

Executes a SQL query against the specified database and returns the result columns and rows as structured JSON.

HTTP Request Headers

Header	Value	Description
Authorization	Bearer <API_KEY>	Required bearer token generated in the PocketSQL app.
Content-Type	application/json	Must be set to `application/json`.
Accept	application/json	Optional. Default is `application/json`.

Step 3

Request Body Payload

The request body must be a valid JSON object containing the target database name and the SQL statement string:

{
  "database": "ecommerce",
  "sql": "SELECT id, product_name, price, stock FROM products WHERE stock > 0 LIMIT 5;"
}

database *string

The name of the database file on the phone to execute the query against.

sql *string

The ANSI SQL query (e.g., SELECT, INSERT, UPDATE, DELETE, CREATE TABLE).

Step 4

Response Schemas

200 OK Success Response Schema

{
  "success": true,
  "columns": ["id", "product_name", "price", "stock"],
  "rows": [
    {"id": 1, "product_name": "Mechanical Keyboard", "price": 129.99, "stock": 45},
    {"id": 2, "product_name": "Ergonomic Mouse", "price": 89.50, "stock": 20}
  ],
  "affected_rows": 0,
  "executionTimeMs": 2.14
}

400 / 403 / 500 Error Response Schema

{
  "success": false,
  "error": "Error 1146 (42S02): Table 'ecommerce.invalid_table' doesn't exist"
}

Step 5

Copy-Paste Client Connectors

Choose your favorite programming language to copy a complete, production-ready snippet for interacting with PocketSQL:

import requests

url = "http://192.168.1.100:8080/api/query"
headers = {
    "Authorization": "Bearer YOUR_POCKETSQL_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "database": "ecommerce",
    "sql": "SELECT id, product_name, price, stock FROM products WHERE stock > 0 ORDER BY price DESC LIMIT 5;"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data.get("success"):
    print(f"Executed in {data['executionTimeMs']}ms")
    for row in data["rows"]:
        print(f"[{row['id']}] {row['product_name']} - ${row['price']}")
else:
    print("Error:", data.get("error"))

const response = await fetch("http://192.168.1.100:8080/api/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_POCKETSQL_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    database: "ecommerce",
    sql: "SELECT id, product_name, price FROM products LIMIT 5;"
  })
});

const result = await response.json();
if (result.success) {
  console.log(`Query took ${result.executionTimeMs}ms:`);
  console.table(result.rows);
} else {
  console.error("SQL Error:", result.error);
}

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
String payload = """
    {
      "database": "ecommerce",
      "sql": "SELECT id, product_name, price FROM products LIMIT 5;"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://192.168.1.100:8080/api/query"))
    .header("Authorization", "Bearer YOUR_POCKETSQL_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status: " + response.statusCode());
System.out.println("Result: " + response.body());

<?php
$ch = curl_init('http://192.168.1.100:8080/api/query');
$payload = json_encode([
    'database' => 'ecommerce',
    'sql' => 'SELECT id, product_name, price FROM products LIMIT 5;'
]);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_POCKETSQL_API_KEY',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

curl -X POST "http://192.168.1.100:8080/api/query" 
  -H "Authorization: Bearer YOUR_POCKETSQL_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "database": "ecommerce",
    "sql": "SELECT id, product_name, price FROM products LIMIT 5;"
  }'

Troubleshooting

Networking & Firewall Tips

Router AP Client Isolation

Some public university or office Wi-Fi networks enable "AP Client Isolation", which blocks devices on the same Wi-Fi from talking to each other. If you cannot reach your phone, enable Mobile Hotspot on your phone and connect your laptop directly to it.

TLS Self-Signed Warning

When using HTTPS on port 8443, client libraries like cURL or Python will warn that the self-signed certificate is untrusted. Pass -k in cURL or verify=False in Python requests.