#client #library #db

bin+lib smol_db_client

A client library for smol_db

7 stable releases

1.3.1 Oct 19, 2023
1.3.0 Sep 17, 2023
1.2.1 Aug 26, 2023

#976 in Database interfaces

Download history 83/week @ 2023-08-09 48/week @ 2023-08-16 27/week @ 2023-08-23 6/week @ 2023-08-30 6/week @ 2023-09-06 39/week @ 2023-09-13 11/week @ 2023-09-20 13/week @ 2023-09-27 6/week @ 2023-10-04 5/week @ 2023-10-11 54/week @ 2023-10-18 11/week @ 2023-10-25 15/week @ 2023-11-01 7/week @ 2023-11-08 9/week @ 2023-11-15 26/week @ 2023-11-22

61 downloads per month
Used in smol_db_viewer



Image of program, small fat cat laying on a server computer

Program art made by Crisis.


A database client and server designed for small databases that simply need quick setup and deletion, read and write. The goal of this database is to use it in most of my other projects when applicable, and make it as easy to use as possible. The database's structure is simply a hashmap.

This project consists of 4 subprojects:

  • smol_db_server: A server program that waits for connections to it, and serves them on port 8222. It also handles the files needed to run the database.
  • smol_db_client: A library that can be used to interface with the server program.
  • smol_db_common: A library used to run a server, should the smol_db_server not be adequate, this library consists of everything necessary to build a server that handles requests and process them.
  • smol_db_viewer: An example program that allows the user to connect to a smol_db_server, the program can connect, view, create, delete, read, and write databases on a given server.

Programs currently using this database:

  • cr_tiler_rs uses the database to store leaderboards information for the game service.
  • Feel free to let me know if you use this database, I would love to know! :)

Reasons to use smol_db:

  • You want to use a more minimal database program
  • You are me, and enjoy using software you make
  • You want a database program that has no specific ties to operating system services, and has minimal setup requirements
  • You want to contribute to the repository
  • You think the program art is cute. Crisis

Notable features:

  • Easy to set up both the server, and the databases within (No fiddling with weird pathing issues or other common annoyances)
  • Simple client library for easy program integration
  • Mostly easy to read code, allowing for easy addition of other features
  • Viewing/editing client for at a glance overviews of a database
  • Opt-in RSA-2048 bit packet encryption
  • Databases are stored in ram for a per database amount of time after any interaction from a client


smol_db is not designed to be extremely secure, most of its use cases are exist on the local network, where security can less necessary.

While the program has opt-in packet encryption, I still do not recommend this program for any high security applications.

If there are any improvements that can be made to security that come to my mind, I will slowly implement them as I get around to those ideas. access keys are not stored in a hash or encrypted format, and therefore should not be assumed to be safe or secure when stored.

Example Docker-Compose entry

    build: https://github.com/CoryRobertson/smol_db.git#main
    image: smol_db_server
      - "8222:8222"
    container_name: "smol_db_server_instance1"
    restart: unless-stopped
      - "./smol_db:/data"


To create a smol_db_server instance, the above docker compose example can be used, or the server package can be built from source and run on the server computer. After creating an instance of the server on either bare-metal or a docker container, simply connect to it using the smol_db_client library, or through the smol_db_viewer. Images below outline what the smol_db_viewer looks like and what screens are available.

Example usage of client library:

use smol_db_client::SmolDbClient;
fn main() {
    // server is assumed to be running on localhost on port 8222
    let mut client = SmolDbClient::new("localhost:8222").unwrap();
    let data = "super cool user data";
    let _ = client.set_access_key("readme_db_key".to_string()).unwrap();
    let _ = client.create_db("cool_db_name", DBSettings::default()).unwrap();
    let _ = client.write_db("cool_db_name", "cool_data_location", data).unwrap();

    match client.read_db("cool_db_name","cool_data_location") {
        SuccessReply(response_data) => {
            assert_eq!(&response_data, data);
        SuccessNoData => {



Image of connecting to a database using the viewing application

Setting the clients access key:

Image of setting the key of the client in the viewing application

Creating a database:

Image of creating a database using the viewing application

Viewing the data, and editing the data on the database:

Image of viewing the data on the database, and also writing to it, using the viewing application

Changing the settings of a database

Image of changing the database settings using the viewing application


~135K SLoC