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 acatalogservice and aProductentity. This page continues from there. - Forge v1.6 or later. Inside Reliant, run it as
reliant forge. Check the version withreliant forge --versioninside 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
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 New files, from The migration is ordinary SQL, and it is yours. Forge never edits it again:
scaffold writes the migration, adds the RPCs to the proto, and runs generate itself. It took about 7 seconds here.terminal
git status (the proto, handlers_crud.go, the hooks and the mocks were updated too):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:To filter on another column, add an
created_atandupdated_atare managed timestamps. Create stamps both, and Update stampsupdated_atagain.- With a
deleted_atcolumn, deletes are soft.DeleteReviewsetsdeleted_at, and Get and List skip the row. The generateddb.ListAllReviewstill returns it. To keep the column as a plain archive stamp, runCOMMENT ON COLUMN reviews.deleted_at IS 'forge:no-soft-delete'in a migration. - Text columns get a free-text
searchfilter, andproduct_idgets an equality filter. Both appear as fields onListReviewsRequest:
proto/services/catalog/v1/catalog.proto
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 The rule’s reference covers the required-parameter case.
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
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, To see the pages, run
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
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, readmiddleware.GetUser(ctx)inhandlers_crud.goand 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_deleteand the delete response’sdeleted_atare not wired. The scaffold puts both fields in the delete messages, but at this forge version the generated handler ignoreshard_deleteand returnsdeleted_atunset.- The pages are starter code. They prove the stack works. They are not a design. See Generated code vs yours.
Troubleshooting
marker inert; evolution is a new migration
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
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