• Stars
    star
    173
  • Rank 220,124 (Top 5 %)
  • Language
    Erlang
  • License
    Apache License 2.0
  • Created over 11 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Erlang Persistency Framework

Stories in Ready

sumo_db

Build Status

About

This is a work in progress. There's also an article about sumo_db. This articles might be a little outdated by now, but can still provide some basic information on how to get started.

sumo_db aims to ease db access for erlang applications. It offers a very simple persistance layer capable of interacting with different db's, while offering a consistent api to your code.

Contact Us

If you find any bugs or have a problem while using this library, please open an issue in this repo (or a pull request :)).

Overview

  • sumo_db gives you a standard way to define your db schema, regardless of the db implementation (mongo, mysql, redis, elasticsearch, etc.).

  • Your entities encapsulate behavior in code (i.e. functions in a module) and state in a sumo:doc() implementation.

  • sumo is the main module. It translates to and from sumo internal records into your own state.

  • Each store is managed by a worker pool of processes, each one using a module that implements sumo_store and calls the actual db driver (e.g: sumo_store_mnesia).

  • Some native domain events are supported, that are dispatched through a gen_event:notify/2 automatically when an entity is created, updated, deleted. Also when a schema is created and when all entities of a given type are deleted. Events are described in this article.

  • Full conditional logic support when using find_by/2 and delete_by/2 function. You can find more information about the syntax of this conditional logic operators here.

  • Support for sorting (asc or desc) based on multiple fields unsing find_by/5 and find_all/4 functions. For example this [{age, desc}, {name, asc}]] will sort descendently by age and ascendently by name.

  • Support for docs/models validations through sumo_changeset (check out the Changeset section).

Backends, Stores and Repositories modules

These three concepts have a specific meaning in the context of sumo_db.

  • Backend: establishes and holds a single Database instance connection.

  • Store: implements the specific operations that modify the contents of the backend and retrieves the information it holds.

  • Repository: the application that uses sumo_db should implement one repository for each entity that's defined in it. The repository is the module that bridges the model and the store.

Supported Backends/Adapters

Implementing an Adapter

To implement an adapter, you must implement two specific behaviours:

You can check the implemented adapters mentioned above in order to have a better idea about how to build a custom adapter from scratch.

Events

Sumo dispatches events when things happen. An Event has this structure:

{EventId, Model, Event, Args}
  • EventId is a reference() which identifies the event
  • Model is the model where the event happend, for example, if we are creating a new entitiy in the model people the value of Model would be people.
  • Event is the type of the event.
  • Args extra data sent.

Supported types of events:

  • pre_persisted just before persisting some entity. This event has the entity we want to persist as Args. It is dispatched on this function:
    • sumo:persist/2
  • persisted just after persisting some entity. This event has the persisted entity as Args. This Event has the same EventId as its pre_persisted event. It is dispatched on this function:
    • sumo:persist/2
  • pre_delete_all just before deleting all entities for a model. This event has no Args. It is dispatched on this function:
    • sumo:delete_all/1
  • deleted_all just after deleting all entities for a model. This event has no Args. This Event has the same EventId as its pre_delete_all event. It is dispatched on this function:
    • sumo:delete_all/1
  • pre_deleted just before deleting an entity. This event has the entity id as Args. It is dispatched on this function:
    • sumo:delete/2
  • deleted just after deleting an entity. This event has the entity id as Args. This Event has the same EventId as its pre_deleted event. It is dispatched on this function:
    • sumo:delete/2
  • pre_deleted_total just before deleting by some delete conditions. This event has the sumo conditions as Args. It is dispatched on this function:
    • sumo:delete_by/2
  • deleted_total just after deleting by some delete conditions. This event has a list with the number of entities deleted and the delete conditions as Args. This Event has the same EventId as its pre_deleted_total event. It is dispatched on this function:
    • sumo:delete_by/2
  • pre_schema_created just before creating a sumo schema. This event has no Args. It is dispatched on this function:
    • sumo:create_schema/2
  • schema_created just after creating a sumo schema. This event has no Args. This Event has the same EventId as its pre_schema_created event. It is dispatched on this function:
    • sumo:create_schema/2

Sumo requires users to add their own gen_event's in order to handle those events. In order to add them Users have to configure sumo properly. In the config file we can add them like this under sumo_db configuration:

{events, [
   {'_', sumo_test_people_events_manager},
   {people, sumo_test_people_events_manager}
 ]}

Sumo allows us to add a gen_event to one type of model (i.e. people) or for all ('_').

Changeset

This feature is inspired by Elixir Ecto.Changeset, and the module that implements this feature is sumo_changeset.

Changeset Usage Example

NOTE: This example uses FancyFlow in order to pipe changeset functions in a nicer way.

%% suppose you have a model/doc `person`, and that module provides a function
%% to encapsulate model/doc creation
Person = person:new(<<"John">>, <<"Doe">>),

%% create the set of params/changes
Params = #{age => 33, id => 1, <<"last_name">> => <<"other">>},

%% run the changeset
Changeset = [pipe](people,
  sumo_changeset:cast(_, Person, Params, [id, first_name, last_name, age, status]),
  sumo_changeset:validate_required(_, [id, last_name, status]),
  sumo_changeset:validate_inclusion(_, status, [<<"active">>, <<"blocked">>]),
  sumo_changeset:validate_number(_, age, [{less_than_or_equal_to, 18}]),
  sumo_changeset:validate_length(_, last_name, [{min, 3}]),
  sumo_changeset:validate_format(_, last_name, <<"^[a-zA-Z]">>)),

Examples

See: examples/blog for a full example. To run it, while being in the top level directory:

make all blog

See: examples/custom_store for creating your own Store. To run it, follow the instructions in this README

Running Dialyzer

$ rebar3 dialyzer

Running Tests

$ rebar3 ct

Change Log

All notable changes to this project will be documented in the CHANGELOG.md.

Contributors

We want to thank all of our contributors for their hard work :muscle:.

More Repositories

1

erlang_guidelines

Inaka's Erlang Coding Guidelines
Erlang
619
star
2

EventSource

A simple Swift client library for the Server Sent Events (SSE)
Swift
483
star
3

galgo

When you want your logs to be displayed on screen
Java
427
star
4

elvis

Erlang Style Reviewer
Erlang
424
star
5

apns4erl

Apple Push Notification Server for Erlang
Erlang
369
star
6

TinyTask

A Tiny Task Library
Java
324
star
7

worker_pool

Erlang worker pool
Erlang
274
star
8

shotgun

For the times you need more than just a gun.
Erlang
166
star
9

Dayron

A repository `similar` to Ecto.Repo that maps to an underlying http client, sending requests to an external rest api instead of a database
Elixir
159
star
10

cowboy_swagger

Swagger integration for Cowboy (built on trails)
Erlang
120
star
11

gold_fever

A Treasure Hunt for Erlangers
Erlang
86
star
12

Jayme

Abstraction layer that eases RESTful interconnections in Swift
Swift
81
star
13

guidelines

General Inaka Guidelines
75
star
14

cowboy-trails

A couple of improvements over Cowboy Routes
Erlang
71
star
15

jem.js

Just Erlang Maps for Javascript
JavaScript
69
star
16

sheldon

Very Simple Erlang Spell Checker
Erlang
62
star
17

elvis_core

The core of an Erlang linter
Erlang
61
star
18

niffy

Inline C code in Erlang modules to build NIFs
Erlang
60
star
19

sumo_rest

Generic cowboy handlers to work with Sumo
Erlang
59
star
20

serpents

Multi-Player Game on top of HDP protocol
Erlang
56
star
21

xref_runner

Erlang Xref Runner (inspired in rebar xref)
Erlang
50
star
22

erlang-github

Github API client
Erlang
46
star
23

lasse

SSE handler for Cowboy
Erlang
45
star
24

beam_olympics

Let's find the fastest beamer!
Erlang
39
star
25

fiar

Four in a Row - A game to learn Erlang
Erlang
36
star
26

zipper

Generic Zipper implementation in Erlang
Erlang
34
star
27

ios-xmpp-sample

Blog post sample project.
Swift
33
star
28

kotlillon

Android Kotlin Examples
Kotlin
33
star
29

katana-test

Meta Testing Utilities for common_test
Erlang
32
star
30

match_stream

A sample project to show in our scale blog post
JavaScript
30
star
31

phoenix_passwordless_login

Phoenix Passwordless Login
Elixir
29
star
32

KillerTask

Android AsyncTask wrapper library, written in Kotlin
Kotlin
26
star
33

canillita

Simple Paperboy-themed PubSub
Erlang
26
star
34

lewis

Rock your Android
Java
22
star
35

tirerl

Erlang interface to Elastic Search
Erlang
19
star
36

itweet

Twitter Stream API on ibrowse
Erlang
18
star
37

katana-code

Code Utilities for Erlang
Erlang
17
star
38

pusherman

queuing system for push notifications
Erlang
17
star
39

galgo-ios

When you want your logs to be displayed on screen
Objective-C
16
star
40

lsl

NIM in Erlang
Erlang
15
star
41

credo_server

Credo Server
Elixir
15
star
42

FadeButton

Fading effects for UIButtons made simple
Swift
15
star
43

Jolly

Jolly Chimp that keeps track of our Github Repos
Swift
12
star
44

rpsls

Rock Paper Scissors Lizzard Spock World Championship in Erlang
Erlang
12
star
45

ikbot

An elixir based customizable hipchat bot
Elixir
12
star
46

nconf

Nested Configuration Manager for Erlang Applications
Erlang
12
star
47

pushito

APNS over HTTP/2
Elixir
11
star
48

rest_guidelines

REST API Design Guidelines
11
star
49

fetjaba

From Erlang To Java and Back Again
Erlang
9
star
50

sumo_db_pgsql

PostgreSQL adapter for sumo_db.
Erlang
9
star
51

jinterface_stdlib

Erlang stdlib implementation on Java, based on JInterface
Java
9
star
52

IKCapture

Snapchat-Like Image Capture Library
Objective-C
8
star
53

MediaPickerController

Neat API for presenting the classical action sheet for picking an image or video from the device or camera.
Swift
8
star
54

PictureViewMaster

Interactive image projector.
Swift
8
star
55

toy_kv

A simple and reduced Key-Value Store written in Erlang
Erlang
7
star
56

ColorPicker

Color Picker for Swift
Swift
7
star
57

swift_guidelines

Inaka's Swift Coding Guidelines
7
star
58

spellingci

Spelling CI Server
Erlang
7
star
59

talks

Sources and pdfs of our talks and speeches
TeX
6
star
60

bookmarks

A collection of bookmarks for Inakos
6
star
61

IKJayma

RESTful API abstraction for Server Interconnection
Objective-C
6
star
62

hexer

Hex.pm integration in escript format.
Erlang
6
star
63

hexer.mk

erlang.mk plugin for hexer
Makefile
5
star
64

android_guidelines

Inaka's Android Development Guidelines
5
star
65

elvis.mk

3rd party erlang.mk plug-in for Elvis
Shell
5
star
66

plixir

Poker + Elixir + Phoenix
CSS
5
star
67

ios_guidelines

Inaka's iOS Coding Guidelines
Objective-C
4
star
68

sumo_db_elasticsearch

ElasticSearch adapter for sumo_db
Erlang
4
star
69

tele_sign

Node.js library to send messages through http://www.telesign.com/
JavaScript
4
star
70

inaka.github.io

Inaka's Open Source Projects
HTML
3
star
71

sumo_db_riak

Riak adapter for sumo_db
Erlang
3
star
72

android-excercises

Quick test for Android candidates
3
star
73

sumo_db_mongo

MongoDB adapter for sumo_db
Erlang
2
star
74

Otec

A swift app to showcase our best open-source libraries
Swift
2
star
75

gold_fever-solver

A solver for the http://github.com/inaka/gold_fever game
Erlang
2
star
76

inaka.mk

erlang.mk extras that we generally use in all of our projects
Makefile
2
star
77

g2x

Graffle to XCode
Objective-C
2
star
78

beam_olympics-extended

Internal repo to keep secret beam_olympics tasks from the public view
Erlang
2
star
79

beam_olympics-solver

Solutions for beam_olympics
Elixir
2
star
80

emarkdown

Based on https://github.com/devinus/markdown - but for Erlang :)
C
2
star
81

sumo_db_mysql

MySQL adapter for sumo_db
Erlang
2
star
82

ruby_guidelines

Our own guidelines when it comes to ruby development
1
star
83

pokedex

Dumb repo to prove what we can do with sumo{_db|rest_}
Erlang
1
star
84

homebrew-formulas

Homebrew formulas for some of our tools
Ruby
1
star
85

updike

Run, rabbit, run
1
star
86

ios-scripts

Helper scripts that you can use in your iOS apps
Shell
1
star
87

INSocketListener

SSE Socket Listener for Objective-C
Objective-C
1
star