Documentation
¶
Overview ¶
Copyright 2026 SGNL.ai, Inc.
Copyright 2026 SGNL.ai, Inc.
Copyright 2026 SGNL.ai, Inc.
Copyright 2026 SGNL.ai, Inc.
Index ¶
- Constants
- func BuildCompositeID(row map[string]interface{}, columns []UniqueConstraintColumn, separator string) string
- func ConstructQuery(request *Request) (string, []any, error)
- func NewAdapter(client Client) framework.Adapter[Config]
- type Adapter
- type Client
- type Config
- type Datasource
- func (d *Datasource) ExtractUniqueKeyColumns(ctx context.Context, tableName string) ([]string, error)
- func (d *Datasource) GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)
- func (d *Datasource) TestConnection(ctx context.Context, request *Request) (*Response, *framework.Error)
- type MockRows
- type MockSQLClient
- type Request
- type Response
- type Rows
- type SQLClient
- type SQLColumnTypes
- type SQLRow
- type SQLRows
- type UniqueConstraintColumn
Constants ¶
const ( // DB2DriverName is the driver name used for sql.Open() calls. DB2DriverName = "go_ibm_db" // DefaultDB2Port is the default port for DB2 connections. DefaultDB2Port = "50000" // ConnectionStringFormat is the format template for DB2 connection strings. // Parameters: hostname, database, username, password, port. ConnectionStringFormat = "HOSTNAME=%s;DATABASE=%s;UID=%s;PWD=%s;PORT=%s;PROTOCOL=TCPIP" // SSLConnectionSuffix is appended to connection strings when SSL is enabled. // Parameter: certificate file path. SSLConnectionSuffix = ";SECURITY=SSL;SSLServerCertificate=%s" )
DB2 connection constants.
const ( DefaultMaxOpenConns = 25 DefaultMaxIdleConns = 5 DefaultConnMaxLifetime = 5 * time.Minute DefaultPingTimeout = 10 * time.Second )
Connection pool defaults for DB2 database connections.
const CompositeIDKey = "composite_id"
CompositeIDKey is the row map key used to store a generated composite ID for tables with multi-column primary keys. It is set during row processing and read back during cursor generation for pagination.
const SyntheticIDAttr = "id"
SyntheticIDAttr is the attribute external ID that signals the adapter should generate a unique identifier from the table's primary key columns rather than reading an existing column value.
const TotalRemainingRowsColumn = "total_remaining_rows"
TotalRemainingRowsColumn is the column name for the COUNT window function result that provides the total count of rows matching the query conditions.
Variables ¶
This section is empty.
Functions ¶
func BuildCompositeID ¶
func BuildCompositeID(row map[string]interface{}, columns []UniqueConstraintColumn, separator string) string
BuildCompositeID creates a composite ID by concatenating the values of the key columns.
This is used when a table has a composite primary key (multiple columns) but the entity configuration expects a single "id" attribute. The function concatenates the values of all key columns using the specified separator to produce a unique string identifier.
Example: For a row with MANDT="100", EBELN="4500001234", EBELP="10" and separator "|", the resulting composite ID would be "100|4500001234|10".
The columns slice determines the order of concatenation (sorted by Position). Missing or nil values result in empty strings in the composite ID.
Types ¶
type Adapter ¶
type Adapter struct {
DB2Client Client
}
Adapter implements the framework.Adapter interface to query pages of objects from DB2 datasources.
func (*Adapter) GetPage ¶
func (a *Adapter) GetPage(ctx context.Context, request *framework.Request[Config]) framework.Response
GetPage is called by SGNL's ingestion service to query a page of objects from a datasource.
func (*Adapter) RequestPageFromDatasource ¶
func (a *Adapter) RequestPageFromDatasource( ctx context.Context, req *Request, entity *framework.EntityConfig, ) framework.Response
RequestPageFromDatasource requests a page of objects from a datasource.
type Client ¶
type Client interface {
GetPage(ctx context.Context, request *Request) (*Response, *framework.Error)
}
Client defines the interface for querying a DB2 datasource.
type Config ¶
type Config struct {
// Common configuration
*config.CommonConfig
// API Version for configuration compatibility
APIVersion string `json:"apiVersion,omitempty"`
// DB2 database to connect to.
Database string `json:"database,omitempty"`
// Schema name to use for table queries (optional, defaults to username if not specified)
Schema string `json:"schema,omitempty"`
// CertificateChain is a base64-encoded PEM certificate chain to use for SSL connections.
// When provided, SSL will be enabled and this certificate chain will be used
// to validate the DB2 server's certificate.
CertificateChain string `json:"certificateChain,omitempty"`
Filters map[string]condexpr.Condition `json:"filters,omitempty"`
}
Config is the configuration passed in each GetPage calls to the adapter.
Adapter configuration example: nolint: godot
{
"requestTimeoutSeconds": 10,
"localTimeZoneOffset": 43200,
"database": "sgnl",
"schema": "MYSCHEMA",
"certificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURYVENDQWtXZ0F3SUJBZ0lKQUtvSy9Pdk16b...",
"filters": {
"users": {
"or": [
{
"and": [
{
"field": "age",
"op": ">",
"value": 18
},
{
"field": "country",
"op": "=",
"value": "USA"
}
]
},
{
"field": "verified",
"op": "=",
"value": true
}
]
},
"groups": {
"field": "country",
"op": "IN",
"value": ["active", "inactive"]
}
}
}
type Datasource ¶
type Datasource struct {
Client SQLClient
}
func (*Datasource) ExtractUniqueKeyColumns ¶
func (d *Datasource) ExtractUniqueKeyColumns(ctx context.Context, tableName string) ([]string, error)
ExtractUniqueKeyColumns returns the column names that make up the unique key for a table.
This function queries the DB2 system catalog (SYSCAT.TABCONST and SYSCAT.KEYCOLUSE) to discover the primary key or unique constraint columns for the given table. The returned columns are used for:
Composite ID Generation: When an entity is configured with a synthetic "id" attribute, the adapter needs to generate a unique identifier from the actual database columns. For tables with composite primary keys (e.g., MANDT|EBELN|EBELP in SAP tables), the unique key columns are concatenated with a separator to form a single ID value.
Cursor-based Pagination: The unique key columns are used to construct ORDER BY clauses and WHERE conditions for keyset pagination. This ensures consistent ordering across pages and allows resuming from the last fetched row.
Query Construction: The columns are added to the SELECT clause to ensure they're available for ID generation even if not explicitly requested in the entity attributes.
The function prioritizes primary keys (constraints with "PK" or "PRIMARY" in the name) over unique constraints. If no primary key is found, it falls back to the first unique constraint available.
func (*Datasource) TestConnection ¶
func (d *Datasource) TestConnection(ctx context.Context, request *Request) (*Response, *framework.Error)
TestConnection tries to connect and query system tables to help debug connection issues.
type MockRows ¶
type MockRows struct {
Data []map[string]interface{}
// contains filtered or unexported fields
}
MockRows is a mock implementation of the Rows interface for testing.
type MockSQLClient ¶
type MockSQLClient struct {
ConnectFunc func(dataSourceName string) (*sql.DB, error)
QueryFunc func(ctx context.Context, query string, args ...interface{}) (Rows, error)
}
MockSQLClient is a mock implementation of SQLClient for testing.
type Request ¶
type Request struct {
// BaseURL is the Base URL of the datasource to query.
BaseURL string `json:"baseURL"`
// Username is the user name used to authenticate with the DB2 instance.
Username string `json:"username"`
// Password is the password used to authenticate with the DB2 instance.
Password string `json:"password"`
// PageSize is the maximum number of objects to return from the entity.
PageSize int64 `json:"pageSize,omitempty"`
// EntityConfig contains the entity configuration for the current request.
EntityConfig framework.EntityConfig
// A filter to apply to the DB2 request when pulling data for the current entity.
Filter *condexpr.Condition
// Cursor identifies the first object of the page to return, as returned by
// the last request for the entity.
// nil in the request for the first page.
Cursor *string `json:"cursor,omitempty"`
// DB2 database to connect to.
Database string `json:"database"`
// Schema name for table queries (optional)
Schema string `json:"schema,omitempty"`
// UniqueAttributeExternalID is used to specify the unique ID that should be used when ordering results from
// the specified table.
UniqueAttributeExternalID string `json:"uniqueAttributeExternalID"`
// UniqueKeyColumns contains the columns that comprise the unique key for composite ID generation
UniqueKeyColumns []string `json:"uniqueKeyColumns,omitempty"`
// ConfigStruct contains the parsed configuration for SSL and other advanced options
ConfigStruct interface{} `json:"configStruct,omitempty"`
}
Request is a request to a DB2 database.
func NewRequestFromConfig ¶
NewRequestFromConfig validates the framework request and constructs an internal Request. It performs nil checks, constructs the Request, and validates all fields. Returns a fully validated Request or an error.
func (*Request) BuildConnectionString ¶
BuildConnectionString constructs the DB2 connection string from request parameters. It handles hostname/port parsing, credentials, and optional SSL configuration.
type Response ¶
type Response struct {
// Objects is a list of objects returned from the query.
Objects []map[string]interface{} `json:"objects,omitempty"`
// NextCursor is the cursor to use for the next page of results.
NextCursor *string `json:"nextCursor,omitempty"`
// TotalCount is the total number of objects matching the query.
TotalCount int64 `json:"totalCount,omitempty"`
// StatusCode is the HTTP status code returned from the DB2 query.
StatusCode int `json:"statusCode,omitempty"`
}
Response is the response returned from a DB2 query.
type Rows ¶
type Rows interface {
Next() bool
Scan(dest ...interface{}) error
Close() error
Err() error
Columns() ([]string, error)
}
Rows represents the result set from a SQL query.
type SQLClient ¶
type SQLClient interface {
Connect(dataSourceName string) (*sql.DB, error)
Query(ctx context.Context, query string, args ...interface{}) (Rows, error)
}
func NewDefaultSQLClient ¶
func NewDefaultSQLClient() SQLClient
NewDefaultSQLClient creates a new SQLClient instance. It is used to connect to a DB2 database and execute queries.
func NewMockSQLClient ¶
func NewMockSQLClient() SQLClient
NewMockSQLClient creates a new MockSQLClient instance.
type SQLColumnTypes ¶
type UniqueConstraintColumn ¶
UniqueConstraintColumn represents a column in a unique constraint.