Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Web and Applications

Persistence with Fuel and Databases

Compare ways to keep Smalltalk objects after a restart: the image, Fuel binary serialization, STON and JSON text, Voyage with MongoDB, and SQL. Read-only Smalltalk plus runnable serialization stand-ins.

An image keeps your objects alive between sessions, but it is a poor database: it is one big file, it has no queries, and two programs cannot share it. Real applications need persistence that is safe, shareable and sometimes human-readable. This lesson compares the common choices in Pharo and shows how each works, with read-only Smalltalk and runnable JavaScript stand-ins for the underlying ideas.

None of these libraries run on this site, so the Smalltalk is for reading. The stand-ins model the core concepts: object graphs with shared references and cycles, text serialization, and the object-to-record mapping.

Choice 1: the image itself

Saving the image persists everything, including live windows. It is fine for personal tools and prototypes. It is not fine for multi-user systems or for data you must not lose when an image corrupts. Treat the image as a cache of state you could rebuild, as discussed in the image workflow.

Choice 2: Fuel, binary object graphs

Fuel serializes a whole graph of objects into a compact binary file, fast, and keeps shared references and cycles intact (read-only):

SMALLTALK
FLSerializer serialize: myCatalog toFileNamed: 'catalog.fuel'.
catalog := FLMaterializer materializeFromFileNamed: 'catalog.fuel'.

If two books share the same Author object, after materializing they still share one author, and a parent-child pair that point at each other still do. Fuel is the right tool for exporting a model, shipping a test fixture, or checkpointing. It is Pharo-specific and the binary format ties files to class definitions, so plan how to migrate when classes change.

Choice 3: STON and JSON, readable text

STON (Smalltalk Object Notation) is a text format close to JSON but able to name classes (read-only):

SMALLTALK
STON toString: (Point x: 3 y: 4).     "Point{#x:3,#y:4}"
STON fromString: 'Point{#x:3,#y:4}'.  "a Point"

For data you share with other languages, use JSON through NeoJSON, which handles only dictionaries, arrays, strings, numbers, booleans and nil, so you map objects by hand with a mapper:

SMALLTALK
NeoJSONWriter toString: { 'title' -> 'Dune'. 'year' -> 1965 } asDictionary.
NeoJSONReader fromString: '{"title":"Dune","year":1965}'.

Text formats are easy to diff and debug, and they survive class changes better. They do not preserve shared references unless you encode them yourself.

Choice 4: Voyage, objects in a database

Voyage is an object-document mapper. You mark a class as a root (isVoyageRoot), connect to a MongoDB or in-memory backend, and use save, selectAll and select: (read-only):

SMALLTALK
VOMongoRepository mongoRepository: 'bank'.     "or VOMemoryRepository new"

Account class >> isVoyageRoot
    ^ true

anAccount save.
Account selectAll.
Account select: [ :each | each balance > 1000 ].
Account selectOne: [ :each | each owner = 'Ana' ].

The backend decides how objects become documents; embedded objects are saved inside the root and referenced ones as links. Voyage with the memory repository is excellent for tests, because it needs no server.

Choice 5: SQL

For relational databases, Pharo has drivers (PostgreSQL, MySQL, SQLite through P3, a MySQL driver or UFFI binding) and mapping layers such as GlorpSQL. Plain SQL works well for reporting and when the data predates the application. The usual advice is the same as in every language: keep the mapping in one layer, use parameters instead of string concatenation, and wrap multi-step changes in transactions.

Which to choose

Need Good fit
Personal tool, prototype The image
Checkpoint or export an object graph Fuel
Config, small data, human review STON or JSON
Shared multi-user data with queries Voyage + MongoDB, or SQL
Exchange with other languages JSON

Graphs, cycles and sharing

A serializer must cope with shared references and cycles: if it simply expands every reference, a cycle recurses forever and a shared object is duplicated. Fuel handles this by numbering each object and storing references to numbers. The following runnable stand-in does the same in JavaScript and restores identity on load.

JS Stand-in: serializing a graph with sharing and cycles

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A plain JSON.stringify would throw on the cycle and duplicate the shared author. Numbering the objects avoids both.

An object-to-record mapping

A mapper converts objects to flat records and back. Voyage and SQL layers are this idea at scale.

JS Stand-in: a tiny in-memory repository

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that changing the loaded object does nothing until you save, because the repository returned a copy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is saving the image a poor database?

    An image suits personal state but not shared, queryable, durable data.
  2. 2. What is Fuel good at?

    Fuel stores graphs with identity preserved and is fast.
  3. 3. What does Voyage do?

    Voyage saves and queries root objects over MongoDB or memory backends.
  4. 4. Which format is best for exchanging data with other languages?

    JSON is universal, while Fuel and STON are Smalltalk-oriented.

Summary

  • Pick persistence by need: image for prototypes, Fuel for graphs, STON/JSON for text, Voyage or SQL for shared data.
  • Serializers must handle shared references and cycles by numbering objects.
  • Mappers and repositories keep persistence code in one layer, separate from the domain.
  • Use the in-memory backend in tests.
  • Smalltalk code is read-only; the JavaScript snippets are stand-ins.

Next: Morphic and Spec: User Interfaces