14 stable releases
1.4.1 | Dec 4, 2022 |
---|---|
1.3.2 | Sep 19, 2022 |
#242 in Database interfaces
44 downloads per month
34KB
748 lines
Siena
Siena is a flat-file (YAML, FrontMatter) ORM for Rust, enabling you to easily use flat-file data stores for your application.
Install
Add the following to your Cargo.toml file:
siena = "1.4.1"
Changelog
To see what's changed, check the changelog.
Usage
Setting Store
The first thing you need to do when using Siena, is setting the Store. This will tell Siena to use a correct provider for getting and setting data.
Example:
use siena::siena::{Store, Siena};
let store = Siena::default().set_store(Store::Local {
directory: "./path-to-somewhere".to_string()
});
Currently, only the Local
store is supported which enables you to use the local disk for the storage of
data by giving a specified directory
to read from, and to write to. There are plans to enable more Stores in the future, such as S3-compatible services.
Fetching Records
Records are placed in collections. A collection is a directory in your store. So let's say that you have a collection called "blog-posts", you could fetch them like this:
let posts = store.collection("blog-posts").get_all();
You can also just get the first record via get_first()
or the last one via
.get_last()
.
Filtering Records
You can filter records using numerous when_*
methods. And yes, you can chain them
as much as you want.
when_is
To filter records by a record key that equals a given value, you can use the when_is
method, like so:
let posts = store
.collection("blog-posts")
.when_is("status", "published")
.get_all();
when_isnt
Similarly, to filter records the opposite way, by a record key that does not equal a given value, you can use the
when_isnt
method:
let posts = store
.collection("blog-posts")
.when_isnt("status", "published")
.get_all();
when_has
To filter records by the presence of a record key, you can use the when_has
method, like so:
let posts = store
.collection("blog-posts")
.when_has("status")
.get_all();
when_hasnt
Similarly, to filter records the opposite way, by the lack of a presence of a record key, you can use the when_hasnt
method:
let posts = store
.collection("blog-posts")
.when_hasnt("status")
.get_all();
when_matches
To filter records by a record key that matches a value according to a Regex pattern, you can use the when_matches
method, like so:
let posts = store
.collection("blog-posts")
.when_matches("date", r"2022\-09")
.get_all();
There is no opposite method for when_matches
, because regex gives you the ability to do that yourself.
Sorting Records
You can sort records with the sort
method, like so:
use siena::siena::{RecordSortOrder};
let posts = store
.collection("blog-posts")
.sort("date", RecordSortOrder::Desc)
.get_all();
The available ways to sort are:
RecordSortOrder::Desc
RecordSortOrder::Asc
Limiting Records
To limit the result, use the limit
method:
let posts = store
.collection("blog-posts")
.limit(10)
.get_all();
Offsetting Records
To offset the result, use the offset
method:
let posts = store
.collection("blog-posts")
.offset(10)
.get_all();
Pagination
With the combination of limit
and offset
method, you can create easy pagination, for example:
let page = 2;
let posts_per_page = 10;
let posts = store
.collection("blog-posts")
.offset((page - 1) * posts_per_page)
.limit(posts_per_page)
.get_all();
Or, simply use the paginate
method which does this work for you, like this:
let posts = store
.collection("blog-posts")
.paginate(2, 10)
.get_all();
Updating Records
You can update the result of your query via the set
method. It doesn't matter if you have one record or multiple records, it will update anything that you have matching your query.
For example:
let posts = store
.collection("blog-posts")
.set(Vec::from([("status", "private")]));
This will update all the records in the blog-post
collection by updating the status
to private
.
Whereas this example:
let posts = store
.collection("blog-posts")
.when_is("status", "public")
.set(Vec::from([("status", "private")]));
Will only update all the records that have status
as public
to private
.
Creating Records
The create
method is what you use for creating a new record. Note however that the
record is not persisted until you use the set
method to add some data. The set
method is the only method
which writes data. The create
method only creates the record in-memory so that the set
method would know
where to write data.
An example:
store
.create("blog-posts", "hello-world")
.set(Vec::from([("title", "Hello, World.")]));
The create
method takes two arguments, the collection name, and the ID of the record, which has to be unique to that collection or it will overwrite an existing record.
Dependencies
~8.5MB
~202K SLoC