DB Adapter Quickstart

Want Chicago Boss to support your favorite database? Then write an adapter! This page explains how.

Database adapters should conform to the boss_db_adapter behaviour and need to implement the following ten functions:

start(Options) -> ok

Performs any adapter initialization.

stop() -> ok

Performs any adapter tear-downs.

init(Options) -> {ok, Connection | undefined}

Performs any connection initialization and return a Connection value (if needed).

terminate(Conn) -> ok

Performs any connection tear-downs.

find(Conn, Id::string()) -> BossRecord | {error, Reason}

Returns a BossRecord matching the Id. The Id must be unique across data types.

find(Conn, Type::atom(), Conditions, Max::integer() | all, Skip::integer(), Sort::atom(), SortOrder) -> [BossRecord]

Queries for BossRecords. The Conditions are guaranteed to be in {Key, Operator, Value} format. See the BossDB API for a list of query operators you need to support.

count(Conn, Type::atom(), Conditions) -> ::integer()

Counts the number of BossRecords of type Type matching Conditions.

counter(Conn, Id::string()) -> ::integer()

Retrieves the value of a counter, or 0 if the counter does not exist.

incr(Conn, Id::string(), Increment::integer()) -> ::integer()

Increments the value of a counter by Increment, and returns the new value.

delete(Conn, Id::string()) -> ok | {error, Reason}

Delete the BossRecord with the given Id.

save_record(Conn, RecordBossRecord) -> {ok, SavedBossRecord}

Saves (that is, creates or updates) the given BossRecord in the database. If the ID is set to ‘id’, the function must generate an ID that is unique across data types. This function should not perform validation or run save hooks.

When you’re finished, just:

1. Put the adapter into boss_db/src/db_adapters
2. Specify the adapter name as the db_adapter in boss.config
3. Add any test configuration to boss_db/priv/test_db_config
4. Add a test_<adapter name> target to the bottom of Makefile
5. Test the adapter by running

   make test_<adapter name>

6. Send a note to the Chicago Boss mailing list