From 8f410814e3668c74759b916f93109e5564301a8f Mon Sep 17 00:00:00 2001 From: PJ Tatlow Date: Tue, 7 Apr 2020 22:59:46 -0600 Subject: [PATCH] add more documentation and update license --- Cargo.lock | 93 +++++++++++++++++++ Cargo.toml | 2 + LICENSE-APACHE | 201 +++++++++++++++++++++++++++++++++++++++++ LICENSE => LICENSE-MIT | 0 README.md | 130 ++++++++++++++++++++++++-- makefile | 10 +- src/bucket.rs | 3 +- src/lib.rs | 100 +++++++++++++++++++- src/transaction.rs | 12 ++- 9 files changed, 528 insertions(+), 23 deletions(-) create mode 100644 LICENSE-APACHE rename LICENSE => LICENSE-MIT (100%) diff --git a/Cargo.lock b/Cargo.lock index 7c7b13e..227b7f1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1,5 +1,10 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +[[package]] +name = "autocfg" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + [[package]] name = "block-buffer" version = "0.7.3" @@ -77,6 +82,8 @@ dependencies = [ "memmap 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)", "page_size 0.4.2 (registry+https://github.com/rust-lang/crates.io-index)", "rand 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)", + "rmp-serde 0.14.3 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.106 (registry+https://github.com/rust-lang/crates.io-index)", "sha3 0.8.2 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -99,6 +106,14 @@ dependencies = [ "winapi 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)", ] +[[package]] +name = "num-traits" +version = "0.2.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "autocfg 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "opaque-debug" version = "0.2.3" @@ -118,6 +133,22 @@ name = "ppv-lite86" version = "0.2.6" source = "registry+https://github.com/rust-lang/crates.io-index" +[[package]] +name = "proc-macro2" +version = "1.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "quote" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "proc-macro2 1.0.10 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "rand" version = "0.7.3" @@ -155,6 +186,43 @@ dependencies = [ "rand_core 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)", ] +[[package]] +name = "rmp" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)", + "num-traits 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "rmp-serde" +version = "0.14.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "byteorder 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)", + "rmp 0.8.9 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.106 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "serde" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "serde_derive 1.0.106 (registry+https://github.com/rust-lang/crates.io-index)", +] + +[[package]] +name = "serde_derive" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "proc-macro2 1.0.10 (registry+https://github.com/rust-lang/crates.io-index)", + "quote 1.0.3 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "sha3" version = "0.8.2" @@ -167,11 +235,26 @@ dependencies = [ "opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)", ] +[[package]] +name = "syn" +version = "1.0.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +dependencies = [ + "proc-macro2 1.0.10 (registry+https://github.com/rust-lang/crates.io-index)", + "quote 1.0.3 (registry+https://github.com/rust-lang/crates.io-index)", + "unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", +] + [[package]] name = "typenum" version = "1.11.2" source = "registry+https://github.com/rust-lang/crates.io-index" +[[package]] +name = "unicode-xid" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" + [[package]] name = "wasi" version = "0.9.0+wasi-snapshot-preview1" @@ -197,6 +280,7 @@ version = "0.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" [metadata] +"checksum autocfg 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)" = "f8aac770f1885fd7e387acedd76065302551364496e46b3dd00860b2f8359b9d" "checksum block-buffer 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)" = "c0940dc441f31689269e10ac70eb1002a3a1d3ad1390e030043662eb7fe4688b" "checksum block-padding 0.1.5 (registry+https://github.com/rust-lang/crates.io-index)" = "fa79dedbb091f449f1f39e53edf88d5dbe95f895dae6135a8d7b881fb5af73f5" "checksum byte-tools 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)" = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7" @@ -209,15 +293,24 @@ source = "registry+https://github.com/rust-lang/crates.io-index" "checksum keccak 0.1.0 (registry+https://github.com/rust-lang/crates.io-index)" = "67c21572b4949434e4fc1e1978b99c5f77064153c59d998bf13ecd96fb5ecba7" "checksum libc 0.2.66 (registry+https://github.com/rust-lang/crates.io-index)" = "d515b1f41455adea1313a4a2ac8a8a477634fbae63cc6100e3aebb207ce61558" "checksum memmap 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "6585fd95e7bb50d6cc31e20d4cf9afb4e2ba16c5846fc76793f11218da9c475b" +"checksum num-traits 0.2.11 (registry+https://github.com/rust-lang/crates.io-index)" = "c62be47e61d1842b9170f0fdeec8eba98e60e90e5446449a0545e5152acd7096" "checksum opaque-debug 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "2839e79665f131bdb5782e51f2c6c9599c133c6098982a54c794358bf432529c" "checksum page_size 0.4.2 (registry+https://github.com/rust-lang/crates.io-index)" = "eebde548fbbf1ea81a99b128872779c437752fb99f217c45245e1a61dcd9edcd" "checksum ppv-lite86 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)" = "74490b50b9fbe561ac330df47c08f3f33073d2d00c150f719147d7c54522fa1b" +"checksum proc-macro2 1.0.10 (registry+https://github.com/rust-lang/crates.io-index)" = "df246d292ff63439fea9bc8c0a270bed0e390d5ebd4db4ba15aba81111b5abe3" +"checksum quote 1.0.3 (registry+https://github.com/rust-lang/crates.io-index)" = "2bdc6c187c65bca4260c9011c9e3132efe4909da44726bad24cf7572ae338d7f" "checksum rand 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)" = "6a6b1679d49b24bbfe0c803429aa1874472f50d9b363131f0e89fc356b544d03" "checksum rand_chacha 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "f4c8ed856279c9737206bf725bf36935d8666ead7aa69b52be55af369d193402" "checksum rand_core 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)" = "90bde5296fc891b0cef12a6d03ddccc162ce7b2aff54160af9338f8d40df6d19" "checksum rand_hc 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ca3129af7b92a17112d59ad498c6f81eaf463253766b90396d39ea7a39d6613c" +"checksum rmp 0.8.9 (registry+https://github.com/rust-lang/crates.io-index)" = "0f10b46df14cf1ee1ac7baa4d2fbc2c52c0622a4b82fa8740e37bc452ac0184f" +"checksum rmp-serde 0.14.3 (registry+https://github.com/rust-lang/crates.io-index)" = "4c1ee98f14fe8b8e9c5ea13d25da7b2a1796169202c57a09d7288de90d56222b" +"checksum serde 1.0.106 (registry+https://github.com/rust-lang/crates.io-index)" = "36df6ac6412072f67cf767ebbde4133a5b2e88e76dc6187fa7104cd16f783399" +"checksum serde_derive 1.0.106 (registry+https://github.com/rust-lang/crates.io-index)" = "9e549e3abf4fb8621bd1609f11dfc9f5e50320802273b12f3811a67e6716ea6c" "checksum sha3 0.8.2 (registry+https://github.com/rust-lang/crates.io-index)" = "dd26bc0e7a2e3a7c959bc494caf58b72ee0c71d67704e9520f736ca7e4853ecf" +"checksum syn 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)" = "0df0eb663f387145cab623dea85b09c2c5b4b0aef44e945d928e682fce71bb03" "checksum typenum 1.11.2 (registry+https://github.com/rust-lang/crates.io-index)" = "6d2783fe2d6b8c1101136184eb41be8b1ad379e4657050b8aaff0c79ee7575f9" +"checksum unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "826e7639553986605ec5979c7dd957c7895e93eabed50ab2ffa7f6128a75097c" "checksum wasi 0.9.0+wasi-snapshot-preview1 (registry+https://github.com/rust-lang/crates.io-index)" = "cccddf32554fecc6acb585f82a32a72e28b48f8c4c1883ddfeeeaa96f7d8e519" "checksum winapi 0.3.8 (registry+https://github.com/rust-lang/crates.io-index)" = "8093091eeb260906a183e6ae1abdba2ef5ef2257a21801128899c3fc699229c6" "checksum winapi-i686-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" diff --git a/Cargo.toml b/Cargo.toml index b9905ab..ea95a37 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -18,6 +18,8 @@ sha3 = "0.8" [dev-dependencies] rand = "0.7" +rmp-serde = "0.14" +serde = { version = "1.0", features = ["derive"] } [badges] codecov = { repository = "pjtatlow/jammdb", branch = "master", service = "github" } diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..d6eab2c --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2020 PJ Tatlow + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/LICENSE b/LICENSE-MIT similarity index 100% rename from LICENSE rename to LICENSE-MIT diff --git a/README.md b/README.md index ee9afab..c620675 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,23 @@ -[![Coverage Status](https://codecov.io/gh/pjtatlow/jammdb/branch/master/graph/badge.svg)](https://codecov.io/gh/pjtatlow/jammdb) - # jammdb ## Just Another Memory Mapped Database -jammdb is an embedded, single-file database that allows you to store key-value pairs as bytes. +[![Crates.io](https://img.shields.io/crates/v/jammdb?style=flat-square)](https://crates.io/crates/jammdb) +[![Crates.io](https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square)](https://docs.rs/jammdb) +[![MacOS Build](https://img.shields.io/travis/com/pjtatlow/jammdb?logo=apple&style=flat-square)](https://travis-ci.com/github/pjtatlow/jammdb) +[![Windows Build](https://img.shields.io/appveyor/build/pjtatlow/jammdb?logo=windows)](https://ci.appveyor.com/project/pjtatlow/jammdb) +[![Linux Build](https://img.shields.io/travis/com/pjtatlow/jammdb?logo=linux&style=flat-square)](https://travis-ci.com/github/pjtatlow/jammdb) +[![Coverage Status](https://img.shields.io/codecov/c/gh/pjtatlow/jammdb?style=flat-square)](https://codecov.io/gh/pjtatlow/jammdb) +[![License](https://img.shields.io/crates/l/jammdb?style=flat-square)](https://crates.io/crates/jammdb) + + +`jammdb` is an embedded, single-file database that allows you to store key-value pairs as bytes. -It is heavily inspired by [Ben Johnson's](https://twitter.com/benbjohnson) awesome [BoltDB](https://github.com/boltdb/bolt), +It started life as a Rust port of [Ben Johnson's](https://twitter.com/benbjohnson) awesome [BoltDB](https://github.com/boltdb/bolt), which was inspired by [Howard Chu's](https://twitter.com/hyc_symas) [LMDB](http://symas.com/mdb/), so please check out both of these awesome projects! -jammdb offers +`jammdb` offers [ACID](https://en.wikipedia.org/wiki/ACID) compliance, [serializable](https://en.wikipedia.org/wiki/Serializability) and [isolated](https://en.wikipedia.org/wiki/Isolation_(database_systems)) transactions, @@ -18,6 +25,115 @@ with multiple lock-free readers and a single concurrent writer. The data is orga [single level](https://en.wikipedia.org/wiki/Single-level_store) [B+ tree](https://en.wikipedia.org/wiki/B%2B_tree) so random and sequential reads are very fast. The underlying file is memory mapped, so reads require no additional memory allocation. -This project is still in the very early stages, but detailed examples are coming soon! +## Supported platforms +`jammdb` is continuously cross-compiled on all of the following platforms, and tested against _most_ of them. + * `x86_64-unknown-linux-gnu` (Linux) + * `i686-unknown-linux-gnu` + * `x86_64-unknown-linux-musl` (Linux MUSL) + * `x86_64-apple-darwin` (OSX) + * `i686-apple-darwin` + * `x86_64-pc-windows-msvc` (Windows) + * `i686-pc-windows-msvc` + * `x86_64-pc-windows-gnu` + * `i686-pc-windows-gnu` + * `arm-linux-androideabi` (Android) + * `aarch64-unknown-linux-gnu` (ARM) + * `arm-unknown-linux-gnueabihf` + * `mips-unknown-linux-gnu` (MIPS) + * `x86_64-apple-ios` (iOS) + * `i686-apple-ios` + +## Examples + +Here are a couple of simple examples to get you started, but you should check out the docs for more details. + +### Simple put and get +```rust +use jammdb::{DB, Data, Error}; + +fn main() -> Result<(), Error> { +{ + // open a new database file + let mut db = DB::open("my-database.db")?; + + // open a writable transaction so we can make changes + let mut tx = db.tx(true)?; + + // create a bucket to store a map of first names to last names + let names_bucket = tx.create_bucket("names")?; + names_bucket.put(b"Kanan", b"Jarrus")?; + names_bucket.put(b"Ezra", b"Bridger")?; + + // commit the changes so they are saved to disk + tx.commit()?; +} +{ + // open the existing database file + let mut db = DB::open("my-database.db")?; + // open a read-only transaction to get the data + let mut tx = db.tx(true)?; + // get the bucket we created in the last transaction + let names_bucket = tx.get_bucket("names")?; + // get the key-value pair we inserted into the bucket + if let Some(Data::KeyValue(kv)) = names_bucket.get(b"Kanan") { + assert_eq!(kv.value(), b"Jarrus"); + } +} + Ok(()) +} +``` + +### Storing structs +```rust +use jammdb::{DB, Data, Error}; +use serde::{Deserialize, Serialize}; +// use rmps crate to serialize structs using the MessagePack format +use rmp_serde::{Deserializer, Serializer}; + +#[derive(Debug, PartialEq, Deserialize, Serialize)] +struct User { + username: String, + password: String, +} + +fn main() -> Result<(), Error> { + let user = User{ + username: "my-user".to_string(), + password: "my-password".to_string(), + }; +{ + // open a new database file and start a writable transaction + let mut db = DB::open("my-database.db")?; + let mut tx = db.tx(true)?; + + // create a bucket to store users + let users_bucket = tx.create_bucket("users")?; + + // serialize struct to bytes and store in bucket + let user_bytes = rmp_serde::to_vec(&user).unwrap(); + users_bucket.put(b"user1", user_bytes)?; + + // commit the changes so they are saved to disk + tx.commit()?; +} +{ + // open the existing database file + let mut db = DB::open("my-database.db")?; + // open a read-only transaction to get the data + let mut tx = db.tx(true)?; + // get the bucket we created in the last transaction + let users_bucket = tx.get_bucket("users")?; + // get the key-value pair we inserted into the bucket + if let Some(Data::KeyValue(kv)) = users_bucket.get(b"user1") { + // deserialize into a user struct + let db_user: User = rmp_serde::from_slice(kv.value()).unwrap(); + assert_eq!(db_user, user); + } +} + Ok(()) +} +``` + +## License -License: MIT +Available under both the [Apache License](LICENSE-APACHE) or the [MIT license](LICENSE-MIT). diff --git a/makefile b/makefile index 72852b5..d00afe0 100644 --- a/makefile +++ b/makefile @@ -1,4 +1,4 @@ -.PHONEY: coverage, readme +.PHONEY: coverage, test-32-bit, docs, docs-open coverage: CARGO_INCREMENTAL=0 \ @@ -13,13 +13,9 @@ coverage: docs: cargo +nightly doc + docs-open: cargo +nightly doc --open -readme: README.md - -README.md: src/lib.rs Cargo.toml - cargo readme > README.md - test-32-bit: - docker run --rm -v "$(PWD)":/usr/src/myapp -w /usr/src/myapp i386/rust:1.42.0 cargo test \ No newline at end of file + docker run --rm -v "$(PWD)":/usr/src/myapp -w /usr/src/myapp i386/rust:1.42.0 cargo test diff --git a/src/bucket.rs b/src/bucket.rs index c3780ea..3419132 100644 --- a/src/bucket.rs +++ b/src/bucket.rs @@ -18,8 +18,7 @@ use crate::transaction::TransactionInner; /// as well as [`get`](#method.get_bucket) and [`create`](#method.create_bucket) /// nested buckets. /// -/// You can use a [`Cursor`] to iterate over -/// all the data in a bucket. +/// You can use a [`Cursor`] to iterate over all the data in a bucket. /// /// Buckets have an inner auto-incremented counter that keeps track /// of how many unique keys have been inserted into the bucket. diff --git a/src/lib.rs b/src/lib.rs index 0422856..34bb0bb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,7 +2,7 @@ //! //! jammdb is an embedded, single-file database that allows you to store key-value pairs as bytes. //! -//! It is heavily inspired by [Ben Johnson's](https://twitter.com/benbjohnson) awesome [BoltDB](https://github.com/boltdb/bolt), +//! It started life as a Rust port of [Ben Johnson's](https://twitter.com/benbjohnson) awesome [BoltDB](https://github.com/boltdb/bolt), //! which was inspired by [Howard Chu's](https://twitter.com/hyc_symas) [LMDB](http://symas.com/mdb/), //! so please check out both of these awesome projects! //! @@ -14,7 +14,103 @@ //! [single level](https://en.wikipedia.org/wiki/Single-level_store) [B+ tree](https://en.wikipedia.org/wiki/B%2B_tree) //! so random and sequential reads are very fast. The underlying file is memory mapped, so reads require no additional memory allocation. //! -//! This project is still in the very early stages, but detailed examples are coming soon! +//! jammdb is meant to be very simple, and has only a few exported types. It will allow you to store data in collections (called [`Buckets`](struct.Bucket.html)), +//! and each bucket can contain any number of unique keys which map to either an arbitrary value (a `&[u8]`) or a nested bucket. Examples on how to use jammdb are below. +//! There are also more examples in the docs, be sure to check out +//! * Using a [`Cursor`] to iterate over the data in a bucket +//! * How to create and use multiple [`Transaction`]s +//! * Nested [`Buckets`](struct.Bucket.html) +//! * [`OpenOptions`](struct.OpenOptions.html) to provide parameters for opening a [`DB`](struct.DB.html) +//! +//! # Examples +//! +//! ## Simple put and get +//! ```no_run +//! use jammdb::{DB, Data, Error}; +//! +//! fn main() -> Result<(), Error> { +//! { +//! // open a new database file +//! let mut db = DB::open("my-database.db")?; +//! +//! // open a writable transaction so we can make changes +//! let mut tx = db.tx(true)?; +//! +//! // create a bucket to store a map of first names to last names +//! let names_bucket = tx.create_bucket("names")?; +//! names_bucket.put(b"Kanan", b"Jarrus")?; +//! names_bucket.put(b"Ezra", b"Bridger")?; +//! +//! // commit the changes so they are saved to disk +//! tx.commit()?; +//! } +//! { +//! // open the existing database file +//! let mut db = DB::open("my-database.db")?; +//! // open a read-only transaction to get the data +//! let mut tx = db.tx(true)?; +//! // get the bucket we created in the last transaction +//! let names_bucket = tx.get_bucket("names")?; +//! // get the key-value pair we inserted into the bucket +//! if let Some(Data::KeyValue(kv)) = names_bucket.get(b"Kanan") { +//! assert_eq!(kv.value(), b"Jarrus"); +//! } +//! } +//! Ok(()) +//! } +//! ``` +//! +//! ## Storing structs +//! ```no_run +//! use jammdb::{DB, Data, Error}; +//! use serde::{Deserialize, Serialize}; +//! // use rmps crate to serialize structs using the MessagePack format +//! use rmp_serde::{Deserializer, Serializer}; +//! +//! #[derive(Debug, PartialEq, Deserialize, Serialize)] +//! struct User { +//! username: String, +//! password: String, +//! } +//! +//! fn main() -> Result<(), Error> { +//! let user = User{ +//! username: "my-user".to_string(), +//! password: "my-password".to_string(), +//! }; +//! { +//! // open a new database file and start a writable transaction +//! let mut db = DB::open("my-database.db")?; +//! let mut tx = db.tx(true)?; +//! +//! // create a bucket to store users +//! let users_bucket = tx.create_bucket("users")?; +//! +//! // serialize struct to bytes and store in bucket +//! let user_bytes = rmp_serde::to_vec(&user).unwrap(); +//! users_bucket.put(b"user1", user_bytes)?; +//! +//! // commit the changes so they are saved to disk +//! tx.commit()?; +//! } +//! { +//! // open the existing database file +//! let mut db = DB::open("my-database.db")?; +//! // open a read-only transaction to get the data +//! let mut tx = db.tx(true)?; +//! // get the bucket we created in the last transaction +//! let users_bucket = tx.get_bucket("users")?; +//! // get the key-value pair we inserted into the bucket +//! if let Some(Data::KeyValue(kv)) = users_bucket.get(b"user1") { +//! // deserialize into a user struct +//! let db_user: User = rmp_serde::from_slice(kv.value()).unwrap(); +//! assert_eq!(db_user, user); +//! } +//! } +//! Ok(()) +//! } +//! ``` +//! #![warn(clippy::all)] #![warn(missing_docs)] diff --git a/src/transaction.rs b/src/transaction.rs index 2d7a319..aedf837 100644 --- a/src/transaction.rs +++ b/src/transaction.rs @@ -24,12 +24,14 @@ use crate::ptr::Ptr; /// Transactions are completely isolated from each other, so a read-only transaction can expect the data to stay exactly the same for the life /// of the transaction, regardless of how many changes are made in other transactions2. /// -/// There are three important methods. Check out their documentation for more details: -/// 1. [`create_bucket`](#method.create_bucket) makes new buckets at the root level. Available in writable transactions. -/// 2. [`get_bucket`](#method.get_bucket) retreives buckets from the root level. Available in read-only or writable transactions. -/// 3. [`commit`](#method.commit) saves a writable transaction. Available in writable transactions. +/// There are four important methods. Check out their documentation for more details: +/// 1. [`get_bucket`](#method.get_bucket) retreives buckets from the root level. Available in read-only or writable transactions. +/// 2. [`create_bucket`](#method.create_bucket) makes new buckets at the root level. Available in writable transactions only. +/// 3. [`detete_bucket`](#method.delete_bucket) deletes a bucket (including all nested buckets) from the database. Available in writable transactions only. +/// 4. [`commit`](#method.commit) saves a writable transaction. Available in writable transactions. /// -/// Trying to use the methods that require writable transactions from a read-only transaction will result in an error. +/// Trying to use the methods that require writable transactions from a read-only transaction will result in an error. If you make edits in a writable transaction, +/// and you want to save them, you must call the [`commit`](#method.commit) method, otherwise when the transaction is dropped all your changes will be lost. /// /// # Examples ///