mssql

README

mssql-uuid

• Go implementation of MS SQL Server uniqueidentifier type.
• Implements the JSON Marshal/Unmarshal and SQL Scan interfaces to ensure that data is read correctly from DB.
• The uniqueidentifier data type is a 16-byte GUID*.
• This data type is used as primary key alternative to identity columns.
• uniqueidentifier is globally unique, whereas identity is unique within a table.
• Can be used alongside ORM such as GORM

Example

package main

import uuid "github.com/tentone/mssql-uuid"

func main() {
	var uid uuid.UUID = uuid.NewV4()
	print(uid.String())
}

UUID Storage

• Microsoft implementation of UUID uses litle endian for the first half the first 8 bytes, and big Endian encoding for the second 8 bytes.
• Because of this other UUID libs fail to correctly parse the data.

LLLLLLLL-LLLL-LLLL-BBBB-BBBBBBBBBBBB

License

• The project is distributed under MIT license.
• The lincese is available on the repository.

Documentation

Index

• Constants
• Variables
• func Batch(uuids []UUID, size int, onBatch func(uuids []UUID) error) error
• func DefaultHWAddrFunc() (net.HardwareAddr, error)
• func Equal(u1 UUID, u2 UUID) bool
• type Generator
  • func NewRFC4122Generator() *Generator
  • func (g *Generator) NewV4() (UUID, error)
• type NullUUID
  • func (u *NullUUID) MarshalJSON() ([]byte, error)
  • func (u *NullUUID) Scan(src any) error
  • func (u *NullUUID) UnmarshalJSON(body []byte) error
  • func (u NullUUID) Value() (driver.Value, error)
• type UUID
  • func FromBytes(input []byte) (u UUID, err error)
  • func FromBytesOrNil(input []byte) UUID
  • func FromString(input string) (u UUID, err error)
  • func FromStringOrNil(input string) UUID
  • func NewV4() UUID
  • func (u UUID) Bytes() []byte
  • func (u UUID) MarshalBinary() (data []byte, err error)
  • func (u *UUID) MarshalJSON() ([]byte, error)
  • func (u UUID) MarshalText() (text []byte, err error)
  • func (u *UUID) Scan(src any) error
  • func (u *UUID) SetFromMSSQLBytes(data []byte) error
  • func (u *UUID) SetVariant(v byte)
  • func (u *UUID) SetVersion(v byte)
  • func (u *UUID) String() string
  • func (u *UUID) UnmarshalBinary(data []byte) error
  • func (u *UUID) UnmarshalJSON(body []byte) error
  • func (u *UUID) UnmarshalText(t []byte) (err error)
  • func (u UUID) Value() (driver.Value, error)
  • func (u UUID) Variant() byte
  • func (u UUID) Version() byte

Constants

const (
	VariantNCS byte = iota
	VariantRFC4122
	VariantMicrosoft
	VariantFuture
)

UUID layout variants.

const CanonicalSize = 36

Size of a canonical representation of UUID in bytes.

const Size = 16

Size of a UUID in bytes.

const (
	V4 byte
)

UUID versions

Variables

var NilUUID = UUID{}

Nil is special form of UUID that is specified to have all 128 bits set to zero.

Functions

func Batch

func Batch(uuids []UUID, size int, onBatch func(uuids []UUID) error) error

Can be used to split slices of UUIDs into multiple subslices with a defined size.

func DefaultHWAddrFunc

func DefaultHWAddrFunc() (net.HardwareAddr, error)

Returns hardware address.

func Equal

func Equal(u1 UUID, u2 UUID) bool

Equal returns true if u1 and u2 equals, otherwise returns false.

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Default generator implementation.

func NewRFC4122Generator

func NewRFC4122Generator() *Generator

func (*Generator) NewV4

func (g *Generator) NewV4() (UUID, error)

NewV4 returns random generated UUID.

type NullUUID

type NullUUID struct {
	UUID

	Valid bool
}

NullUUID can be used with the standard sql package to represent a UUID value that can be NULL in the database.

Contains a Valid parameter using to check if the UUID value is null or not.

func (*NullUUID) MarshalJSON

func (u *NullUUID) MarshalJSON() ([]byte, error)

Implements the json.Marshaler interface.

Marshal JSON value as string using the canonical format

func (*NullUUID) Scan

func (u *NullUUID) Scan(src any) error

Scan implements the sql.Scanner interface.

Used to read the value provided by the SQL server.

func (*NullUUID) UnmarshalJSON

func (u *NullUUID) UnmarshalJSON(body []byte) error

Implements the json.Unmarshaler interface.

Unmarshal JSON value from canonical format

func (NullUUID) Value

func (u NullUUID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Used to provide a value to the SQL server for storage.

type UUID

type UUID [Size]byte

UUID representation compliant with specification described in RFC 4122.

func FromBytes

func FromBytes(input []byte) (u UUID, err error)

FromBytes returns UUID converted from raw byte slice input.

It will return error if the slice isn't 16 bytes long.

func FromBytesOrNil

func FromBytesOrNil(input []byte) UUID

FromBytesOrNil returns UUID converted from raw byte slice input.

Same behavior as FromBytes, but returns a Nil UUID on error.

func FromString

func FromString(input string) (u UUID, err error)

FromString returns UUID parsed from string input.

Input is expected in a form accepted by UnmarshalText.

func FromStringOrNil

func FromStringOrNil(input string) UUID

FromStringOrNil returns UUID parsed from string input.

Same behavior as FromString but returns a Nil UUID on error.

func NewV4

func NewV4() UUID

NewV4 returns random generated UUID.

func (UUID) Bytes

func (u UUID) Bytes() []byte

Bytes returns bytes slice representation of UUID.

func (UUID) MarshalBinary

func (u UUID) MarshalBinary() (data []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (*UUID) MarshalJSON

func (u *UUID) MarshalJSON() ([]byte, error)

Implements the json.Marshaler interface.

Marshal JSON value as string using the canonical format

func (UUID) MarshalText

func (u UUID) MarshalText() (text []byte, err error)

MarshalText implements the encoding.TextMarshaler interface.

The encoding is the same as returned by String.

func (*UUID) Scan

func (u *UUID) Scan(src any) error

Scan implements the sql.Scanner interface with a solution specific for MSSQL.

A 16-byte slice is handled by UnmarshalBinary, while a longer byte slice or a string is handled by UnmarshalText.

func (*UUID) SetFromMSSQLBytes

func (u *UUID) SetFromMSSQLBytes(data []byte) error

Set UUID from data fetched from a MSSQL Server as unique identifier.

SQL server stores UUID in a different way some conversion is required.

func (*UUID) SetVariant

func (u *UUID) SetVariant(v byte)

SetVariant sets variant bits.

func (*UUID) SetVersion

func (u *UUID) SetVersion(v byte)

SetVersion sets version bits.

func (*UUID) String

func (u *UUID) String() string

Returns canonical string representation of UUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

func (*UUID) UnmarshalBinary

func (u *UUID) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

It will return error if the slice isn't 16 bytes long.

func (*UUID) UnmarshalJSON

func (u *UUID) UnmarshalJSON(body []byte) error

Implements the json.Unmarshaler interface.

Unmarshal JSON value from canonical format

func (*UUID) UnmarshalText

func (u *UUID) UnmarshalText(t []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface.

Following format is supported "6ba7b810-9dad-11d1-80b4-00c04fd430c8",

func (UUID) Value

func (u UUID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Exports the value as a canonical string that most SQL servers supports.

func (UUID) Variant

func (u UUID) Variant() byte

Variant returns UUID layout variant.

func (UUID) Version

func (u UUID) Version() byte

Version returns algorithm version used to generate UUID.