sqlconnect

Documentation

Index

• Variables
• func QueryAsync[T any](ctx context.Context, db QueryDB, mapper RowMapper[T], query string, ...) (ch <-chan ValueOrError[T], leave func())
• func QueryJSONAsync(ctx context.Context, db JsonQueryDB, query string, params ...any) (ch <-chan ValueOrError[json.RawMessage], leave func())
• func QueryJSONMapAsync(ctx context.Context, db JsonQueryDB, query string, params ...any) (ch <-chan ValueOrError[map[string]any], leave func())
• func RegisterDBFactory(name string, factory DBFactory)
• type CatalogAdmin
• type ColumnRef
• type DB
  • func NewDB(name string, credentialsJSON json.RawMessage) (DB, error)
• type DBFactory
• type Dialect
• type JsonQueryDB
• type JsonRowMapper
• type NilAny
  • func (v *NilAny) Scan(src any) error
• type Option
  • func WithCatalog(catalog string) Option
  • func WithRelationType(relationType RelationType) Option
  • func WithSchema(schema string) Option
• type QueryCondition
• type QueryDB
• type QueryDef
  • func (query *QueryDef) ToSQL(d Dialect) string
• type QueryOrder
• type RelationRef
  • func NewRelationRef(name string, options ...Option) RelationRef
  • func NewSchemaTableRef(schema, table string) RelationRef
  • func (t RelationRef) String() string
  • func (r *RelationRef) UnmarshalJSON(data []byte) error
• type RelationRefOption
• type RelationType
• type RowMapper
  • func JSONRowMapper(valueMapper func(databaseTypeName string, value any) any) RowMapper[map[string]any]
• type RowScan
• type SchemaAdmin
• type SchemaRef
  • func (s SchemaRef) String() string
• type TableAdmin
• type ValueOrError

Variables

var (
	ErrNotSupported         = errors.New("sqconnect: feature not supported")
	ErrDropOldTablePostCopy = errors.New("sqlconnect move table: dropping old table after copying its contents to the new table")
)

Functions

func QueryAsync

func QueryAsync[T any](ctx context.Context, db QueryDB, mapper RowMapper[T], query string, params ...any) (ch <-chan ValueOrError[T], leave func())

QueryAsync executes a query and returns a channel that will receive the results or an error, along with a function that the caller can use to leave the channel early. The channel will be closed when the query is done or when the context is canceled.

func QueryJSONAsync

func QueryJSONAsync(ctx context.Context, db JsonQueryDB, query string, params ...any) (ch <-chan ValueOrError[json.RawMessage], leave func())

QueryJSONAsync executes a query and returns a channel that will receive the results as json or an error, along with a function that the caller can use to leave the channel early. The channel will be closed when the query is done or when the context is canceled.

func QueryJSONMapAsync

func QueryJSONMapAsync(ctx context.Context, db JsonQueryDB, query string, params ...any) (ch <-chan ValueOrError[map[string]any], leave func())

QueryJSONMapAsync executes a query and returns a channel that will receive the results as a map or an error, along with a function that the caller can use to leave the channel early. The channel will be closed when the query is done or when the context is canceled.

func RegisterDBFactory

func RegisterDBFactory(name string, factory DBFactory)

Types

type CatalogAdmin

type CatalogAdmin interface {
	// CurrentCatalog returns the current catalog.
	// If this operation is not supported by the warehouse [ErrNotSupported] will be returned.
	CurrentCatalog(ctx context.Context) (string, error)
}

type ColumnRef

type ColumnRef struct {
	Name    string `json:"name"`
	Type    string `json:"type"`
	RawType string `json:"rawType"`
}

ColumnRef provides a reference to a table column

type DB

type DB interface {

	// SqlDB returns the underlying *sql.DB
	SqlDB() *sql.DB
	CatalogAdmin
	SchemaAdmin
	TableAdmin
	JsonRowMapper
	Dialect
	// contains filtered or unexported methods
}

func NewDB

func NewDB(name string, credentialsJSON json.RawMessage) (DB, error)

NewDB creates a new database client for the provided name.

type DBFactory

type DBFactory func(credentialsJSON json.RawMessage) (DB, error)

type Dialect

type Dialect interface {
	// QuoteTable quotes a table name
	QuoteTable(table RelationRef) string
	// QuoteIdentifier quotes an identifier, e.g. a column name
	QuoteIdentifier(name string) string
	// FormatTableName formats a table name, typically by lower or upper casing it, depending on the database
	FormatTableName(name string) string
}

type JsonQueryDB

type JsonQueryDB interface {
	JsonRowMapper
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

type JsonRowMapper

type JsonRowMapper interface {
	// JSONRowMapper returns a row mapper that maps rows to map[string]any
	JSONRowMapper() RowMapper[map[string]any]
}

type NilAny

type NilAny struct {
	Value any
}

func (*NilAny) Scan

func (v *NilAny) Scan(src any) error

type Option

type Option func(options *RelationRefOption)

func WithCatalog

func WithCatalog(catalog string) Option

func WithRelationType

func WithRelationType(relationType RelationType) Option

func WithSchema

func WithSchema(schema string) Option

type QueryCondition

type QueryCondition struct {
	Column   string `json:"column,omitempty"`
	Operator string `json:"operator,omitempty"`
	Value    string `json:"value,omitempty"`
}

QueryCondition defines a query condition.

type QueryDB

type QueryDB interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

type QueryDef

type QueryDef struct {
	Table      RelationRef       `json:"table"`                // Reference to table that should be queried
	Columns    []string          `json:"columns,omitempty"`    // Columns that should be included. Defaults to "*" if nil or empty.
	Conditions []*QueryCondition `json:"conditions,omitempty"` // Conditions is a list of query conditions.
	OrderBy    *QueryOrder       `json:"order_by,omitempty"`   // OrderBy defines the query's order by clause.
}

QueryDef describes a query that consists of a table and columns that should be queried.

func (*QueryDef) ToSQL

func (query *QueryDef) ToSQL(d Dialect) string

type QueryOrder

type QueryOrder struct {
	Column string // the order by column
	Order  string // supported values are ('ASC', 'DESC')
}

QueryOrder defines the query's order by clause.This only supports one order by column.

type RelationRef

type RelationRef struct {
	Name    string       `json:"name"`              // the relation's name
	Schema  string       `json:"schema,omitempty"`  // the relation's schema
	Catalog string       `json:"catalog,omitempty"` // the relation's catalog
	Type    RelationType `json:"type,omitempty"`    // the relation's type
}

RelationRef provides a reference to a database table

func NewRelationRef

func NewRelationRef(name string, options ...Option) RelationRef

func NewSchemaTableRef

func NewSchemaTableRef(schema, table string) RelationRef

NewSchemaTableRef creates a new RelationRef with a schema and a table

func (RelationRef) String

func (t RelationRef) String() string

func (*RelationRef) UnmarshalJSON

func (r *RelationRef) UnmarshalJSON(data []byte) error

type RelationRefOption

type RelationRefOption struct {
	Schema  string
	Catalog string
	Type    RelationType
}

type RelationType

type RelationType string

const (
	TableRelation RelationType = "table"
	ViewRelation  RelationType = "view"
)

type RowMapper

type RowMapper[T any] func(cols []*sql.ColumnType, row RowScan) (T, error)

RowMapper is a function that maps database rows to a value

func JSONRowMapper

func JSONRowMapper(valueMapper func(databaseTypeName string, value any) any) RowMapper[map[string]any]

JSONRowMapper returns a row mapper that scans rows and maps them to [map[string]any]

type RowScan

type RowScan interface {
	Scan(dest ...any) error
}

RowScan is an interface that represents a row scanner

type SchemaAdmin

type SchemaAdmin interface {
	// CreateSchema creates a schema
	CreateSchema(ctx context.Context, schema SchemaRef) error
	// GetSchemas returns a list of schemas
	ListSchemas(ctx context.Context) ([]SchemaRef, error)
	// SchemaExists returns true if the schema exists
	SchemaExists(ctx context.Context, schemaRef SchemaRef) (bool, error)
	// DropSchema drops a schema
	DropSchema(ctx context.Context, schema SchemaRef) error
}

type SchemaRef

type SchemaRef struct {
	Name string `json:"name"` // the schema
}

SchemaRef provides a reference to a database schema

func (SchemaRef) String

func (s SchemaRef) String() string

type TableAdmin

type TableAdmin interface {
	// CreateTestTable creates a test table
	CreateTestTable(ctx context.Context, relation RelationRef) error
	// ListTables returns a list of tables in the given schema
	ListTables(ctx context.Context, schema SchemaRef) ([]RelationRef, error)
	// ListTablesWithPrefix returns a list of tables in the given schema that have the given prefix
	ListTablesWithPrefix(ctx context.Context, schema SchemaRef, prefix string) ([]RelationRef, error)
	// TableExists returns true if the table exists
	TableExists(ctx context.Context, relation RelationRef) (bool, error)
	// ListColumns returns a list of columns for the given table
	ListColumns(ctx context.Context, relation RelationRef) ([]ColumnRef, error)
	// ListColumnsForSqlQuery returns a list of columns for the given sql query
	ListColumnsForSqlQuery(ctx context.Context, sql string) ([]ColumnRef, error)
	// CountTableRows returns the number of rows in the given table
	CountTableRows(ctx context.Context, table RelationRef) (count int, err error)
	// DropTable drops a table
	DropTable(ctx context.Context, ref RelationRef) error
	// TruncateTable truncates a table
	TruncateTable(ctx context.Context, ref RelationRef) error
	// RenameTable renames a table. It might fall back to using MoveTable if the underlying database does not support renaming tables.
	RenameTable(ctx context.Context, oldRef, newRef RelationRef) error
	// MoveTable creates a new table by copying the old table's contents to it and then drops the old table. Returns [ErrDropOldTablePostCopy] if the old table could not be dropped after copy.
	MoveTable(ctx context.Context, oldRef, newRef RelationRef) error
	// CreateTableFromQuery creates a table from the results of a query
	CreateTableFromQuery(ctx context.Context, table RelationRef, query string) error
	// GetRowCountForQuery returns the number of rows returned by the query
	GetRowCountForQuery(ctx context.Context, query string, params ...any) (int, error)
}

type ValueOrError

type ValueOrError[T any] struct {
	Value T
	Err   error
}

ValueOrError represents a value or an error