001Getting startedRuns in browser
Your first query
Write a migration and three annotated queries, generate, and call the result.
Examples
Learn Seagull by example.
53 concepts and 214 runnable examples across 8 engines. Each one is a small program in the Seagull repository: the SQL you write, the Go sgl generates, and the code that calls it.
★SandboxRuns in browser
Blank playground
Start from the SQLite starter that sgl init writes, pick any dialect, and watch the Go appear as you type.
002Getting startedRuns in browser
Choosing a command: one, many, exec, execrows, execresult
Each command kind gives a different Go signature; pick the one that matches what the caller needs back.
003Getting startedRuns in browser
Placeholders, inferred names and Params structs
Seagull names parameters from what they are compared with, and groups two or more into a Params struct.
004Getting startedRuns in browser
Nullability through joins, COALESCE and aggregates
A column that can be NULL becomes a pointer, and Seagull works that out through joins, COALESCE and aggregates.
005Types and nullabilityRuns in browser
From SQL types to Go types
How each engine's column types arrive in Go, from integers and decimals to times and UUIDs.
006Types and nullabilityRuns in browser
JSON columns
JSON columns and JSON operators, read into the generated JSON type.
007Types and nullability
Enums as generated Go types, and your own types with go_type
Each enum becomes a named Go type with a constant per value; a go_type override maps it to your own Go type instead.
008Types and nullability
Arrays and lists as typed slices
Array and list columns arrive as typed Go slices.
009Types and nullabilityRuns in browser
Type overrides
Override a column's Go type in a query, in a migration, or for a whole SQL type in sgl.yaml.
010Dynamic queriesRuns in browser
IN lists from Go slices
Pass a Go slice where the SQL expects a list.
011Dynamic queriesRuns in browser
Optional filters
A filter the caller may leave out, with an optional parameter and the IS NULL idiom.
012Dynamic queriesRuns in browser
Validated ORDER BY
Let callers choose the sort column and direction from an allow-list, never from raw text.
013Dynamic queriesRuns in browser
Pagination with defaults and limits
LIMIT and OFFSET parameters with a default and a maximum, combined into a full search endpoint.
014Dynamic queriesRuns in browser
The runtime query builder
Build WHERE, ORDER BY, LIMIT and COUNT at run time from an allow-list, with every value bound.
015Shaping resultsRuns in browser
Nested structs with sgl.embed
Return a joined table as a nested struct, and as a pointer when the join is outer.
016Shaping resultsRuns in browser
Parents with child slices
Collapse repeated parent rows into one parent with a slice of children using group_by.
017Shaping resultsRuns in browser
Range over rows
Stream rows one at a time with a range-over-func iterator, and stop early.
018Shaping resultsRuns in browser
Missing rows without errors
Make a one query report a missing row with a bool instead of sql.ErrNoRows.
019Shaping resultsRuns in browser
Types through CTEs, window functions and views
Column types and nullability follow CTEs, recursive CTEs, window functions and views.
020Writing dataRuns in browser
Rows back from INSERT, UPDATE and DELETE
Use RETURNING to get the written row back in one round trip.
021Writing dataRuns in browser
Insert or update
Insert a row or update the one that is already there, in each engine's own syntax.
022Writing dataRuns in browser
Batch and copyfrom
Write many rows in one call, chunked under each engine's bind-variable limit.
023Connections and transactionsRuns in browser
Transactions
Run several queries atomically with RunInTx, or bind the queries to a transaction with WithTx.
024Connections and transactions
Read replicas
Send read-only queries to a replica and writes to the primary, decided by Seagull's read-only detection.
025Connections and transactionsRuns in browser
Prepared statements
Prepare every query once with go.prepared and the generated Prepare.
026Connections and transactionsRuns in browser
Query names for tracing
Name every query in traces and logs with go.query_names and a wrapping DBTX.
027Migrations and seeds
Migrations at start-up
Embed the migration files in the binary and apply them when the program starts.
028Migrations and seeds
The migration lifecycle
Migrate up to a version, roll back, check status and validate checksums, with locking.
029Migrations and seeds
Seeds, namespaces and hooks
Seed data, keep several migration histories in one database, and run code around each migration.
030Engine features
Functions in migrations
Define SQL functions in migrations; whether they change data decides whether queries that call them are read-only.
031Engine features
PostgreSQL power queries
LATERAL joins, DISTINCT ON, full-text search and data-modifying CTEs, all typed.
032Engine features
Hypertables and time buckets
Create a hypertable and query it with time_bucket, first, last and gap filling.
033Engine features
Continuous aggregates
Define a continuous aggregate, refresh it, and query it with hyperfunctions.
034Engine features
MergeTree engines
ReplacingMergeTree, SummingMergeTree and AggregatingMergeTree, read with FINAL and PREWHERE.
035Engine features
Arrays, maps and tuples in ClickHouse
ARRAY JOIN, Map, Tuple, LowCardinality and IPv4 columns, typed in Go.
036Engine features
Asynchronous mutations
Declare ALTER TABLE UPDATE and DELETE as asyncexec so callers know the server queues them.
037Engine features
Nested types in DuckDB
STRUCT, MAP, LIST and UNION columns as Go types.
038Engine features
Analytics in DuckDB
QUALIFY, FILTER, PIVOT, macros and read_parquet, with typed results.
039Engine features
MySQL dialect features
INSERT IGNORE, REPLACE INTO, SET columns, GROUP_CONCAT and unsigned integers.
040Engine features
SQLite extensions
FTS5 and R*Tree virtual tables, json_each and generated columns.
041Tooling
sgl vet and diagnostics
Check queries without generating, read a diagnostic, and look a code up with sgl explain.
042Tooling
Seagull in CI
Fail the build when generated code is stale, and report diagnostics as GitHub annotations or SARIF.
043Tooling
Describe queries and diff schemas
Print a query's Go signature, dump the schema, and diff it against a live database.
044Tooling
Formatting directives and prefixes
Normalise directives with sgl fmt, require the canonical prefix, and adopt queries written with another tool's prefix.
045Tooling
Migrations from the command line
Create, apply, roll back and inspect migrations and seeds with sgl.
046Embedding Seagull
Generating from Go
Run Seagull as a library from your own generator, with a --check mode for CI.
047Embedding Seagull
Vet and the catalogue from Go
Read the analysed queries and the schema catalogue to build your own checks.
048Embedding Seagull
Custom functions
Declare a Go function registered with the driver so Seagull can type queries that call it.
049Embedding Seagull
White-label presets
Generate with your own directive prefix, header and helper names.
050Embedding Seagull
Schema from a live database
Generate against a database's real schema instead of migration files.
051Embedding Seagull
Observing the generator
Trace each stage of generation and migration with an observer and slog.
052Embedding Seagull
A custom emitter
Wrap the database/sql emitter to add a generated file of your own.
053Embedding Seagull
Your own sgl
Build an sgl with your dialect options and emitter using cli.Main.
No example matches.