Better example and docs

Author: gloomweaver

README.md

@@ -1,12 +1,29 @@
 # sqlf
 
-MVP for a SQL-first TypeScript code generator targeting `effect` + `@effect/sql`.
+`sqlf` is an MVP for a SQL-first TypeScript code generator targeting `effect` + `@effect/sql`.
+
+It is inspired by `sqlc`, but uses:
+
+- TypeScript / JS config via `defineConfig()`
+- database introspection for result / parameter typing
+- generated `Schema` + `SqlSchema.*` helpers for Effect-native usage
 
 ## Workspace
 
 - `packages/core` — config loading, SQL parsing, Postgres analysis, code generation
-- `packages/cli` — `sqlf generate` command
-- `examples/basic` — example config and SQL queries
+- `packages/cli` — `sqlf generate`
+- `examples/basic` — self-contained Postgres + generated CRUD example + Effect HTTP API
+
+## MVP scope
+
+Current MVP supports:
+
+- JS / TS config via `defineConfig()`
+- Postgres-only
+- sqlc-style query annotations: `:one`, `:maybeOne`, `:many`, `:exec`
+- named params via `@param`
+- Postgres-backed result type inference
+- generated Effect SQL wrappers via `SqlSchema.single/findOne/findAll/void`
 
 ## Commands
 
@@ -16,46 +33,176 @@ vp lint
 vp run -r check
 vp run -r test
 vp run -r build
+```
+
+## Quick start
+
+Generate the example output:
+
+```bash
+vp run -r build
 vp run @sqlf/example-basic#generate
 ```
 
-## Generated output
+Start the example API:
+
+```bash
+vp run @sqlf/example-basic#start
+```
+
+Reset the example database if you want to re-run `schema.sql` from scratch:
 
-The generated module now emits:
+```bash
+cd examples/basic
+pnpm run db:stop
+pnpm run db:start
+```
 
-- `*ParamsSchema` and `*ResultSchema`
-- `*Params` and `*Result` type aliases via `Schema.Schema.Type<...>`
-- raw `*Sql` constants
-- query docs with source file + SQL
-- `SqlSchema.single/findOne/findAll/void` wrappers
+## Example: generated CRUD module
 
-## Integration testing
+The basic example lives in `examples/basic` and is fully local:
 
-`packages/core/tests/postgres.integration.test.ts` runs against:
+- `examples/basic/compose.yaml` starts Postgres on `127.0.0.1:54329`
+- `examples/basic/schema.sql` creates and seeds the `users` table
+- `examples/basic/sql/queries.sql` defines CRUD queries
+- `examples/basic/generated/index.ts` is committed generated output
+- `examples/basic/src/httpApi.ts` shows how to use generated queries inside an Effect `HttpApi`
 
-- `SQLF_TEST_DATABASE_URL`, if provided, or
-- an ephemeral Docker `postgres:16-alpine` container
+The example SQL includes:
+
+```sql
+-- name: CreateUser :one
+INSERT INTO users (id, email, created_at)
+VALUES (@id::uuid, @email::text, now())
+RETURNING id, email, created_at;
+
+-- name: GetUser :one
+SELECT id, email, created_at
+FROM users
+WHERE id = @id::uuid;
+
+-- name: ListUsers :many
+SELECT id, email, created_at
+FROM users
+ORDER BY created_at DESC;
+
+-- name: UpdateUser :one
+UPDATE users
+SET email = @email::text
+WHERE id = @id::uuid
+RETURNING id, email, created_at;
+
+-- name: DeleteUser :exec
+DELETE FROM users
+WHERE id = @id::uuid;
+```
+
+## Example: direct generated usage
 
-## Example
+You can call the generated functions directly by providing a SQL client layer:
 
-`examples/basic` now includes a Docker Compose Postgres setup.
+```ts
+import { PgClient } from "@effect/sql-pg";
+import { Effect, Redacted } from "effect";
+import { createUser, listUsers } from "./generated/index.ts";
+
+const program = Effect.gen(function* () {
+  const created = yield* createUser({
+    id: "33333333-3333-3333-3333-333333333333",
+    email: "grace@example.com",
+  });
+
+  const users = yield* listUsers({});
+
+  return { created, users };
+});
+
+const runnable = program.pipe(
+  Effect.provide(
+    PgClient.layer({
+      url: Redacted.make("postgres://postgres:postgres@127.0.0.1:54329/postgres"),
+    }),
+  ),
+);
+```
+
+## Example: generated output shape
+
+Generated modules export:
+
+- `*ParamsSchema`
+- `*ResultSchema`
+- `*Params` / `*Result` type aliases
+- raw `*Sql` strings
+- `SqlSchema.*` wrappers
+
+Example output from `examples/basic/generated/index.ts`:
+
+```ts
+export const CreateUserResultSchema = Schema.Struct({
+  id: Schema.UUID,
+  email: Schema.String,
+  created_at: Schema.DateFromSelf,
+});
+
+export const createUser = SqlSchema.single({
+  Request: CreateUserParamsSchema,
+  Result: CreateUserResultSchema,
+  execute: (request) =>
+    Effect.flatMap(SqlClient.SqlClient, (sql) =>
+      sql.unsafe(createUserSql, [request.id, request.email]),
+    ),
+});
+```
+
+## Example: Effect HTTP API
+
+`examples/basic/src/httpApi.ts` wires the generated module into an Effect `HttpApi`.
+
+It exposes:
+
+- `POST /users`
+- `GET /users`
+- `GET /users/:id`
+- `PUT /users/:id`
+- `DELETE /users/:id`
+
+Start it:
 
 ```bash
-vp run -r build
-vp run @sqlf/example-basic#generate
+vp run @sqlf/example-basic#start
 ```
 
-That will:
+Then try it:
 
-- start Postgres via `examples/basic/compose.yaml`
-- initialize the `users` table from `examples/basic/schema.sql`
-- generate `examples/basic/generated/index.ts`
+```bash
+curl http://127.0.0.1:3000/users
 
-## MVP scope
+curl http://127.0.0.1:3000/users/11111111-1111-1111-1111-111111111111
 
-- JS/TS config via `defineConfig()`
-- Postgres-only
-- Query annotations inspired by sqlc (`:one`, `:maybeOne`, `:many`, `:exec`)
-- Named params via `@param`
-- Result type inference through lightweight Postgres analysis
-- Effect SQL code generation
+curl -X POST http://127.0.0.1:3000/users \
+  -H 'content-type: application/json' \
+  -d '{"email":"grace@example.com"}'
+
+curl -X PUT http://127.0.0.1:3000/users/11111111-1111-1111-1111-111111111111 \
+  -H 'content-type: application/json' \
+  -d '{"email":"ada+updated@example.com"}'
+
+curl -X DELETE http://127.0.0.1:3000/users/11111111-1111-1111-1111-111111111111
+```
+
+## Generated output notes
+
+The generator currently emits:
+
+- query doc comments with source file + SQL
+- Effect schemas for params and results
+- raw SQL strings
+- executable wrappers built on `SqlSchema`
+
+## Integration testing
+
+`packages/core/tests/postgres.integration.test.ts` runs against either:
+
+- `SQLF_TEST_DATABASE_URL`, or
+- an ephemeral Docker `postgres:16-alpine` container

examples/basic/.gitignore

@@ -1,4 +1,5 @@
 node_modules
-generated
+generated/*
+!generated/index.ts
 *.log
 .DS_Store

examples/basic/README.md

@@ -0,0 +1,47 @@
+# @sqlf/example-basic
+
+Self-contained example for `sqlf`.
+
+## What it contains
+
+- Docker Compose Postgres database
+- `schema.sql` to create + seed `users`
+- SQL CRUD queries in `sql/queries.sql`
+- committed generated output in `generated/index.ts`
+- Effect `HttpApi` in `src/httpApi.ts`
+- runnable Node server in `src/server.ts`
+
+## Commands
+
+```bash
+pnpm run db:start
+pnpm run generate
+pnpm run start
+```
+
+Reset the database volume:
+
+```bash
+pnpm run db:stop
+pnpm run db:start
+```
+
+## API
+
+- `POST /users`
+- `GET /users`
+- `GET /users/:id`
+- `PUT /users/:id`
+- `DELETE /users/:id`
+
+## Sample requests
+
+```bash
+curl http://127.0.0.1:3000/users
+
+curl http://127.0.0.1:3000/users/11111111-1111-1111-1111-111111111111
+
+curl -X POST http://127.0.0.1:3000/users \
+  -H 'content-type: application/json' \
+  -d '{"email":"grace@example.com"}'
+```