From fdb7e2895255989936f7b600f85b3f125d5d210a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Wed, 25 Feb 2026 09:41:59 +0100 Subject: [PATCH 1/7] Add Claude Code project settings Allow common development commands (composer scripts, phpunit, phpcs, phpcbf, parallel-lint, npm for WordPress test env) and relevant documentation domains (developer.wordpress.org, sqlite.org). Also gitignore .claude/settings.local.json for personal overrides. --- .claude/settings.json | 21 +++++++++++++++++++++ .gitignore | 1 + 2 files changed, 22 insertions(+) create mode 100644 .claude/settings.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..ee4d6d5e --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "allow": [ + "Bash(composer install *)", + "Bash(composer update *)", + "Bash(composer check-cs *)", + "Bash(composer fix-cs *)", + "Bash(composer test *)", + "Bash(composer wp-*)", + "Bash(vendor/bin/phpunit *)", + "Bash(vendor/bin/phpcs *)", + "Bash(vendor/bin/phpcbf *)", + "Bash(vendor/bin/parallel-lint *)", + "Bash(npm --prefix wordpress *)", + "Bash(npm --prefix tests/e2e *)", + "WebFetch(domain:developer.wordpress.org)", + "WebFetch(domain:www.sqlite.org)" + ] + } +} diff --git a/.gitignore b/.gitignore index 0de6379d..0947ee4b 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ composer.lock .DS_Store ._* /wordpress +/.claude/settings.local.json From a8e796ddec33d31c9f36caab5c1247aabb3e6abc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Wed, 25 Feb 2026 10:00:49 +0100 Subject: [PATCH 2/7] Add AGENTS.md and CLAUDE.md files --- AGENTS.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 162 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..41361c9f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,161 @@ + + +# AGENTS.md +This file provides guidance to AI coding agents when working with code in this repository. + +## Project overview +This project implements SQLite database support for MySQL-based projects. + +It is a monorepo that includes the following components: +- **MySQL lexer** — A fast MySQL lexer with multi-version support. +- **MySQL parser** — An exhaustive MySQL parser with multi-version support. +- **SQLite driver** — A MySQL emulation layer on top of SQLite with a PDO-compatible API. +- **MySQL proxy** — A MySQL binary protocol implementation to support MySQL-based projects beyond PHP. +- **WordPress plugin** — A plugin that adds SQLite support to WordPress. +- **Test suites** — A set of extensive test suites to cover MySQL syntax and functionality. + +The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5, MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer (with legacy mode down to 3.27.0). + +### New and old driver +At the moment, the project includes two MySQL-on-SQLite driver implementations: +1. A new, AST-based MySQL-on-SQLite driver (`class-wp-pdo-mysql-on-sqlite.php`). +2. A legacy, token-based MySQL-to-SQLite translator (`class-wp-sqlite-translator.php`). + +This state is temporary. The new driver will fully replace the legacy one. New features +must always be implemented in the new driver. The legacy driver can receive small fixes. +The new driver is under a `WP_SQLITE_AST_DRIVER` feature flag, but it is widely used. + +## Commands +The codebase is written in PHP and Composer is used to manage the project. +The following commands are useful for development and testing: + +```bash +composer install # Install dependencies +composer run check-cs # Check coding standards (PHPCS) +composer run fix-cs # Auto-fix coding standards (PHPCBF) + +# Tests +composer run test # Run unit tests +composer run test tests/SomeTest.php # Run specific unit test file +composer run test -- --filter testName # Run specific unit test class/method +composer run test-e2e # Run E2E tests (Playwright via WP env) + +# WordPress tests +composer run wp-setup # Set up WordPress with SQLite for tests +composer run wp-test-start # Start WordPress environment (Docker) +composer run wp-test-php # Run WordPress PHPUnit tests +composer run wp-test-e2e # Run WordPress E2E tests (Playwright) +composer run wp-test-clean # Clean up WordPress environment (Docker and DB) +``` + +## Architecture +The project consists of multiple components providing different APIs that funnel +into the SQLite driver to support diverse use cases both inside and outside the +PHP ecosystem. + +### Component overview +The following diagram shows how different types of applications can be supported +using components from this project: + +``` +Consumers: Components: + +PHP applications ─────────────────────────┐ +Adminer, phpMyAdmin │ + │ +WordPress + plugins │ +WordPress Playground ─────→ wpdb drop-in ─────┼────→ SQLite driver ────→ SQLite + (Studio, wp-env) │ (PDO API) (DB) + │ +MySQL CLI │ +Desktop clients ─────→ MySQL proxy ──────┘ +``` + +### Query processing pipeline +The following diagram illustrates how a MySQL query is processed and emulated: + +``` +MySQL query + ↓ string +Lexer + ↓ tokens +Parser + ↓ AST +Translation & Emulation ← INFORMATION_SCHEMA emulation + ↓ SQL +SQLite +``` + +## Principles +This project implements sophisticated emulation and complex APIs. Any changes and +new features must be carefully designed and planned, and their implementation +must fit into the project architecture. + +When working on changes to the project: +- **Analyze** the existing code and its architecture. +- **Design** changes in accordance with the existing architecture, if possible. +- **Modify** or extend the architecture with consideration when appropriate. +- **Plan** the implementation carefully so that the changes align with the project. +- **Implement** the changes following the planned design and architecture. +- **Test** all newly added logic using a test suite that is appropriate. +- **Verify** implemented changes. Review their architecture and its suitability. +- **Adjust** the implemented changes if needed to improve the implementation. +- **Simplify** the implemented changes when possible to keep them lean. + +Always aim to implement changes and solve problems fully and properly. Don't use +shortcuts and hacks. Never silence errors, linters, or tests to simplify the job. + +## Security +Security is critical to this project. The implementation must prevent all vulnerabilities +that could lead to data compromise or corruption. This includes: +- **Quoting and escaping:** Always use correct escaping and quoting that's appropriate + in a given context. Always correctly prevent SQL injection and other vulnerabilities. +- **Encoding:** Be diligent about encodings and the nuances between MySQL and SQLite. +- **Data integrity:** Always preserve data integrity to avoid data loss or corruption. + +Always scrutinize implemented logic for security vulnerabilities and verify any +assumptions. Never take shortcuts. + +## Compatibility +This project must support a range of PHP and SQLite versions, and it must evolve +the public APIs responsibly, following semantic versioning practices. + +In particular: +- **Public APIs:** It's possible to evolve the public API, but this must always be + surfaced to the developer so versioning decisions can be made. +- **PDO API:** The SQLite driver must follow PDO\MySQL API as closely as possible. +- **MySQL binary protocol:** The MySQL proxy must follow the MySQL binary protocol + as closely as possible. +- **PHP version support:** All PHP versions starting from **PHP 7.2** must be supported. + It is possible to use PHP version checks when needed. +- **SQLite version support:** All SQLite versions starting from **SQLite 3.37.0** must be + supported. Older versions (down to 3.27.0) have limited compatibility and require setting + `WP_SQLITE_UNSAFE_ENABLE_UNSUPPORTED_VERSIONS`. + +## Coding conventions +Follow these conventions when writing code in this project: +- **Coding style:** Use WordPress Coding Standards via PHPCS (`phpcs.xml.dist`). +- **Function ordering:** First caller, then callee. When function A calls function B, write first A, then B. +- **Method ordering:** First public, then protected, then private. Respect Function ordering as well. + +## Git +When creating commits, branches, and pull requests, use clear, concise, and +human-readable prose in plain English. + +### Commits +- Make commits readable for humans, not machines. +- Make subject of a commit message short but clear. +- Start with a verb, use present-tense, imperative form. +- Explain details in a commit body below, if needed. +- Include links in the body if the change relates to external sources, issues, PRs, or tickets. + +### Pull requests +- When creating a pull request, always follow the repository PR template. +- Pull request title must be brief and accurate. +- Pull request description must be clear, comprehensible, and well organized. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 31b7c8187bb501414938fbed78dc1265679f6d24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Wed, 25 Feb 2026 15:07:33 +0100 Subject: [PATCH 3/7] Add devcontainer configuration for development Add a root-level devcontainer for developing the SQLite driver and running all test suites. This is separate from the existing WordPress- specific devcontainer in wordpress/.devcontainer/. The configuration provides: - PHP 8.4 with pdo_sqlite extension - Composer (included in the base image) - Node.js 20 (for Playwright E2E tests) - Docker-in-Docker (for WordPress integration tests) --- .devcontainer/devcontainer.json | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..9db40ecd --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,13 @@ +{ + "name": "SQLite Database Integration", + "image": "mcr.microsoft.com/devcontainers/php:8.4", + "features": { + "ghcr.io/devcontainers/features/node:1": { + "version": "20" + }, + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "moby": false + } + }, + "postCreateCommand": "composer install" +} From df285125de8546102c3beb5f7222fcac4aece056 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Thu, 26 Feb 2026 09:38:02 +0100 Subject: [PATCH 4/7] Fix domain for sqlite.org --- .claude/settings.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/settings.json b/.claude/settings.json index ee4d6d5e..074e3b06 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -15,7 +15,7 @@ "Bash(npm --prefix wordpress *)", "Bash(npm --prefix tests/e2e *)", "WebFetch(domain:developer.wordpress.org)", - "WebFetch(domain:www.sqlite.org)" + "WebFetch(domain:sqlite.org)" ] } } From 7f082167f1d9e88efbabce8b35c48229cd006445 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Thu, 26 Feb 2026 09:35:54 +0100 Subject: [PATCH 5/7] Improve AGENTS.md - Add project name to the heading - Wrap long lines in the project overview paragraph - Add `composer run wp-run` to the commands list - Split the component overview into three separate diagrams --- AGENTS.md | 51 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 41361c9f..910d8160 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,7 @@ MAINTENANCE: Update this file when: - Adding new architectural patterns or conventions --> -# AGENTS.md -This file provides guidance to AI coding agents when working with code in this repository. +# AGENTS.md - SQLite Database Integration ## Project overview This project implements SQLite database support for MySQL-based projects. @@ -20,7 +19,9 @@ It is a monorepo that includes the following components: - **WordPress plugin** — A plugin that adds SQLite support to WordPress. - **Test suites** — A set of extensive test suites to cover MySQL syntax and functionality. -The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5, MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer (with legacy mode down to 3.27.0). +The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5, +MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer +(with legacy mode down to 3.27.0). ### New and old driver At the moment, the project includes two MySQL-on-SQLite driver implementations: @@ -48,6 +49,7 @@ composer run test-e2e # Run E2E tests (Playwright via WP env) # WordPress tests composer run wp-setup # Set up WordPress with SQLite for tests +composer run wp-run # Run a WordPress repository command composer run wp-test-start # Start WordPress environment (Docker) composer run wp-test-php # Run WordPress PHPUnit tests composer run wp-test-e2e # Run WordPress E2E tests (Playwright) @@ -60,21 +62,38 @@ into the SQLite driver to support diverse use cases both inside and outside the PHP ecosystem. ### Component overview -The following diagram shows how different types of applications can be supported -using components from this project: +The following diagrams show how different types of applications can be supported +using components from this project. +**PHP applications** are supported through a PDO\MySQL-compatible API: ``` -Consumers: Components: - -PHP applications ─────────────────────────┐ -Adminer, phpMyAdmin │ - │ -WordPress + plugins │ -WordPress Playground ─────→ wpdb drop-in ─────┼────→ SQLite driver ────→ SQLite - (Studio, wp-env) │ (PDO API) (DB) - │ -MySQL CLI │ -Desktop clients ─────→ MySQL proxy ──────┘ +PHP applications, Adminer, phpMyAdmin + ↓ PDO\MySQL API +SQLite driver + ↓ PDO\SQLite +SQLite +``` + +**WordPress** projects are powered by a `wpdb` compatible drop-in: +``` +WordPress + plugins, WordPress Playground, WordPress Studio, wp-env + ↓ wpdb +wpdb drop-in + ↓ PDO\MySQL API +SQLite driver + ↓ PDO\SQLite +SQLite +``` + +**Other applications** can be run using the MySQL proxy: +``` +MySQL CLI, Desktop clients + ↓ MySQL binary protocol v10 +MySQL proxy + ↓ PDO\MySQL API +SQLite driver + ↓ PDO\SQLite +SQLite ``` ### Query processing pipeline From c7a0d9ace11306ca15df7429c0fc40beddce6aa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Thu, 26 Feb 2026 10:48:24 +0100 Subject: [PATCH 6/7] Add README.md with human-readable diagrams --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..2312a095 --- /dev/null +++ b/README.md @@ -0,0 +1,84 @@ + + +# SQLite database integration +This project implements SQLite database support for MySQL-based projects. + +It is a monorepo that includes the following components: +- **MySQL lexer** — A fast MySQL lexer with multi-version support. +- **MySQL parser** — An exhaustive MySQL parser with multi-version support. +- **SQLite driver** — A MySQL emulation layer on top of SQLite with a PDO-compatible API. +- **MySQL proxy** — A MySQL binary protocol implementation to support MySQL-based projects beyond PHP. +- **WordPress plugin** — A plugin that adds SQLite support to WordPress. +- **Test suites** — A set of extensive test suites to cover MySQL syntax and functionality. + +The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5, +MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer +(with legacy mode down to 3.27.0). + +## Quick start +The codebase is written in PHP and Composer is used to manage the project. +The following commands are useful for development and testing: + +```bash +composer install # Install dependencies +composer run check-cs # Check coding standards (PHPCS) +composer run fix-cs # Auto-fix coding standards (PHPCBF) + +# Tests +composer run test # Run unit tests +composer run test tests/SomeTest.php # Run specific unit test file +composer run test -- --filter testName # Run specific unit test class/method +composer run test-e2e # Run E2E tests (Playwright via WP env) + +# WordPress tests +composer run wp-setup # Set up WordPress with SQLite for tests +composer run wp-run # Run a WordPress repository command +composer run wp-test-start # Start WordPress environment (Docker) +composer run wp-test-php # Run WordPress PHPUnit tests +composer run wp-test-e2e # Run WordPress E2E tests (Playwright) +composer run wp-test-clean # Clean up WordPress environment (Docker and DB) +``` + +## Architecture +The project consists of multiple components providing different APIs that funnel +into the SQLite driver to support diverse use cases both inside and outside the +PHP ecosystem. + +### Component overview +The following diagrams show how different types of applications can be supported +using components from this project: + +``` +┌──────────────────────┐ +│ PHP applications │ +│ Adminer, phpMyAdmin │──────────────────────────┐ +└──────────────────────┘ │ + │ +┌──────────────────────┐ wpdb API │ PDO\MySQL API PDO\SQLite +│ WordPress + plugins │ │ ╔══════════════╗ │ │ ╔═══════════════╗ │ ┌────────┐ +│ WordPress Playground │───┴──→║ wpdb drop-in ║───┼───┴──→║ SQLite driver ║───┴──→│ SQLite │ +│ Studio, wp-env │ ╚══════════════╝ │ ╚═══════════════╝ └────────┘ +└──────────────────────┘ │ + MySQL binary protocol │ +┌──────────────────────┐ │ ╔══════════════╗ │ +│ MySQL CLI │───┴──→║ MySQL proxy ║───┘ +│ Desktop clients │ ╚══════════════╝ +└──────────────────────┘ +``` + +### Query processing pipeline +The following diagram illustrates how a MySQL query is processed and emulated: + +``` + string tokens AST ╔═════════════╗ SQL +┌─────────────┐ │ ╔═══════╗ │ ╔════════╗ │ ║ Translation ║ │ ┌────────┐ +│ MySQL query │──┴─→║ Lexer ║──┴─→║ Parser ║──┴─→║ & ║──┴─→│ SQLite │ +└─────────────┘ ╚═══════╝ ╚════════╝ ║ Emulation ║ └────────┘ + ╚═════════════╝ +``` From 64c787cc152ac610ef4949501a1e59b8713304b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Jake=C5=A1?= Date: Thu, 26 Feb 2026 11:11:58 +0100 Subject: [PATCH 7/7] Enable "composer run" syntax for Composer scripts --- .claude/settings.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/settings.json b/.claude/settings.json index 074e3b06..ab30017e 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -4,6 +4,7 @@ "allow": [ "Bash(composer install *)", "Bash(composer update *)", + "Bash(composer run *)", "Bash(composer check-cs *)", "Bash(composer fix-cs *)", "Bash(composer test *)",