{"id":51638251,"url":"https://github.com/interdev7/phorm","last_synced_at":"2026-07-17T13:01:15.179Z","repository":{"id":354607540,"uuid":"1170100449","full_name":"interdev7/phorm","owner":"interdev7","description":"A lightweight, type-safe, driver-agnostic ORM for Dart and Flutter with zero N+1 overhead","archived":false,"fork":false,"pushed_at":"2026-07-13T06:29:09.000Z","size":27140,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-13T17:21:48.914Z","etag":null,"topics":["code-generation","dart","dart-package","database","flutter","flutter-package","orm","reactive","sql","sqlite","type-safe","wasm"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interdev7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T17:45:36.000Z","updated_at":"2026-07-13T06:26:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/interdev7/phorm","commit_stats":null,"previous_names":["interdev7/sqflow","interdev7/phorm"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/interdev7/phorm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interdev7%2Fphorm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interdev7%2Fphorm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interdev7%2Fphorm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interdev7%2Fphorm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interdev7","download_url":"https://codeload.github.com/interdev7/phorm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interdev7%2Fphorm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35582007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","dart","dart-package","database","flutter","flutter-package","orm","reactive","sql","sqlite","type-safe","wasm"],"created_at":"2026-07-13T17:01:13.475Z","updated_at":"2026-07-17T13:01:15.157Z","avatar_url":"https://github.com/interdev7.png","language":"Dart","funding_links":["https://ko-fi.com/T6T71WI3NN"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/logo/phorm.png\" alt=\"phorm\" height=350/\u003e\n\n  \u003cbr/\u003e\n\n[![pub.dev](https://img.shields.io/pub/v/phorm.svg?label=phorm\u0026logo=dart)](https://pub.dev/packages/phorm)\n[![pub.dev](https://img.shields.io/pub/v/phorm_sqlite.svg?label=phorm_sqlite\u0026logo=dart)](https://pub.dev/packages/phorm_sqlite)\n[![pub.dev](https://img.shields.io/pub/v/phorm_generator.svg?label=phorm_generator\u0026logo=dart)](https://pub.dev/packages/phorm_generator)\n[![pub.dev](https://img.shields.io/pub/v/phorm_annotations.svg?label=phorm_annotations\u0026logo=dart)](https://pub.dev/packages/phorm_annotations)\n[![VS Code Extension](https://badgen.net/vs-marketplace/v/interlibdev.phorm-code?label=VS%20Code\u0026icon=visualstudio\u0026color=007acc)](https://marketplace.visualstudio.com/items?itemName=interlibdev.phorm-code)\n[![Open VSX](https://img.shields.io/open-vsx/v/interlibdev/phorm-code?label=Open%20VSX\u0026logo=eclipse-ide)](https://open-vsx.org/extension/interlibdev/phorm-code)\n[![Build Status](https://github.com/interdev7/phorm/actions/workflows/main.yml/badge.svg)](https://github.com/interdev7/phorm/actions)\n[![codecov](https://codecov.io/gh/interdev7/phorm/branch/main/graph/badge.svg)](https://codecov.io/gh/interdev7/phorm)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Dart SDK](https://img.shields.io/badge/Dart-%3E%3D3.5.0-blue?logo=dart)](https://dart.dev)\n[![Flutter](https://img.shields.io/badge/Flutter-compatible-54C5F8?logo=flutter)](https://flutter.dev)\n[![PubStats Popularity](https://pubstats.dev/badges/packages/phorm_sqlite/popularity.svg)](https://pubstats.dev/packages/phorm_sqlite/popularity.svg)\n\n\u003c/div\u003e\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/T6T71WI3NN)\n\n# PHORM (***P***redictable ***H***armonious **_ORM_**)\n\nA lightweight, type-safe, driver-agnostic ORM for Dart and Flutter.\n\n**PHORM** is designed from the ground up to be database-independent. It separates query building and relationship mapping from database-specific SQL grammar using a pluggable **Dialect system**. This allows using the same declarative models and generated service APIs across multiple SQL backends, starting with SQLite (via `phorm_sqlite`) and expanding to PostgreSQL, MySQL and more in the future.\n\nBy leveraging **Single-Query JSON Aggregation**, PHORM aggregates complex parent-child relationship trees into a **single, highly-optimized SQL query** using database-native JSON capabilities (such as SQLite's `json_group_array` or PostgreSQL's `jsonb_agg`), offering stellar performance and zero N+1 query overhead.\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/diagrams/diagram_1.png\" alt=\"Phorm Architecture\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Packages\n\n| Package                                           | Install?              | Description                                                                            |\n| :------------------------------------------------ | :-------------------- | :------------------------------------------------------------------------------------- |\n| [phorm_sqlite](./packages/phorm_sqlite)           | ✅ `dependencies`     | SQLite driver — includes full phorm core, use this for all SQLite projects             |\n| [phorm_generator](./packages/phorm_generator)     | ✅ `dev_dependencies` | Code generator — SQL schemas, `toJson`/`fromJson`, static service mixins               |\n| [phorm](./packages/phorm)                         | ⚙️ driver authors     | Core engine only — CRUD, WhereBuilder, Transactions; already included via phorm_sqlite |\n| [phorm_annotations](./packages/phorm_annotations) | ⚙️ driver authors     | Annotation library — `@Schema`, `@Column`, `@ID`; already included via phorm           |\n\n---\n\n## Tooling\n\n| Tool                                                                                                                   | Description                                                                                                                                                                                                                                            |\n| :--------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [PHORM Code Generator](https://marketplace.visualstudio.com/items?itemName=interlibdev.phorm-code) (VS Code extension) | Convert a plain Dart class into a PHORM model in one click — adds `@Schema`/`@Column`/`@ID`, the `id` field, constructor and `fromJson`. Also ships snippets and a `build_runner` command. Source: [`extensions/phorm-code`](./extensions/phorm-code). |\n\nInstall it from the VS Code Marketplace (search **\"PHORM Code Generator\"**) or run:\n\n```\ncode --install-extension interlibdev.phorm-code\n```\n\n---\n\n## Motivation 🎯\n\nPHORM was created to solve three main problems in Flutter database management:\n\n1. **Type Safety over Strings**: Most SQLite wrappers rely on `Map\u003cString, dynamic\u003e`. PHORM generates type-safe columns and models, catching errors at compile-time rather than runtime.\n2. **Active Record DX**: Instead of managing complex DAO/Repository layers, PHORM provides a clean, declarative API directly on your models (`Users.insert()`, `Users.where(...)`).\n3. **Performance \u0026 Relationships**: Fetching complex graphs (Many-to-Many, HasMany) usually leads to N+1 query problems. PHORM uses JSON aggregation to resolve entire dependency trees in a **single SQL query**.\n\n---\n\n## Installation\n\nFor most projects, you only need **two packages**:\n\n```yaml\ndependencies:\n  phorm_sqlite: ^1.0.0 # SQLite driver — automatically includes phorm core\n\ndev_dependencies:\n  phorm_generator: ^1.0.0 # Code generation (SQL schemas, toJson/fromJson)\n  build_runner: ^2.4.0\n```\n\n\u003e `phorm_sqlite` re-exports the entire `phorm` core, so a separate `phorm:` dependency is **not needed**.\n\u003e\n\u003e Add `phorm` directly only if you are building a **custom database driver** (e.g. `phorm_postgres`).\n\n---\n\n## Quick Start\n\n```dart\n// One import covers everything: PhormCore, WhereBuilder, DB, Table, etc.\nimport 'package:phorm_sqlite/phorm_sqlite.dart';\n\n// 1. Table config (auto-generated by phorm_generator)\nfinal usersTable = Table\u003cUser\u003e(...);\n\n// 2. DB manager\nfinal appDb = DB.autoVersion(\n  databaseName: 'app.db',\n  tables: [usersTable],\n);\n\n// 3. Recommended: static service API on your model\nawait Users.insert(user);\nfinal user = await Users.readOne('id123');\n\n// 4. Fluent queries\nfinal adults = await Users\n    .where(UserTable.age.gt(18))\n    .orderBy(UserTable.name)                        // ASC\n    .orderBy(UserTable.createdAt, descending: true) // DESC\n    .get();\n\n// 5. Direct PhormCore access (for advanced use / transactions)\nfinal svc = appDb.service\u003cUser\u003e();\nfinal paged = await svc.readAllWithCount(limit: 20);\n\n// 6. Transactions\nawait appDb.transaction((txn) async {\n  await svc.insert(newUser, executor: txn);\n  await Posts.insertBatch(posts, executor: txn);\n});\n```\n\n---\n\n## Key Features\n\n- **🚀 Performance** — Load complex relationships in **exactly one** SQL query via JSON aggregation\n- **🛡️ Type Safety** — No `dynamic` maps in queries; compile-safe `Includable.model\u003cT\u003e()`\n- **🔍 Fluent API** — `WhereBuilder` and `SortBuilder` with full SQL injection protection\n- **🔗 Cross-table Filtering** — Filter by related table columns with automatic `LEFT JOIN`\n- **🗑️ Soft Deletes** — Built-in paranoid mode with restore support\n- **📦 Batch \u0026 Transactions** — Atomic bulk operations\n- **🔄 Smart Migrations** — Versioned, idempotent migration tracking\n- **🌐 Flutter Web** — WebAssembly (WASM) backend with IndexedDB persistence, zero code changes\n\n---\n\n## Benchmarks 🏁\n\nMeasured against [drift](https://pub.dev/packages/drift) and raw `sqlite3`\n(Apple M3, median of 5 runs; `drift-bg` = drift over its background isolate —\nthe apples-to-apples config, since PHORM **always** keeps SQLite off the UI\nthread):\n\n| Scenario                       | PHORM      | drift | drift-bg | raw sqlite3 |\n| :----------------------------- | ---------: | ----: | -------: | ----------: |\n| insert 5k rows (single txn)    | **6.6ms**  |  13ms |     12ms |         3ms |\n| load 500 parents × 10 children | **4.2ms**  |  12ms |     12ms |         4ms |\n| read + map 5k rows             | 5.5ms      |   4ms |      5ms |         2ms |\n| filtered read (~1/6 of 5k)     | 1.0ms      | 0.7ms |    1.1ms |       0.3ms |\n\nRelationship trees load at **near-raw speed** thanks to Single-Query JSON\nAggregation (one indexed query — no N+1, no join-row duplication crossing the\nisolate). Full methodology and a runnable harness: [`benchmarks/`](./benchmarks).\n\n---\n\n## CRUD Methods\n\n| Method                  | Returns                      | Description               |\n| :---------------------- | :--------------------------- | :------------------------ |\n| `insert(item)`          | `Future\u003cint\u003e`                | Row ID                    |\n| `update(item)`          | `Future\u003cint\u003e`                | Affected rows             |\n| `upsert(item)`          | `Future\u003cvoid\u003e`               | Insert or replace         |\n| `readOne(id)`           | `Future\u003cT?\u003e`                 | By primary key            |\n| `readAll(...)`          | `Future\u003cResult\u003cT\u003e\u003e`          | Paginated list            |\n| `readAllWithCount(...)` | `Future\u003cResultWithCount\u003cT\u003e\u003e` | List + total count        |\n| `delete(id)`            | `Future\u003cint\u003e`                | Soft or hard delete       |\n| `restore(id)`           | `Future\u003cint\u003e`                | Un-delete (paranoid only) |\n| `exists(id)`            | `Future\u003cbool\u003e`               | Check presence            |\n| `transaction(fn)`       | `Future\u003cR\u003e`                  | Raw transaction           |\n\n---\n\n## WhereBuilder Highlights\n\n```dart\nUsers.where(Users.status.eq('active'))\n  .where(Users.age.gt(18))\n  .where(Users.name.like('%John%'))\n  .get();\n\n// Manual WhereBuilder still works\nWhereBuilder().eq(Users.status, 'active').gt(Users.age, 18);\n```\n\n---\n\n## Documentation\n\nFull documentation is in the [`docs/`](./docs) folder:\n\n| File                                                                  | Contents                                                          |\n| :-------------------------------------------------------------------- | :---------------------------------------------------------------- |\n| [01. Overview](./docs/01-overview.md)                                 | Architecture, why PHORM, package structure                        |\n| [02. Schema Definition](./docs/02-schema-definition.md)               | `@Schema`, `@Column`, `@ID`, data types, indexes, CHECK           |\n| [03. Where Builder](./docs/03-where-builder.md)                       | All WhereBuilder methods, groups, cross-table filtering, pitfalls |\n| [04. CRUD Operations](./docs/04-crud-operations.md)                   | Insert, Read, Update, Delete, Batch, Transactions, Attributes     |\n| [05. Relationships](./docs/05-relationships.md)                       | HasMany, HasOne, BelongsTo, Includable API, fromJson patterns     |\n| [06. DB and Migrations](./docs/06-db-and-migrations.md)               | DB manager, MigrationBuilder, version lifecycle                   |\n| [07. Code Generation](./docs/07-code-generation.md)                   | Generator setup, commands, generated code anatomy                 |\n| [08. Soft Deletes](./docs/08-soft-deletes.md)                         | Paranoid mode, restore, hard delete                               |\n| [09. Pitfalls and Limitations](./docs/09-pitfalls-and-limitations.md) | Known issues, gotchas, design trade-offs                          |\n| [10. Validators](./docs/10-validators.md)                             | Built-in validators (NotEmpty, Email, Range, etc.)                |\n| [11. Many to Many](./docs/11-many-to-many.md)                         | Detailed guide on pivot tables and Many-to-Many setup             |\n| [12. Query Builder](./docs/12-query-builder.md)                       | Fluent API reference — .get(), .first(), chaining                 |\n| [13. Seeders and Factories](./docs/13-seeders-and-factories.md)       | Data seeding and mock generation for testing                      |\n| [14. Reactivity](./docs/14-reactivity.md)                             | Reactive streams, watchOne(), watchAll(), updatesSync integration |\n| [15. Flutter Web](./docs/15-flutter-web.md)                           | **Flutter Web / WASM** — setup, IndexedDB persistence, limits     |\n\n---\n\n## Contributing\n\nThis monorepo is managed with [Melos](https://melos.invertase.dev). To get started:\n\n```bash\ndart pub global activate melos\nmelos bootstrap   # link local packages and fetch dependencies\nmelos run test    # run tests in every package\nmelos run analyze # static analysis in every package\nmelos run format  # verify formatting\n```\n\nReleasing: run `melos run release-check` — it verifies that every package's\npubspec version, CHANGELOG and pub.dev state are consistent, and prints the\npublish commands for pending releases in dependency order. Git tags and\nGitHub Releases are created automatically by CI (`auto_tag` in `main.yml`)\nonce the version bump lands on `main` — never tag manually.\n\n---\n\n## License\n\nMIT © 2024–2026 PHORM Contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterdev7%2Fphorm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterdev7%2Fphorm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterdev7%2Fphorm/lists"}