Documentation
¶
Overview ¶
Package cloudberry provides a database/sql driver for Apache Cloudberry (Incubating) and Greenplum-derived MPP databases.
The driver wraps the pgx/v5 stdlib driver but configures the connection to behave like the C libpq client (psql): it forces the PostgreSQL *simple* (text) query protocol and disables server-side prepared-statement caching.
Motivation ¶
Cloudberry coordinates work across segment backends. Some Cloudberry server builds mishandle the PostgreSQL *extended* query protocol (Parse/Bind/Execute with cached prepared statements) when commands are dispatched to segments, which can terminate a segment backend. The reference C client (libpq, used by psql) issues statements through the simple query protocol and does not cache prepared statements, and does not trigger that behaviour. This driver mirrors that behaviour so MPP tooling written in Go (e.g. gpbackup/gprestore) talks to segments the same way psql does.
Usage
import (
"database/sql"
_ "github.com/vyrodovalexey/cloudberry-sql/cloudberry"
)
db, err := sql.Open("cloudberry", "host=localhost port=5432 user=gpadmin dbname=mydb sslmode=disable")
The driver is registered under the names "cloudberry" and (for drop-in compatibility with tools that hard-code the pgx driver name) "pgx".
Index ¶
- Constants
- func CopyFromProgramOnSegment(ctx context.Context, execer execerContext, table, program string) error
- func CopyToProgramOnSegment(ctx context.Context, execer execerContext, table, program string) error
- func ExportSnapshot(ctx context.Context, tx *sql.Tx) (string, error)
- func NewConnector(dsn string) (driver.Connector, error)
- func Open(dsn string) (*sql.DB, error)
- func SetSerializable(ctx context.Context, execer execerContext) error
- func SetTransactionSnapshot(ctx context.Context, tx *sql.Tx, snapshotID string) error
- type Driver
- type Flavor
- type Segment
- type SegmentRole
- type VersionInfo
Constants ¶
const CompatDriverName = "pgx"
CompatDriverName is an additional name registered for drop-in compatibility with tooling (such as cloudberry-go-libs / gpbackup) that opens the database using the historical "pgx" driver name.
const DriverName = "cloudberry"
DriverName is the primary name this driver registers under.
Variables ¶
This section is empty.
Functions ¶
func CopyFromProgramOnSegment ¶
func CopyFromProgramOnSegment(ctx context.Context, execer execerContext, table, program string) error
CopyFromProgramOnSegment runs a parallel, per-segment COPY that loads each segment's slice of the table from an external program. As with CopyToProgramOnSegment, program must contain the <SEGID> token. This is the gprestore data path.
func CopyToProgramOnSegment ¶
CopyToProgramOnSegment runs a parallel, per-segment COPY that pipes each segment's slice of the table to an external program. The program string must contain the literal token <SEGID>, which Cloudberry substitutes with each segment's content id at execution time (this is the standard gpbackup data path). table should be a schema-qualified, already-quoted identifier.
Example:
CopyToProgramOnSegment(ctx, db, "public.customers",
"cat > /backup/seg_<SEGID>.dat")
func ExportSnapshot ¶
ExportSnapshot exports a transaction snapshot id from tx, for use by sibling connections that want a consistent view via SetTransactionSnapshot. tx must already be in an open transaction.
func NewConnector ¶
NewConnector builds a driver.Connector for the given DSN. It is a convenience wrapper around sql.OpenDB for callers that want to construct a *sql.DB directly without registering/looking up the driver by name.
func SetSerializable ¶
SetSerializable sets the session's transaction isolation to serializable. On Cloudberry/Greenplum the server transparently falls back to repeatable read (serializable is not yet supported); this helper hides that detail and is a no-op-equivalent on those servers.
Types ¶
type Driver ¶
type Driver struct{}
Driver is the database/sql driver for Cloudberry. It implements driver.Driver and driver.DriverContext.
type Flavor ¶
type Flavor string
Flavor identifies the database product behind a connection.
const ( // FlavorCloudberry indicates an Apache Cloudberry (Incubating) server. FlavorCloudberry Flavor = "cloudberry" // FlavorGreenplum indicates a Greenplum Database server. FlavorGreenplum Flavor = "greenplum" // FlavorPostgres indicates a vanilla PostgreSQL server. FlavorPostgres Flavor = "postgres" // FlavorUnknown indicates the product could not be determined. FlavorUnknown Flavor = "unknown" )
type Segment ¶
type Segment struct {
Content int
Role SegmentRole
PreferredRole SegmentRole
Status string // "u" (up) or "d" (down)
Mode string // "s" (synced) or "n" (not in sync)
Hostname string
Address string
Port int
DataDir string
}
Segment describes one entry from gp_segment_configuration.
func GetSegmentConfiguration ¶
GetSegmentConfiguration returns the cluster segment configuration from gp_segment_configuration. It requires an MPP (Cloudberry/Greenplum) server.
func (Segment) IsCoordinator ¶
IsCoordinator reports whether this segment entry is the coordinator (content -1).
type SegmentRole ¶
type SegmentRole string
SegmentRole identifies a segment's role in the cluster.
const ( // RolePrimary is a primary segment (or the coordinator, content -1). RolePrimary SegmentRole = "p" // RoleMirror is a mirror segment. RoleMirror SegmentRole = "m" )
type VersionInfo ¶
type VersionInfo struct {
// Raw is the full version() string.
Raw string
// Flavor is the detected product family.
Flavor Flavor
// Major/Minor/Patch are the parsed product version numbers. For Cloudberry
// and Greenplum these reflect the MPP product version (e.g. 2.1.0), not the
// embedded PostgreSQL version.
Major int
Minor int
Patch int
}
VersionInfo describes the server product and version behind a connection.
func DetectVersion ¶
func DetectVersion(ctx context.Context, q queryRower) (VersionInfo, error)
DetectVersion queries the server and returns its product and version. The querier may be a *sql.DB or a *sql.Conn.
func (VersionInfo) IsCloudberry ¶
func (v VersionInfo) IsCloudberry() bool
IsCloudberry reports whether the server is Apache Cloudberry.
func (VersionInfo) IsGreenplum ¶
func (v VersionInfo) IsGreenplum() bool
IsGreenplum reports whether the server is Greenplum.
func (VersionInfo) IsMPP ¶
func (v VersionInfo) IsMPP() bool
IsMPP reports whether the server is an MPP product (Cloudberry or Greenplum) rather than vanilla PostgreSQL.
Source Files