README

A PHP REST client library for QuestDB time-series database.

This repository is experimental.

Overview

This library provides a simple way to interact with QuestDB's REST API. It allows you to execute SQL queries, import and export data in QuestDB. This client provides a clean and consistent interface for working with QuestDB.

Requirements

PHP 8.4 or higher
PSR-17 and PSR-18 compatible HTTP client

Installation

composer require 22h/questdb-client

This package is decoupled from any HTTP messaging client, you can visit HTTPlug for library users to get more information about installing HTTPlug related packages.

Usage

Client Initialization

use TwentyTwo\QuestDB\Client;

// Create a client instance
$client = new Client();

// Set the QuestDB server URL
$client->setUrl('http://localhost:9000');

// Alternatively, set the URL during initialization
$client = new Client(url: 'http://localhost:9000');

Executing SQL Queries

// Simple select query
$results = $client->execute()->select('SELECT * FROM trades LIMIT 10');

// Count query
$count = $client->execute()->count('SELECT COUNT(*) FROM trades');

// Execute with options (metadata, timings, explain)
$options = new ExecuteOptions();
$options->showMetadata();
$options->showTimings();
$options->showExplain();

$result = $client->execute()->selectWithOptions('SELECT * FROM trades LIMIT 10', $options);

// Create Tables, insert rows and update rows
$result = $client->execute()->execute('CREATE TABLE trades [...];');

Table Operations

// Get a table instance
$table = $client->table('trades');

// Get table columns
$columns = $table->columns();

// Get table partitions
$partitions = $table->partitions();

// Get CREATE TABLE statement
$createStatement = $table->showCreate();

// Drop a table
$table->drop(); // With IF EXISTS
$table->drop(false); // Without IF EXISTS

Importing Data

// Import from a CSV file
$client->import()->file('/path/to/data.csv');

// Import with custom table name
$options = new ImportOptions();
$options->setName('custom_table_name');
$client->import()->file('/path/to/data.csv', options: $options);

// Import from a resource
$resource = fopen('/path/to/data.csv', 'r');
$client->import()->resource($resource, options: $options);

Exporting Data

// Export query results to a stream
$stream = $client->export()->resource('SELECT * FROM trades;');

// Export with limit and offset
$stream = $client->export()->resource('SELECT * FROM trades;', limit: 100, offset: 200);

// Export to a file
$client->export()->file('/path/to/output.csv', 'SELECT * FROM trades;');

Meta Information

// Get QuestDB server version
$version = $client->meta()->version();

// Get QuestDB build information
$build = $client->meta()->build();

// List all tables
$tables = $client->meta()->tables();

// Get detailed table metadata
$tablesWithMetadata = $client->meta()->tablesWithMetadata();

// Get server parameters
$parameters = $client->meta()->parameters();

// Get available functions
$functions = $client->meta()->functions();

// Get query activity
$queryActivity = $client->meta()->queryActivity();

// Get memory metrics
$memoryMetrics = $client->meta()->memoryMetrics();

// Flush query cache
$client->meta()->flushQueryCache();

Basic Auth

// Simple way
$client->authenticateWithBasicAuth('username', 'password');

// Another way
use Http\Client\Common\Plugin\AuthenticationPlugin;
use Http\Message\Authentication\BasicAuth;

$clientBuilder = new ClientBuilder();
$clientBuilder->addPlugin(new AuthenticationPlugin(new BasicAuth('username', 'password')));
$client = new Client($clientBuilder);

Documentation

For more information about QuestDB, please refer to the official documentation.

Credits

Inspired by the structure of GitLabPHP/Client.

License

This library is released under the MIT License. See the LICENSE file for details.

22h / questdb-client

Maintainers

Details