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(2mo ago)003MITPHPPHP ^8.1

Since Mar 6Pushed 2mo 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 1mo ago

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

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

35

—

LowBetter than 79% of packages

Maintenance94

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity33

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

64d 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.

101372.9k40](/packages/verbb-formie)[blair2004/nexopos

The Free Modern Point Of Sale System build with Laravel, TailwindCSS and Vue.js.

1.2k2.3k](/packages/blair2004-nexopos)[solspace/craft-freeform

The most flexible and user-friendly form building plugin!

52664.9k12](/packages/solspace-craft-freeform)[mmo/faker-images

Different images provider for Faker

59370.3k6](/packages/mmo-faker-images)[aedart/athenaeum

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

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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