sqlconnect

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) (CatalogRef, error)
	// ListCatalogs returns all available catalogs linked to the credentials. System catalogs are filtered out.
	// If this operation is not supported by the warehouse [ErrNotSupported] will be returned.
	ListCatalogs(ctx context.Context) ([]CatalogRef, error)
}

type CatalogRef struct {
	Name string `json:"name"` // the catalog/database name
}

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

type DB interface {

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

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

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

type DBFactoryWithOptions func(credentialsJSON json.RawMessage, opts DBFactoryOptions) (DB, error)

type DBOption interface {
	// contains filtered or unexported methods
}

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.
	// Fabric preserves the original case because its default collation is case-sensitive.
	//
	// 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 DialectFactory func(optionsJSON json.RawMessage) (Dialect, error)

type ErrorClassifier interface {
	ClassifyError(error) ErrorInfo
}

type ErrorInfo struct {
	Category   string
	Code       string
	ServerCode int32
}

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

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)
}

type FilterOptions struct {
	Catalog string
}

type GoquExpression = goqu.Expression

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

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

type MaterializationAdmin interface {
	// CreateTableForQueryWithOptions runs DESCRIBE, CREATE and AwaitTable.
	// It runs no INSERT.
	CreateTableForQueryWithOptions(
		context.Context, QueryExecutor, RelationRef, string, MaterializationOptions,
	) (uuid string, err error)
	// InsertFromQueryWithOptions runs the INSERT ... SELECT into a table
	// that CreateTableForQueryWithOptions created with the same options.
	InsertFromQueryWithOptions(
		context.Context, QueryExecutor, RelationRef, string, MaterializationOptions,
	) error
	// CreateTableFromQueryWithOptions runs both calls above in sequence.
	CreateTableFromQueryWithOptions(
		context.Context, QueryExecutor, RelationRef, string, MaterializationOptions,
	) (uuid string, err error)
	MoveTableWithOptions(
		context.Context, QueryExecutor, RelationRef, RelationRef, MaterializationOptions,
	) (uuid string, err error)
}

type MaterializationOptions struct {
	SortingKey        []string
	RequireSortingKey bool
	AllowNullableKey  bool
	Columns           []ColumnRef
	Visibility        VisibilityPolicy
}

type NilAny struct {
	Value any
}

type Option func(options *Options)

type Options struct {
	Schema  string
	Catalog string
	Type    RelationType
	Prefix  string
}

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

type QueryController interface {
	// StopQuery stops the connector's own query with queryID on the replica
	// that answers. It never stops a query of another user. Query ids must be
	// unique per execution: a reused id lets a stop reach a later query. The
	// outcome is [StopError] exactly when err is not nil. Callers must verify
	// what a stopped write left behind from their own tables.
	StopQuery(ctx context.Context, queryID string) (StopOutcome, error)
}

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

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.
}

type QueryExecutor interface {
	ExecContext(context.Context, string, ...any) (sql.Result, error)
	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
	QueryRowContext(context.Context, string, ...any) *sql.Row
}

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

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
}

type RelationType string

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

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

type SchemaAdmin interface {
	// CreateSchema creates a schema
	CreateSchema(ctx context.Context, schema SchemaRef) error
	// ListSchemas returns a list of schemas.
	//
	// Supported options:
	//   - [WithCatalog]: scope the listing to a specific catalog.
	//
	//	schemas, err := db.ListSchemas(ctx, WithCatalog("my_catalog"))
	ListSchemas(ctx context.Context, opts ...Option) ([]SchemaRef, error)
	// SchemaExists returns true if the schema exists.
	//
	// Supported options:
	//   - [WithCatalog]: scope the check to a specific catalog.
	//
	//	exists, err := db.SchemaExists(ctx, schemaRef, WithCatalog("my_catalog"))
	SchemaExists(ctx context.Context, schemaRef SchemaRef, opts ...Option) (bool, error)
	// DropSchema drops a schema.
	DropSchema(ctx context.Context, schema SchemaRef) error
}

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

type StopOutcome string

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.
	//
	// Supported options:
	//   - [WithCatalog]: scope the listing to a specific catalog.
	//   - [WithPrefix]: filter tables by name prefix.
	//
	//	tables, err := db.ListTables(ctx, schema, WithCatalog("my_catalog"), WithPrefix("test"))
	ListTables(ctx context.Context, schema SchemaRef, opts ...Option) ([]RelationRef, error)
	// TableExists returns true if the table exists. If RelationRef.Catalog is set, the check is scoped to that catalog.
	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 TableListOptions struct {
	Catalog string
	Prefix  string
}

type ValidationOptions struct {
	SyncLogPruning bool
	// WorkingDatabase names the validation working database. ClickHouse has no
	// default and refuses an empty name with CH_CONFIG_INVALID.
	WorkingDatabase string
}

type ValidationReporter interface {
	ValidateContext(context.Context) (ValidationResult, error)
}

type ValidationResult struct {
	ServerVersion string
	GrantsChecked bool
	Warnings      []ValidationWarning
}

type ValidationStageError struct {
	Stage int
	Tag   string
	Err   error
}

type ValidationWarning struct {
	Info      ErrorInfo
	Operation string
}

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

type VisibilityChecker interface {
	// AwaitTable returns the table's UUID once it is visible.
	// A non-empty wantUUID also requires that UUID.
	AwaitTable(ctx context.Context, exec QueryExecutor, ref RelationRef,
		wantUUID string, p VisibilityPolicy) (uuid string, err error)
	// AwaitTableAbsent returns once the name resolves to no table.
	AwaitTableAbsent(ctx context.Context, exec QueryExecutor, ref RelationRef,
		p VisibilityPolicy) error
}

type VisibilityPolicy struct {
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	Deadline       time.Duration
}