Skip to content
Relational database persistence for Pharo objects
Smalltalk HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
BaselineOfReStore Move SQLite3 support from UDBC to pharo-rdbms Dec 10, 2019
SSW ReStore Base Additions Initial commit Dec 4, 2019
SSW ReStore Collections Initial commit Dec 4, 2019
SSW ReStore Examples Add Examples package Dec 6, 2019
SSW ReStore Main Add support for inlined/embedded objects (objects stored directly in … Jan 24, 2020
SSW ReStore MySQL Refactor Database Connections - more Traits, Add MySQL initial versio… Dec 20, 2019
SSW ReStore P3 Refactor Database Connections - more Traits, Add MySQL initial versio… Dec 20, 2019
SSW ReStore Querying Add support for inlined/embedded objects (objects stored directly in … Jan 24, 2020
SSW ReStore SQL Entities Bugfixes Dec 6, 2019
SSW ReStore SQL Queries Initial commit Dec 4, 2019
SSW ReStore SQLite3 Updates for recent changes to SQLite Dec 20, 2019
SSW ReStore Tables Add support for inlined/embedded objects (objects stored directly in … Jan 24, 2020
SSW ReStore Tests-Pharo Move SQLite3 support from UDBC to pharo-rdbms Dec 10, 2019
SSW ReStore Tests
SSW ReStore for Pharo Add support for inlined/embedded objects (objects stored directly in … Jan 24, 2020
Wolphin Bugfixes Dec 6, 2019
.project Initial commit Dec 4, 2019
.properties Initial commit Dec 4, 2019
LICENSE Initial commit Dec 4, 2019
README.md Update README.md Jan 15, 2020
_config.yml Set theme jekyll-theme-slate Dec 6, 2019

README.md

What is ReStore?

ReStore is a framework enabling Pharo objects to be stored in and read from relational databases (SQLite, PostgreSQL etc.). ReStore aims to make relational persistency as simple as possible, creating and maintaining the database structure itself and providing access to stored objects via familiar Smalltalk messages.

Getting Started

To load ReStore into your Pharo 7 or 8 image, evaluate:

Metacello new
    repository: 'github://rko281/ReStoreForPharo';
    baseline: 'ReStore';
    load: 'all'

This will load ReStore with support for SQLite (via pharo-rdbms) and PostgreSQL (via P3), plus the example classes we'll discuss next.

A Simple Example

Let's consider a simple customer order application with the following classes (found in the SSW ReStore Examples package):

Object subclass: #Customer
	instanceVariableNames: 'firstName surname emailAddress dateOfBirth address orders'

Object subclass: #Address
	instanceVariableNames: 'line1 postcode country'

Object subclass: #Order
	instanceVariableNames: 'date product quantity customer'
    
Object subclass: #Product
	instanceVariableNames: 'name description'

The first step in adding persistency with ReStore is to define the structure of the classes. This is done with the class method reStoreDefinition - for the Customer class this is:

reStoreDefinition

	^super reStoreDefinition
		define: #surname as: (String maxSize: 100);
		define: #firstName as: (String maxSize: 100);
		define: #emailAddress as: (String maxSize: 100);
		define: #dateOfBirth as: Date;
		define: #address as: Address dependent;
		define: #orders as: (OrderedCollection of: Order dependent owner: #customer);
		yourself.

A couple of things worth highlighting here:

  • define: #address as: Address dependent - adding dependent to a definition means that object is dependent on the originating object for its existence. In this case the customer's address object is dependent on the owning customer - this means any changes to the address will be saved along with the customer, and the address will be deleted if the customer is deleted.
  • define: #orders as: (OrderedCollection of: Order dependent owner: #customer) - this is an example of an owned collection definition. An owned collection is one where the elements of the collection contain a reference to the owner of the collection. In this case instances of Order refer to their owning customer via their customer instance variable.

Creating the Database

With ReStore definitions created for all classes we can now connect to the database and create the database structure:

ReStore
	connection: (SSWSQLite3Connection on: (Smalltalk imageDirectory / 'test.db') fullName);
	connect;
	addClasses: {Customer. Address. Order. Product};
	synchronizeAllClasses.
  • for simplicity we're using SQLite; please ensure the SQLite3 library/DLL is available to your image. If you'd rather use PostgreSQL you'll need to specify a connection similar to this: (SSWP3Connection new url: 'psql://user:pwd@192.168.1.234:5432/database')
  • synchronizeAllClasses prompts ReStore to create the necessary database tables for the classes Customer, Address, Order and Product. If you subsequently modify these classes (and their ReStore definitions) you can run synchronizeAllClasses again to prompt ReStore to automatically update the table definitions (add or remove columns from the tables) to match the updated class definitions.

Storing Objects

With the database setup we can now create and persist objects using the store message:

Customer new
	firstName: 'John';
	surname: 'Smith';
	address: (Address new country: 'UK'; yourself);
	store.

Customer new
	firstName: 'Jen';
	surname: 'Smith';
	address: (Address new country: 'France'; yourself);
	store.

Reading Objects

Now we have some objects in the database we need a way to find and read them. ReStore does this via the message storedInstances which gives a virtual collection of instances of a particular class stored in the database. The virtual collection can then be queried using the familiar Smalltalk collection enumeration messages select:, detect: etc.

"All Smiths"
Customer storedInstances select: [ :each | each surname = 'Smith'].

"John Smith"
Customer storedInstances select: [ :each | (each firstName = 'John') & (each surname = 'Smith')].
"alternatively:"
Customer storedInstances select: [ :each | each fullName = 'John Smith'].

"Customers in France"
Customer storedInstances select: [ :each | each address country = 'France'].

ReStore analyses the block argument to select:, detect: etc., translating this to SQL which is used to query the database. In this way required objects can be efficiently located without having to read all objects into the image. If all objects are required this can be done by converting the storedInstances virtual collection to a real collection:

Customer storedInstances asOrderedCollection

Updating Objects

Persisting changes to objects is also done using the store message:

"Updating a Customer"
johnSmith := Customer storedInstances detect: [ :each | each fullName = 'John Smith'].
johnSmith dateOfBirth: (Date newDay: 1 monthIndex: 2 year: 1983).
johnSmith address postcode: 'W1 1AA'.
johnSmith store.

"Check it:"
Customer storedInstances detect: [ :each | each address postcode = 'W1 1AA'].

"Creating an Order - first we need a product"
widget := Product new name: 'Widget'.
widget store.

johnSmith 
    addOrder: 
        (Order new 
            date: Date today;
            product: widget;
            quantity: 4;
            yourself);
    store.
    
"Check it:"
Customer storedInstances detect: [ :each | each orders anySatisfy: [ :order | (order product = widget) & (order quantity = 4)]].

Next Steps

This is just a sample of what ReStore can do, with an empahsis on simplicity. ReStore also supports more sophisticated usage patterns including:

  • transactions with automatic change-tracking
  • multi-user update clash detection and resolution
  • persistent class hierarchies
  • multiple, independent ReStore instances, including per-process and per-session support
  • query-by-example (template queries)
  • customisable Smalltalk-to-SQL conversion

Documentation and examples of these to follow. In the meantime please browse the included SUnits for more examples.

You can’t perform that action at this time.