PHPackages npbreland/sqlator - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. npbreland/sqlator ActiveLibrary[Utility & Helpers](/categories/utility) npbreland/sqlator ================= Use AI to translate human language into SQL v1.0.0(2y ago)051AGPL-3.0-or-laterPHP Since Jun 5Pushed 2y ago1 watchersCompare [ Source](https://github.com/npbreland/SQLator)[ Packagist](https://packagist.org/packages/npbreland/sqlator)[ RSS](/packages/npbreland-sqlator/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (9)Versions (2)Used By (0) SQLator ======= [](#sqlator) An AI tool for translating human language into SQL queries. Level up your business users into power users! Install ------- [](#install) `composer require npbreland/sqlator` Overview -------- [](#overview) SQLator takes a user command or question and turns it into an SQL query. Take a simple example: ``` Question: Give me the first names of all students. SQL: SELECT first_name FROM students ``` This can empower business users who don't know SQL by allowing them to directly query for the information they need. Alternatively, SQLator can be used by programmers to help them quickly determine the queries they need to write in their code, or to give them a query to start with that they can then modify, enhancing their productivity. How it Works ------------ [](#how-it-works) SQLator works by sending the query to a language models, including with it the table schema for your database. Currently, it only works with OpenAI's chat models and with MySQL. I want to support other models and databases in the future, however. You will need an API key from OpenAI. If you don't already have one, you can sign up for API access on their [website](https://openai.com/). How to Use ---------- [](#how-to-use) First, here is an example of instantiating the SQLator class. ``` $SQLator = new SQLator( client: $client, open_AI_key: 'your-api-key', model: 'gpt-3.5-turbo', // Try GPT-4 if you can get access! DB_host: 'localhost', DB_name: 'my_db' DB_user: 'walter_white', DB_pass: 'example', ); ``` *Please look at the [constructor](https://github.com/npbreland/SQLator/blob/main/src/SQLator.php#L34)for the full list of options, including enabling write access.* `$client` must be a PSR-18-compliant HTTP client, such as [Guzzle](https://github.com/guzzle/guzzle) or [Symfony's HTTP client](https://github.com/symfony/http-client). [Here is a list on packagist.](https://packagist.org/providers/psr/http-client-implementation)Note: if you are using Laravel, its HTTP client is a wrapper around Guzzle, so it will work. There are two ways to use SQLator. 1. **With execution.** SQLator will produce SQL from the given query and run it on your database. **Note: The default is to allow only read access (i.e. SELECT queries), and I highly recommend to keep this setting for production use. Please only allow write access if you know what you are doing and your end users know what they are doing.** `$result = $SQLator->commandToResult('Give me all students.');` This should return an array of students. 2. **Without execution.** SQLator will only return the SQL it produces. This would mostly be useful to developers and database administrators. `$result = $SQLator->commandToSQL('Give me all students.');` This should return SQL like: `SELECT * FROM students` Limitations and suggested fixes/workarounds ------------------------------------------- [](#limitations-and-suggested-fixesworkarounds) ### Schemas [](#schemas) The AI is not magic, so its resolution skills will be hampered if your schemas are not set up well. For best results, I recommend setting up foreign keys where applicable and adding comments to your columns, especially where their meaning is not straightforward. These two steps should aid the AI, just like they would aid a human. ### Token maxes [](#token-maxes) Language models have a maximum number of tokens that can be supplied. GPT-3.5-turbo accepts up to 4,096 tokens. This may mean that for large schema aggregates you run out of tokens in your prompt. GPT-4 can handle much more, so definitely try it out if you have access. I am planning to improve the tool to reduce this problem, perhaps by shortening the schema readouts to only the information that is absolutely needed by the language model, and/or allowing the user to specify the tables they want to include in SQLator's scope. ### Complex queries [](#complex-queries) SQLator is surprisingly powerful even with just GPT-3.5-turbo. However, I have noticed that it becomes less reliable the more complex queries become. You may be able to improve its resolution abilities by passing in additional information about your data to the `$additional_prompt` parameter in the SQLator constructor. If you have access to GPT-4, you may see a great improvement in its abilities. Error handling -------------- [](#error-handling) Currently I have defined three different exceptions that you may catch and handle as you see fit. **OnlySelectException:** Thrown when the AI resolves a command to a non-SELECT query and SQLator is in read-only mode. The exception will contain the original user command and the response from the AI. **NotSingleSelectStatement:** Thrown when the AI resolves a command to something that is not a single select statement and SQLator is in read-only mode. This could occur if the user query somehow resolves to multiple queries. The exception will contain the original user command and the response from the AI. **AI\_APIException:** Thrown when there is a ClientException to the request to the AI endpoint. The exception will contain the HTTP error code and the HTTP response body encoded in JSON. Testing ------- [](#testing) PHPUnit is included as a dev dependency, so you can run the suite of tests I have written using it. To bring up the testing environment, use `docker-compose up`. See the [docker-compose.yml](https://github.com/npbreland/SQLator/blob/main/docker-compose.yml)for more details. You may need to change the ports if you already have something running on the defaults. To run the tests, you can run this: `docker exec sqlator_www ./vendor/bin/phpunit tests` This will run the command inside the sqlator\_www container, which you'll need to do for the Docker network DNS resolution to work properly. Note that since we are working with the output of a language model, tests may occasionally fail. I have reduced the likelihood of variable responses by decreasing the "temperature" in the model's settings, but it could still happen. You may also get 429 "Too Many Request" errors if you run the tests too much in a short span of time. I have added a short `sleep` in between tests to reduce this. Feel free to contribute more tests if you like. I am using the ORM [RedBeanPHP](https://www.redbeanphp.com/index.php) to seed the test database. Contributing ------------ [](#contributing) Please feel free to contribute! You can have a look at the [TODO.md](https://github.com/npbreland/SQLator/blob/main/TODO.md)to see what I am considering so far, but if you have other ideas I am definitely open to them! ### Health Score 21 — LowBetter than 19% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity5 Limited adoption so far Community8 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 1077d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/a93a997a38b84ef7c5bed5b50334c0c43be5b9d51a885ca073887f41a6ac5805?d=identicon)[npbreland](/maintainers/npbreland) --- Top Contributors [![npbreland](https://avatars.githubusercontent.com/u/34611559?v=4)](https://github.com/npbreland "npbreland (36 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/npbreland-sqlator/health.svg) ``` [![Health](https://phpackages.com/badges/npbreland-sqlator/health.svg)](https://phpackages.com/packages/npbreland-sqlator) ``` ### Alternatives [w7corp/easywechat 微信SDK 10.4k761.6k60](/packages/w7corp-easywechat)[embed/embed PHP library to retrieve page info using oembed, opengraph, etc 2.1k11.0M97](/packages/embed-embed)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 728272.9k20](/packages/civicrm-civicrm-core)[cognesy/instructor-php The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control 310107.9k1](/packages/cognesy-instructor-php)[csharpru/vault-php Best Vault client for PHP that you can find 8410.3M4](/packages/csharpru-vault-php)[tigitz/php-spellchecker Provides an easy way to spellcheck multiple text source by many spellcheckers, directly from PHP 309498.4k1](/packages/tigitz-php-spellchecker) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)