genesisdb/genesisdb-ce

By genesisdb

•Updated 6 months ago

GenesisDB CE is an event sourcing database engine for building event-driven apps.

Image

Databases & storage

10K+

Overview Tags

genesisdb/genesisdb-ce repository overview

⁠GenesisDB CE (Community Edition)

GenesisDB CE is a free and production ready event store database system for building event-driven apps.

⁠Advantages

Incredibly fast when reading, fast when writing
Easy backup creation and recovery
CloudEvents⁠ compatible
Easily accessible via the HTTP interface
Built-in consistency
Logging and metrics
HTTP API
SQL like query language called GenesisDB Query Language (limited functionality)
...

⁠Community Edition Limitations

Community Edition shares the same technical core and version as Enterprise, the difference is only in the feature set. The Community Edition has the following limitations compared to the enterprise version:

⁠Not Available Features:

No /api/v1/query endpoint: GDBQL queries cannot be executed via the standalone query endpoint
No storeDataAsReference option: Cannot store event data as external references for GDPR compliance
No /api/v1/erase endpoint: Cannot erase referenced data
No /api/v1/schema/register endpoint: Cannot register schemas for event validation
No /api/v1/schema/get endpoint: Cannot retrieve registered schemas
No gRPC API Endpoint: The gRPC API Endpoint is available exclusively in the Enterprise edition

⁠Limited Features:

GDBQL isQueryResultTrue precondition only: The GenesisDB Query Language is only available within commit event preconditions for validation purposes.

For full GDPR compliance features and advanced query capabilities, please upgrade to the enterprise version at https://www.genesisdb.io⁠

⁠Pull the latest docker image

Just run:

docker pull genesisdb/genesisdb-ce:latest

Or execute the following directly:

⁠Install a new instance

docker run -d \
  --name <instance-name> \
  -e GENESISDB_AUTH_TOKEN=<secret> \
  -e GENESISDB_TZ=Europe/Vienna \
  -e GENESISDB_PORT=8080 \
  -e GENESISDB_METRICS=true \
  -p 8080:8080 \
  genesisdb/genesisdb-ce:latest

Note: Community Edition does not require a license key.

⁠Available client SDKs

⁠API Usage

⁠Commit Events

curl --location "http://localhost:8080/api/v1/commit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
  "events": [
        {
            "source": "io.genesisdb.app"
            "subject": "/customer",
            "type": "io.genesisdb.app.customer-added",
            "data": {
                "firstName": "Bruce",
                "lastName": "Wayne",
                "emailAddress": "[email protected]"
            }
        },
        {
            "source": "io.genesisdb.app"
            "subject": "/customer",
            "type": "io.genesisdb.app.customer-added",
            "data": {
                "firstName": "Alfred",
                "lastName": "Pennyworth",
                "emailAddress": "[email protected]"
            }
        },
        {
            "source": "io.genesisdb.store"
            "subject": "/article",
            "type": "io.genesisdb.store.article-added",
            "data": {
                "name": "Tumbler",
                "color": "black"
                "price": 2990000.00
            }
        },
        {
            "source": "io.genesisdb.app"
            "subject": "/customer/fed2902d-0135-460d-8605-263a06308448",
            "type": "io.genesisdb.app.customer-personaldata-changed",
            "data": {
                "firstName": "Angus",
                "lastName": "MacGyver",
                "emailAddress": "[email protected]"
            }
        }
    ]
  }
'

⁠Usage of preconditions

GenesisDB supports preconditions to ensure data consistency and enforce business rules atomically at the database level.

⁠Available Precondition Types

⁠1. `isSubjectNew`

Ensures that no events exist for the specified subject.

curl --location "http://localhost:8080/api/v1/commit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
  "events": [
        {
            "source": "io.genesisdb.app",
            "subject": "/user/456",
            "type": "io.genesisdb.app.foo-added",
            "data": {
                "firstName": "John",
                "lastName": "Doe",
                "email": "[email protected]"
            }
        }
    ],
    "preconditions": [
        {
            "type": "isSubjectNew",
            "payload": {
                "subject": "/user/456"
            }
        }
    ]
  }
'

⁠2. `isSubjectExisting`

Ensures that events exist for the specified subject.

curl --location "http://localhost:8080/api/v1/commit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
  "events": [
        {
            "source": "io.genesisdb.app",
            "subject": "/user/456",
            "type": "io.genesisdb.app.foo-added",
            "data": {
                "firstName": "John",
                "lastName": "Doe",
                "email": "[email protected]"
            }
        }
    ],
    "preconditions": [
        {
            "type": "isSubjectExisting",
            "payload": {
                "subject": "/user/456"
            }
        }
    ]
  }
'

⁠3. `isQueryResultTrue` (Community Edition - LIMITED)

Note: In Community Edition, GDBQL is only available within commit preconditions for validation purposes.

Executes a GDBQL query and validates that the result evaluates to true. Supports the full GDBQL feature set including complex WHERE clauses, aggregations, and calculated fields.

Basic uniqueness check:

curl --location "http://localhost:8080/api/v1/commit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
  "events": [
        {
            "source": "io.genesisdb.app",
            "subject": "/user/456",
            "type": "io.genesisdb.app.user-created",
            "data": {
                "firstName": "John",
                "lastName": "Doe",
                "email": "[email protected]"
            }
        }
    ],
    "preconditions": [
        {
            "type": "isQueryResultTrue",
            "payload": {
                "query": "STREAM e FROM events WHERE e.data.email == '[email protected]' MAP COUNT() == 0"
            }
        }
    ]
  }
'

Business rule enforcement (transaction limits):

curl --location "http://localhost:8080/api/v1/commit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
  "events": [
        {
            "source": "io.genesisdb.banking",
            "subject": "/user/123/transactions",
            "type": "io.genesisdb.banking.transaction-processed",
            "data": {
                "amount": 500.00,
                "currency": "EUR"
            }
        }
    ],
    "preconditions": [
        {
            "type": "isQueryResultTrue",
            "payload": {
                "query": "STREAM e FROM events WHERE e.subject UNDER '/user/123' AND e.type == 'transaction-processed' AND e.time >= '2024-01-01T00:00:00Z' MAP SUM(e.data.amount) + 500 <= 10000"
            }
        }
    ]
  }
'

Complex validation with aggregations:

curl --location "http://localhost:8080/api/v1/commit" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
  "events": [
        {
            "source": "io.genesisdb.events",
            "subject": "/conference/2024/registrations",
            "type": "io.genesisdb.events.registration-created",
            "data": {
                "attendeeId": "att-789",
                "ticketType": "premium"
            }
        }
    ],
    "preconditions": [
        {
            "type": "isQueryResultTrue",
            "payload": {
                "query": "STREAM e FROM events WHERE e.subject UNDER '/conference/2024/registrations' AND e.type == 'registration-created' GROUP BY e.data.ticketType HAVING e.data.ticketType == 'premium' MAP COUNT() < 50"
            }
        }
    ]
  }
'

Supported GDBQL Features in Preconditions:

WHERE conditions with AND/OR/IN/BETWEEN operators
Hierarchical subject queries (UNDER, DESCENDANTS)
Aggregation functions (COUNT, SUM, AVG, MIN, MAX)
GROUP BY with HAVING clauses
ORDER BY and TOP clauses
Calculated fields and expressions
Nested field access (e.data.address.city)
String concatenation and arithmetic operations

If a precondition fails, the commit returns HTTP 412 (Precondition Failed) with details about which condition failed.

⁠Stream Events

curl --location "http://localhost:8080/api/v1/stream" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "subject": "/customer"
  }
'

⁠Stream Events from lower bound

curl --location "http://localhost:8080/api/v1/stream" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "subject": "/",
    "options": {
        "lowerBound": "2d6d4141-6107-4fb2-905f-445730f4f2a9",
        "includeLowerBoundEvent": true
    }
}
'

⁠Stream Events with upper bound

curl --location "http://localhost:8080/api/v1/stream" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "subject": "/",
    "options": {
        "upperBound": "9f3e4141-7208-4fb2-905f-445730f4f3b1",
        "includeUpperBoundEvent": false
    }
}
'

⁠Stream Events with both lower and upper bounds

curl --location "http://localhost:8080/api/v1/stream" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "subject": "/",
    "options": {
        "lowerBound": "2d6d4141-6107-4fb2-905f-445730f4f2a9",
        "includeLowerBoundEvent": true,
        "upperBound": "9f3e4141-7208-4fb2-905f-445730f4f3b1",
        "includeUpperBoundEvent": false
    }
}
'

⁠Stream Latest Events by Event Type

curl --location "http://localhost:8080/api/v1/stream" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "subject": "/",
    "options": {
        "latestByEventType": "io.genesisdb.app.customer-added"
    }
}
'

⁠Observe Events (Message queue)

curl --location "http://localhost:8080/api/v1/observe" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "events": "/customer"
  }
'

⁠Observe Events from lower bound (Message queue)

curl --location "http://localhost:8080/api/v1/observe" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "events": "/customer",
    "options": {
        "lowerBound": "2d6d4141-6107-4fb2-905f-445730f4f2a9",
        "includeLowerBoundEvent": true
    }
  }
'

⁠Observe Events with upper bound (Message queue)

curl --location "http://localhost:8080/api/v1/observe" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "events": "/customer",
    "options": {
        "upperBound": "9f3e4141-7208-4fb2-905f-445730f4f3b1",
        "includeUpperBoundEvent": false
    }
  }
'

⁠Observe Events with both bounds (Message queue)

curl --location "http://localhost:8080/api/v1/observe" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "events": "/customer",
    "options": {
        "lowerBound": "2d6d4141-6107-4fb2-905f-445730f4f2a9",
        "includeLowerBoundEvent": true,
        "upperBound": "9f3e4141-7208-4fb2-905f-445730f4f3b1",
        "includeUpperBoundEvent": false
    }
  }
'

⁠Observe Latest Events by Event Type (Message queue)

curl --location "http://localhost:8080/api/v1/observe" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data '{
    "events": "/customer",
    "options": {
        "latestByEventType": "io.genesisdb.app.customer-added"
    }
  }
'

⁠GDBQL (GenesisDB Query Language) - Community Edition

IMPORTANT: In Community Edition, GDBQL is only available within commit event preconditions using isQueryResultTrue. The standalone /api/v1/query endpoint is not available.

GenesisDB features a powerful SQL-like query language called GDBQL (GenesisDB Query Language). In the Community Edition, this is limited to validation within commit preconditions.

⁠Basic GDBQL Syntax (for use in preconditions)

⁠Current Syntax (Recommended)

STREAM handle FROM stream
[WHERE conditions]
[ORDER BY field [ASC|DESC]]
[GROUP BY field [HAVING conditions]]
[LIMIT number]
MAP { field_mappings }

⁠Alternative Syntax Options

GDBQL supports multiple syntax variations for flexibility:

Data Sources: STREAM e FROM events or FROM e IN events
Projections: MAP { ... } or PROJECT INTO { ... }
Limits: LIMIT number or TOP number

⁠Simple Query Examples (in preconditions)

⁠Basic Event Retrieval

-- Get all events from /user subject (includes direct children like /user/123)
STREAM e FROM events WHERE e.subject UNDER '/user' ORDER BY e.time MAP { id: e.id, name: e.data.name }

⁠Complex WHERE Conditions

-- Multiple conditions with AND/OR
STREAM e FROM events
WHERE e.type == 'user.created' AND e.data.age > 18
MAP { id: e.id, email: e.data.email, age: e.data.age }

-- IN operator for multiple values
STREAM e FROM events
WHERE e.type IN ('user.created', 'user.updated', 'user.deleted')
ORDER BY e.time DESC

-- BETWEEN for ranges
STREAM e FROM events
WHERE e.time BETWEEN '2024-01-01T00:00:00Z' AND '2024-12-31T23:59:59Z'
AND e.type != 'system.internal'

⁠Hierarchical Subject Queries

-- Direct children only (one level): /user/123 but not /user/123/profile
STREAM e FROM events WHERE e.subject UNDER '/user'

-- All descendants (any depth)
STREAM e FROM events WHERE e.subject DESCENDANTS '/organization'

⁠Nested Field Access

-- Access deeply nested JSON data
STREAM e FROM events
WHERE e.data.address.city == 'Vienna'
MAP {
    user: e.data.name,
    city: e.data.address.city,
    zip: e.data.address.postal_code
}

⁠Calculated Fields and Expressions

⁠String Concatenation

-- Combine multiple fields with string literals
STREAM e FROM events
WHERE e.type == 'user.created'
MAP {
    fullName: e.data.firstName + ' ' + e.data.lastName,
    displayText: 'User: ' + e.data.name + ' (' + e.data.email + ')'
}

⁠Arithmetic Operations

-- Calculate derived values
STREAM e FROM events
WHERE e.type == 'order.completed'
MAP {
    orderId: e.id,
    total: e.data.price * e.data.quantity,
    discount: e.data.price * 0.1,
    finalPrice: e.data.price - e.data.discount
}

⁠Aggregations and GROUP BY

⁠Count Events by Type

STREAM e FROM events
GROUP BY e.type
MAP {
    eventType: e.type,
    count: COUNT(),
    avgSize: AVG(e.data.size)
}
HAVING COUNT() > 10

⁠Sum Values by Subject

STREAM e FROM events
WHERE e.type == 'transaction.completed'
GROUP BY e.subject
MAP {
    user: e.subject,
    totalAmount: SUM(e.data.amount),
    transactionCount: COUNT(),
    avgAmount: AVG(e.data.amount)
}
ORDER BY totalAmount DESC

⁠Supported Operators

⁠Comparison Operators

== - Equals (with hierarchical semantics for subjects)
!= - Not equals
>, <, >=, <= - Numeric/string comparisons
IN - Value in list: e.type IN ('type1', 'type2')
BETWEEN - Range: e.data.age BETWEEN 18 AND 65

⁠Logical Operators

AND - Logical AND
OR - Logical OR
NOT - Logical NOT

⁠Subject Hierarchy Operators

== - Matches exact subject and direct children
UNDER - Only direct children (excluding parent)
DESCENDANTS - All descendants (any depth)
PARENT_OF - Reverse hierarchy check

⁠Arithmetic Operators

+ - Addition or string concatenation
- - Subtraction
* - Multiplication
/ - Division

⁠Aggregate Functions

COUNT() - Count events
COUNT(DISTINCT field) - Count unique values
SUM(field) - Sum numeric values
AVG(field) - Average of numeric values
MIN(field) - Minimum value
MAX(field) - Maximum value

⁠Get Subjects

curl --location "http://localhost:8080/api/v1/subjects" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret"

⁠Get Event Types

curl --location "http://localhost:8080/api/v1/types" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret"

⁠Backup create

curl --location 'http://localhost:8080/api/v1/backup/create' \
--header 'Authorization: Bearer secret'

⁠Backup restore (NOTE: The Event Store must be empty)

curl --location "http://localhost:8080/api/v1/backup/restore" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer secret" \
--data-raw '[
    {
        "source": "io.genesisdb.app",
        "subject": "/role/c63bd3d5-a49e-44d1-8637-ded8c2e50d46",
        "type": "io.genesisdb.app.role-added",
        "specversion": "1.0",
        "id": "ac138b87-ea2c-4790-ae35-b726052c6117",
        "time": "2025-06-02T15:40:01.157792875Z",
        "datacontenttype": "application/json",
        "predecessorhash": "0000000000000000000000000000000000000000000000000000000000000000",
        "data": {
            "name": "Administrator"
        },
        "hash": "7861f3ac1492b2c6771877b4ee871459ae23925781c6c47429a539f256ad3c46"
    },
    {
        "source": "io.genesisdb.app",
        "subject": "/user/6b6f5aa7-56b5-42ba-b093-fe6e921c863d",
        "type": "io.genesisdb.app.user-added",
        "specversion": "1.0",
        "id": "d8605ee4-9507-4974-8a2a-190baaea2b50",
        "time": "2025-06-02T15:40:01.188557875Z",
        "datacontenttype": "application/json",
        "predecessorhash": "7861f3ac1492b2c6771877b4ee871459ae23925781c6c47429a539f256ad3c46",
        "data": {
            "emailAddress": "[email protected]",
            "firstName": "Bruce",
            "lastName": "Wayne"
        },
        "hash": "ed937741bec97bec0f22e6203f09370241f996274116b7ea2d798ebbe5fbb1ca"
    },
    {
        "source": "io.genesisdb.app",
        "subject": "/user/fed2902d-0135-460d-8605-263a06308448",
        "type": "io.genesisdb.app.user-added",
        "specversion": "1.0",
        "id": "d8605ee4-9507-4974-8a2a-190baaea2b50",
        "time": "2025-06-02T15:40:01.188557875Z",
        "datacontenttype": "application/json",
        "predecessorhash": "ed937741bec97bec0f22e6203f09370241f996274116b7ea2d798ebbe5fbb1ca",
        "data": {
            "emailAddress": "[email protected]",
            "firstName": "Angus",
            "lastName": "MacGyver"
        },
        "hash": "b5699862763ac25d1725977e6937a855d7cad22b8a2b6670f320c559311a0147"
    }
]'

⁠Upgrade to Enterprise Version

For access to:

GDPR features (storeDataAsReference and /api/v1/erase)
Standalone /api/v1/query endpoint for GDBQL queries
Schema registration and validation (/api/v1/schema/register and /api/v1/schema/get)
Additional enterprise features

Visit: https://www.genesisdb.io⁠

⁠Author

Tag summary

Recent tags

Content type

Image

Digest

sha256:50c90b9d7…

Size

13.1 MB

Last updated

6 months ago

docker pull genesisdb/genesisdb-ce