sqlconnect

package
v1.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2024 License: MIT Imports: 11 Imported by: 3

Documentation

Index

Constants

This section is empty.

Variables

View Source 
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 added in v1.1.0 

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
	//
	// Deprecated: to be removed in future versions, since its behaviour is not consistent across databases, e.g. using lowercase for BigQuery while it shouldn't.
	// If you want to have a consistent behaviour across databases, use [NormaliseIdentifier] and [ParseRelationRef] instead.
	FormatTableName(name string) string

	// NormaliseIdentifier normalises the identifier's parts that are unquoted, typically by lower or upper casing them, depending on the database
	NormaliseIdentifier(identifier string) string

	// ParseRelationRef parses a string into a RelationRef after normalising the identifier and stripping out surrounding quotes.
	// The result is a RelationRef with case-sensitive fields, i.e. it can be safely quoted (see [QuoteTable] and, for instance, used for matching against the database's information schema.
	ParseRelationRef(identifier string) (RelationRef, error)

	// QueryCondition returns a dialect-specific query expression for the provided identifier, operator and value(s).
	//
	// E.g. QueryCondition("age", "gt", 18) returns "age > 18"
	//
	// Each operator has a different number of arguments, e.g. [eq] requires one argument, [in] requires at least one argument, etc.
	// See [op] package for the list of supported operators
	QueryCondition(identifier, operator string, args ...any) (Expression, error)

	// ParseGoquExpression converts a goqu Expression to an Expression
	ParseGoquExpression(goquExpression GoquExpression) (Expression, error)

	// Expressions returns the dialect-specific expressions
	Expressions() Expressions
}

type Expression added in v1.10.0 

type Expression interface {
	GoquExpression() GoquExpression
	fmt.Stringer
}

Expression represents a dialect-specific expression. One can get the expression's SQL string by calling [String()] on it.

type Expressions added in v1.10.0 

type Expressions interface {
	// TimestampAdd returns an expression that adds the interval to the timestamp value.
	// The value can either be a string literal (column, timestamp, function etc.) or a [time.Time] value.
	TimestampAdd(timeValue any, interval int, unit string) (Expression, error)

	// DateAdd returns an expression that adds the interval to the date value.
	// The value can either be a string literal (column, timestamp, function etc.) or a [time.Time] value.
	// Values are cast to [DATE].
	DateAdd(dateValue any, interval int, unit string) (Expression, error)

	// Literal creates a literal sql expression
	Literal(sql string, args ...any) (Expression, error)
}

Expressions provides dialect-specific expressions

type GoquExpression added in v1.10.0 

type GoquExpression = goqu.Expression

GoquExpression represents a goqu expression

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
cleanup
internal
base
bigquery
bigquery/driver
databricks
integration_test
mysql
postgres
redshift
redshift/driver
snowflake
sshtunnel
trino
util

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.