Database Compatibility Matrix
Supported relational databases and the Framework M features available on each.
0. Supported Databases
Framework M's standard SQL adapter supports the following relational databases:
| Database | Driver | Test Status |
|---|---|---|
| SQLite | aiosqlite | ✅ CI |
| PostgreSQL | asyncpg | ✅ CI |
| MySQL | aiomysql | ✅ CI |
| MariaDB | aiomysql | ✅ CI |
| Oracle | oracledb | ✅ CI |
| Microsoft SQL Server | aioodbc + ODBC Driver 18 | ✅ CI |
These are validated by the shared integration test suite on every merge request and default-branch commit.
1. Feature Matrix
| Feature | SQLite | PostgreSQL | MySQL | MariaDB | Oracle | MSSQL |
|---|---|---|---|---|---|---|
| DocType CRUD | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Unique constraints | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Child tables | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Link fields / fetch_from | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Filtering (all operators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Ordering | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Pagination (limit/offset) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Optimistic concurrency | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Exists / Count | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| JSON fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| UUID primary keys | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Soft delete | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Version history | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Full-text search | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Array columns | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Geospatial types | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Legend
- ✅ Supported and covered by CI.
- ❌ Not supported by the standard SQL adapter.
2. Known Dialect Quirks
These differences are handled automatically by the framework, but they are worth knowing when debugging or writing portable logic.
| Quirk | Databases Affected | Framework Handling |
|---|---|---|
Empty string equals NULL | Oracle | Persisted as NULL; retrieved as None. |
| Unbounded strings in unique indexes | MSSQL | Mapped to VARCHAR(255) by default. |
OFFSET/LIMIT requires ORDER BY | MSSQL | Default ordering by creation DESC, id ASC is applied. |
| UUID column type | MSSQL | Mapped to UNIQUEIDENTIFIER. |
| UUID column type | MySQL / MariaDB | Mapped to CHAR(36). |
| JSON column type | Oracle | Mapped to OracleJSON. |
| Case-insensitive string comparison | MySQL (default collation) | Filter behavior may differ from PostgreSQL. |
NULL ordering in ORDER BY ... ASC | MySQL / MariaDB | NULLs sort first by default; other databases sort them last. |
BOOLEAN type | MySQL / MariaDB / Oracle / MSSQL | Mapped to dialect-appropriate boolean or integer type. |
3. Choosing a Database
| Use Case | Recommended Database |
|---|---|
| Local development / tests | SQLite |
| Default production | PostgreSQL |
| Existing MySQL/MariaDB fleet | MySQL or MariaDB |
| Enterprise Oracle environment | Oracle |
| Existing Microsoft stack | MSSQL |
4. Non-Relational and Hybrid Data
For databases not listed above, use the MX Adapter Extension Pattern. This allows you to implement a custom repository adapter for document stores, graph databases, or external APIs while keeping the same DocType and controller layers.
See Build a Hybrid Database Adapter.