CLI Usage & Evolution
How to safely use the GO-DUCK Generator without destroying your manual Go code edits over time.
1. The Command Pipeline
The GO-DUCK-CLI operates on basically two commands. The initialization of your system, and the continuous evolution pipeline.
# Command 1: Fresh Creation
# Scaffold an entirely new ecosystem. This generates ALL baseline infrastructure.
go-duck create -o ./MY_APP -c config.yaml -g initial_schema.gdl
# Command 2: Incremental Stateful Update
# Used whenever you modify your GDL (add an entity, drop a column, add a link)
go-duck import-gdl my_new_schema.gdl -o ./MY_APP2. Schema Evolution & the `.go-duck/` State
"If I run the generator to import a new GDL, will it overwrite my database or delete existing entities?" No, thanks to stateful evolution.
The generator maintains a stateful snapshot of every entity it has ever generated inside the hidden .go-duck/ directory at the root of your target project. When you run import-gdl, the CLI intelligently merges existing entities with newly parsed entities and executes targeted diff operations:
Supports splitting your entities into multiple GDL files. Unspecified active models are loaded from the .go-duck/ folder and merged with new entities, keeping active routers and endpoints in sync.
Adding, dropping, or modifying fields inside entity blocks generates specific ADD COLUMN or DROP COLUMN SQL statements in a timestamped Goose migration file.
Marking an entity with the @Delete annotation automatically triggers a database DROP TABLE SQL migration, purges all generated Go/Protobuf code files, and clears its snapshot.
Warning
Never manually delete `.go-duck/` unless you are intentionally wiping the entire database state and starting configuration completely from scratch.
3. JHipster-Style "Needles" (Safe Code Injection)
"If I write custom endpoints in `main.go`, will running the generator wipe them out?" No, as long as you use Needles!
The generator utilizes carefully placed specific comments called "needles". For example, inside main.go, you will see markers exactly like // go-duck-needle-add-init-server.
When the generator runs an incremental update, it doesn't arbitrarily overwrite main.go via a template. It opens the existing compiled main.go file on your machine, locates the Needle anchor point via REGEX, and safely inserts the new syntax directly below it.
- // go-duck-needle-add-import (main.go)
- // go-duck-needle-add-init-repository (main.go)
- // go-duck-needle-add-grpc-service (internal/server/grpc.go)