Databases

MolnOS Databases provides a simple, fast key-value database system built on PikoDB. Store and retrieve structured data with support for tables, TTL (time-to-live), and optional dictionary grouping.

Don’t forget to register and start the service

Any service you want to use must be registered and started before using it. Also note that services may require other services to run—expect Databases to be needed by some other services.

Features

Table Management

Organize your data into tables. Each table is an isolated namespace for key-value pairs, allowing logical separation of different data types.

Key-Value Storage

Store any JSON-serializable data against string keys. Values can be objects, arrays, strings, numbers, or any valid JSON structure.

Time-to-Live (TTL)

Set expiration times on values with TTL support. Values automatically expire after the specified duration, perfect for caching and temporary data.

Dictionary Grouping

Optionally organize values within tables using dictionary names. Group related data together for easier management and querying.

Table Statistics

View table-level statistics including item counts and storage size. Monitor table growth and usage patterns.

Item Listing

List all items (key-value pairs) within a table for inspection and debugging.

Common Use Cases

• Application State: Store user sessions, shopping carts, and temporary application state
• Caching: Cache expensive computations or API responses with TTL
• Configuration: Store application configuration and feature flags
• User Preferences: Store user settings and preferences
• Counters: Track metrics, page views, and event counts
• Rate Limiting: Implement rate limiting with TTL-based counters
• Queues: Simple task queues and job tracking

How It Works

Console

The Console allows creating, editing, reading, and deleting items and tables.

API

Databases are managed through the HTTP API at /databases/* endpoints.

List Tables

GET /databases/tables

Returns all database tables with metadata:

{
  "tables": [
    {
      "name": "users",
      "items": 150,
      "size": "2.3 KB"
    },
    {
      "name": "sessions",
      "items": 42,
      "size": "1.1 KB"
    }
  ]
}

Create Table

POST /databases/tables/{tableName}

Creates a new empty table. Optionally associate it with a context:

{
  "context": "my-app"
}

Parameters:

• context (optional) - Context name to associate this table with for organizational grouping

Response:

{
  "success": true,
  "name": "users",
  "message": "Table created successfully"
}

Get Table Details

GET /databases/tables/{tableName}

Returns detailed information about a table:

{
  "name": "users",
  "items": 150,
  "size": "2.3 KB"
}

Get Table Size

GET /databases/table?tableName=users

Returns the number of items in a table:

150

List Items in Table

GET /databases/tables/{tableName}/items

Returns all key-value pairs in a table:

{
  "items": [
    {
      "key": "user_123",
      "value": {
        "id": "user_123",
        "name": "Jane Doe",
        "email": "[email protected]"
      }
    },
    {
      "key": "user_456",
      "value": {
        "id": "user_456",
        "name": "John Smith",
        "email": "[email protected]"
      }
    }
  ]
}

Delete Table

DELETE /databases/tables/{tableName}

Deletes an entire table and all its data:

{
  "success": true,
  "name": "users",
  "message": "Table deleted successfully"
}

Write Value

POST /databases/write

Write a value to a table:

{
  "tableName": "users",
  "key": "user_123",
  "value": {
    "id": "user_123",
    "name": "Jane Doe",
    "email": "[email protected]",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  },
  "expiration": 3600,
  "dictionaryName": "active-users"
}

Parameters:

• tableName (required) - The table to write to
• key (optional) - The key for this value (if omitted, only table is created)
• value (required) - The JSON value to store
• expiration (optional) - TTL in seconds
• dictionaryName (optional) - Group this value in a dictionary

Response:

{
  "success": true
}

Get Value

POST /databases/get

Retrieve a value by key:

{
  "tableName": "users",
  "key": "user_123"
}

Response:

{
  "id": "user_123",
  "name": "Jane Doe",
  "email": "[email protected]",
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

Delete Value

DELETE /databases/delete?tableName=users&key=user_123

Deletes a specific key-value pair:

{
  "success": true
}

CLI

Database operations using the MolnOS CLI:

# List all tables
molnos db tables

# Create table
molnos db table create users

# Get table details
molnos db table get users

# Get table size (number of items)
molnos db table size users

# List all items in table
molnos db table items users

# Delete table
molnos db table delete users

# Write value to table
molnos db write users user_123 '{"name":"Jane Doe","email":"[email protected]"}'

# Get value from table
molnos db get users user_123

# Delete value from table
molnos db delete users user_123

Note: TTL (time-to-live) and dictionary support are available through the API but not yet exposed in the CLI.

Permissions

Database operations require appropriate permissions:

• databases.table.create - Create new tables
• databases.table.get - List tables, view statistics, and read specific table details
• databases.table.delete - Delete tables and delete values from tables
• databases.table.update - Write values to tables

Fine-grained permissions can target specific tables:

• databases.table.update:users - Write access to users table only
• databases.table.get:sessions - Read access to sessions table only
• databases.table.delete:sessions - Delete items from sessions table only

Data Modeling Best Practices

Choose Meaningful Keys

Use descriptive, hierarchical keys that reflect your data structure:

user:123:profile
user:123:settings
user:123:sessions:abc

Use TTL for Temporary Data

Set expiration times on temporary data to avoid manual cleanup:

{
  "tableName": "sessions",
  "key": "session_abc123",
  "value": {"userId": "user_123", "createdAt": "2025-12-19T10:00:00Z"},
  "expiration": 86400
}

Group Related Data

Use dictionary names to organize related values:

{
  "tableName": "users",
  "key": "user_123",
  "value": {...},
  "dictionaryName": "active-users"
}

Store Denormalized Data

Key-value stores work best with denormalized data. Store complete objects rather than references:

Good:

{
  "key": "order_123",
  "value": {
    "id": "order_123",
    "user": {
      "id": "user_456",
      "name": "Jane Doe",
      "email": "[email protected]"
    },
    "items": [...]
  }
}

Avoid:

{
  "key": "order_123",
  "value": {
    "id": "order_123",
    "userId": "user_456"
  }
}

Index Important Fields

For frequently queried fields, create separate index entries:

// Main user record
{
  "key": "user:123",
  "value": {"id": "123", "email": "[email protected]"}
}

// Email index
{
  "key": "email:[email protected]",
  "value": "user:123"
}

Performance Considerations

• Keys are indexed for fast lookup
• Values are stored as JSON and parsed on read
• Large values (>1MB) may impact performance
• Use TTL to automatically clean up expired data
• Batch writes when possible to reduce round trips