Skip to main content
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 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 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.
proto/services/catalog/v1/catalog.proto
2

Preview the scaffold

terminal
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.
terminal
New files, from git status (the proto, handlers_crud.go, the hooks and the mocks were updated too):
The migration is ordinary SQL, and it is yours. Forge never edits it again:
db/migrations/20261120063312_create_reviews.up.sql
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:
proto/services/catalog/v1/catalog.proto
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:
terminal
The rule’s reference covers the required-parameter case.
6

Verify the build, the gate and the shapes

terminal
project shapes lists each new symbol with its file and line:
terminal
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:
terminal
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.

Troubleshooting

The message already has a table, so scaffolding does nothing. Write a migration for the change instead.

Next steps

Add a custom RPC

Add logic that CRUD can’t express, with typed hooks

Zero-downtime migrations

Change the table without breaking the running release

Adding a feature

The everyday loop: services, RPCs, migrations, the gate

Two sources of truth

How proto and migrations become the generated code