pip_services3_mysql.persistence package

Submodules

• pip_services3_mysql.persistence.IdentifiableJsonMySqlPersistence module
• pip_services3_mysql.persistence.IdentifiableMySqlPersistence module
• pip_services3_mysql.persistence.MySqlPersistence module

Module contents

class pip_services3_mysql.persistence.IdentifiableMySqlPersistence(table_name: str = None, schema_name: str = None)

Bases: pip_services3_mysql.persistence.MySqlPersistence.MySqlPersistence

Abstract persistence component that stores data in MySQL and implements a number of CRUD operations over data items with unique ids. The data items must implement IIdentifiable interface.

In basic scenarios child classes shall only override get_page_by_filter, get_list_by_filter or delete_by_filter operations with specific filter function. All other operations can be used out of the box.

In complex scenarios child classes can implement additional operations by accessing self._collection and self._model properties.

### Configuration parameters ###

• table: (optional) MySQL table name

• schema: (optional) MySQL schema name

• connection(s):

  • discovery_key: (optional) a key to retrieve the connection from IDiscovery

  • host: host name or IP address

  • port: port number (default: 27017)

  • uri: resource URI or connection string with all parameters in it

• credential(s):

  • store_key: (optional) a key to retrieve the credentials from ICredentialStore

  • username: (optional) user name

  • password: (optional) user password

• options:

  • connect_timeout: (optional) number of milliseconds to wait before timing out when connecting a new client (default: 0)

  • idle_timeout: (optional) number of milliseconds a client must sit idle in the pool and not be checked out (default: 10000)

  • max_pool_size: (optional) maximum number of clients the pool should contain (default: 10)

### References ###

• *:logger:*:*:1.0 (optional) ILogger components to pass log messages components to pass log messages

• *:discovery:*:*:1.0 (optional) IDiscovery services

• *:credential-store:*:*:1.0 (optional) ICredentialStore stores to resolve credentials

Example:

class MyMySqlPersistence(IdentifiableMySqlPersistence):
    def __init__(self):
        super(MyMySqlPersistence, self).__init__("mydata", MyDataMySqlSchema())

    def __compose_filter(self, filter):
        filter = filter or FilterParams()
        criteria = []
        name = filter.get_as_nullable_string('name')
        if name:
            criteria.append({'name': name})
        return {'$and': criteria} if len(criteria) > 0 else None

    def get_page_by_filter(self, correlation_id, filter, paging):
        return super().get_page_by_filter(correlation_id, self.__compose_filter(filter), paging, None, None)

persistence = MyMySqlPersistence()
persistence.configure(ConfigParams.from_tuples(
    "host", "localhost",
    "port", 27017
))

persistence.open('123')
persistence.create('123', {'id': "1", 'name': "ABC"})
page = persistence.get_page_by_filter('123', FilterParams.from_tuples('name', 'ABC'), None)
print(page.data) # Result: { id: "1", name: "ABC" }

persistence.delete_by_id("123", "1")
# ...

create(correlation_id: Optional[str], item: T) → Optional[T]

Creates a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – an item to be created.

Returns

created item

delete_by_id(correlation_id: Optional[str], id: Any) → T

Deleted a data item by it’s unique id.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• id – an id of the item to be deleted

Returns

deleted item

delete_by_ids(correlation_id: Optional[str], ids: List[Any])

Deletes multiple data items by their unique ids.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• ids – ids of data items to be deleted.

Returns

None for success

get_list_by_ids(correlation_id: Optional[str], ids: List[Any]) → List[T]

Gets a list of data items retrieved by given unique ids.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• ids – ids of data items to be retrieved

Returns

data list

get_one_by_id(correlation_id: Optional[str], id: Any) → T

Gets a data item by its unique id.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• id – an id of data item to be retrieved.

Returns

data item

set(correlation_id: Optional[str], item: T) → Optional[T]

Sets a data item. If the data item exists it updates it, otherwise it create a new data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – a item to be set.

Returns

updated item

update(correlation_id: Optional[str], item: T) → Optional[T]

Updates a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – an item to be updated.

Returns

updated item

update_partially(correlation_id: Optional[str], id: Any, data: pip_services3_commons.data.AnyValueMap.AnyValueMap) → Optional[T]

Updates only few selected fields in a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• id – an id of data item to be updated.

• data – a map with fields to be updated.

Returns

updated item

class pip_services3_mysql.persistence.IdentifiableMySqlPersistence(table_name: str = None, schema_name: str = None)

Bases: pip_services3_mysql.persistence.MySqlPersistence.MySqlPersistence

Abstract persistence component that stores data in MySQL and implements a number of CRUD operations over data items with unique ids. The data items must implement IIdentifiable interface.

In basic scenarios child classes shall only override get_page_by_filter, get_list_by_filter or delete_by_filter operations with specific filter function. All other operations can be used out of the box.

In complex scenarios child classes can implement additional operations by accessing self._collection and self._model properties.

### Configuration parameters ###

• table: (optional) MySQL table name

• schema: (optional) MySQL schema name

• connection(s):

  • discovery_key: (optional) a key to retrieve the connection from IDiscovery

  • host: host name or IP address

  • port: port number (default: 27017)

  • uri: resource URI or connection string with all parameters in it

• credential(s):

  • store_key: (optional) a key to retrieve the credentials from ICredentialStore

  • username: (optional) user name

  • password: (optional) user password

• options:

  • connect_timeout: (optional) number of milliseconds to wait before timing out when connecting a new client (default: 0)

  • idle_timeout: (optional) number of milliseconds a client must sit idle in the pool and not be checked out (default: 10000)

  • max_pool_size: (optional) maximum number of clients the pool should contain (default: 10)

### References ###

• *:logger:*:*:1.0 (optional) ILogger components to pass log messages components to pass log messages

• *:discovery:*:*:1.0 (optional) IDiscovery services

• *:credential-store:*:*:1.0 (optional) ICredentialStore stores to resolve credentials

Example:

class MyMySqlPersistence(IdentifiableMySqlPersistence):
    def __init__(self):
        super(MyMySqlPersistence, self).__init__("mydata", MyDataMySqlSchema())

    def __compose_filter(self, filter):
        filter = filter or FilterParams()
        criteria = []
        name = filter.get_as_nullable_string('name')
        if name:
            criteria.append({'name': name})
        return {'$and': criteria} if len(criteria) > 0 else None

    def get_page_by_filter(self, correlation_id, filter, paging):
        return super().get_page_by_filter(correlation_id, self.__compose_filter(filter), paging, None, None)

persistence = MyMySqlPersistence()
persistence.configure(ConfigParams.from_tuples(
    "host", "localhost",
    "port", 27017
))

persistence.open('123')
persistence.create('123', {'id': "1", 'name': "ABC"})
page = persistence.get_page_by_filter('123', FilterParams.from_tuples('name', 'ABC'), None)
print(page.data) # Result: { id: "1", name: "ABC" }

persistence.delete_by_id("123", "1")
# ...

create(correlation_id: Optional[str], item: T) → Optional[T]

Creates a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – an item to be created.

Returns

created item

delete_by_id(correlation_id: Optional[str], id: Any) → T

Deleted a data item by it’s unique id.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• id – an id of the item to be deleted

Returns

deleted item

delete_by_ids(correlation_id: Optional[str], ids: List[Any])

Deletes multiple data items by their unique ids.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• ids – ids of data items to be deleted.

Returns

None for success

get_list_by_ids(correlation_id: Optional[str], ids: List[Any]) → List[T]

Gets a list of data items retrieved by given unique ids.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• ids – ids of data items to be retrieved

Returns

data list

get_one_by_id(correlation_id: Optional[str], id: Any) → T

Gets a data item by its unique id.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• id – an id of data item to be retrieved.

Returns

data item

set(correlation_id: Optional[str], item: T) → Optional[T]

Sets a data item. If the data item exists it updates it, otherwise it create a new data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – a item to be set.

Returns

updated item

update(correlation_id: Optional[str], item: T) → Optional[T]

Updates a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – an item to be updated.

Returns

updated item

update_partially(correlation_id: Optional[str], id: Any, data: pip_services3_commons.data.AnyValueMap.AnyValueMap) → Optional[T]

Updates only few selected fields in a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• id – an id of data item to be updated.

• data – a map with fields to be updated.

Returns

updated item

class pip_services3_mysql.persistence.MySqlPersistence(table_name: str = None, schema_name: str = None)

Bases: pip_services3_commons.refer.IReferenceable.IReferenceable, pip_services3_commons.refer.IUnreferenceable.IUnreferenceable, pip_services3_commons.config.IConfigurable.IConfigurable, pip_services3_commons.run.IOpenable.IOpenable, pip_services3_commons.run.ICleanable.ICleanable

Abstract persistence component that stores data in MySQL using plain driver.

This is the most basic persistence component that is only able to store data items of any type. Specific CRUD operations over the data items must be implemented in child classes by accessing self._db or self._collection properties.

### Configuration parameters ###

• table: (optional) MySQL table name

• schema: (optional) MySQL schema name

• connection(s):

  • discovery_key: (optional) a key to retrieve the connection from IDiscovery

  • host: host name or IP address

  • port: port number (default: 27017)

  • uri: resource URI or connection string with all parameters in it

• credential(s):

  • store_key: (optional) a key to retrieve the credentials from ICredentialStore

  • username: (optional) user name

  • password: (optional) user password

• options:

  • connect_timeout: (optional) number of milliseconds to wait before timing out when connecting a new client (default: 0)

  • idle_timeout: (optional) number of milliseconds a client must sit idle in the pool and not be checked out (default: 10000)

  • max_pool_size: (optional) maximum number of clients the pool should contain (default: 10)

### References ###

• *:logger:*:*:1.0 (optional) ILogger components to pass log messages components to pass log messages

• *:discovery:*:*:1.0 (optional) IDiscovery services

• *:credential-store:*:*:1.0 (optional) ICredentialStore stores to resolve credentials

Example:

class MyMySqlPersistence(MySqlPersistence):
    def __init__(self):
        super(MyMySqlPersistence, self).__init__('mydata')

    def get_by_name(self, correlation_id, name):
        criteria = {'name':name}
        return self._model.find_one(criteria)

    def set(self,correlation_id, item):
        criteria = {'name': item['name']}
        options = {'upsert': True, 'new': True}
        return self._model.find_one_and_update(criteria, item, options)

persistence =MyMySqlPersistence()
persistence.configure(ConfigParams.from_tuples(
    "host", "localhost",
    "port", 27017
))
persistence.open('123')
persistence.set('123', {'name':'ABC'})
item = persistence.get_by_name('123', 'ABC')
print(item) # Result: { name: "ABC" }

clear(correlation_id: Optional[str])

Clears component state.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

Returns

raise error or None no errors occured.

close(correlation_id: Optional[str])

Closes component and frees used resources.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

Returns

raise error or None no errors occured.

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

create(correlation_id: Optional[str], item: T) → Optional[T]

Creates a data item.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• item – an item to be created.

Returns

created item

delete_by_filter(correlation_id: Optional[str], filter: Any)

Deletes data items that match to a given filter.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• filter – (optional) a filter JSON object.

Returns

null for success

get_count_by_filter(correlation_id: Optional[str], filter: Any) → int

Gets a number of data items retrieved by a given filter. This method shall be called by a public getCountByFilter method from child class that receives FilterParams and converts them into a filter function.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• filter – (optional) a filter JSON object

Returns

a data page or error

get_list_by_filter(correlation_id: Optional[str], filter: Any, sort: Any, select: Any) → List[T]

Gets a list of data items retrieved by a given filter and sorted according to sort parameters. This method shall be called by a public getListByFilter method from child class that receives FilterParams and converts them into a filter function.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• filter – (optional) a filter JSON object

• sort – (optional) sorting JSON object

• select – (optional) projection JSON object

Returns

a data list

get_one_random(correlation_id: Optional[str], filter: Any) → T

Gets a random item from items that match to a given filter. This method shall be called by a public getOneRandom method from child class that receives FilterParams and converts them into a filter function.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• filter – (optional) a filter JSON object

Returns

a random item

get_page_by_filter(correlation_id: Optional[str], filter: Any, paging: pip_services3_commons.data.PagingParams.PagingParams, sort: Any, select: Any) → pip_services3_commons.data.DataPage.DataPage

Gets a page of data items retrieved by a given filter and sorted according to sort parameters. This method shall be called by a public getPageByFilter method from child class that receives FilterParams and converts them into a filter function.

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• filter – (optional) a filter JSON object

• paging – (optional) paging parameters

• sort – (optional) sorting JSON object

• select – (optional) projection JSON object

Returns

a data page or raise error

is_open()

Checks if the component is opened.

Returns

true if the component has been opened and false otherwise.

open(correlation_id: Optional[str])

Opens the component.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

Returns

raise error or null no errors occured.

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

unset_references()

Unsets (clears) previously set references to dependent components.