sqlcomment

README

sqlcomment

sqlcomment is an ent driver that adds SQL comments following sqlcommenter specification.
sqlcomment includes support for OpenTelemetry and OpenCensus (see examples).

Installing

go install ariga.io/sqlcomment

Basic Usage

// Create db driver.
// make sure to import "entgo.io/ent/dialect/sql" instead of "database/sql"
db, err := sql.Open("sqlite3", "file:ent?mode=memory&cache=shared&_fk=1")
if err != nil {
  log.Fatalf("Failed to connect to database: %v", err)
}
// Create sqlcomment driver which wraps sqlite driver.
drv := sqlcomment.NewDriver(db,
  sqlcomment.WithDriverVerTag(),
  sqlcomment.WithTags(sqlcomment.Tags{
    sqlcomment.KeyApplication: "my-app",
    sqlcomment.KeyFramework:   "net/http",
  }),
)
// Create and configure ent client
client := ent.NewClient(ent.Driver(drv))

Adding context level tags

Suppose you have a REST API and you want to add a tag with the request URL (typically route tag). You can achieve that by using sqlcomment.WithTag(ctx, key, val) which adds the given tag to the context to later be serialized by sqlcomment driver. (see full example here)

// Add a middleware to your HTTP server which puts the `route` tag on the context for every request.
middleware := func(next http.Handler) http.Handler {
  fn := func(w http.ResponseWriter, r *http.Request) {
    ctx := sqlcomment.WithTag(r.Context(), "route", r.URL.Path)
    next.ServeHTTP(w, r.WithContext(ctx))
  }
  return http.HandlerFunc(fn)
}

Documentation

Index

• Constants
• func NewDriver(drv dialect.Driver, options ...Option) dialect.Driver
• func NewDriverVersionTagger() driverVersionTagger
• func NewStaticTagger(tags Tags) staticTagger
• func Skip(ctx context.Context) context.Context
• func WithTag(ctx context.Context, key, val string) context.Context
• type CommentCarrier
  • func NewCommentCarrier() CommentCarrier
  • func (c CommentCarrier) Get(key string) string
  • func (c CommentCarrier) Keys() []string
  • func (c CommentCarrier) Set(key string, value string)
• type Driver
  • func (d *Driver) BeginTx(ctx context.Context, opts *sql.TxOptions) (dialect.Tx, error)
  • func (d *Driver) Exec(ctx context.Context, query string, args, v interface{}) error
  • func (d *Driver) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
  • func (d *Driver) Query(ctx context.Context, query string, args, v interface{}) error
  • func (d *Driver) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
  • func (d *Driver) Tx(ctx context.Context) (dialect.Tx, error)
• type OCTagger
  • func NewOCTagger() OCTagger
  • func (ot OCTagger) Tag(ctx context.Context) Tags
• type OTELTagger
  • func NewOTELTagger() OTELTagger
  • func (ot OTELTagger) Tag(ctx context.Context) Tags
• type Option
  • func WithDriverVerTag() Option
  • func WithTagger(taggers ...Tagger) Option
  • func WithTags(tags Tags) Option
• type Tagger
• type Tags
  • func FromContext(ctx context.Context) Tags
  • func (t Tags) Marshal() string
  • func (t Tags) Merge(tags ...Tags) Tags
• type Tx
  • func (d *Tx) Commit() error
  • func (d *Tx) Exec(ctx context.Context, query string, args, v interface{}) error
  • func (d *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
  • func (d *Tx) Query(ctx context.Context, query string, args, v interface{}) error
  • func (d *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
  • func (d *Tx) Rollback() error

Constants

const (
	KeyDBDriver    = "db_driver"
	KeyFramework   = "framework"
	KeyApplication = "application"
	KeyRoute       = "route"
	KeyController  = "controller"
	KeyAction      = "action"
)

Functions

func NewDriver

func NewDriver(drv dialect.Driver, options ...Option) dialect.Driver

NewDriver decorates the given driver and adds an SQL comment to every query.

func NewDriverVersionTagger

func NewDriverVersionTagger() driverVersionTagger

func NewStaticTagger

func NewStaticTagger(tags Tags) staticTagger

NewStaticTagger returns an Tagger which adds tags to every SQL comment.

func Skip

func Skip(ctx context.Context) context.Context

Skip returns a new Context that tells the Driver to skip the commenting on Query.

client.T.Query().All(sqlcomment.Skip(ctx))

func WithTag

func WithTag(ctx context.Context, key, val string) context.Context

WithTag stores the key and val pair on the context. for example, if you want to add `route` tag to your SQL comment, put the url path on request context:

middleware := func(next http.Handler) http.Handler {
	fn := func(w http.ResponseWriter, r *http.Request) {
		ctx := sqlcomment.WithTag(r.Context(), "route", r.URL.Path)
		next.ServeHTTP(w, r.WithContext(ctx))
	}
	return http.HandlerFunc(fn)
}

Types

type CommentCarrier

type CommentCarrier Tags

CommentCarrier implements propagation.TextMapCarrier in order to retrieve trace information from OTEL.

func NewCommentCarrier

func NewCommentCarrier() CommentCarrier

func (CommentCarrier) Get

func (c CommentCarrier) Get(key string) string

Get returns the value associated with the passed key.

func (CommentCarrier) Keys

func (c CommentCarrier) Keys() []string

Keys lists the keys stored in this carrier.

func (CommentCarrier) Set

func (c CommentCarrier) Set(key string, value string)

Set stores the key-value pair.

type Driver

type Driver struct {
	dialect.Driver // underlying driver.
	// contains filtered or unexported fields
}

Driver is a driver that adds an SQL comment. See: https://google.github.io/sqlcommenter.

func (*Driver) BeginTx

func (d *Driver) BeginTx(ctx context.Context, opts *sql.TxOptions) (dialect.Tx, error)

BeginTx wraps the underlying transaction with commenter and calls the underlying driver BeginTx command if it's supported.

func (*Driver) Exec

func (d *Driver) Exec(ctx context.Context, query string, args, v interface{}) error

Exec adds an SQL comment to the original query and calls the underlying driver Exec method.

func (*Driver) ExecContext

func (d *Driver) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext calls ExecContext of the underlying driver, or fails if it is not supported.

func (*Driver) Query

func (d *Driver) Query(ctx context.Context, query string, args, v interface{}) error

Query adds an SQL comment to the original query and calls the underlying driver Query method.

func (*Driver) QueryContext

func (d *Driver) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext calls QueryContext of the underlying driver, or fails if it is not supported.

func (*Driver) Tx

func (d *Driver) Tx(ctx context.Context) (dialect.Tx, error)

Tx wraps the underlying Tx command with a commenter.

type OCTagger

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

OCTagger is a Tagger that adds `traceparent` and `tracestate` tags to the SQL comment.

func NewOCTagger

func NewOCTagger() OCTagger

NewOCTagger adds OC trace information as SQL tags.

func (OCTagger) Tag

func (ot OCTagger) Tag(ctx context.Context) Tags

Tag finds trace information on the given context and returns SQL tags with trace information.

type OTELTagger

type OTELTagger struct{}

OTELTagger is a Tagger that adds `traceparent` and `tracestate` tags to the SQL comment.

func NewOTELTagger

func NewOTELTagger() OTELTagger

NewOTELTagger adds OTEL trace information as SQL tags.

func (OTELTagger) Tag

func (ot OTELTagger) Tag(ctx context.Context) Tags

Tag finds trace information on the given context and returns SQL tags with trace information.

type Option

type Option func(*options)

func WithDriverVerTag

func WithDriverVerTag() Option

WithDriverVerTag adds `db_driver` tag with the current version of ent.

func WithTagger

func WithTagger(taggers ...Tagger) Option

WithTagger sets the taggers to be used to populate the SQL comment.

func WithTags

func WithTags(tags Tags) Option

WithTags appends the given tags to every SQL query.

type Tagger

type Tagger interface {
	Tag(context.Context) Tags
}

A Tagger is used by the driver to add tags to SQL queries.

type Tags

type Tags map[string]string

Tags represents key value pairs which can be serialized into SQL comment. see https://google.github.io/sqlcommenter/spec/

func FromContext

func FromContext(ctx context.Context) Tags

FromContext returns the tags stored in ctx, if any.

func (Tags) Marshal

func (t Tags) Marshal() string

Marshal returns the sqlcomment encoding of t following the spec (see https://google.github.io/sqlcommenter/).

func (Tags) Merge

func (t Tags) Merge(tags ...Tags) Tags

Merge copies given tags into sc.

type Tx

type Tx struct {
	dialect.Tx // underlying transaction.
	// contains filtered or unexported fields
}

Tx is a transaction implementation that adds an SQL comment.

func (*Tx) Commit

func (d *Tx) Commit() error

Commit commits the underlying Tx.

func (*Tx) Exec

func (d *Tx) Exec(ctx context.Context, query string, args, v interface{}) error

Exec adds an SQL comment and calls the underlying transaction Exec method.

func (*Tx) ExecContext

func (d *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext logs its params and calls the underlying transaction ExecContext method if it is supported.

func (*Tx) Query

func (d *Tx) Query(ctx context.Context, query string, args, v interface{}) error

Query adds an SQL comment and calls the underlying transaction Query method.

func (*Tx) QueryContext

func (d *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext logs its params and calls the underlying transaction QueryContext method if it is supported.

func (*Tx) Rollback

func (d *Tx) Rollback() error

Rollback rolls back the underlying Tx.