bun

Bun Writer

Generates Go source files with Bun model definitions from database schema information.

Overview

The Bun Writer converts RelSpec's internal database model representation into Go source code with Bun struct definitions, complete with proper tags, relationships, and table configuration.

Features

• Generates Bun-compatible Go structs
• Creates proper bun struct tags
• Adds relationship fields
• Supports both single-file and multi-file output
• Maps SQL types to Go types
• Handles nullable fields with sql.Null* types
• Generates table aliases

Usage

Basic Example

package main

import (
    "git.warky.dev/wdevs/relspecgo/pkg/models"
    "git.warky.dev/wdevs/relspecgo/pkg/writers"
    "git.warky.dev/wdevs/relspecgo/pkg/writers/bun"
)

func main() {
    options := &writers.WriterOptions{
        OutputPath:  "models.go",
        PackageName: "models",
    }

    writer := bun.NewWriter(options)
    err := writer.WriteDatabase(db)
    if err != nil {
        panic(err)
    }
}

CLI Examples

# Generate Bun models from a DBML schema (default: resolvespec types)
relspec convert --from dbml --from-path schema.dbml \
  --to bun --to-path models.go --package models

# Use standard library database/sql nullable types instead of resolvespec
relspec convert --from dbml --from-path schema.dbml \
  --to bun --to-path models.go --package models \
  --types stdlib

# Explicitly select resolvespec types (same as omitting --types)
relspec convert --from pgsql --from-conn "postgres://localhost/mydb" \
  --to bun --to-path models.go --package models \
  --types resolvespec

# Multi-file output (one file per table)
relspec convert --from json --from-path schema.json \
  --to bun --to-path models/ --package models

Generated Code Examples

Default — resolvespec types (--types resolvespec)

package models

import (
    resolvespec_common "github.com/bitechdev/ResolveSpec/pkg/spectypes"
    "github.com/uptrace/bun"
)

type User struct {
    bun.BaseModel `bun:"table:users,alias:u"`

    ID        int64                              `bun:"id,type:uuid,pk," json:"id"`
    Username  string                             `bun:"username,type:text,notnull," json:"username"`
    Email     resolvespec_common.SqlString       `bun:"email,type:text,nullzero," json:"email"`
    Tags      resolvespec_common.SqlStringArray  `bun:"tags,type:text[],default:'{}',notnull," json:"tags"`
    CreatedAt resolvespec_common.SqlTimeStamp    `bun:"created_at,type:timestamptz,default:now(),notnull," json:"created_at"`
}

Standard library — --types stdlib

package models

import (
    "database/sql"
    "time"
    "github.com/uptrace/bun"
)

type User struct {
    bun.BaseModel `bun:"table:users,alias:u"`

    ID        string         `bun:"id,type:uuid,pk," json:"id"`
    Username  string         `bun:"username,type:text,notnull," json:"username"`
    Email     sql.NullString `bun:"email,type:text,nullzero," json:"email"`
    Tags      []string       `bun:"tags,type:text[],default:'{}',notnull," json:"tags"`
    CreatedAt time.Time      `bun:"created_at,type:timestamptz,default:now(),notnull," json:"created_at"`
}

Supported Bun Tags

• table - Table name and alias
• column - Column name (auto-derived if not specified)
• pk - Primary key
• autoincrement - Auto-increment
• notnull - NOT NULL constraint
• unique - Unique constraint
• default - Default value
• rel - Relationship definition
• type - Explicit SQL type

Type Mapping

The nullable type package is selected with --types (or WriterOptions.NullableTypes).

* In resolvespec mode, NOT NULL timestamps use SqlTimeStamp (not time.Time) unless the base type is a simple integer or boolean. In stdlib mode, NOT NULL timestamps use time.Time.

Writer Options

NullableTypes

Controls which Go package is used for nullable column types. Set via the --types CLI flag or WriterOptions.NullableTypes:

// Use resolvespec types (default — omit NullableTypes or set to "resolvespec")
options := &writers.WriterOptions{
    OutputPath:    "models.go",
    PackageName:   "models",
    NullableTypes: writers.NullableTypeResolveSpec,
}

// Use standard library database/sql types
options := &writers.WriterOptions{
    OutputPath:    "models.go",
    PackageName:   "models",
    NullableTypes: writers.NullableTypeStdlib,
}

Metadata Options

options := &writers.WriterOptions{
    OutputPath:  "models.go",
    PackageName: "models",
    Metadata: map[string]any{
        "multi_file":          true, // Enable multi-file mode
        "populate_refs":       true, // Populate RefDatabase/RefSchema
        "generate_get_id_str": true, // Generate GetIDStr() methods
    },
}

Notes

• Model names are derived from table names (singularized, PascalCase)
• Table aliases are auto-generated from table names
• Nullable columns use resolvespec_common.SqlString, resolvespec_common.SqlTimeStamp, etc. by default; pass --types stdlib to use sql.NullString, sql.NullTime, etc. instead
• Array columns use resolvespec_common.SqlStringArray, resolvespec_common.SqlInt32Array, etc. by default; --types stdlib produces plain Go slices ([]string, []int32, …)
• Multi-file mode: one file per table named sql_{schema}_{table}.go
• Generated code is auto-formatted
• JSON tags are automatically added