SQLSourcery🔗ℹ

Database backed structs for functional programmers. A SQLSourcery programmer is a sourcerer.

Github Repo

1 Motivation🔗ℹ

Racket programs require lots of boilerplate for any sort of basic I/O persistency, and getting this I/O to fit into a functional style causes many additional problems. SQLSourcery attempts to allow a sourcerer to easily spin up state persistency of their structures that can fit into their coding paradigms with minimal adaptation.

2 Database Connection🔗ℹ

SQLSourcery programs must first connect to a SQLite database. It is typical to set the database at the top of a file or module. Test modules typically use a different database than programs. When a database is changed, all loaded sourcery structures currently in existence are subject to error. Any operations besides sourcery structure declarations will throw an error if a database is not set.

3 Sourcery Structures🔗ℹ

3.1 Structure Definition🔗ℹ

A sourcery-struct acts as a typical structure with added database persistence.

This will create a new structure source or connect to an existing structure source with an identical definition. If an existing sourcery-struct deinition with the same name already exists in the database but the definition is not identical, an error will be raised.

No field name identifier can start with the characters "__", nor can they be one of the following reserved fields:

• update

• create

• map

• unmapped

A sourcery-struct definition will create the following functions:

> (spell-power bees-new)

200

> (spell-power bees)

200

Here both bees and new-bees reference the same spell.

3.2 Loading Structures🔗ℹ

3.3 Deleting Structures🔗ℹ

Attempting to operate on bees will result in an error.

The example above deletes all spells that are not deadly.

4 Testing🔗ℹ

SQLSourcery programs must test mutation and be able to easily write setup and teardown. While possible with racket, the library can be combersome to use. SQLSourcery comes with a testing library.

4.1 Testing Philosophy🔗ℹ

Sourcery Test Suites uses the racket test-suite and adds the tests to a module level global lists of tests that can be run with a single command. At its core, these are most useful for their before and after clauses, which take in actions.

In order to take advantage of before and after clauses in test suites, varaibles must be avaiable in the before, during, and after stages, as well as being able to be modified. While this can be done with set!, the testing library allows easy declaration, setting, and clearing of testing varaibles through a simple API that clearly signifies their status for testing and will prevent accidental mutation of variables not used in testing.

Before and after clauses in test-suite are thunks that return void. To simplify writing these thunks, the testing library introduces the concept of actions that can perform multiple operations at once and can be composed together in an intuitive order for the context of testing.

Testing will use the currently set sourcery-db. It is customary to test by using a test module and using a testing database via a call to sourcery-db at the start of the module

4.2 Testing Variables🔗ℹ

4.3 Testing Actions🔗ℹ

4.4 Testing Cleanup🔗ℹ

4.5 Sourcery Test Suites🔗ℹ

5 Programming with SQLSourcery🔗ℹ

5.1 SQLSourcery, Side Effects, and Mutation🔗ℹ

By nature, SQLSourcery is at odds with one of the often noted rules and advantages of functional programming - that mutation and side effects should be avoided when possible.

However, this does not mean that programmers should be forced to change the way they write their functional code, only that a few additional considerations must be made in order to get the advantages of database backing. This section is dedicated to explaining how programmers can think about these issues while still writing idiomatic code.

5.2 Under The Hood🔗ℹ

At its core, SQLSourcery simply translates all operations with structures into SQL queries. It then introduces unique numeric idenifiers that are tied to each structure. Instances of structures are in fact simply references to these identifiers. Programming with sourcery structures is thus working with references, not values. While SQLSourcery allows for multiple references to the same value, it is designed so that there is no need use the feature, and one can write fully functional code, which then tracks its state with the connected database.

5.3 Dead References🔗ℹ

Since sourcery structures at their core are references, and the values that a reference points to can be modified or deleted, it is then possible to have an invalid or "dead" reference. When sourcery-delete is used, any remaining references then become dead references. If a sourcerer chooses to use multiple references to the same value, it is the responsibility of the sourcerer to keep track of the status of references.