DockieDb
A simple in-memory document database.
Installation
Build the Wheel
Fork or clone this repository and run python setup.py bdist_wheel in the repository root.
Install the Wheel
In your consuming project, run pip install
.
Document Database Primer
Looking at the tests in the test folder will give you a good idea on how to use DockieDb. Nevertheless, this section offers some guidance.
In general, document database objects have the following hierarchy:
Database ---> Container (1 or more) --->Document (1 or more)
At the root, there is a Database. A database consists of one or more Containers. A Container holds one or more Documents.
If you’re coming from a relational background then you can think of the Database as the schema, a Container as the table, and a Document as a row in the table.
Whereas the rows in the table conform to the same schema, Documents in a Container are schemaless. In other words you can store Documents of different shapes in the same container.
This tutorial is a great read for those new to document databases. It does a better job explaining it than I ever could in this readme.
Creating Database Objects
Create a Database
from dockie.core.database import Database
db = Database()
Create a Container
container = db.add_container("items")
Add a Document to the Container
from dockie.core.document import Document
document = Document("item1", {"name": "basketball", "price": 29.99})
container.add_document(document)
A document id must be a string or integer.
Retrieving Documents
There are two ways to retrieve a document:
- By its id.
- By querying against one or more non-id attributes.
Retrieving a Document by ID
from dockie.query.query import DocumentIdQuery
query = DocumentIdQuery()
document = query.execute(container, document_id="item1")
Retrieving a Document by a Non-ID Attribute
Querying by non-ID attributes is accomplished with the dictquery library.
from dockie.query.query import DocumentAttributeQuery
query = DocumentAttributeQuery()
document = query.execute(container, query='name=="basketball"')
Refer to the tests in this repository for more query examples. Refer to the dictquery homepage for details on dictquery syntax.
Persisting the Database
Although DockieDb is an in-memory database, it can be saved and loaded to/from a file.
Save the Database to File
from dockie.core.persistence import persist_to_file
persist_to_file(db, "db.bak")
Load the Database from File
from dockie.core.persistence import load_from_file
db = load_from_file("db.bak)
Miscellania
Running Tests
From the project root folder, run pytest without any arguments.
