SleekDB is a simple NoSQL database implementation that store data in plain JSON files.
Intentionally SleekDB is not designed for heavy-load IO operations, it is designed to have a simple solution where we need a database for managing few gigabytes of data.
SleekDB works great as the database engine for most low to medium traffic websites.
Any site that gets fewer than 50k to 100K hits/day should work fine with SleekDB.
To use SleekDB make sure that you have PHP up and running in your system, and SleekDB has write permission.
Using SleekDB in a PHP project
To install SleekDB using composer, open a terminal, cd into your project root directory where "composer.json" file lives and run this:
composer require rakibtg/sleekdb
SleekDB should be auto loaded into your app using the composer. Find SleekDB on packagist.
Install Manually (Without Composer)
Getting started with SleekDB is super easy. We keep data in a "store", which is similar to MySQL "table" or MongoDB "collection". To start working with data at first we create a new instance of SleekDB. Later, we create a "store" using the instantiated object to start working with data.
$database = new \SleekDB\SleekDB( "/Users/username/data/my_site" );Optionally you can pass a configuration array in the second parameter. Read more about configurations.
$newsStore = $database->store( "news" );
// An array that we want to insert. $newsInsertable = [ "title" => "Google Pixel XL", "about" => "The unlocked biggest Pixel 2..." ]; $results = $newsStore->insert( $newsInsertable );The results variable would contain all the inserted data and with the _id property.
SleekDB would have a server that could be used as the database server that works separately and independently. This feature is not implemented yet.
At this moment SleekDB only allows two configurations, which are "auto_cache" and "timeout". Configurations should be passed as an array in the second parameter while instantiating SleekDB, store's created from this object will follow the configurations we have provided.Using Custom Configuration
You should pass the configurations array in the second parameter, example:
$database = new \SleekDB\SleekDB( "/Users/username/data/my_site", [ 'auto_cache' => true, 'timeout' => 120 ]);
Let's talk about what this configurations do.
The auto_cache is set to true by default!
This tells SleekDB to cache the data of an unique database query and later re-use the cache for the same query.
To keep the cached data synced with new data, SleekDB will delete all cache when we insert any new data to a store.
To disable it update the value of auto_cache to false in the config array.
Note that you can manually manage cache data with methods that SleekDB provides. Available caching method's are: makeCache(), useCache(), deleteCache() and deleteAllCache()
Set timeout value, default value is 120 second.
Store is a simple directory where SleekDB will write all your data in JSON documents. "Store" is similar with the idea of "Table" in MySQL or "Collection" in MongoDB. You dont need to create a "store" manually, while you use the "store" method from the SleekDB object it will first check if the "store" directory exists or not, if not then it would be created instantly.
At this moment you can not rename a store, but you can do it manually using the File Browser of your OS or using the terminal.
Your first store
To start working with a store, at first we need to create an object of SleekDB. Later, we can use that object to work with any store.
$database = new \SleekDB\SleekDB( "/path/to/data-dir/mysite" );
$userStore = $database->store( "users" );Another store to keep all the posts shared by the user.
$postStore = $database->store( "posts" );
$userStore->insert([ 'name' => 'Mike Doe', 'email' => 'email@example.com' ]);This could be also written as,
$database->store( "users" )->insert([ 'name' => 'Mike Doe', 'email' => 'firstname.lastname@example.org' ]);
To insert data first you make a PHP array, and simply insert that array into a store.
Insert A Single Data Object
Using the insert() method we will insert a new data object. Example:
// Prepare a PHP array to insert. $user = [ 'name' => 'Kazi Hasan', 'products' => [ 'totalSaved' => 19, 'totalBought' => 27 ], 'location' => [ 'town' => 'Nagar', 'city' => 'Dhaka', 'country' => 'Bangladesh' ] ]; // Insert the data. $user = $usersDB->insert( $user );Here, the insert() method will return the inserted object with the _id property which is generated by SleekDB.
Insert Multiple Data ObjectUsing the insertMany() method you can insert more than one data object at a time, example:
// Prepare users data. $users = [ [ 'name' => 'Russell Newman', 'products' => [ 'totalSaved' => 5, 'totalBought' => 3 ], 'location' => [ 'town' => 'Andreas Ave', 'city' => 'Maasdriel', 'country' => 'England' ] ], [ 'name' => 'Willard Bowman', 'products' => [ 'totalSaved' => 0, 'totalBought' => 0 ], ], [ 'name' => 'Tommy Mendoza', 'products' => [ 'totalSaved' => 172, 'totalBought' => 54 ], ], [ 'name' => 'Joshua Edwards', 'phone' => '(382)-450-8197' ] ]; // Insert all data. $usersDB->insertMany( $users );The insertMany() method will return the inserted object with the _id property which is generated by SleekDB.
To get data from the store we use the fetch() method. Example:
The above command would query into the "users" store to fetch all the data.
Apply Filters and Conditions
To filter data we use the where() method.
The where() method takes three arguments, those are:
where( $fieldName, $condition, $value );
The filed name argument is the property that we want to check in our data object.
As our data object is basically a JSON document so it could have nested properties.
To target nested properties we use a single dot between the property/field name.
Example: From our above users object if we want to target the "country" property of a user, then we would pass location.country in this argument, because "location" is the parent property of the "country" property in our data object.
To apply the comparison filters we use this argument.
Allowed comparisonal conditions are:
Data to be used as against the property value of the JSON documents.
Example of using where() to filter data
To only get the user whose country is equal to "England" we would query like this:
$user = $usersDB->where( 'name', '=', 'Joshua Edwards' )->fetch();
You can use multiple where() conditions. Example:
$user = $usersDB->where( 'products.totalSaved', '>', 10 ) ->where( 'products.totalBought', '>', 20 ) ->fetch();
To edit a data object we would use the update() method.
The update method takes only one argument.
update( $updateable );
Lets update the "totalBought" value of a user whose name is "Joshua Edwards"
$updateable = [ 'products' => [ 'totalBought' => 1 ] ]; $usersDB->where( 'name', '=', 'Joshua Edwards' )->update( $updateable );
You can use more than one where condition if required.
To delete a data object we would use the delete() method. Example:
Lets delete the user whose name is "Joshua Edwards"
$usersDB->where( 'name', '=', 'Joshua Edwards' )->delete();
You can use more than one where condition if required.
To skip a set of record we will use the skip() method. Example:
// Skip the first 5 users. $users = $usersDB->skip( 5 )->fetch();
To limit a set of record we will use the limit() method. Example:
// Fetch only 5 users. $users = $usersDB->limit( 5 )->fetch();
To obtain the query offset feature we can chain skip() and limit() into one query. Example:
$users = $usersDB ->where( 'age', '>=', 18 ) ->skip( 15 ) ->limit( 5 ) ->fetch();
The above query will skip first 15 records and will limit to next 5 records of data objects. This way we can also perform paginate.
To sort data objects we would use the orderBy() method.
The orderBy method takes two argument,
orderBy( $order, $orderBy );
Lets sort the data based on total items bought by the user.
$users = $usersDB ->orderBy( 'desc', 'products.totalBought' ) ->limit( 20 ) ->fetch();
We can search data using the search() method. It utilizes the similar_text() function and works better on medium length string.
The search method takes two argument,
search( $field, $keyword );
Lets search for users who lives in Canada.
$users = $usersDB ->search( 'location.country', 'Canada' ) ->fetch();
To ensure proper search result we can search more than one property at a time. Example,
$users = $usersDB ->search( 'bio', 'I Love Canada' ) ->search( 'location.country', 'Canada' ) ->where( 'active', '=', 1 ) ->fetch();
The useCache() method would return the data from the cache storage, if cache dosent exists then it would fetch the result then creates the cache for later use and return the data. Example,
$user = $usersDB ->where( 'active', '=', 1 ) ->where( 'location.country', '=' 'United States' ) ->search( 'bio', 'PHP developer' ) ->search( 'bio', 'SleekDB' ) ->orderBy( 'desc', 'rank' ) ->limit( 20 ) ->useCache() // Use the cache data. ->fetch();
To re-generate the cache for a query we would use the makeCache() method.
Its more like the useCache() method but the only difference is that instead of looking for existing cache data it would replace the old cache by generating a new cache from fresh data fetched. Example,
$user = $usersDB ->search( 'bio', 'SleekDB' ) ->orderBy( 'desc', 'rank' ) ->skip( 80 ) ->limit( 20 ) ->makeCache() // Re-generate the cache data. ->fetch();
To delete the cache of a query we would use the deleteCache() method. Example,
$user = $usersDB ->search( 'bio', 'SleekDB' ) ->orderBy( 'desc', 'rank' ) ->skip( 80 ) ->limit( 20 ) ->deleteCache();
Note that if you need to get the data please add the fetch() method.
To delete all cache use the deleteAllCache() method. Example,
We would love to see how you are using the database, if you have implemented something or how it is working for you.
What changes will make you more interested.
If you want to submit a bug feel free to create a new issue or email me @ rakibtg [-at-] gmail.
The design sometime breaks in Firefox, please visit using Opera or Chrome. Fix in progress.