Skip to content
EasySQL

Documentation

Everything you need to connect a database, ask questions, audit the generated SQL, and embed EasySQL in your own product.

PHP SDK

Install the official EasySQL PHP & Laravel SDK, connect to your account, and run your first query in under 5 minutes.

packagist clearsoft/easysql-sdk github Clearsoft-net/easysql-php docs API reference

Requirements

  • PHP >= 8.2
  • ext-json
  • guzzlehttp/guzzle ^7.0
  • (Optional) Laravel ^11.0 — for the EasySQL facade and Service Provider

Installation

Install via Composer:

composer require clearsoft/easysql-sdk

Standalone PHP — typed Client

Use the generated Client with typed methods for every endpoint. This is the recommended entry point for non-Laravel projects.

<?php

require 'vendor/autoload.php';

use Clearsoft\EasySql\SDK\Client;

$client = new Client([
    'base_url'     => 'https://api.easysql.net',
    'access_token' => 'your-access-token',
]);

// Login by email + password (public endpoint)
$tokens = $client->login([
    'email'    => '[email protected]',
    'password' => 'secret',
]);
$user = $client->me();

Standalone PHP — auto-refreshing EasySQLClient

Use EasySQLClient when you want the SDK to automatically refresh the JWT on 401 responses. Provide a TokenStoreInterface implementation to persist tokens in Redis, the session, or a database table.

<?php

require 'vendor/autoload.php';

use Clearsoft\EasySql\SDK\EasySQLClient;
use Clearsoft\EasySql\SDK\TokenStoreInterface;

$client = new EasySQLClient([
    'base_url'      => 'https://api.easysql.net',
    'access_token'  => $accessToken,
    'refresh_token' => $refreshToken,
]);

class SessionTokenStore implements TokenStoreInterface
{
    public function load(): ?array
    {
        return $_SESSION['easysql_tokens'] ?? null;
    }

    public function save(string $accessToken, string $refreshToken): void
    {
        $_SESSION['easysql_tokens'] = [
            'access_token'  => $accessToken,
            'refresh_token' => $refreshToken,
        ];
    }

    public function clear(): void
    {
        unset($_SESSION['easysql_tokens']);
    }
}

$client->setTokenStore(new SessionTokenStore());

Laravel integration

The SDK auto-discovers in Laravel 11+. Publish the config (optional):

php artisan vendor:publish --tag=easysql-config

Add credentials to .env:

EASYSQL_BASE_URL=https://api.easysql.net
EASYSQL_ACCESS_TOKEN=your-access-token
EASYSQL_TIMEOUT=30

Use the EasySQL facade:

<?php

use Clearsoft\EasySql\Laravel\Facades\EasySQL;

// Ask a question in natural language
$result = EasySQL::createQuery([
    'connector_id' => 'conn_abc123',
    'question'     => 'How many users registered this month?',
]);

$sql  = $result['sql'];
$rows = $result['result'];

// Paginated query history
$queries = EasySQL::listQueries(['page' => 1, 'per_page' => 10]);

// Connector management
$connectors = EasySQL::listConnectors();
$connector  = EasySQL::getConnector('conn_abc123');

// Named connection from config/easysql.php
$analyticsClient = EasySQL::connection('analytics');
$stats = $analyticsClient->dashboardStats();

Connectors

// Create a MySQL connector
$client->createConnector([
    'name'   => 'Production MySQL',
    'type'   => 'mysql',
    'config' => [
        'host'     => 'db.example.com',
        'port'     => 3306,
        'database' => 'myapp',
        'user'     => 'readonly',
        'password' => 'secret',
    ],
]);

// List, get, sync, update, delete
$connectors = $client->listConnectors();
$connector  = $client->getConnector('conn_abc123');
$client->syncConnector('conn_abc123');
$client->updateConnector('conn_abc123', ['name' => 'Staging']);
$client->deleteConnector('conn_abc123');

// Test a connection before saving
$test = $client->testConnector([
    'type'   => 'mysql',
    'config' => [/* ... */],
]);

Asking questions

// Create a question (async; returns status=processing)
$query = $client->createQuery([
    'connector_id' => 'conn_abc123',
    'question'     => 'What were the top 5 selling products last week?',
]);

// Poll until ready (or use SDK convenience helper)
$query = $client->getQuery($query['id']); // loop until status === 'ready'

print_r($query['sql']);     // generated SELECT statement
print_r($query['result']); // rows

Next steps