A lightweight, Go-based open source document-oriented JSON database.

deo (/'dioh/, pronounced dee-oh) is a Go-based, open source document-oriented database that stores data as msgpack-compressed JSON files. It’s entirely accessed through a RESTful API, making it simple to integrate and easy to deploy as a single binary.

go install github.com/myferr/deo@latest

curl -X POST http://localhost:6741/api/dbs/my_db/collections/my_collection/documents \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "age": 30}'

curl http://localhost:6741/api/dbs/my_db/collections/my_collection/documents/<document_id>

curl -X PUT http://localhost:6741/api/dbs/my_db/collections/my_collection/documents/<document_id> \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "age": 31}'

curl -X DELETE http://localhost:6741/api/dbs/my_db/collections/my_collection/documents/<document_id>

$HOME/.deo/{database_name}/{collection_name}/*.msgpack
│      │              │                   │
│      │              │                   └── Documents (*.msgpack)
│      │              └── Collection
│      └── Deo Database
└── User Home Directory

localhost:6741   /api   /dbs   /{database_name}   /collections   /{collection_name}   /documents
│                │      │      │                  │              │                    │
│                │      │      │                  │              │                    └── Documents endpoint
│                │      │      │                  │              └── Collection name slug
│                │      │      │                  └── Collections endpoint
│                │      │      └── Database name slug
│                │      └── Database endpoint
│                └── API root
└── Hostname + Port

Images:

• myferr/deo
• ghcr.io/myferr/deo

Tags

To run Deo in a Docker container, use the following command:

docker run -d -p 6741:6741 --name deo ghcr.io/myferr/deo:latest

To run Deo in a Docker Compose setup, use the following configuration:

services:
  deo:
    image: ghcr.io/myferr/deo:latest
    ports:
      - "6741:6741"

and then start the container:

docker-compose up -dv

deo has a "studio" web UI to manage databases, collections, and documents which is useful for testing. Accessible at http://localhost:6741/studio

deo relies upon a RESTful application programming interface (API) to interact with databases, collections, and documents. The same route can be called in different methods to perform various operations so to explain the API in a more detailed manner, read below for documentation.

http://localhost:6741/api

All API errors return a JSON object with success: false and a message field.

{
  "success": false,
  "message": "Error description"
}

• Endpoint: /api/dbs
• Method: POST
• Description: Creates a new database.
• Request Body:

  {
    "db_name": "string"
  }

  • db_name (string, required): The name of the database to create.
• Success Response:
  • Code: 201 Created

  {
    "success": true,
    "message": "Database created successfully"
  }

• Error Responses:
  • 400 Bad Request: Invalid request body (e.g., db_name missing).
  • 500 Internal Server Error: Failed to create database (e.g., file system error).

• Endpoint: /api/dbs
• Method: GET
• Description: Lists all available databases.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "data": ["db1", "db2"]
  }

  • data (array of strings): An array of database names.
• Error Responses:
  • 500 Internal Server Error: Failed to list databases.

• Endpoint: /api/dbs/:db_name
• Method: DELETE
• Description: Deletes a specific database and all its contents (collections and documents).
• Path Parameters:
  • db_name (string, required): The name of the database to delete.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "message": "Database deleted successfully"
  }

• Error Responses:
  • 500 Internal Server Error: Failed to delete database.

• Endpoint: /api/dbs/:db_name/collections
• Method: POST
• Description: Creates a new collection within a specified database.
• Path Parameters:
  • db_name (string, required): The name of the database.
• Request Body:

  {
    "collection_name": "string"
  }

  • collection_name (string, required): The name of the collection to create.
• Success Response:
  • Code: 201 Created

  {
    "success": true,
    "message": "Collection created successfully"
  }

• Error Responses:
  • 400 Bad Request: Invalid request body (e.g., collection_name missing).
  • 500 Internal Server Error: Failed to create collection.

• Endpoint: /api/dbs/:db_name/collections
• Method: GET
• Description: Lists all collections within a specified database.
• Path Parameters:
  • db_name (string, required): The name of the database.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "data": ["collection1", "collection2"]
  }

  • data (array of strings): An array of collection names.
• Error Responses:
  • 500 Internal Server Error: Failed to list collections.

• Endpoint: /api/dbs/:db_name/collections/:collection_name
• Method: DELETE
• Description: Deletes a specific collection and all its documents within a database.
• Path Parameters:
  • db_name (string, required): The name of the database.
  • collection_name (string, required): The name of the collection to delete.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "message": "Collection deleted successfully"
  }

• Error Responses:
  • 500 Internal Server Error: Failed to delete collection.

• Endpoint: /api/dbs/:db_name/collections/:collection_name/documents
• Method: POST
• Description: Creates a new document within a specified collection. A unique _id (UUID) is automatically generated for the document.
• Path Parameters:
  • db_name (string, required): The name of the database.
  • collection_name (string, required): The name of the collection.
• Request Body:
  • Any valid JSON object. The _id field will be added automatically.

  {
    "field1": "value1",
    "field2": "value2"
  }

• Success Response:
  • Code: 201 Created

  {
    "success": true,
    "message": "Document created successfully",
    "data": {
      "_id": "uuid-string",
      "field1": "value1",
      "field2": "value2"
    }
  }

  • data (object): The created document, including its generated _id.
• Error Responses:
  • 400 Bad Request: Invalid JSON in request body.
  • 500 Internal Server Error: Failed to create document.

• Endpoint: /api/dbs/:db_name/collections/:collection_name/documents
• Method: GET
• Description: Lists all documents within a specified collection.
• Path Parameters:
  • db_name (string, required): The name of the database.
  • collection_name (string, required): The name of the collection.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "data": [
      { "_id": "doc1-id", "fieldA": "valueA" },
      { "_id": "doc2-id", "fieldB": "valueB" }
    ]
  }

  • data (array of objects): An array of documents.
• Error Responses:
  • 500 Internal Server Error: Failed to list documents.

• Endpoint: /api/dbs/:db_name/collections/:collection_name/documents/:document_id
• Method: GET
• Description: Retrieves a specific document by its ID.
• Path Parameters:
  • db_name (string, required): The name of the database.
  • collection_name (string, required): The name of the collection.
  • document_id (string, required): The ID of the document to retrieve.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "data": {
      "_id": "document-id",
      "field1": "value1",
      "field2": "value2"
    }
  }

  • data (object): The retrieved document.
• Error Responses:
  • 404 Not Found: Document not found.
  • 500 Internal Server Error: Error loading document.

• Endpoint: /api/dbs/:db_name/collections/:collection_name/documents/:document_id
• Method: PUT
• Description: Updates an existing document with the provided JSON data. The entire document is replaced.
• Path Parameters:
  • db_name (string, required): The name of the database.
  • collection_name (string, required): The name of the collection.
  • document_id (string, required): The ID of the document to update.
• Request Body:
  • Any valid JSON object representing the new content of the document.

  {
    "newField": "newValue",
    "anotherField": 123
  }

• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "message": "Document updated successfully",
    "data": {
      "newField": "newValue",
      "anotherField": 123
    }
  }

  • data (object): The updated document.
• Error Responses:
  • 400 Bad Request: Invalid JSON in request body.
  • 500 Internal Server Error: Failed to update document.

• Endpoint: /api/dbs/:db_name/collections/:collection_name/documents/:document_id
• Method: DELETE
• Description: Deletes a specific document from a collection.
• Path Parameters:
  • db_name (string, required): The name of the database.
  • collection_name (string, required): The name of the collection.
  • document_id (string, required): The ID of the document to delete.
• Success Response:
  • Code: 200 OK

  {
    "success": true,
    "message": "Document deleted successfully"
  }

• Error Responses:
  • 404 Not Found: Document not found.
  • 500 Internal Server Error: Failed to delete document.

deo has official libraries to provide a cleaner developer experience, letting you access the database through clean code and not web requests.

All official libraries are provided here.

• JavaScript / TypeScript

  • deo-client

• Python

  • deo-client