|
| 1 | +<!-- |
| 2 | +MAINTENANCE: Update this file when: |
| 3 | +- Adding/removing composer scripts |
| 4 | +- Changing the directory structure (new modules, major refactors) |
| 5 | +- Modifying build/test workflows |
| 6 | +- Adding new architectural patterns or conventions |
| 7 | +--> |
| 8 | + |
| 9 | +# AGENTS.md - SQLite Database Integration |
| 10 | + |
| 11 | +## Project overview |
| 12 | +This project implements SQLite database support for MySQL-based projects. |
| 13 | + |
| 14 | +It is a monorepo that includes the following components: |
| 15 | +- **MySQL lexer** — A fast MySQL lexer with multi-version support. |
| 16 | +- **MySQL parser** — An exhaustive MySQL parser with multi-version support. |
| 17 | +- **SQLite driver** — A MySQL emulation layer on top of SQLite with a PDO-compatible API. |
| 18 | +- **MySQL proxy** — A MySQL binary protocol implementation to support MySQL-based projects beyond PHP. |
| 19 | +- **WordPress plugin** — A plugin that adds SQLite support to WordPress. |
| 20 | +- **Test suites** — A set of extensive test suites to cover MySQL syntax and functionality. |
| 21 | + |
| 22 | +The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5, |
| 23 | +MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer |
| 24 | +(with legacy mode down to 3.27.0). |
| 25 | + |
| 26 | +### New and old driver |
| 27 | +At the moment, the project includes two MySQL-on-SQLite driver implementations: |
| 28 | +1. A new, AST-based MySQL-on-SQLite driver (`class-wp-pdo-mysql-on-sqlite.php`). |
| 29 | +2. A legacy, token-based MySQL-to-SQLite translator (`class-wp-sqlite-translator.php`). |
| 30 | + |
| 31 | +This state is temporary. The new driver will fully replace the legacy one. New features |
| 32 | +must always be implemented in the new driver. The legacy driver can receive small fixes. |
| 33 | +The new driver is under a `WP_SQLITE_AST_DRIVER` feature flag, but it is widely used. |
| 34 | + |
| 35 | +## Commands |
| 36 | +The codebase is written in PHP and Composer is used to manage the project. |
| 37 | +The following commands are useful for development and testing: |
| 38 | + |
| 39 | +```bash |
| 40 | +composer install # Install dependencies |
| 41 | +composer run check-cs # Check coding standards (PHPCS) |
| 42 | +composer run fix-cs # Auto-fix coding standards (PHPCBF) |
| 43 | + |
| 44 | +# Tests |
| 45 | +composer run test # Run unit tests |
| 46 | +composer run test tests/SomeTest.php # Run specific unit test file |
| 47 | +composer run test -- --filter testName # Run specific unit test class/method |
| 48 | +composer run test-e2e # Run E2E tests (Playwright via WP env) |
| 49 | + |
| 50 | +# WordPress tests |
| 51 | +composer run wp-setup # Set up WordPress with SQLite for tests |
| 52 | +composer run wp-run # Run a WordPress repository command |
| 53 | +composer run wp-test-start # Start WordPress environment (Docker) |
| 54 | +composer run wp-test-php # Run WordPress PHPUnit tests |
| 55 | +composer run wp-test-e2e # Run WordPress E2E tests (Playwright) |
| 56 | +composer run wp-test-clean # Clean up WordPress environment (Docker and DB) |
| 57 | +``` |
| 58 | + |
| 59 | +## Architecture |
| 60 | +The project consists of multiple components providing different APIs that funnel |
| 61 | +into the SQLite driver to support diverse use cases both inside and outside the |
| 62 | +PHP ecosystem. |
| 63 | + |
| 64 | +### Component overview |
| 65 | +The following diagrams show how different types of applications can be supported |
| 66 | +using components from this project. |
| 67 | + |
| 68 | +**PHP applications** are supported through a PDO\MySQL-compatible API: |
| 69 | +``` |
| 70 | +PHP applications, Adminer, phpMyAdmin |
| 71 | + ↓ PDO\MySQL API |
| 72 | +SQLite driver |
| 73 | + ↓ PDO\SQLite |
| 74 | +SQLite |
| 75 | +``` |
| 76 | + |
| 77 | +**WordPress** projects are powered by a `wpdb` compatible drop-in: |
| 78 | +``` |
| 79 | +WordPress + plugins, WordPress Playground, WordPress Studio, wp-env |
| 80 | + ↓ wpdb |
| 81 | +wpdb drop-in |
| 82 | + ↓ PDO\MySQL API |
| 83 | +SQLite driver |
| 84 | + ↓ PDO\SQLite |
| 85 | +SQLite |
| 86 | +``` |
| 87 | + |
| 88 | +**Other applications** can be run using the MySQL proxy: |
| 89 | +``` |
| 90 | +MySQL CLI, Desktop clients |
| 91 | + ↓ MySQL binary protocol v10 |
| 92 | +MySQL proxy |
| 93 | + ↓ PDO\MySQL API |
| 94 | +SQLite driver |
| 95 | + ↓ PDO\SQLite |
| 96 | +SQLite |
| 97 | +``` |
| 98 | + |
| 99 | +### Query processing pipeline |
| 100 | +The following diagram illustrates how a MySQL query is processed and emulated: |
| 101 | + |
| 102 | +``` |
| 103 | +MySQL query |
| 104 | + ↓ string |
| 105 | +Lexer |
| 106 | + ↓ tokens |
| 107 | +Parser |
| 108 | + ↓ AST |
| 109 | +Translation & Emulation ← INFORMATION_SCHEMA emulation |
| 110 | + ↓ SQL |
| 111 | +SQLite |
| 112 | +``` |
| 113 | + |
| 114 | +## Principles |
| 115 | +This project implements sophisticated emulation and complex APIs. Any changes and |
| 116 | +new features must be carefully designed and planned, and their implementation |
| 117 | +must fit into the project architecture. |
| 118 | + |
| 119 | +When working on changes to the project: |
| 120 | +- **Analyze** the existing code and its architecture. |
| 121 | +- **Design** changes in accordance with the existing architecture, if possible. |
| 122 | +- **Modify** or extend the architecture with consideration when appropriate. |
| 123 | +- **Plan** the implementation carefully so that the changes align with the project. |
| 124 | +- **Implement** the changes following the planned design and architecture. |
| 125 | +- **Test** all newly added logic using a test suite that is appropriate. |
| 126 | +- **Verify** implemented changes. Review their architecture and its suitability. |
| 127 | +- **Adjust** the implemented changes if needed to improve the implementation. |
| 128 | +- **Simplify** the implemented changes when possible to keep them lean. |
| 129 | + |
| 130 | +Always aim to implement changes and solve problems fully and properly. Don't use |
| 131 | +shortcuts and hacks. Never silence errors, linters, or tests to simplify the job. |
| 132 | + |
| 133 | +## Security |
| 134 | +Security is critical to this project. The implementation must prevent all vulnerabilities |
| 135 | +that could lead to data compromise or corruption. This includes: |
| 136 | +- **Quoting and escaping:** Always use correct escaping and quoting that's appropriate |
| 137 | + in a given context. Always correctly prevent SQL injection and other vulnerabilities. |
| 138 | +- **Encoding:** Be diligent about encodings and the nuances between MySQL and SQLite. |
| 139 | +- **Data integrity:** Always preserve data integrity to avoid data loss or corruption. |
| 140 | + |
| 141 | +Always scrutinize implemented logic for security vulnerabilities and verify any |
| 142 | +assumptions. Never take shortcuts. |
| 143 | + |
| 144 | +## Compatibility |
| 145 | +This project must support a range of PHP and SQLite versions, and it must evolve |
| 146 | +the public APIs responsibly, following semantic versioning practices. |
| 147 | + |
| 148 | +In particular: |
| 149 | +- **Public APIs:** It's possible to evolve the public API, but this must always be |
| 150 | + surfaced to the developer so versioning decisions can be made. |
| 151 | +- **PDO API:** The SQLite driver must follow PDO\MySQL API as closely as possible. |
| 152 | +- **MySQL binary protocol:** The MySQL proxy must follow the MySQL binary protocol |
| 153 | + as closely as possible. |
| 154 | +- **PHP version support:** All PHP versions starting from **PHP 7.2** must be supported. |
| 155 | + It is possible to use PHP version checks when needed. |
| 156 | +- **SQLite version support:** All SQLite versions starting from **SQLite 3.37.0** must be |
| 157 | + supported. Older versions (down to 3.27.0) have limited compatibility and require setting |
| 158 | + `WP_SQLITE_UNSAFE_ENABLE_UNSUPPORTED_VERSIONS`. |
| 159 | + |
| 160 | +## Coding conventions |
| 161 | +Follow these conventions when writing code in this project: |
| 162 | +- **Coding style:** Use WordPress Coding Standards via PHPCS (`phpcs.xml.dist`). |
| 163 | +- **Function ordering:** First caller, then callee. When function A calls function B, write first A, then B. |
| 164 | +- **Method ordering:** First public, then protected, then private. Respect Function ordering as well. |
| 165 | + |
| 166 | +## Git |
| 167 | +When creating commits, branches, and pull requests, use clear, concise, and |
| 168 | +human-readable prose in plain English. |
| 169 | + |
| 170 | +### Commits |
| 171 | +- Make commits readable for humans, not machines. |
| 172 | +- Make subject of a commit message short but clear. |
| 173 | +- Start with a verb, use present-tense, imperative form. |
| 174 | +- Explain details in a commit body below, if needed. |
| 175 | +- Include links in the body if the change relates to external sources, issues, PRs, or tickets. |
| 176 | + |
| 177 | +### Pull requests |
| 178 | +- When creating a pull request, always follow the repository PR template. |
| 179 | +- Pull request title must be brief and accurate. |
| 180 | +- Pull request description must be clear, comprehensible, and well organized. |
0 commit comments