PHPackages                             k-kinzal/sql-faker - 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. k-kinzal/sql-faker

ActiveLibrary[Utility & Helpers](/categories/utility)

k-kinzal/sql-faker
==================

Faker Provider for generating syntactically valid SQL statements

v0.1.1(3mo ago)016MITPHPPHP ^8.1

Since Mar 6Pushed 3mo agoCompare

[ Source](https://github.com/k-kinzal/sql-faker)[ Packagist](https://packagist.org/packages/k-kinzal/sql-faker)[ RSS](/packages/k-kinzal-sql-faker/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (10)Versions (3)Used By (6)

SQL Faker
=========

[](#sql-faker)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/7535257ca228724c93658bd52583d4e47a9bab02c356abf6e54c1d575f2151e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c75652e737667)](https://www.php.net/)

A [FakerPHP](https://github.com/FakerPHP/Faker) provider for generating syntactically valid MySQL SQL statements based on MySQL's official Bison grammar (`sql_yacc.yy`).

Overview
--------

[](#overview)

SQL Faker uses formal grammar derivation to generate random but syntactically valid MySQL SQL. It parses MySQL's actual Bison grammar definition and uses it to produce any MySQL statement type (DML, DDL, TCL, etc.) and SQL fragments (expressions, clauses, subqueries, CTEs).

- **Grammar-accurate** - Derived from MySQL's official `sql_yacc.yy`, not hand-written rules
- **Version-aware** - Supports MySQL 5.6 through 9.1, generating only syntax valid for the target version
- **Depth-controllable** - `maxDepth` parameter controls SQL complexity from simple to arbitrarily nested
- **Fragment generation** - Generate not just full statements but individual expressions, clauses, and subqueries
- **FakerPHP integration** - Standard Faker provider pattern, works with seeded generators for reproducibility

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- [fakerphp/faker](https://github.com/FakerPHP/Faker) ^1.23

Installation
------------

[](#installation)

```
composer require --dev k-kinzal/sql-faker
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
use Faker\Factory;
use SqlFaker\MySqlProvider;

$faker = Factory::create();
$faker->addProvider(new MySqlProvider($faker));

// Generate random SQL statements
$faker->sql();              // Any valid MySQL statement
$faker->selectStatement();  // SELECT statement
$faker->insertStatement();  // INSERT statement
$faker->updateStatement();  // UPDATE statement
$faker->deleteStatement();  // DELETE statement
```

### Statement Types

[](#statement-types)

```
// DML
$faker->selectStatement();
$faker->insertStatement();
$faker->updateStatement();
$faker->deleteStatement();
$faker->replaceStatement();
$faker->truncateStatement();

// DDL
$faker->createTableStatement();
$faker->alterTableStatement();
$faker->dropTableStatement();
$faker->createIndexStatement();
$faker->dropIndexStatement();

// TCL
$faker->beginStatement();
$faker->commitStatement();
$faker->rollbackStatement();

// Any simple statement
$faker->simpleStatement();
```

### SQL Fragments

[](#sql-fragments)

Generate individual SQL components for targeted testing:

```
// Expressions
$faker->expr();           // Any expression
$faker->simpleExpr();     // Simple expression
$faker->literal();        // Literal value
$faker->predicate();      // Predicate (comparison)

// Clauses
$faker->whereClause();    // WHERE clause
$faker->orderClause();    // ORDER BY clause
$faker->limitClause();    // LIMIT clause

// Table references
$faker->tableReference();  // Table reference
$faker->joinedTable();     // Joined table expression
$faker->tableIdent();      // Table identifier

// Subqueries and CTEs
$faker->subquery();        // Subquery
$faker->withClause();      // CTE (WITH clause)
```

### Terminal Generators

[](#terminal-generators)

Generate individual lexical tokens:

```
$faker->identifier();              // e.g., "t1", "col42"
$faker->quotedIdentifier();        // e.g., "`my_table`"
$faker->stringLiteral();           // e.g., "'abc123'"
$faker->nationalStringLiteral();   // e.g., "N'abc'"
$faker->integerLiteral();          // e.g., "42"
$faker->longIntegerLiteral();      // e.g., "2147483647"
$faker->unsignedBigIntLiteral();   // e.g., "18446744073709551615"
$faker->decimalLiteral();          // e.g., "123.45"
$faker->floatLiteral();            // e.g., "1.23e10"
$faker->hexLiteral();              // e.g., "0xdeadbeef"
$faker->binaryLiteral();           // e.g., "0b1010"
```

### Controlling Complexity

[](#controlling-complexity)

Use `maxDepth` to control the complexity of generated SQL. Lower values produce simpler statements:

```
$faker->selectStatement(maxDepth: 3);   // Simple SELECT
$faker->selectStatement(maxDepth: 6);   // Moderate SELECT
$faker->selectStatement();              // Complex SELECT (unlimited depth)
```

The generator uses shortest-path termination: once the target depth is reached, it selects the shortest production alternative at each step to terminate quickly.

### Specifying MySQL Version

[](#specifying-mysql-version)

```
// Use specific MySQL version (default: mysql-8.4.7)
$faker->addProvider(new MySqlProvider($faker, 'mysql-5.7.44'));
```

Supported versions:

VersionTagMySQL 5.6`mysql-5.6.51`MySQL 5.7`mysql-5.7.44`MySQL 8.0`mysql-8.0.44`MySQL 8.1`mysql-8.1.0`MySQL 8.2`mysql-8.2.0`MySQL 8.3`mysql-8.3.0`MySQL 8.4`mysql-8.4.7` (default)MySQL 9.0`mysql-9.0.1`MySQL 9.1`mysql-9.1.0`### Reproducible Generation

[](#reproducible-generation)

Use a seeded Faker generator for reproducible SQL output:

```
$faker = Factory::create();
$faker->seed(12345);
$faker->addProvider(new MySqlProvider($faker));

// Same seed always produces the same SQL
$sql = $faker->selectStatement(maxDepth: 6);
```

How It Works
------------

[](#how-it-works)

SQL Faker implements formal grammar derivation (leftmost derivation):

1. **Grammar Loading** - Pre-compiled MySQL Bison grammar is loaded from serialized AST
2. **Derivation** - Starting from a non-terminal (e.g., `select_stmt`), the generator repeatedly replaces the leftmost non-terminal with a randomly chosen production alternative
3. **Depth Control** - Before `maxDepth`, alternatives are chosen randomly; at/after `maxDepth`, the shortest alternative is selected to terminate quickly
4. **Terminal Rendering** - Terminal symbols are rendered to SQL strings with proper spacing and syntax

```
select_stmt
  → SELECT select_item_list FROM table_reference
  → SELECT expr FROM table_ident
  → SELECT simple_expr FROM IDENT
  → SELECT NUM FROM IDENT
  → SELECT 42 FROM t1

```

Development
-----------

[](#development)

```
# Run tests
composer test

# Run linter (PHP-CS-Fixer + PHPStan level max)
composer lint

# Run fuzz tests
composer fuzz

# Build grammar AST from MySQL's sql_yacc.yy
composer build-mysql

# Fix code style
composer format
```

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance79

Regular maintenance activity

Popularity2

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 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

Every ~0 days

Total

2

Last Release

109d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4458a22db62c885006248e08715301bcb73e78c1057e2bbf686af001729165d5?d=identicon)[kinzal](/maintainers/kinzal)

---

Top Contributors

[![k-kinzal](https://avatars.githubusercontent.com/u/1281825?v=4)](https://github.com/k-kinzal "k-kinzal (2 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/k-kinzal-sql-faker/health.svg)

```
[![Health](https://phpackages.com/badges/k-kinzal-sql-faker/health.svg)](https://phpackages.com/packages/k-kinzal-sql-faker)
```

###  Alternatives

[verbb/formie

The most user-friendly forms plugin for Craft.

100387.6k57](/packages/verbb-formie)[solspace/craft-freeform

The most flexible and user-friendly form building plugin!

53675.5k15](/packages/solspace-craft-freeform)[blackfire/player

A powerful web crawler and web scraper with Blackfire support

49517.1k](/packages/blackfire-player)[directorytree/dummy

438.9k](/packages/directorytree-dummy)[beyondcode/laravel-masked-db-dump

Dump masked information from your database

11345.8k](/packages/beyondcode-laravel-masked-db-dump)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)