sqlite-database-integration / README.md

README.md in SQLite Database Integration 2.2.18, at README.md

85 lines 4.9 KB

Raw Download Zip

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	# SQLite database integration
10	This project implements SQLite database support for MySQL-based projects.
11
12	It is a monorepo that includes the following components:
13	- MySQL lexer — A fast MySQL lexer with multi-version support.
14	- MySQL parser — An exhaustive MySQL parser with multi-version support.
15	- SQLite driver — A MySQL emulation layer on top of SQLite with a PDO-compatible API.
16	- MySQL proxy — A MySQL binary protocol implementation to support MySQL-based projects beyond PHP.
17	- WordPress plugin — A plugin that adds SQLite support to WordPress.
18	- Test suites — A set of extensive test suites to cover MySQL syntax and functionality.
19
20	The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5,
21	MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer
22	(with legacy mode down to 3.27.0).
23
24	## Quick start
25	The codebase is written in PHP and Composer is used to manage the project.
26	The following commands are useful for development and testing:
27
28	```bash
29	composer install # Install dependencies
30	composer run check-cs # Check coding standards (PHPCS)
31	composer run fix-cs # Auto-fix coding standards (PHPCBF)
32
33	# Tests
34	composer run test # Run unit tests
35	composer run test tests/SomeTest.php # Run specific unit test file
36	composer run test -- --filter testName # Run specific unit test class/method
37	composer run test-e2e # Run E2E tests (Playwright via WP env)
38
39	# WordPress tests
40	composer run wp-setup # Set up WordPress with SQLite for tests
41	composer run wp-run # Run a WordPress repository command
42	composer run wp-test-start # Start WordPress environment (Docker)
43	composer run wp-test-php # Run WordPress PHPUnit tests
44	composer run wp-test-e2e # Run WordPress E2E tests (Playwright)
45	composer run wp-test-clean # Clean up WordPress environment (Docker and DB)
46	```
47
48	## Architecture
49	The project consists of multiple components providing different APIs that funnel
50	into the SQLite driver to support diverse use cases both inside and outside the
51	PHP ecosystem.
52
53	### Component overview
54	The following diagrams show how different types of applications can be supported
55	using components from this project:
56
57	```
58	┌──────────────────────┐
59	│ PHP applications │
60	│ Adminer, phpMyAdmin │──────────────────────────┐
61	└──────────────────────┘ │
62	│
63	┌──────────────────────┐ wpdb API │ PDO\MySQL API PDO\SQLite
64	│ WordPress + plugins │ │ ╔══════════════╗ │ │ ╔═══════════════╗ │ ┌────────┐
65	│ WordPress Playground │───┴──→║ wpdb drop-in ║───┼───┴──→║ SQLite driver ║───┴──→│ SQLite │
66	│ Studio, wp-env │ ╚══════════════╝ │ ╚═══════════════╝ └────────┘
67	└──────────────────────┘ │
68	MySQL binary protocol │
69	┌──────────────────────┐ │ ╔══════════════╗ │
70	│ MySQL CLI │───┴──→║ MySQL proxy ║───┘
71	│ Desktop clients │ ╚══════════════╝
72	└──────────────────────┘
73	```
74
75	### Query processing pipeline
76	The following diagram illustrates how a MySQL query is processed and emulated:
77
78	```
79	string tokens AST ╔═════════════╗ SQL
80	┌─────────────┐ │ ╔═══════╗ │ ╔════════╗ │ ║ Translation ║ │ ┌────────┐
81	│ MySQL query │──┴─→║ Lexer ║──┴─→║ Parser ║──┴─→║ & ║──┴─→│ SQLite │
82	└─────────────┘ ╚═══════╝ ╚════════╝ ║ Emulation ║ └────────┘
83	╚═════════════╝
84	```
85