For senior developers

Move an existing Gin and GORM API into Grit

You already have a Gin and GORM API that works. The attraction of a generator is the twelve CRUD resources and the admin panel you have not built yet, not a rewrite of the six endpoints you have.

So do not rewrite. This is an incremental route: a new project beside the old one, your models moved across, and resources generated around them one at a time. Every step ends somewhere you could stop.

18 min read. Commands and output last run against Grit v3.562.0.

What you will have at the end

Your existing models and business logic, in a project that can generate around them.

An admin panel over data you already have, without changing the schema.

A clear answer at each step to "what breaks if I stop here".

First, decide whether to

A migration costs real days. It is worth it for specific reasons and not as a general improvement.

  • Worth it if you are facing a dozen more CRUD resources, each with a list, a form, a filter and an admin screen.
  • Worth it if you need an admin panel and were about to build one. That is usually the item that justifies the whole move.
  • Worth it if the frontend and backend keep disagreeing about shapes, and generated types would end it.
  • Not worth it for a service with six endpoints that is finished. There is nothing to generate.
  • Not worth it if your models are not relational, or your project has conventions you are attached to that differ from the generated ones. You would spend the migration arguing with the tool.

A cheaper option first

If what you want is one capability rather than the whole framework, take that one. The plugins write real files into a repository and several of them do not assume a Grit project at all. Copying an idea is also allowed: the outbox, the saga runner and the audit chain in these guides are a few hundred lines each.

01Scaffold beside, not over

Generate a new project next to the old one. Do not run the generator inside your existing repository: it writes a whole project, and you want to compare rather than merge.

Terminal
$cd ..
$grit new myapp-next --arch triple --db postgres
$cd myapp-next
$grit start

Spend an hour in it before moving anything. Generate a throwaway resource, look at the handler, the service and the admin screen, and decide whether this is a shape you want your code to live in. That hour is the cheapest part of the decision.

Stopping point. You have learned what it looks like and lost an hour.

02Point it at your database, read-only at first

The fastest way to find out whether this will work is to let the new project read your real schema.

.env
DATABASE_URL=postgres://user:pass@localhost:5432/your_existing_db

Take a copy, and do not let it migrate

Point it at a restored copy of production, never at production, and make sure nothing runs AutoMigrate against it until you have read what that would do. A generated project migrates on start in development, and your existing schema is not one it wrote.

Terminal
$pg_dump -Fc your_db > copy.dump
$createdb your_db_migration_test
$pg_restore -d your_db_migration_test copy.dump

Stopping point. Nothing of yours has changed. You have a second project reading a copy.

03Move one model, and let the generator build around it

Pick the simplest resource you have: few fields, few relationships, ideally one nobody is actively changing.

Copy the struct into apps/api/internal/models/ and adjust it to the conventions the generator expects. The differences are usually small:

// Yours
type Product struct {
gorm.Model
Name string
Price float64
}
// What the generator expects to find
type Product struct {
ID uint `json:"id" gorm:"primaryKey"`
Name string `json:"name" gorm:"not null" binding:"required,max=200"`
// Money as minor units rather than a float, which is the one change
// here that is a correctness fix rather than a convention.
Price money.Money `json:"price" gorm:"embedded;embeddedPrefix:price_"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
DeletedAt gorm.DeletedAt `json:"-" gorm:"index"`
}

The json tags matter most: they decide what the generated TypeScript calls each field, so matching the names your existing clients already use means the frontend does not have to change.

Then generate the rest around it:

Terminal
$grit generate resource Product \
--fields "name:string:required,price:money"

When a model of that name already exists, the generator writes the service, handler, routes, types, schema, hook and admin screen around it rather than replacing it. Read the diff before accepting it.

Stopping point. One resource exists in both projects. The old one still serves traffic.

04Move the business logic, not the handlers

This is where the thinking is. Your handlers almost certainly contain logic, because most handlers do, and the generated shape puts it in a service.

// Before: the rule is in the handler, so only HTTP can reach it.
func CreateOrder(c *gin.Context) {
var req OrderRequest
c.ShouldBindJSON(&req)
if req.Total > 10000 && !user.Verified {
c.JSON(403, gin.H{"error": "verification required"})
return
}
...
}
// After: the rule is in the service, so a job, the CLI and a test can
// reach it too, and the handler is five lines.
func (s *OrderService) Create(ctx context.Context, userID uint, req CreateOrder) (*models.Order, error) {
user, err := s.users.ByID(ctx, userID)
if err != nil {
return nil, fmt.Errorf("load user: %w", err)
}
if req.Total > verificationThreshold && !user.Verified {
return nil, ErrVerificationRequired
}
...
}

Move the rule and write a test for it as you go. This is the step where a migration pays for itself, because the rules become testable without HTTP, and it is also the step where bugs hide: a condition quietly dropped in the move is a rule nobody enforces and nothing reports.

Keep a list

Write down every rule you find in a handler before you move any of them. A checklist you tick is the only defence against moving eleven of twelve.

Stopping point. One resource is complete in the new project, including its rules and their tests.

05Run both, and move traffic one route at a time

Put both behind the same proxy and route by path. The old service keeps everything it has; the new one takes the resources you have moved.

Caddyfile
api.example.com {
# Moved across, and serving from the new project
handle /api/products* {
reverse_proxy localhost:8080
}
handle /api/categories* {
reverse_proxy localhost:8080
}
# Everything else is still the old one
handle {
reverse_proxy localhost:9000
}
}
  • One database, two applications. Both read and write the same tables, which is fine as long as only one of them migrates the schema. Decide which, and write it down.
  • Sessions have to work across both. Either share the signing secret and the cookie settings, or move authentication first and have the old service verify tokens the new one issues.
  • Move one route, watch it for a day, move the next. The rollback is a proxy change, which is seconds.

Stopping point. Any of them. This is the state you can sit in for weeks, and sitting in it is fine.

06Retire the old one

When the last route has moved, the old service stops. Keep it deployable for a release or two: the first unexpected behaviour is much easier to diagnose when you can still run the thing it used to be.

Then take the schema ownership decision properly. Your existing tables were created by something else, and the new project has migrations starting from empty. Generate a baseline migration that describes the schema as it is, so the two agree from here on.

Terminal
$grit migrate status

The differences you will hit

Primary keys

If yours are UUIDs and the generator expects an integer, or the reverse, that is a real mismatch rather than a convention. Decide early, because every foreign key follows it.

Money as a float

A column of float or decimal against the generated money type, which stores minor units as an integer and a currency. Worth converting, and it is a migration with a backfill rather than a type change.

Timestamps

A generated project uses a date type that accepts what a browser date picker actually sends, because time.Time accepts RFC3339 and nothing else, and a picker sends 2026-11-22. If your API already takes dates in some other shape, decide whether to change the client or keep your own type.

Soft delete

The generated screens and the trash page assume gorm.DeletedAt. A model without it works; it simply has no trash and deletes for good.

Your own conventions

A codebase has naming you are attached to. The generator has its own, and fighting it per resource is how a migration becomes a grind. Either adopt the generated names or accept that generated code and hand-written code will look different, which is survivable and worth deciding on purpose.

What not to move

  • A screen that is not a resource. An operations page stitching four queries together is a hand-written page in either project. Copy it across unchanged.
  • Anything with no CRUD in it. A webhook receiver, a scheduled reconciliation, an export. Move them last, and move them as they are.
  • Code you were going to delete. A migration is an unusually good moment to notice that three endpoints have no callers. Check the logs before porting them.

Frequently asked questions

Can I run the generator inside my existing repository?
It is possible and it is not the way to start. grit new writes a whole project, including configuration, Docker files and a frontend, and reconciling that with an existing tree by hand is harder than copying models into a fresh one. Scaffold beside, compare, and move across.
Will it change my database schema?
Only if you let it. A generated project runs AutoMigrate in development, which adds what is missing and never drops, so pointing it at a restored copy first is the safe order. Production should be on versioned migrations in both projects, and exactly one of them should own the schema during the move.
How long does this take?
The first resource is a day, because that is where you learn the shape. After that it is roughly an hour each for simple ones and a day each for the ones with real rules in the handler. The honest estimate is: count the resources, count the rules you will have to move, and expect the rules to dominate.
What if I get halfway and stop?
You have two services behind a proxy, which is a normal way to run a system and not a failure state. Every step in this guide ends somewhere you can sit. That is deliberate: a migration that is only valuable when complete is one that gets abandoned expensively.

Next steps