schema

type FieldMeta struct {
	Index     int
	Column    string // value of the db:"" tag (without options)
	Kind      reflect.Kind
	Type      reflect.Type
	IsPK      bool
	OldColumn string // for renames
	NotNull   bool   // from tag: quark:"not_null" or nullable:"false"
	Default   string // from tag: default:"value"
	Unique    bool   // from tag: quark:"unique"

	// SQL-type sizing options parsed from the db tag, e.g.
	//   db:"name,size=512"
	//   db:"price,precision=18,scale=4"
	// A zero value means "use the dialect default for the Go type". The
	// migrate layer applies these to VARCHAR/CHAR sizing and DECIMAL
	// precision/scale; custom type mappers can read them via TypeOptions.
	Size      int
	Precision int
	Scale     int

	// IsVersion marks the field as the optimistic-locking version column.
	// Set by quark:"version". When present, Update / UpdateFields /
	// Tracked.Save include "version = version + 1" in SET and
	// "AND version = ?" in WHERE; a zero rows-affected on the response
	// surfaces ErrStaleEntity. Only one field per model may carry this tag.
	IsVersion bool

	// TZName is the raw IANA timezone string from quark:"tz=Europe/Madrid",
	// or "" when the field has no tz tag. TZ is the parsed *time.Location.
	// Parsing happens eagerly in computeModelMeta (no lazy load): an
	// invalid name leaves both zero-valued and records ModelMeta.TZError.
	// When TZ is non-nil the bind path converts the field's time.Time to
	// UTC for the wire and the scan path applies .In(TZ) in memory.
	// Applies to time.Time, *time.Time and Nullable[time.Time] fields;
	// ignored for non-time Go types.
	TZName string
	TZ     *time.Location
}

type ModelMeta struct {
	Table          string
	PK             PKMeta
	HasPK          bool
	CompositePK    []PKMeta // populated when two or more fields carry pk:"true"
	HasCompositePK bool     // true when len(CompositePK) > 1
	Fields         []FieldMeta
	FieldByCol     map[string]*FieldMeta    // lookup by db column name
	Relations      map[string]*RelationMeta // lookup by field name

	// VersionFieldIndex is the FieldMeta index of the optimistic-locking
	// version column, or -1 when the model does not have one. Cached at
	// schema-compute time so the hot Update / Save paths don't have to
	// re-scan Fields.
	VersionFieldIndex int

	// HasTZ is true when at least one field carries a valid quark:"tz=..."
	// tag. The hot bind / scan paths read this flag first so models that
	// don't use per-column timezones pay nothing — no FieldByCol lookup,
	// no type switch.
	HasTZ bool

	// TZError holds the first timezone-parsing failure encountered while
	// computing this model's metadata, or nil. computeModelMeta cannot
	// return an error (the public GetModelMeta API doesn't expose one),
	// so an invalid quark:"tz=..." value is recorded here and surfaced
	// fail-fast by Client.RegisterModel / Client.Migrate, which wrap it
	// in quark.ErrInvalidTimezone.
	TZError error
}

type PKMeta struct {
	Column string
	Index  int
	Kind   reflect.Kind
}

type RelationMeta struct {
	Type           string       // "has_one", "has_many", "belongs_to", "m2m", "polymorphic"
	Field          string       // struct field name
	JoinCol        string       // foreign key column (for belongs_to, has_one, has_many)
	JoinTable      string       // join table name (for m2m)
	JoinFK         string       // foreign key in join table pointing to this model (for m2m)
	JoinRefFK      string       // foreign key in join table pointing to related model (for m2m)
	PolyType       string       // polymorphic type identifier (for polymorphic)
	PolyTypeColumn string       // column storing the polymorphic type (for polymorphic)
	PolyIDColumn   string       // column storing the polymorphic foreign key (for polymorphic)
	RefType        reflect.Type // type of the related model (the struct type)
	IsSlice        bool         // true for has_many, m2m
}

type TableNamer interface {
	TableName() string
}