polypheny

README

Polypheny Go Driver

Connect to Polypheny-DB from Go using database/sql. The driver supports SQL queries, positional parameters, and transactions. The raw connection provides MQL queries and Prism entity metadata.

Installation

Use Go 1.23 or newer and a Polypheny server with a compatible Prism 2.x interface. The driver includes the generated Go bindings from the Prism 2.2 release. Document collection metadata requires server-side Prism 2.2 support.

go get github.com/polypheny/Polypheny-Go-Driver

Querying with SQL

The driver registers as polypheny and accepts host:port,username:password as its connection string. Prism uses port 20590 by default. The example assumes a local instance configured with the user pa and an empty password. The driver uses plain TCP, which does not encrypt credentials or query traffic. Connect through a trusted network or an encrypted tunnel.

package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"time"

	_ "github.com/polypheny/Polypheny-Go-Driver"
)

func main() {
	db, err := sql.Open("polypheny", "localhost:20590,pa:")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	if err := db.PingContext(ctx); err != nil {
		log.Fatal(err)
	}
	var value int
	if err := db.QueryRowContext(ctx, "SELECT 1").Scan(&value); err != nil {
		log.Fatal(err)
	}
	fmt.Println(value)
}

Use ? placeholders with QueryContext, QueryRowContext, and ExecContext, or prepare a statement with PrepareContext. For example, db.QueryRowContext(ctx, "SELECT name FROM employees WHERE id = ?", 42) queries an existing employees table. Statements outside an explicit transaction use auto-commit. Use db.BeginTx(ctx, nil) to group statements and call Commit or Rollback to finish the transaction.

MQL and entity metadata

Import the driver as polypheny instead of the blank import and use (*sql.Conn).Raw to access driver-specific methods. The following example queries an existing employees collection or table in the default namespace, then lists the entities in public. Call SearchEntities with a pattern pointer to filter the results. The response types are available in github.com/polypheny/Polypheny-Go-Driver/prism.

conn, err := db.Conn(ctx)
if err != nil {
	return err
}
defer conn.Close()

return conn.Raw(func(raw any) error {
	driverConn := raw.(*polypheny.PolyphenyConn)
	documents, err := driverConn.QueryMongoContext(ctx, "db.employees.find()")
	if err != nil {
		return err
	}
	fmt.Println(*documents)

	entities, err := driverConn.SearchEntities(ctx, "public", nil)
	if err != nil {
		return err
	}
	for _, entity := range entities.GetEntities() {
		fmt.Println(entity)
	}
	return nil
})

Testing

go test -race ./...
go vet ./...

To run the integration tests, set POLYPHENY_TEST_DSN to a test instance that supports Prism 2.2. The tests create and remove their own fixtures.

POLYPHENY_TEST_DSN='localhost:20590,pa:' go test -count=1 -run '^TestIntegration' ./...

Updating the Prism bindings

When updating Prism, set the version and SHA-256 of its official Go release archive in scripts/update-prism-bindings.sh, run the script, and commit the generated prism/ files. Run the script with --check to compare the tracked files with the verified archive. Builds use the tracked files directly.

Resources

• Go package documentation
• Prism protocol documentation
• Open Go driver issues
• Polypheny project and contribution guidelines
• Code of conduct

License

Apache License 2.0

Documentation

Index

• type ArgSpec
• type ClientError
  • func (e *ClientError) Error() string
• type Connector
  • func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)
  • func (c *Connector) Driver() driver.Driver
• type PolyphenyConn
  • func (conn *PolyphenyConn) Begin() (driver.Tx, error)
  • func (conn *PolyphenyConn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)
  • func (conn *PolyphenyConn) Close() error
  • func (conn *PolyphenyConn) Exec(query string, args []driver.Value) (driver.Result, error)
  • func (conn *PolyphenyConn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (result driver.Result, err error)
  • func (conn *PolyphenyConn) IsValid() bool
  • func (conn *PolyphenyConn) Ping(ctx context.Context) error
  • func (conn *PolyphenyConn) Prepare(query string) (driver.Stmt, error)
  • func (conn *PolyphenyConn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)
  • func (conn *PolyphenyConn) Query(query string, args []driver.Value) (driver.Rows, error)
  • func (conn *PolyphenyConn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (rows driver.Rows, err error)
  • func (conn *PolyphenyConn) QueryMongoContext(ctx context.Context, query string) (rows *[]map[any]any, err error)
  • func (conn *PolyphenyConn) SearchEntities(ctx context.Context, namespace string, pattern *string) (*prism.EntitiesResponse, error)
• type PolyphenyDriver
  • func (d PolyphenyDriver) Open(name string) (driver.Conn, error)
  • func (d PolyphenyDriver) OpenConnector(name string) (driver.Connector, error)
• type PolyphenyResult
  • func (r *PolyphenyResult) LastInsertId() (int64, error)
  • func (r *PolyphenyResult) RowsAffected() (int64, error)
• type PolyphenyRows
  • func (r *PolyphenyRows) Close() error
  • func (r *PolyphenyRows) Columns() []string
  • func (r *PolyphenyRows) Next(dest []driver.Value) error
• type PolyphenyTransaction
  • func (tx *PolyphenyTransaction) Commit() error
  • func (tx *PolyphenyTransaction) Rollback() error
• type PreparedStatement
  • func (stmt *PreparedStatement) Close() error
  • func (stmt *PreparedStatement) Exec(args []driver.Value) (driver.Result, error)
  • func (stmt *PreparedStatement) ExecContext(ctx context.Context, args []driver.NamedValue) (result driver.Result, err error)
  • func (stmt *PreparedStatement) NumInput() int
  • func (stmt *PreparedStatement) Query(args []driver.Value) (driver.Rows, error)
  • func (stmt *PreparedStatement) QueryContext(ctx context.Context, args []driver.NamedValue) (rows driver.Rows, err error)

Types

type ArgSpec

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

type ClientError

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

func (*ClientError) Error

func (e *ClientError) Error() string

type Connector

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

Connector implements driver.Connector.

func (*Connector) Connect

func (c *Connector) Connect(ctx context.Context) (driver.Conn, error)

Connect connects to a Polypheny server using the Prism TCP transport.

func (*Connector) Driver

func (c *Connector) Driver() driver.Driver

Driver returns the underlying Polypheny driver.

type PolyphenyConn

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

PolyphenyConn implements driver.Conn.

func (*PolyphenyConn) Begin

func (conn *PolyphenyConn) Begin() (driver.Tx, error)

Begin starts a transaction.

func (*PolyphenyConn) BeginTx

func (conn *PolyphenyConn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

BeginTx starts a transaction with the server's default isolation level.

func (*PolyphenyConn) Close

func (conn *PolyphenyConn) Close() error

Close disconnects from the server and releases the network connection.

func (*PolyphenyConn) Exec

func (conn *PolyphenyConn) Exec(query string, args []driver.Value) (driver.Result, error)

Exec executes a SQL statement.

func (*PolyphenyConn) ExecContext

func (conn *PolyphenyConn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (result driver.Result, err error)

ExecContext executes a SQL statement with positional arguments.

func (*PolyphenyConn) IsValid

func (conn *PolyphenyConn) IsValid() bool

IsValid reports whether the connection can be reused by database/sql.

func (*PolyphenyConn) Ping

func (conn *PolyphenyConn) Ping(ctx context.Context) error

Ping checks that the server responds on this connection.

func (*PolyphenyConn) Prepare

func (conn *PolyphenyConn) Prepare(query string) (driver.Stmt, error)

Prepare prepares a SQL statement on the server.

func (*PolyphenyConn) PrepareContext

func (conn *PolyphenyConn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

PrepareContext prepares a SQL statement with positional parameters.

func (*PolyphenyConn) Query

func (conn *PolyphenyConn) Query(query string, args []driver.Value) (driver.Rows, error)

Query executes a SQL query.

func (*PolyphenyConn) QueryContext

func (conn *PolyphenyConn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (rows driver.Rows, err error)

QueryContext executes a SQL query with positional arguments.

func (*PolyphenyConn) QueryMongoContext

func (conn *PolyphenyConn) QueryMongoContext(ctx context.Context, query string) (rows *[]map[any]any, err error)

QueryMongoContext executes an MQL query and returns all documents in its result. Document keys are strings. Nested documents are maps with string keys, and lists are slices of values.

func (*PolyphenyConn) SearchEntities

func (conn *PolyphenyConn) SearchEntities(ctx context.Context, namespace string, pattern *string) (*prism.EntitiesResponse, error)

SearchEntities returns metadata about the entities in namespace. A nil pattern requests all entities. Document collection metadata requires a server that implements the Prism 2.2 document metadata fields.

type PolyphenyDriver

type PolyphenyDriver struct{}

PolyphenyDriver implements driver.Driver and DriverContext interface

func (PolyphenyDriver) Open

func (d PolyphenyDriver) Open(name string) (driver.Conn, error)

Open will return a PolyphenyConn which implements driver.Conn and represents a Connection to Polypheny server The name, also called DSN, has the following format: addr:port,user:password

func (PolyphenyDriver) OpenConnector

func (d PolyphenyDriver) OpenConnector(name string) (driver.Connector, error)

OpenConnector will return a Connector

type PolyphenyResult

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

PolyphenyResult implements driver.Result and represents the results of queries that don't return data

func (*PolyphenyResult) LastInsertId

func (r *PolyphenyResult) LastInsertId() (int64, error)

LastInsertId returns the ID of the last inserted row TODO: does Polypheny support this at present?

func (*PolyphenyResult) RowsAffected

func (r *PolyphenyResult) RowsAffected() (int64, error)

RowsAffected returns the number of affected rows of a query

type PolyphenyRows

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

PolyphenyRows implements driver.Rows and represents the results of queries that return data

func (*PolyphenyRows) Close

func (r *PolyphenyRows) Close() error

Close will close the Rows iterator

func (*PolyphenyRows) Columns

func (r *PolyphenyRows) Columns() []string

Columns returns the names of columns of a query

func (*PolyphenyRows) Next

func (r *PolyphenyRows) Next(dest []driver.Value) error

Next iterates over the Rows

type PolyphenyTransaction

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

PolyphenyTransaction implements driver.Tx.

func (*PolyphenyTransaction) Commit

func (tx *PolyphenyTransaction) Commit() error

Commit commits the transaction and restores auto-commit.

func (*PolyphenyTransaction) Rollback

func (tx *PolyphenyTransaction) Rollback() error

Rollback rolls back the transaction and restores auto-commit.

type PreparedStatement

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

PreparedStatement implements driver.Stmt and its context-aware extensions.

func (*PreparedStatement) Close

func (stmt *PreparedStatement) Close() error

Close releases the prepared statement on the server.

func (*PreparedStatement) Exec

func (stmt *PreparedStatement) Exec(args []driver.Value) (driver.Result, error)

Exec executes a prepared statement.

func (*PreparedStatement) ExecContext

func (stmt *PreparedStatement) ExecContext(ctx context.Context, args []driver.NamedValue) (result driver.Result, err error)

ExecContext executes a prepared statement with the supplied parameters.

func (*PreparedStatement) NumInput

func (stmt *PreparedStatement) NumInput() int

NumInput returns the number of positional parameters.

func (*PreparedStatement) Query

func (stmt *PreparedStatement) Query(args []driver.Value) (driver.Rows, error)

Query executes a prepared query.

func (*PreparedStatement) QueryContext

func (stmt *PreparedStatement) QueryContext(ctx context.Context, args []driver.NamedValue) (rows driver.Rows, err error)

QueryContext executes a prepared query with the supplied parameters.