JSON columns
On this page
On MariaDB:
- JSON is an alias for LONGTEXT with a CHECK (JSON_VALID(...)) constraint: an invalid document fails the constraint, and a valid one is stored as text
- Documents come back byte for byte as written, keys in their original order and spacing; MySQL hands back its own normalised text
- No -> or ->> operators: sgl vet reports Q010 for them and names the replacement, JSON_EXTRACT for -> and JSON_UNQUOTE(JSON_EXTRACT(...)) for ->>
- JSON_EXTRACT writes the fragment it returns in MariaDB's own style, with a space after each comma, even though the stored document has none
- The parameter compared with JSON_UNQUOTE(...) is inferred as a string, so sgl.param(fish) only names it (it would be p1); MySQL's ->> left it as any and needed type: text
A JSON column holds a whole document in one value: a basket of items, a set of preferences, a payload you do not want to split into tables. The database can still search inside it. On the Go side you want to keep your own struct for the document, and let the generated code carry it in and out of the database without getting in the way.
Seagull gives every JSON column one generated type, JSON, which holds the raw document as bytes. You fill it with json.Marshal and read it with json.Unmarshal into whatever struct you like. Fragments extracted inside a query come back as JSON too, and values extracted as text come back as plain strings.
This example keeps a chip shop's orders. Each has a basket document, and a delivery document only when the order is delivered.
The schema
db/migrations/0001_orders.up.sql
CREATE TABLE orders (
id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
customer VARCHAR(50) NOT NULL,
basket JSON NOT NULL,
delivery JSON
);
The JSON type
sgl generate writes the JSON type into its own file in your package, so there is nothing extra to import:
internal/store/sgl_json.go
// Code generated by sgl. DO NOT EDIT.
package store
import (
"database/sql/driver"
"encoding/json"
"fmt"
)
type JSON []byte
func (j *JSON) Scan(source any) error {
switch value := source.(type) {
case nil:
*j = nil
return nil
case []byte:
clone := make(JSON, len(value))
copy(clone, value)
*j = clone
return nil
case string:
*j = JSON(value)
return nil
default:
encoded, err := json.Marshal(value)
if err != nil {
return fmt.Errorf("sgl: encode %T to JSON: %w", source, err)
}
*j = encoded
return nil
}
}
func (j JSON) Value() (driver.Value, error) {
if j == nil {
return nil, nil
}
return string(j), nil
}
func (j JSON) MarshalJSON() ([]byte, error) {
if j == nil {
return []byte("null"), nil
}
return j, nil
}
func (j *JSON) UnmarshalJSON(data []byte) error {
clone := make(JSON, len(data))
copy(clone, data)
*j = clone
return nil
}
It is a []byte with the methods database/sql and encoding/json look for. Scan accepts whatever shape the driver returns for a JSON column, and a nil JSON is SQL NULL. That is why the nullable delivery column is a plain JSON, not a pointer: nil already says "no document".
Reading a document
internal/store
type GetOrderRow struct {
ID int64 `json:"id"`
Customer string `json:"customer"`
Basket JSON `json:"basket"`
Delivery JSON `json:"delivery"`
}
type JSON []byte
func (queries *Queries) GetOrder(ctx context.Context, id int64) (GetOrderRow, error) {
var row GetOrderRow
err := queries.reader.QueryRowContext(ctx, getOrderSQL, id).Scan(&row.ID, &row.Customer, &row.Basket, &row.Delivery)
if err != nil {
return GetOrderRow{}, err
}
return row, nil
}
Searching inside documents
OrdersWithFish finds the orders for one kind of fish, and pulls two things out of each document as it goes.
db/queries/orders.sql
-- sgl.query(OrdersWithFish, many)
-- ?1 as sgl.param(fish)
SELECT
id,
customer,
JSON_EXTRACT(basket, '$.extras') AS extras,
JSON_UNQUOTE(JSON_EXTRACT(delivery, '$.address')) AS address
FROM orders
WHERE JSON_UNQUOTE(JSON_EXTRACT(basket, '$.fish')) = ?1
ORDER BY id;
internal/store
type OrdersWithFishRow struct {
ID int64 `json:"id"`
Customer string `json:"customer"`
Extras JSON `json:"extras"`
Address *string `json:"address"`
}
type JSON []byte
func (queries *Queries) OrdersWithFish(ctx context.Context, fish string) ([]OrdersWithFishRow, error) {
rows, err := queries.reader.QueryContext(ctx, ordersWithFishSQL, fish)
if err != nil {
return nil, err
}
defer rows.Close()
var results []OrdersWithFishRow
for rows.Next() {
var row OrdersWithFishRow
if err := rows.Scan(&row.ID, &row.Customer, &row.Extras, &row.Address); err != nil {
return nil, err
}
results = append(results, row)
}
if err := rows.Err(); err != nil {
return nil, err
}
return results, nil
}
Using it
The program encodes each basket with json.Marshal and places three orders, only one of them for delivery. It reads the first order back and decodes its basket, then searches for the cod orders.
example.go
package main
import (
"context"
"database/sql"
"encoding/json"
"fmt"
"io"
"seagull.sh/seagull/examples/mariadb/006_json/internal/store"
)
// basket is the document an order's basket column holds.
type basket struct {
// Fish is the fish the order is for.
Fish string `json:"fish"`
// Portions is how many portions of fish and chips.
Portions int `json:"portions"`
// Extras lists the sides.
Extras []string `json:"extras"`
}
// delivery is the document an order's delivery column holds, when the order is delivered.
type delivery struct {
// Address is where the order goes.
Address string `json:"address"`
}
// run places three chip shop orders and reads them back. A JSON column becomes the
// generated store.JSON type, which holds the raw document as bytes: encode a value into
// it with json.Marshal and decode it with json.Unmarshal. A nil store.JSON is SQL NULL.
//
// In MariaDB, JSON is another name for LONGTEXT with a JSON_VALID check. An invalid
// document is refused, and a valid one is kept as the text it was written as, so it comes
// back byte for byte: here, in the field order and compact form json.Marshal gave it.
//
// MariaDB has no -> or ->> operators, and sgl vet reports Q010 for them, naming the
// function to use instead. OrdersWithFish calls those functions. JSON_EXTRACT returns a
// JSON fragment, so Extras is store.JSON again, written in MariaDB's own style with a
// space after each comma. JSON_UNQUOTE(JSON_EXTRACT(...)) returns SQL text, so Address is
// *string, NULL when the delivery column or its address is missing. The fish parameter is
// compared with that text, so it is inferred as a string, and its binding line only gives
// it a name in place of p1. JSON_VALUE(basket, '$.fish') is a shorter spelling for a
// single value.
//
// Takes database (*sql.DB) which is a migrated database.
// Takes output (io.Writer) which receives the decoded orders and the search.
//
// Returns error when a query fails or a document does not encode or decode.
func run(ctx context.Context, database *sql.DB, output io.Writer) error {
queries := store.New(database)
orders := []struct {
customer string
basket basket
delivery *delivery
}{
{customer: "Steven", basket: basket{Fish: "cod", Portions: 2, Extras: []string{"mushy peas", "curry sauce"}}},
{customer: "Gwen", basket: basket{Fish: "haddock", Portions: 1, Extras: []string{}}},
{customer: "Morwenna", basket: basket{Fish: "cod", Portions: 1, Extras: []string{"pickled egg"}}, delivery: &delivery{Address: "4 Harbour Row"}},
}
for _, order := range orders {
encodedBasket, err := json.Marshal(order.basket)
if err != nil {
return fmt.Errorf("encoding %s's basket: %w", order.customer, err)
}
parameters := store.PlaceOrderParams{Customer: order.customer, Basket: encodedBasket, Delivery: nil}
if order.delivery != nil {
encodedDelivery, err := json.Marshal(order.delivery)
if err != nil {
return fmt.Errorf("encoding %s's delivery: %w", order.customer, err)
}
parameters.Delivery = encodedDelivery
}
if err := queries.PlaceOrder(ctx, parameters); err != nil {
return fmt.Errorf("placing %s's order: %w", order.customer, err)
}
}
first, err := queries.GetOrder(ctx, 1)
if err != nil {
return fmt.Errorf("getting order 1: %w", err)
}
var decoded basket
if err := json.Unmarshal(first.Basket, &decoded); err != nil {
return fmt.Errorf("decoding order 1's basket: %w", err)
}
fmt.Fprintf(output, "order 1 stored %s\n", first.Basket)
fmt.Fprintf(output, "decoded: %d x %s with %v, delivery is NULL: %t\n", decoded.Portions, decoded.Fish, decoded.Extras, first.Delivery == nil)
cod, err := queries.OrdersWithFish(ctx, "cod")
if err != nil {
return fmt.Errorf("finding cod orders: %w", err)
}
fmt.Fprintln(output, "\ncod orders:")
for _, order := range cod {
address := "collecting"
if order.Address != nil {
address = "to " + *order.Address
}
fmt.Fprintf(output, " order %d %-9s extras %-30s %s\n", order.ID, order.Customer, order.Extras, address)
}
return nil
}
What it prints
order 1 stored {"fish":"cod","portions":2,"extras":["mushy peas","curry sauce"]}
decoded: 2 x cod with [mushy peas curry sauce], delivery is NULL: true
cod orders:
order 1 Steven extras ["mushy peas", "curry sauce"] collecting
order 3 Morwenna extras ["pickled egg"] to 4 Harbour Row
Across engines
Only these Go types of OrdersWithFish differ between engines; the rest are the same everywhere.
| MariaDB | SQLite | PostgreSQL | MySQL | DuckDB | ClickHouse | |
|---|---|---|---|---|---|---|
id column | int64 | int64 | int64 | int64 | int64 | uint64 |
extras column | JSON | JSON | JSON | JSON | JSON | string |
address column | *string | *string | · | *string | *string | *string |
delivery_address column | · | · | *string | · | · | · |
A · marks a parameter or column that version of the example does not have.
CockroachDB and TimescaleDB run the PostgreSQL version unchanged.
Compare the whole example side by side with SQLite, PostgreSQL, MySQL, DuckDB and ClickHouse.
Run it locally
From the directory you cloned the Seagull repository into:
cd seagull/examples/mariadb && go run ./006_json
Its test runs it too, and checks what it prints against output.txt:
cd seagull/examples/mariadb && SGL_EXAMPLE_DSN="$DATABASE_URL" go test ./006_json
Needs a running MariaDB server: set DATABASE_URL, or pass -dsn, to the address of an empty database.
The files
Every file of the example, as it is in the Seagull repository.
sgl.yaml
# Copyright 2026 PolitePixels Limited
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# This project stands against fascism, authoritarianism, and all forms of
# oppression. We built this to empower people, not to enable those who would
# strip others of their rights and dignity.
version: 1
databases:
- name: orders
dialect: mariadb
migrations: db/migrations
queries: db/queries
go:
package: store
out: internal/store
db/migrations/0001_orders.up.sql
CREATE TABLE orders (
id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
customer VARCHAR(50) NOT NULL,
basket JSON NOT NULL,
delivery JSON
);
db/migrations/0001_orders.down.sql
DROP TABLE orders;
db/queries/orders.sql
-- sgl.query(PlaceOrder, exec)
INSERT INTO orders (customer, basket, delivery) VALUES (?, ?, ?);
-- sgl.query(GetOrder, one)
SELECT id, customer, basket, delivery FROM orders WHERE id = ?;
-- sgl.query(OrdersWithFish, many)
-- ?1 as sgl.param(fish)
SELECT
id,
customer,
JSON_EXTRACT(basket, '$.extras') AS extras,
JSON_UNQUOTE(JSON_EXTRACT(delivery, '$.address')) AS address
FROM orders
WHERE JSON_UNQUOTE(JSON_EXTRACT(basket, '$.fish')) = ?1
ORDER BY id;
example.go
package main
import (
"context"
"database/sql"
"encoding/json"
"fmt"
"io"
"seagull.sh/seagull/examples/mariadb/006_json/internal/store"
)
// basket is the document an order's basket column holds.
type basket struct {
// Fish is the fish the order is for.
Fish string `json:"fish"`
// Portions is how many portions of fish and chips.
Portions int `json:"portions"`
// Extras lists the sides.
Extras []string `json:"extras"`
}
// delivery is the document an order's delivery column holds, when the order is delivered.
type delivery struct {
// Address is where the order goes.
Address string `json:"address"`
}
// run places three chip shop orders and reads them back. A JSON column becomes the
// generated store.JSON type, which holds the raw document as bytes: encode a value into
// it with json.Marshal and decode it with json.Unmarshal. A nil store.JSON is SQL NULL.
//
// In MariaDB, JSON is another name for LONGTEXT with a JSON_VALID check. An invalid
// document is refused, and a valid one is kept as the text it was written as, so it comes
// back byte for byte: here, in the field order and compact form json.Marshal gave it.
//
// MariaDB has no -> or ->> operators, and sgl vet reports Q010 for them, naming the
// function to use instead. OrdersWithFish calls those functions. JSON_EXTRACT returns a
// JSON fragment, so Extras is store.JSON again, written in MariaDB's own style with a
// space after each comma. JSON_UNQUOTE(JSON_EXTRACT(...)) returns SQL text, so Address is
// *string, NULL when the delivery column or its address is missing. The fish parameter is
// compared with that text, so it is inferred as a string, and its binding line only gives
// it a name in place of p1. JSON_VALUE(basket, '$.fish') is a shorter spelling for a
// single value.
//
// Takes database (*sql.DB) which is a migrated database.
// Takes output (io.Writer) which receives the decoded orders and the search.
//
// Returns error when a query fails or a document does not encode or decode.
func run(ctx context.Context, database *sql.DB, output io.Writer) error {
queries := store.New(database)
orders := []struct {
customer string
basket basket
delivery *delivery
}{
{customer: "Steven", basket: basket{Fish: "cod", Portions: 2, Extras: []string{"mushy peas", "curry sauce"}}},
{customer: "Gwen", basket: basket{Fish: "haddock", Portions: 1, Extras: []string{}}},
{customer: "Morwenna", basket: basket{Fish: "cod", Portions: 1, Extras: []string{"pickled egg"}}, delivery: &delivery{Address: "4 Harbour Row"}},
}
for _, order := range orders {
encodedBasket, err := json.Marshal(order.basket)
if err != nil {
return fmt.Errorf("encoding %s's basket: %w", order.customer, err)
}
parameters := store.PlaceOrderParams{Customer: order.customer, Basket: encodedBasket, Delivery: nil}
if order.delivery != nil {
encodedDelivery, err := json.Marshal(order.delivery)
if err != nil {
return fmt.Errorf("encoding %s's delivery: %w", order.customer, err)
}
parameters.Delivery = encodedDelivery
}
if err := queries.PlaceOrder(ctx, parameters); err != nil {
return fmt.Errorf("placing %s's order: %w", order.customer, err)
}
}
first, err := queries.GetOrder(ctx, 1)
if err != nil {
return fmt.Errorf("getting order 1: %w", err)
}
var decoded basket
if err := json.Unmarshal(first.Basket, &decoded); err != nil {
return fmt.Errorf("decoding order 1's basket: %w", err)
}
fmt.Fprintf(output, "order 1 stored %s\n", first.Basket)
fmt.Fprintf(output, "decoded: %d x %s with %v, delivery is NULL: %t\n", decoded.Portions, decoded.Fish, decoded.Extras, first.Delivery == nil)
cod, err := queries.OrdersWithFish(ctx, "cod")
if err != nil {
return fmt.Errorf("finding cod orders: %w", err)
}
fmt.Fprintln(output, "\ncod orders:")
for _, order := range cod {
address := "collecting"
if order.Address != nil {
address = "to " + *order.Address
}
fmt.Fprintf(output, " order %d %-9s extras %-30s %s\n", order.ID, order.Customer, order.Extras, address)
}
return nil
}
main.go
// Command 006_json applies its migrations to a MariaDB database, then runs the example in
// example.go: chip shop orders are stored as JSON documents, read back into Go structs
// and searched with JSON_EXTRACT and JSON_UNQUOTE.
//
// Run it with `go run . -dsn 'user:password@tcp(localhost:3306)/orders'`, or set
// DATABASE_URL instead of passing -dsn. Give it an empty database of its own, as the
// migrations create its tables and the example adds rows each time it runs.
package main
import (
"context"
"database/sql"
"embed"
"errors"
"flag"
"fmt"
"log"
"os"
"github.com/go-sql-driver/mysql"
"seagull.sh/seagull/sdk/migrate"
"seagull.sh/seagull/sdk/migrate/migrate_backend_mysql"
)
// migrations holds the migration files, compiled into the binary.
//
//go:embed db/migrations
var migrations embed.FS
func main() {
dsn := flag.String("dsn", os.Getenv("DATABASE_URL"), "MariaDB data source name; defaults to $DATABASE_URL")
flag.Parse()
if err := execute(context.Background(), *dsn); err != nil {
log.Fatal(err)
}
}
// execute opens and migrates the database dsn names, and runs the example against it.
//
// Takes dsn (string) which is the database's data source name.
//
// Returns error when the database cannot be prepared or the example fails.
func execute(ctx context.Context, dsn string) error {
if dsn == "" {
return errors.New("set -dsn or DATABASE_URL to a MariaDB data source name")
}
config, err := mysql.ParseDSN(dsn)
if err != nil {
return err
}
// Seagull maps DATETIME and TIMESTAMP columns to time.Time, which the driver returns
// only when parseTime is set.
config.ParseTime = true
dsn = config.FormatDSN()
database, err := sql.Open("mysql", dsn)
if err != nil {
return err
}
defer func() { _ = database.Close() }()
migrator, err := migrate.NewMigrator(database, migrate_backend_mysql.New(migrate.WithDriverMultiStatements(config.MultiStatements)), migrations, "db/migrations")
if err != nil {
return err
}
if _, err := migrator.Up(ctx); err != nil {
return fmt.Errorf("migrating: %w", err)
}
return run(ctx, database, os.Stdout)
}
internal/store/models.go
// Code generated by sgl. DO NOT EDIT.
package store
type Orders struct {
ID int64 `json:"id"`
Customer string `json:"customer"`
Basket JSON `json:"basket"`
Delivery JSON `json:"delivery"`
}
internal/store/orders.sql.go
// Code generated by sgl. DO NOT EDIT.
package store
import "context"
const getOrderSQL = `SELECT id, customer, basket, delivery FROM orders WHERE id = ?;`
type GetOrderRow struct {
ID int64 `json:"id"`
Customer string `json:"customer"`
Basket JSON `json:"basket"`
Delivery JSON `json:"delivery"`
}
func (queries *Queries) GetOrder(ctx context.Context, id int64) (GetOrderRow, error) {
var row GetOrderRow
err := queries.reader.QueryRowContext(ctx, getOrderSQL, id).Scan(&row.ID, &row.Customer, &row.Basket, &row.Delivery)
if err != nil {
return GetOrderRow{}, err
}
return row, nil
}
const ordersWithFishSQL = `SELECT
id,
customer,
JSON_EXTRACT(basket, '$.extras') AS extras,
JSON_UNQUOTE(JSON_EXTRACT(delivery, '$.address')) AS address
FROM orders
WHERE JSON_UNQUOTE(JSON_EXTRACT(basket, '$.fish')) = ?
ORDER BY id;`
type OrdersWithFishRow struct {
ID int64 `json:"id"`
Customer string `json:"customer"`
Extras JSON `json:"extras"`
Address *string `json:"address"`
}
func (queries *Queries) OrdersWithFish(ctx context.Context, fish string) ([]OrdersWithFishRow, error) {
rows, err := queries.reader.QueryContext(ctx, ordersWithFishSQL, fish)
if err != nil {
return nil, err
}
defer rows.Close()
var results []OrdersWithFishRow
for rows.Next() {
var row OrdersWithFishRow
if err := rows.Scan(&row.ID, &row.Customer, &row.Extras, &row.Address); err != nil {
return nil, err
}
results = append(results, row)
}
if err := rows.Err(); err != nil {
return nil, err
}
return results, nil
}
const placeOrderSQL = `INSERT INTO orders (customer, basket, delivery) VALUES (?, ?, ?);`
type PlaceOrderParams struct {
Customer string
Basket JSON
Delivery JSON
}
func (queries *Queries) PlaceOrder(ctx context.Context, params PlaceOrderParams) error {
_, err := queries.writer.ExecContext(ctx, placeOrderSQL, params.Customer, params.Basket, params.Delivery)
return err
}
internal/store/querier.go
// Code generated by sgl. DO NOT EDIT.
// Package store reads DATETIME, DATE and TIMESTAMP columns into time.Time, so the DSN it connects with must set parseTime=true.
package store
import (
"context"
"database/sql"
)
type DBTX interface {
ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}
type dbtxWrapper interface {
WrapDBTX(inner any) any
}
type Queries struct {
reader DBTX
writer DBTX
wrapper dbtxWrapper
}
func New(db DBTX) *Queries {
wrapper, _ := db.(dbtxWrapper)
return &Queries{reader: db, writer: db, wrapper: wrapper}
}
func NewWithReplica(writer DBTX, reader DBTX) *Queries {
wrapper, _ := writer.(dbtxWrapper)
return &Queries{reader: reader, writer: writer, wrapper: wrapper}
}
func (queries *Queries) WithTx(transaction *sql.Tx) *Queries {
if queries == nil {
return &Queries{reader: transaction, writer: transaction, wrapper: nil}
}
db := queries.wrapDBTX(transaction)
return &Queries{reader: db, writer: db, wrapper: queries.wrapper}
}
func (queries *Queries) wrapDBTX(db DBTX) DBTX {
if queries.wrapper == nil {
return db
}
wrapped, ok := queries.wrapper.WrapDBTX(db).(DBTX)
if !ok {
return db
}
return wrapped
}
func (queries *Queries) RunInTx(ctx context.Context, db *sql.DB, fn func(*Queries) error) error {
transaction, err := db.BeginTx(ctx, nil)
if err != nil {
return err
}
defer transaction.Rollback()
if err = fn(queries.WithTx(transaction)); err != nil {
return err
}
return transaction.Commit()
}
internal/store/sgl_json.go
// Code generated by sgl. DO NOT EDIT.
package store
import (
"database/sql/driver"
"encoding/json"
"fmt"
)
type JSON []byte
func (j *JSON) Scan(source any) error {
switch value := source.(type) {
case nil:
*j = nil
return nil
case []byte:
clone := make(JSON, len(value))
copy(clone, value)
*j = clone
return nil
case string:
*j = JSON(value)
return nil
default:
encoded, err := json.Marshal(value)
if err != nil {
return fmt.Errorf("sgl: encode %T to JSON: %w", source, err)
}
*j = encoded
return nil
}
}
func (j JSON) Value() (driver.Value, error) {
if j == nil {
return nil, nil
}
return string(j), nil
}
func (j JSON) MarshalJSON() ([]byte, error) {
if j == nil {
return []byte("null"), nil
}
return j, nil
}
func (j *JSON) UnmarshalJSON(data []byte) error {
clone := make(JSON, len(data))
copy(clone, data)
*j = clone
return nil
}
output.txt
order 1 stored {"fish":"cod","portions":2,"extras":["mushy peas","curry sauce"]}
decoded: 2 x cod with [mushy peas curry sauce], delivery is NULL: true
cod orders:
order 1 Steven extras ["mushy peas", "curry sauce"] collecting
order 3 Morwenna extras ["pickled egg"] to 4 Harbour Row