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, PostgreSQL, SQLite, or ClickHouse 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`	`clearsoft/easysql-client`	🤖 Generated API client (from the OpenAPI spec) + token-refresh runtime
`packages/connectors`	`clearsoft/easysql-connectors`	Local introspection + SELECT execution for MySQL/MariaDB, PostgreSQL, SQLite and ClickHouse
`packages/common`	`clearsoft/easysql-common`	Shared code (SQL safety validation, credential sanitization)
`packages/schema-generation`	`clearsoft/easysql-schema-generation`	Raw introspection → canonical API schema payload (deterministic, no I/O)
`packages/laravel`	`clearsoft/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), ext-curl (clickhouse 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 clearsoft/easysql-client
composer require clearsoft/easysql-connectors
composer require clearsoft/easysql-schema-generation
composer require clearsoft/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([
    'connection_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 connections
$connections = EasySQL::listConnections();
$connection  = EasySQL::getConnection('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 Connections
$client->createConnection([
    'name'   => 'Production MySQL',
    'type'   => 'mysql',
    'schema' => $schemaPayload, // from the schema-generation package
]);

$connections = $client->listConnections();

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

print_r($query['sql_generated']);
print_r($query['needs_local_execution']);

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 canonical schema to the API — credentials never leave the machine. Supported engines are MySQL/MariaDB, PostgreSQL, SQLite, and ClickHouse HTTP.

use Clearsoft\EasySQL\Connectors\ConnectorEngine;
use Clearsoft\EasySQL\Connectors\ConnectorFactory;
use Clearsoft\EasySQL\SchemaGeneration\SchemaGenerator;

$connector = ConnectorFactory::create(ConnectorEngine::MySQL, [
    '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->syncConnection(['schema' => $payload], 'conn_abc123');

API Overview

Module	Available Methods
Auth	`refresh`, `logout`, `me`, `deleteMe`, `updateMe`
Queries	`createQuery`, `listQueries`, `getQuery`
Connections	`listConnections`, `createConnection`, `getConnection`, `getConnectionSchema`, `getSuggestions`, `updateConnection`, `deleteConnection`, `syncConnection`
Billing	`getPlan`, `getUsage`, `checkout`, `portal`
Dashboard	`dashboardStats`
Health	`health`, `healthHealth`

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

Migration from 3.x to 4.0

4.0 consolidates the connector packages into one and adds 11 engines.

One connector package. The four packages clearsoft/easysql-connectors-mysql, …-postgres, …-sqlite and …-clickhouse are replaced by a single clearsoft/easysql-connectors. Replace those requirements with:

composer remove clearsoft/easysql-connectors-mysql clearsoft/easysql-connectors-postgres \
    clearsoft/easysql-connectors-sqlite clearsoft/easysql-connectors-clickhouse
composer require clearsoft/easysql-connectors

Connection classes keep their namespaces (Clearsoft\EasySQL\Connectors\MySQL\Connector, …\Postgres\…, …), so most code is unchanged. New engines add SqlServer, Oracle, Firebird, Db2, DuckDb, LibSql, D1, Snowflake, BigQuery, Trino and Hana sub-namespaces.
ConnectorException is shared — import Clearsoft\EasySQL\Connectors\ConnectorException (the per-engine …\MySQL\ConnectorException etc. no longer exist).
New entry point ConnectorFactory::create($engine, $connection) accepts a config object, an options array, or an engine-native URL/DSN.
PostgreSQL gained provider (postgres/neon/cockroachdb/redshift) and transport (tcp/http); the Neon websocket transport is not supported in PHP.
Driver extensions are optional (suggest), so install only the one for the engine you use.

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 `clearsoft/easysql-laravel`)

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

$client->getConnection('conn_abc123');              // was: getConnection() — broken URL
$client->updateConnection(['name' => 'X'], 'conn_abc123');
$client->syncConnection(['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