Dbaas base-client

Basic and not database specific (does not provide any db driver) DBaaS REST API client implementation. Allows acquiring raw databases connections.

• Install
• Usage
  • Configuration
  • LogicalDbProviders
  • LogicalDb
  • BaseDbParams
• Quick example

Install

To get dbaasbase use

 go get github.com/netcracker/qubership-core-lib-go-dbaas-base-client/v3@<latest released version>

List of all released versions may be found here

Usage

At first, it's necessary to register security implemention - dummy or your own, the followning example shows registration of required services:

import (
	"github.com/netcracker/qubership-core-lib-go/v3/serviceloader"
	"github.com/netcracker/qubership-core-lib-go/v3/security"
)

func init() {
	serviceloader.Register(1, &security.DummyToken{})
}

Then you have to create dbaasbase.DbaasPool object with constructor dbaasbase.NewDbaaSPool(options ...PoolOptions) *DbaaSPool. Constructor has optional parameter PoolOptions.

PoolOptions are options for configuring dbaas pool and base dbaas client, which will be used with dbaasPool. PoolOptions has such fields as:

• LogicalDbProviders []LogicalDbProvider - list of possible logicalDb providers. See more info at LogicalDbProviders

Example of dbaasPool creation:

    dbPool := dbaasbase.NewDbaasPool() // without options
    ...
    // or with some client options
    opts := dbaasbase.PoolOptions{
    	LogicalDbProviders : []dbaasbase.LogicalDbProvider{customProvider}
    }   
    dbPool := dbaasbase.NewDbaasPool(opts)

DbaasPool has next API:

• GetOrCreateDb(dbType string, classifier map[string]interface{}, params rest.BaseDbParams) (*LogicalDb, error)

  This function allows getting information about database and collect it into LogicalDb struct. This function will return info about existing database or create new one and return connection to it.

  Parameters:

  • ctx context.Context - golang request scope context object.
  • dbType string - type of database, e.g. cassandra, postgresql, mongodb.
  • classifier map[string]interface{} - Composite uniq key. It distinguishes this database from other databases in the same namespace.
  • params rest.BaseDbParams - some extra not required parameters for specific database creation. More info at BaseDbParams

• GetConnection(dbType string, classifier map[string]interface{}, params rest.BaseDbParams) (map[string]interface{}, error)

  This function allows getting information about connection and get response as map[string]interface{}. Please note, that this method doesn't use cache and always send request to dbaas-aggregator. Also, it won't create a database. If database doesn't exist func will just return nil.

  Parameters:

  • ctx context.Context - golang request scope context object.
  • dbType string - type of database, e.g. cassandra, postgresql, mongodb.
  • classifier map[string]interface{} - describes the purpose of the database, and it distinguishes this database from other databases in the same namespace.
  • params rest.BaseDbParams - some extra not required parameters for specific database creation and getting connection. More info at BaseDbParams

Configuration

Name	Description	Optional	Default	Since
microservice.name	Name of current microservice (eg. tenant-manager)	false	-	0.1.0
microservice.namespace	Name of current namespace	false	-	0.1.0
dbaas.baseclient.retry.max-attempts	Number of retry attempts	true	12	0.1.0
dbaas.baseclient.retry.delay-ms	Delay per attempt (ms)	true	5000	0.1.0

LogicalDbProviders

LogicalDbProvider allows use different sources as database providers (for example zookeeper or some localy created database). Default databases source is dbaas-aggregator.

To add another database source user, at first, have to implement LogicalDbProvider interface.

type LogicalDbProvider interface {
    GetOrCreateDb(dbType string, classifier map[string]interface{}, params rest.BaseDbParams) (*LogicalDb, error)
    GetConnection(dbType string, classifier map[string]interface{}, params rest.BaseDbParams) (map[string]interface{}, error)
}

• Func GetOrCreateDb must return LogicalDb with mandatory connectionProperties value.
• Func GetConnection must return map[string]interface{} with information about connection properties (like password, username, connection string, etc.)

Then user have to create PoolOptions object with list of created LogicalDbProviders and pass this object as a parameter to NewDbaaSPool(options ...PoolOptions). Now when user call any DbaasPool method, LogicalDbProviders from list will be used as new connection sources.

Depending on the presence of LogicalDbProviders, the behavior of the module differs.

• There are no LogicalDbProviders. Module will load information from dbaas-aggregator.
• There are some LogicalDbProviders. Module will first use LogicalDbProvider from the list in the passed order. If each LogicalDbProvider returns nil then logical database will be created through dbaas-aggregator.
• There are some LogicalDbProviders and some LogicalDbProvider returns error. In this case module will stop executing the function and return an error.
• There are some LogicalDbProviders and first LogicalDbProvider in the list returns nil when GetOrCreateDb or GetConnection was called.
  In this case module will switch to the next provider in the list. If all providers run out, the module will go back to using dbaas-aggregator.

Example of custom LogicalDbProvider creation:

package main

import "github.com/netcracker/qubership-core-lib-go-dbaas-base-client/v3"

type CustomLogicalDbProvider struct{}

func (CLDB CustomLogicalDbProvider) GetOrCreateDb(dbType string, classifier map[string]interface{}, params rest.BaseDbParams) (*dbaasbase.LogicalDb, error) {
  connectionProperties, err := getConnectionProperties()
  if err != nil {
    return nil, err
  }
  
  logicalDb := &dbaasbase.LogicalDb{
    Classifier:           classifier,
    ConnectionProperties: connectionProperties,
    Namespace:            getNamespace(),
    Type:                 dbType,
  }
  return logicalDb, nil
}

func (CLDB CustomLogicalDbProvider) GetConnection(dbType string, classifier map[string]interface{}, params rest.BaseDbParams) (map[string]interface{}, error) {
  connectionProperties, err := getConnectionProperties()
  return connectionProperties, err
}

func main() {
  options := dbaasbase.PoolOptions{LogicalDbProviders: []dbaasbase.LogicalDbProvider{CustomLogicalDbProvider{}}}
  dbPool := dbaasbase.NewDbaaSPool(options)
}

LogicalDb

LogicalDb is a way to store information about databases locally, it is a representation of dbaas-aggregator response.

LogicalDb has such fields as:

Name	Description	Schema
classifier	Classifier describes the purpose of the database and it distinguishes this database from other databases in the same namespace. It contains such keys as dbClassifier, scope (service or tenant), microserviceName, namespace. Setting keys depends on the database type.	map[string]interface{}
connectionProperties	This is an information about connection to database. It contains such keys as url, authDbName, username, password, port, host.Setting keys depends on the database type.	map[string]interface{}
id	A unique identifier of the document in the database. This field might not be used when searching by classifier for security purpose. And it exists in the response when executing Create database API	string
namespace	Namespace where database is placed.	string
settings	Additional settings for creating a database.	map[string]interface{}
type	Type of database, for example PostgreSQL or MongoDB	string

BaseDbParams

BaseDbParams allows customizing database creation and getting connection.

Name	Description	Schema
userRole	Indicates connection properties with which user role should be returned to a client and indicates if it has rights to create a database. Default is admin.	string
namePrefix	This is a prefix of the database name. Prefix depends on the type of the database and it should be less than 27 characters if dbName is not specified.	string
physicalDatabaseId	Specifies the identificator of physical database where a logical database will be created. If it is not specified then logical database will be created in default physical database. You can get the list of all physical databases by "List registered physical databases" API.	string
settings	Additional settings for creating database. There is a possibility to update settings after database creation.	object

Quick example

package main

import (
  "fmt"
  "github.com/netcracker/qubership-core-lib-go/v3/logging"
  "github.com/netcracker/qubership-core-lib-go-dbaas-base-client/v3/dbaasbase"
)

var logger logging.Logger

func init() {
  logger = logging.GetLogger("main")
}

func main() {
  dbaasPool := dbaasbase.NewDbaaSPool()

  classifier := make(map[string]interface{})
  classifier["scope"] = "service"
  classifier["microserviceName"] = "service_name"

  settings := make(map[string]interface{})
  listOfExtensions := []string{"bloom", "pgcrypt"}
  settings["pgExtensions"] = listOfExtensions

  params := dbaasbase.BaseDbParams{
    NamePrefix:         "test_db",
    Settings:           settings,
	userRole:           "admin",   //optional
  }
  
  // create new database of type postgres with classifier and params
  logicalDb, err := dbaasPool.CreateOrGetDatabase("postgresql", classifier, params)
  if err != nil {
    logger.Error("Problem with database creation")
  }
  fmt.Println(logicalDb)
  
  // acquire connection to created database
  conn, err := dbaasPool.GetConnection("postgresql", classifier, params)
  if err != nil {
    logger.Errorf("Problem with acquiring connection to db with classifier %+v", classifier)
  }
  fmt.Println(conn)
}