> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a database table with a CRUD API and pages

> Generate a Postgres table, five CRUD RPCs, typed React hooks and list, detail and edit pages from one proto message marked // forge:entity.

You will add a `reviews` table to a Forge project. One marked proto message produces the migration, the five CRUD RPCs and their handlers, the data access code, typed React hooks, and list, detail, create and edit pages. After that you own every file it wrote.

Forge projects everything else from two inputs, the proto and the migrations; [Two sources of truth](https://docs.reliantlabs.io/forge/concepts/two-sources-of-truth.md) explains the split.

## Before you begin

* A Forge project with a service and a web frontend. [Build a Go and React app with Connect RPC](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md) creates `shop`, with a `catalog` service and a `Product` entity. This page continues from there.
* Forge v1.6 or later. Inside Reliant, run it as `reliant forge`. Check the version with `reliant forge --version` inside the project.
* No account. Every step runs locally.

**1. Mark a message as an entity**

Add the message to the service's proto with a `// forge:entity` comment directly above it. Leave out `id`, `created_at` and `updated_at`, because Forge adds them. A `deleted_at` field asks for soft delete, and a field named `<entity>_id` becomes a foreign key when an entity with that name exists.

```protobuf proto/services/catalog/v1/catalog.proto theme={null}
// forge:entity
message Review {
  string product_id = 2;
  int32 rating = 3;
  string body = 4;
  google.protobuf.Timestamp deleted_at = 5;
}
```

**2. Preview the scaffold**

```bash terminal theme={null}
reliant forge scaffold --dry-run
```

```text theme={null}
── Phase 1: entity births (// forge:entity markers) ─────────────
  ⏭️  Product: table "products" exists — marker inert; evolution is a new migration
  📋 would birth services.catalog.v1.Review → table "reviews" (migration)
        quintet: would inject 5 rpc(s) [CreateReview GetReview UpdateReview DeleteReview ListReviews] + 10 message(s)
```

The marker on `Product` does nothing now, because its table exists. A message is born once. After that, you change its table with a new migration.

**3. Run the scaffold**

Bare `scaffold` writes the migration, adds the RPCs to the proto, and runs `generate` itself. It took about 7 seconds here.

```bash terminal theme={null}
reliant forge scaffold
```

```text theme={null}
── Summary ───────────────────────────────────────────────────────
  entities birthed:    1 (services.catalog.v1.Review → reviews)
  managed fields:      3 declared on entity messages
  quintets completed:  1
```

New files, from `git status` (the proto, `handlers_crud.go`, the hooks and the mocks were updated too):

```text theme={null}
db/migrations/20261120063312_create_reviews.up.sql
internal/db/review_orm_gen.go
internal/db/review_store_gen.go
internal/db/review_repo_ext.go
frontends/web/src/app/reviews/                 (page.tsx, new/, view/, edit/)
frontends/web/src/components/dashboard-tiles/reviews_gen.tsx
frontends/web/src/lib/nav-routes/reviews_gen.ts
frontends/web/src/mocks/reviews_gen.ts
db/grants/readonly/public.reviews_gen.sql
```

The migration is ordinary SQL, and it is yours. Forge never edits it again:

```sql db/migrations/20261120063312_create_reviews.up.sql theme={null}
CREATE TABLE reviews (
    id TEXT PRIMARY KEY CHECK (id <> ''),
    product_id TEXT NOT NULL,
    rating BIGINT NOT NULL DEFAULT 0,
    body TEXT NOT NULL DEFAULT '',
    created_at TIMESTAMPTZ NOT NULL DEFAULT (now()),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT (now()),
    deleted_at TIMESTAMPTZ
);
ALTER TABLE reviews ADD CONSTRAINT reviews_product_id_fkey FOREIGN KEY (product_id) REFERENCES products (id);
CREATE INDEX reviews_product_id_idx ON reviews (product_id);
```

**4. Read what the columns turn on**

Behaviour comes from the columns in the applied schema, not from proto annotations:

* `created_at` and `updated_at` are managed timestamps. Create stamps both, and Update stamps `updated_at` again.
* With a `deleted_at` column, deletes are soft. `DeleteReview` sets `deleted_at`, and Get and List skip the row. The generated `db.ListAllReview` still returns it. To keep the column as a plain archive stamp, run `COMMENT ON COLUMN reviews.deleted_at IS 'forge:no-soft-delete'` in a migration.
* Text columns get a free-text `search` filter, and `product_id` gets an equality filter. Both appear as fields on `ListReviewsRequest`:

```protobuf proto/services/catalog/v1/catalog.proto theme={null}
message ListReviewsRequest {
  int32 page_size = 1;
  string page_token = 2;
  optional string search = 3;
  optional string product_id = 4;
  string order_by = 5;
  bool descending = 6;
}
```

To filter on another column, add an `optional` field with that column's name. Forge wires it through the query, the hook and the list page.

**5. Keep list filters optional**

A filter field without `optional` cannot tell "no filter" from an empty value, so it never filters. `lint` rejects it. This is the output after removing `optional` from `product_id`:

```bash terminal theme={null}
reliant forge lint --conventions
```

```text theme={null}
❌ conventions — 1 error
   ✗ proto/services/catalog/v1/catalog.proto:214 [forgeconv-list-filter-optional] ListReviewsRequest.product_id has no field presence: unset and "" are the same value on the wire, ...
      → a filter: mark it `optional` — `optional string product_id = 4;` — so unset means "no filter" end to end (Go pointer, TS `?:`, generated nil-guard). A required parameter (a parent or org id the handler insists on): declare it with `[(buf.validate.field).required = true]`
```

[The rule's reference](https://docs.reliantlabs.io/forge/linting/rules-conventions.md#forgeconv-list-filter-optional) covers the required-parameter case.

**6. Verify the build, the gate and the shapes**

```bash terminal theme={null}
go build ./... && reliant forge lint --quiet
```

```text theme={null}
✅ All 29 gating linters passed.
```

`project shapes` lists each new symbol with its file and line:

```bash terminal theme={null}
reliant forge project shapes --grep Review
```

```text theme={null}
rpc      CatalogService.CreateReview    proto/services/catalog/v1/catalog.proto:52
handler  CatalogService.CreateReview    internal/handlers/catalog/handlers_crud.go:107
table    reviews                        db/migrations/20261120063312_create_reviews.up.sql:5
store    ReviewStore                    internal/db/review_store_gen.go:17
hook     useListReviews                 frontends/web/src/hooks/catalog-service-hooks_gen.ts:250
...
```

**7. Test the behaviour**

The first entity in a service gets a lifecycle test, `TestCRUD_Product_Lifecycle` in `internal/handlers/catalog/handlers_crud_test.go`. Later entities get request factories (`catalog.NewCreateReviewRequest`) but no test of their own, so copy that test for `Review`. This version also checks soft delete and the filter. It passed against a real Postgres that the test harness starts for you:

```bash terminal theme={null}
task test:short -- -v -run 'TestCRUD_Product_Lifecycle|TestReview_' ./internal/handlers/catalog/...
```

```text theme={null}
--- PASS: TestCRUD_Product_Lifecycle (0.91s)
=== RUN   TestReview_SoftDeleteAndFilter
    review_test.go:26: created_at=2026-11-20 07:08:49.220164445 +0000 UTC updated_at=2026-11-20 07:08:49.220164445 +0000 UTC
    review_test.go:34: filtered by product_id: 1 of 2
    review_test.go:41: after delete: ListReviews returns 1, table holds 2
--- PASS: TestReview_SoftDeleteAndFilter (0.83s)
```

To see the pages, run `reliant forge env up dev` and open `/reviews`.

## What this does not do

* **No access control.** Every generated handler requires a signed-in caller but does not check who it is. The comment above each one says `AUTHENTICATED, UNSCOPED`. To scope rows to their owner, read `middleware.GetUser(ctx)` in `handlers_crud.go` and filter on it.
* **No later schema changes.** The marker only works once. To add a column, write a new migration (`reliant forge db migration new`) and add the field to the proto.
* **`hard_delete` and the delete response's `deleted_at` are not wired.** The scaffold puts both fields in the delete messages, but at this forge version the generated handler ignores `hard_delete` and returns `deleted_at` unset.
* **The pages are starter code.** They prove the stack works. They are not a design. See [Generated code vs yours](https://docs.reliantlabs.io/forge/concepts/generated-vs-yours.md).

## Troubleshooting

> [accordion] marker inert; evolution is a new migration
>
> The message already has a table, so scaffolding does nothing. Write a migration for the change instead.

## Next steps

> [card] [Add a custom RPC](https://docs.reliantlabs.io/guides/forge/add-custom-rpc.md)
>
> Add logic that CRUD can't express, with typed hooks

> [card] [Zero-downtime migrations](https://docs.reliantlabs.io/guides/forge/zero-downtime-postgres-migrations.md)
>
> Change the table without breaking the running release

> [card] [Adding a feature](https://docs.reliantlabs.io/forge/adding-features.md)
>
> The everyday loop: services, RPCs, migrations, the gate

> [card] [Two sources of truth](https://docs.reliantlabs.io/forge/concepts/two-sources-of-truth.md)
>
> How proto and migrations become the generated code


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.