How-to guides

Choose a guide by the task you need to complete. These guides assume you already have a configured project.

Connections

• Run queries in a transaction
• Route reads to a replica
• Use prepared statements
• Name and trace generated queries

Dialects

• Use PostgreSQL-specific queries
• Use TimescaleDB hypertables
• Use continuous aggregates
• Use ClickHouse MergeTree tables
• Read ClickHouse arrays, maps and tuples
• Run asynchronous ClickHouse mutations
• Read nested data with DuckDB
• Write analytical DuckDB queries
• Use MySQL and MariaDB
• Use SQLite databases and extensions
• Use CockroachDB

Embedding

• Generate SQL wrappers from Go
• Vet and inspect a catalogue from Go
• Register custom SQL functions
• Customise generation with a preset
• Generate from an existing database
• Observe and limit generator work
• Provide a custom schema source
• Read configuration and assemble a generator

Extensions

• Writing an emitter
• Build and test a custom emitter
• Build a custom sgl binary
• Configure a built-in dialect
• Implement a migration backend or executor

Interactive tools

• Use the playground and open an example
• Run an example locally

Migrations

• Run migrations at application start-up
• Create, apply and roll back migrations
• Apply seeds, namespaces and hooks
• Run migrations from the command line
• Configure migration locks and namespaces
• Recover an interrupted migration
• Investigate checksum mismatches
• Roll back or target a migration version
• Use migration hooks and observability

Operations

• Verifying releases

Projects

• Add Seagull to an existing project
• Configure multiple databases
• Choose and configure a driver

Queries

• Choose a query command
• Name and type parameters
• Pass a slice to a query
• Add optional filters
• Validate sorting and pagination
• Add bounded pagination
• Build queries at runtime
• Query through CTEs, views and functions
• Declare SQL functions in migrations

Results

• Handle NULL and missing rows
• Embed joined results
• Collect one-to-many results
• Stream rows and stop early
• Handle an optional single row
• Tag, document and mock generated code

Tooling

• Troubleshoot generation and execution
• Check SQL and generated code in CI
• Inspect queries and compare schemas
• Format directives and change prefixes
• Upgrade Seagull and regenerate
• Test generated queries

Types

• Inspect SQL-to-Go types
• Use JSON and custom Go types
• Work with enums, arrays and nested values
• Read arrays and lists
• Override SQL-to-Go types

Writes

• Return inserted or updated rows
• Write an upsert
• Batch writes and use COPY