{"id":20181516,"url":"https://github.com/antoniosarosi/mkdb","last_synced_at":"2025-05-15T13:06:05.993Z","repository":{"id":199133130,"uuid":"700017073","full_name":"antoniosarosi/mkdb","owner":"antoniosarosi","description":"Toy Database","archived":false,"fork":false,"pushed_at":"2024-10-21T16:00:08.000Z","size":853,"stargazers_count":720,"open_issues_count":0,"forks_count":65,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-15T05:32:44.731Z","etag":null,"topics":["database","relational-databases","rust","sql"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antoniosarosi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-03T19:31:51.000Z","updated_at":"2025-04-15T04:48:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"53e11212-2c65-4d5f-90ca-ff2dbf99bfcd","html_url":"https://github.com/antoniosarosi/mkdb","commit_stats":null,"previous_names":["antoniosarosi/mkown-db","antoniosarosi/mkdb"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoniosarosi%2Fmkdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoniosarosi%2Fmkdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoniosarosi%2Fmkdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antoniosarosi%2Fmkdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antoniosarosi","download_url":"https://codeload.github.com/antoniosarosi/mkdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","relational-databases","rust","sql"],"created_at":"2024-11-14T02:35:50.386Z","updated_at":"2025-05-15T13:06:05.955Z","avatar_url":"https://github.com/antoniosarosi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MKDB\n\nToy database implemented for learning purposes. Almost all of the implementation\nideas come from these resources:\n\n- [SQLite 2.8.1 source code](https://github.com/antoniosarosi/sqlite2-btree-visualizer)\n- [CMU Intro to Database Systems 2023](https://www.youtube.com/playlist?list=PLSE8ODhjZXjbj8BMuIrRcacnQh20hmY9g)\n- [CMU Intro to Database Systems 2018](https://www.youtube.com/playlist?list=PLSE8ODhjZXja3hgmuwhf89qboV1kOxMx7)\n\nOther less important resources are linked in the source code.\n\n# Compilation\n\nInstall [`rustup`](https://rustup.rs/) if you don't have it and then install the\n`nightly` toolchain:\n\n```bash\nrustup toolchain install nightly\n```\n\nUse `cargo` to compile the project:\n\n```bash\ncargo +nightly build\n```\n\nAlternatively, set your default toolchain to `nightly` to avoid specifying\n`+nightly` for every `cargo` command:\n\n```bash\nrustup default nightly\n```\n\n## Compiler Version\n\nIf you see any compilation errors it's probably because of the compiler\nversion. Run `rustc +nightly --version` and compare the output to the last\nversion used to compile and test the project:\n\n```\nrustc 1.78.0-nightly (9c3ad802d 2024-03-07)\n```\n\n# Tests\n\nUse [`cargo test`](https://doc.rust-lang.org/cargo/commands/cargo-test.html) to\nrun all the unit tests:\n\n```bash\ncargo +nightly test\n```\n\n## Unsafe\n\nAll the [unsafe](https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html) code\nis located in [`./src/storage/page.rs`](./src/paging/page.rs), which is the\nmodule that implements slotted pages. [`Miri`](https://github.com/rust-lang/miri)\ncan be used to test possible undefined behaviour bugs. Install the component\nusing `rustup`:\n\n```bash\nrustup +nightly component add miri\n```\n\nThen use `cargo` to test the `page` module:\n\n```bash\ncargo +nightly miri test storage::page::tests\n```\n\nThe [`./src/paging/`](./src/paging/) and\n[`./src/storage/btree.rs`](./src/storage/btree.rs) modules are not unsafe\nthemselves but they heavily rely on the slotted page module so it's worth\ntesting them with Miri as well:\n\n```bash\ncargo +nightly miri test paging\ncargo +nightly miri test storage::btree\n```\n\nIf all these modules work correctly without UB then the rest of the codebase\nshould be fine. The ultimate UB test is the [`./src/db.rs`](./src/db.rs) module\nsince it's the entry point to SQL execution so it makes use of every other\nmodule. It can be tested with Miri as well since tests are configured to run\ncompletely in memory without files or system calls:\n\n```bash\ncargo +nightly miri test db::tests\n```\n\nThe rest of modules don't make any use of unsafe code so it's not necessary to\ntest them with Miri.\n\n# Running The Program\n\nUse this command to start the TCP server on port `8000` (the default if not\nspecified):\n\n```bash\ncargo +nightly run -- file.db 8000\n```\n\n`file.db` can be any empty file or a file previously\nmanaged by `mkdb`. It works like SQLite in that regard, the difference is that\nin order to use `mkdb` you have to connect to the server with some TCP client\nthat implements the network protocol described at\n[`./src/tcp/proto.rs`](./src/tcp/proto.rs). The [`./client`](`./client`) package\nis a console client similar to that of MySQL or any other database and can be\nused like this:\n\n```bash\ncargo +nightly run --package client -- 8000\n```\n\nThis will connect to the `mkdb` server running on port `8000` and provide you with\na shell where you can type SQL and see the results of the queries.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantoniosarosi%2Fmkdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantoniosarosi%2Fmkdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantoniosarosi%2Fmkdb/lists"}