README

EasySQL PHP & Laravel SDK

Official PHP & Laravel SDK for the EasySQL API · A Clearsoft Product

Ask questions in natural language to your MySQL, MariaDB, or SQLite databases directly from your PHP applications and Laravel projects.

Packages

This is a multipackage repository. All packages are versioned and released together.

Package	Composer name	Description
`packages/client`	`easysql/client`	🤖 Generated API client (from the OpenAPI spec) + token-refresh runtime
`packages/connectors/mysql`	`easysql/connectors-mysql`	Local MySQL/MariaDB introspection + SELECT execution
`packages/connectors/postgres`	`easysql/connectors-postgres`	Local PostgreSQL introspection + SELECT execution
`packages/connectors/sqlite`	`easysql/connectors-sqlite`	Local SQLite introspection + SELECT execution
`packages/common`	`easysql/common`	Shared code (SQL safety validation, credential sanitization)
`packages/schema-generation`	`easysql/schema-generation`	Raw introspection → API schema payload (deterministic, no I/O)
`packages/laravel`	`easysql/laravel`	Laravel service provider, manager and facade

Requirements

PHP >= 8.2
ext-json
guzzlehttp/guzzle ^7.0 (client package)
ext-pdo_mysql (mysql connector), ext-pdo_pgsql (postgres connector), ext-pdo_sqlite (sqlite connector)
(Optional) Laravel ^11.0 || ^12.0 (for Service Provider and Facade)

Installation

# Client + schema generation (the meta-package; connectors and Laravel are opt-in)
composer require clearsoft/easysql-sdk

# Or pick individual packages:
composer require easysql/client
composer require easysql/connectors-mysql
composer require easysql/connectors-postgres
composer require easysql/connectors-sqlite
composer require easysql/schema-generation
composer require easysql/laravel

Laravel Integration

The SDK provides first-class support for Laravel with automatic package discovery, configuration publishing, and a dedicated EasySQL facade.

1. Publish Configuration (Optional)

Publish the easysql.php configuration file:

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

This creates config/easysql.php in your Laravel application.

2. Configure Environment Variables

Add your credentials to your .env file:

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

3. Using the Facade

use Clearsoft\EasySql\Laravel\Facades\EasySQL;

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

// Generated SQL and query results
$sql  = $result['sql'];
$rows = $result['result'];

// List recent queries
$queries = EasySQL::listQueries(['page' => 1, 'per_page' => 10]);

// Manage database connectors
$connectors = EasySQL::listConnectors();
$connector  = EasySQL::getConnector('conn_abc123');

// Access specific named connections defined in config/easysql.php
$analyticsClient = EasySQL::connection('analytics');
$stats = $analyticsClient->dashboardStats();

Standalone PHP Usage

Typed API Client (Recommended)

Use the generated Client with typed methods for all endpoints:

<?php

require 'vendor/autoload.php';

use Clearsoft\EasySQL\Api\Client;

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

// Authentication
$tokens = $client->refresh(['refresh_token' => $refreshToken]);
$user = $client->me();

// Managing Database Connectors
$client->createConnector([
    'name'   => 'Production MySQL',
    'type'   => 'mysql',
    'schema' => $schemaPayload, // from the schema-generation package
]);

$connectors = $client->listConnectors();

// Running Natural Language Queries
$query = $client->createQuery([
    'connector_id' => 'conn_abc123',
    'question'     => 'What were the top 5 selling products last week?',
]);

print_r($query['sql']);
print_r($query['result']);

Automatic Token Refresh

The typed Client supports a token store and refreshes the access token automatically (once) on a 401, persisting the new tokens:

use Clearsoft\EasySQL\Client\Client;
use Clearsoft\EasySQL\Client\Http\TokenStoreInterface;

$client = new Client([
    'base_url'      => 'https://api.easysql.net',
    'access_token'  => $accessToken,
    'refresh_token' => $refreshToken,
]);
$client->setTokenStore(new SessionTokenStore()); // implements TokenStoreInterface

For raw Guzzle access, EasySQLClient wraps the same token manager:

use Clearsoft\EasySQL\Client\Http\EasySQLClient;
use Clearsoft\EasySQL\Client\Http\TokenStoreInterface;

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

// Implement TokenStoreInterface to persist tokens in Redis, Session, or Database
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());

Typed DTOs

The generated packages/client/src/Models classes hydrate an API response array into a typed object:

use Clearsoft\EasySQL\Client\Models\TokenResponse;

$tokens = TokenResponse::fromArray($client->refresh(['refresh_token' => $refreshToken]));
echo $tokens->access_token;

Local Connectors + Schema Generation

Introspect a local database and push only the schema to the API — credentials never leave the machine:

use Clearsoft\EasySQL\Connectors\MySQL\ConnectionConfig;
use Clearsoft\EasySQL\Connectors\MySQL\Connector as MySQLConnector;
use Clearsoft\EasySQL\SchemaGeneration\SchemaGenerator;

$connector = new MySQLConnector(new ConnectionConfig(
    host: '127.0.0.1',
    user: 'readonly',
    password: 'secret',
    database: 'myapp',
));
$connector->connect();

try {
    $raw = $connector->introspect();
    $payload = (new SchemaGenerator())->generate($raw);

    // Execute a generated SELECT locally
    $result = $connector->execute('SELECT * FROM users LIMIT 10');
} finally {
    $connector->close();
}

// Push the schema to the API
$client->syncConnector(['schema' => $payload], 'conn_abc123');

API Overview

Module	Available Methods
Auth	`refresh`, `logout`, `me`, `deleteMe`, `updateMe`
Queries	`createQuery`, `listQueries`, `getQuery`, `answerQuery`
Connectors	`listConnectors`, `createConnector`, `getConnector`, `getConnectorSchema`, `getSuggestions`, `updateConnector`, `deleteConnector`, `syncConnector`
Billing	`getPlan`, `checkout`, `portal`
Dashboard	`dashboardStats`
Health	`health`, `healthHealth`

See packages/client/docs/API.md for full endpoint reference and parameters.

Migration from the single-package layout (v1.x)

Version 1.x shipped a single package clearsoft/easysql-sdk with namespace Clearsoft\EasySQL\SDK. The multipackage layout keeps that package as a meta-package (same name, same version line), so composer require clearsoft/easysql-sdk keeps working — but the namespaces changed:

Before (v1.x)	After
`Clearsoft\EasySQL\SDK\Client`	`Clearsoft\EasySQL\Api\Client`
`Clearsoft\EasySQL\SDK\Models\*`	`Clearsoft\EasySQL\Api\Models\*`
`Clearsoft\EasySQL\SDK\Exceptions\ApiException`	`Clearsoft\EasySQL\Api\Exceptions\ApiException`
`Clearsoft\EasySQL\SDK\EasySQLClient`	`Clearsoft\EasySQL\Api\Http\EasySQLClient`
`Clearsoft\EasySQL\SDK\TokenStoreInterface`	`Clearsoft\EasySQL\Api\Http\TokenStoreInterface`
`Clearsoft\EasySql\Laravel\*`	unchanged (now in `easysql/laravel`)

Connector methods now take their path parameters explicitly (this also fixes a v1.x bug where getConnector('conn_1') silently ignored the id and requested a literal {connector_id} URL):

$client->getConnector('conn_abc123');              // was: getConnector() — broken URL
$client->updateConnector(['name' => 'X'], 'conn_abc123');
$client->syncConnector(['schema' => $payload], 'conn_abc123');

Samples

Runnable examples for every package live in samples/ — from a basic client call and token refresh to MySQL/PostgreSQL/SQLite introspection + sync and the Laravel integration. See the samples README.

php samples/09-schema-generation.php   # no credentials needed

Development & Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on the development workflow and pull request process.

make install                          # install composer dependencies
make lint                             # check PHP syntax in every package
make analyse                          # PHPStan static analysis
make test                             # run PHPUnit test suite (all packages)
make generate                         # regenerate packages/client from OpenAPI spec
make check                            # verify packages/client was not hand-edited
make db-up                            # start local MySQL for integration tests
make test-integration                 # tests including MySQL integration (needs db-up)
make db-down                          # stop and remove the MySQL container
make build                            # full build (generate + lint + analyse + test)

Composer scripts mirror the common ones: composer test, composer analyse, composer generate.

License

This project is open source and licensed under the MIT License.

Maintained by Clearsoft.

clearsoft / easysql-sdk

Package info

Security

Statistics