Add Seagull to an existing project

Add SQL source directories and a generated package alongside your application. Keep the existing connection setup and handwritten data-layer logic.

Configure one package

Pin the CLI, then create sgl.yaml with the actual database dialect and a dedicated output directory. Use the project layout as a starting point.

Put schema-building SQL in files such as db/migrations/0001_schema.up.sql. A reverse migration is optional. If your existing migration tool puts up and down SQL in one file, split them before giving them to Seagull; see migration file layouts.

For the PostgreSQL family or SQLite, you can instead generate from the live schema when the database is the schema authority.

Generate the first query

Add one query with an sgl.query header, then inspect the planned output:

sgl config validate
sgl vet --strict
sgl generate --diff

Review the method and result types. When they fit the caller, write the package:

sgl generate
go test ./...

Import the package and pass your existing connection to its constructor. Run the query against a disposable database with the expected schema, then add CI checks.

Choose output ownership

Use a directory dedicated to the generated package. Keep handwritten files under names the generator does not produce. Current output filenames are replaced regardless of their old header; stale-file pruning uses recognised generated headers.

Review output writing before moving files from another generator or changing legacy-header settings.