--- title: "Overview" description: "What effect-orm is, what it does and does not do, and where to start." --- > Documentation Index > Fetch the complete documentation index at: https://effect-orm.maple.dev/llms.txt > Use this file to discover all available pages before exploring further. # Overview `@maple-dev/effect-orm` builds ClickHouse and Postgres SQL from typed TypeScript. You describe a table once, and the builder infers column types, output row shapes, and join accessors from it. Queries are immutable values — every method returns a new query — and nothing touches the network: the end product is a `CompiledQuery` holding a SQL string plus a typed decoder. You bring your own database client. Each database has one entry that holds everything for it, the way drizzle and kysely split dialects: `import * as CH from "@maple-dev/effect-orm/clickhouse"` or `import * as PG from "@maple-dev/effect-orm/postgres"`. The query builder is the same in both; the column types, functions, table DDL, and `compile` are the database's own. ## Is this for your project? Use the builder when you want typed ClickHouse or Postgres queries, reusable query definitions, and runtime result decoding in TypeScript. It works with an ordinary async application as well as an Effect application. The database client remains your choice. You do not need a Maple account, Maple's schema, or tenant columns. Tenant analysis is an optional feature for applications that share tables between tenants. The builder does not manage connections, create tables, or run migrations. It builds SELECTs, [INSERTs](https://effect-orm.maple.dev/mysql/queries/inserts/), and [UPDATEs and DELETEs](https://effect-orm.maple.dev/mysql/queries/updates-and-deletes/). Every `table` carries its DDL, and opt-in [schema and migration entry points](https://effect-orm.maple.dev/mysql/database/migrations/) turn it into migrations: generated and applied for ClickHouse and Postgres, generated for SQLite and MySQL. It does not validate SQL against a live server, choose query plans, enforce authorization, or supply retries. Your existing tables and your executor own those responsibilities. [Getting started](https://effect-orm.maple.dev/mysql/start/getting-started/) covers npm installation and building from source. ## Start here 1. [Compile and decode offline](https://effect-orm.maple.dev/mysql/start/getting-started/) with one complete file. 2. [Run a real query](https://effect-orm.maple.dev/mysql/queries/running-queries/) against `system.numbers`, without creating a table. 3. [Adapt a recipe](https://effect-orm.maple.dev/mysql/start/recipes/) to your own schema. 4. [Benchmark a change](https://effect-orm.maple.dev/benchmarks/benchmarking/) with a fixed workload and saved baseline. 5. Consult [Troubleshooting](https://effect-orm.maple.dev/reference/troubleshooting/) if installation or results differ from expectations. Coming from another ORM? [Coming from Drizzle or Prisma](https://effect-orm.maple.dev/mysql/start/coming-from-drizzle-prisma/) maps their operations to effect-orm, with one checked program and a Cloudflare Worker sketch. The named complete examples are extracted from Markdown, typechecked, and exercised by [`check-doc-examples.mjs`](https://github.com/MapleTechLabs/effect-orm/blob/main/scripts/check-doc-examples.mjs). Focused behavior tests also live in [`src/docs-examples.test.ts`](https://github.com/MapleTechLabs/effect-orm/blob/main/src/docs-examples.test.ts). Client execution requires a server; the offline checks verify SQL construction and decoding, not database execution plans. ## Guides Roughly in reading order. | Guide | What it covers | | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | | [Getting started](https://effect-orm.maple.dev/mysql/start/getting-started/) | Install, define a table, build → compile → decode | | [Tables and column types](https://effect-orm.maple.dev/mysql/queries/tables-and-types/) | `table()`, column options, external tables, the column-type constructors | | [Building queries](https://effect-orm.maple.dev/mysql/queries/queries/) | `select`, `where`, `groupBy`, `orderBy`, `limit`, `format`, immutability, `pipe` | | [Expressions and conditions](https://effect-orm.maple.dev/mysql/queries/expressions/) | Comparisons, arithmetic, optional predicates, aggregates | | [Joins and subqueries](https://effect-orm.maple.dev/mysql/queries/joins-and-subqueries/) | The join family, `fromQuery`, correlated subqueries | | [Unions and CTEs](https://effect-orm.maple.dev/mysql/queries/unions-and-ctes/) | `unionAll`, `fromUnion`, `withCTE` | | [Inserting rows](https://effect-orm.maple.dev/mysql/queries/inserts/) | `insertInto`, the insert row type, `DEFAULT`, binding | | [Updating and deleting](https://effect-orm.maple.dev/mysql/queries/updates-and-deletes/) | `update`, `deleteFrom`, `allRows`, ClickHouse mutations | | [Params and compilation](https://effect-orm.maple.dev/mysql/queries/params-and-compilation/) | `param.*`, how values reach the SQL, `CompiledQuery` | | [Decoding results](https://effect-orm.maple.dev/mysql/queries/decoding-results/) | `rowSchema`, `decodeRows`, `decodeFirstRow`, decode errors | | [Running a query](https://effect-orm.maple.dev/mysql/queries/running-queries/) | Executing the SQL with a real client, wire settings, `SETTINGS` | | [Benchmarking](https://effect-orm.maple.dev/benchmarks/benchmarking/) | Define suites, measure baseline/candidate runs, verify results, and compare budgets | | [Agent benchmark playbook](https://effect-orm.maple.dev/benchmarks/benchmark-agent/) | Repeatable optimization workflow and evidence checklist | | [Tenant scoping](https://effect-orm.maple.dev/mysql/database/tenant-scoping/) | `tenantScope`, what marks a query scoped, `crossTenant()` | | [Extending the DSL](https://effect-orm.maple.dev/mysql/queries/extending/) | `defineFn`, raw escape hatches, handwritten SQL | | [Postgres](https://effect-orm.maple.dev/postgres/specifics/overview/) | The Postgres dialect, its column types and functions | | [Schema and migrations](https://effect-orm.maple.dev/mysql/database/migrations/) | DDL from `CH.table` / `PG.table` / `SQLite.table` / `MySQL.table`, `materializedView`, `effect-orm generate`, applying migrations, adopting drizzle-kit | | [Statements and transactions](https://effect-orm.maple.dev/mysql/database/database/) | `Database` over your `SqlClient`: `run`, `execute`, `transaction`, retry, repositories | | [Testing your code](https://effect-orm.maple.dev/mysql/database/testing/#testing-your-own-code-layertest) | `layerTest`: a `Database` with no server for unit tests | | [Seeding](https://effect-orm.maple.dev/mysql/database/seeding/) | Deterministic test and demo rows from the column Schemas: `rows`, `insert`, `arbitrary` | | [Relational reads](https://effect-orm.maple.dev/mysql/database/relations/) | `defineRelations`, `findMany` with nested `with`, tenant scope per level | | [Coming from Drizzle or Prisma](https://effect-orm.maple.dev/mysql/start/coming-from-drizzle-prisma/) | Their operations mapped to effect-orm, what differs by design, a Worker on Hyperdrive | ## Reference - [Recipes](https://effect-orm.maple.dev/mysql/start/recipes/) — complete examples for everyday queries. - [Troubleshooting](https://effect-orm.maple.dev/reference/troubleshooting/) — common failures and sharp edges. - [API reference](https://effect-orm.maple.dev/reference/reference/) — the full export catalog by module, plus error types. ## Entry points | Import | Contents | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@maple-dev/effect-orm/clickhouse` | Everything for ClickHouse: the query builder (`from`, `param`, `insertInto`, `compile`, …), column types (`string`, `uint64`, `map`, …), ClickHouse functions under friendly names (`min`, `max`, `count`, `quantile`, …), and `table`, `column`, `engine`, `index`, `materializedView` | | `@maple-dev/effect-orm/postgres` | Everything for Postgres: the same builder, Postgres column types (`text`, `int8`, `timestamptz`, `jsonb`, …) and functions, `table`, `column`, `index`, `uniqueIndex`, `foreignKey`, and a `compile` for Postgres | | `@maple-dev/effect-orm/expr` | Kitchen-sink namespace: every expression helper plus all ClickHouse functions under their raw names (`min_`, `toString_`, `dynamicColumn`, `not`, …) | | `@maple-dev/effect-orm/sql` | The low-level `SqlFragment` AST (`raw`, `ident`, `compile`, …) for hand-rolling fragments | | `@maple-dev/effect-orm/benchmark` | Driver-free suite definitions, runner, report schemas, and comparisons | | `@maple-dev/effect-orm/benchmark/http` | ClickHouse HTTP transport, environment configuration, and query-log collection | | `@maple-dev/effect-orm/benchmark/cli` | `runCli(args)` for embedding the bundled `ch-bench` commands | | `@maple-dev/effect-orm/tinybird` | Tinybird datasources and views with `@tinybirdco/sdk` call shapes; each datasource is a query table. See [Tinybird](https://effect-orm.maple.dev/clickhouse/specifics/tinybird/) | | `@maple-dev/effect-orm/schema` | Tooling over `table` values: `renderSchema` / `renderPgSchema`, `entitiesOf` / `pgEntitiesOf`, snapshots, and the schema diff. Pure | | `@maple-dev/effect-orm/kit` | `generate` and `check` over a migrations folder, `defineConfig`, and `runCli` for the bundled `effect-orm` command. Node or Bun | | `@maple-dev/effect-orm/migrate` | `run`, `status`, `verify`, `baseline`, and `MigrationDriver`: applies ClickHouse or Postgres migrations through a driver you provide | | `@maple-dev/effect-orm/database` | `Database` over your `SqlClient`: `run` compiled queries, `execute` statements, `transaction` with settings and contention retry | | `@maple-dev/effect-orm/seed` | `rows`, `insert`, `arbitrary` and `pick`: deterministic rows from each column's Schema through `Schema` → `Arbitrary`, inserted in batches. See [Seeding](https://effect-orm.maple.dev/mysql/database/seeding/) | There is no root import: pick the dialect entry. [The reference](https://effect-orm.maple.dev/reference/reference/) lists every export of both. ## Query benchmarks The optional `@maple-dev/effect-orm/benchmark` entry point and bundled `ch-bench` CLI measure real queries, compare fixed workloads, and save evidence. See [Benchmarking](https://effect-orm.maple.dev/benchmarks/benchmarking/) and the [agent playbook](https://effect-orm.maple.dev/benchmarks/benchmark-agent/). The SQL builders remain driver-free. ## MySQL and MariaDB [MySQL and MariaDB](https://effect-orm.maple.dev/mysql/specifics/overview/) covers `@maple-dev/effect-orm/mysql`: its codecs and functions, `@effect/sql-mysql2` wiring (including Cloudflare Hyperdrive's text protocol), collations, table DDL and what MySQL does differently. `effect-orm generate` writes MySQL migrations; effect-orm does not apply them yet. ## SQLite and D1 [SQLite and D1](https://effect-orm.maple.dev/sqlite/specifics/overview/) covers `@maple-dev/effect-orm/sqlite`, its codecs and functions, table DDL, Effect SQL drivers, tenant checks and transaction limits. `effect-orm generate` writes SQLite migrations; effect-orm does not apply them yet. Source: https://effect-orm.maple.dev/mysql/start/overview/index.mdx