{"id":28153959,"url":"https://github.com/spongejump/axum-sqlx","last_synced_at":"2025-05-15T06:12:37.442Z","repository":{"id":282613025,"uuid":"877163317","full_name":"spongejump/axum-sqlx","owner":"spongejump","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-23T07:43:47.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-20T08:41:25.979Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spongejump.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":"2024-10-23T07:41:46.000Z","updated_at":"2024-10-23T07:43:51.000Z","dependencies_parsed_at":"2025-03-15T19:39:00.583Z","dependency_job_id":"fe18a496-5c7b-4f94-a008-a6b95a5483d3","html_url":"https://github.com/spongejump/axum-sqlx","commit_stats":null,"previous_names":["spongepump/axum-sqlx","spongejump/axum-sqlx"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spongejump%2Faxum-sqlx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spongejump%2Faxum-sqlx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spongejump%2Faxum-sqlx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spongejump%2Faxum-sqlx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spongejump","download_url":"https://codeload.github.com/spongejump/axum-sqlx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283287,"owners_count":22045141,"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":[],"created_at":"2025-05-15T06:12:34.425Z","updated_at":"2025-05-15T06:12:37.428Z","avatar_url":"https://github.com/spongejump.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# realworld-axum-sqlx\nA Rust implementation of the [Realworld] demo app spec showcasing the use of the [Axum] web framework and [SQLx]\nSQL database client, with [PostgreSQL] as the database backend.\n\nThis project also serves as a commentary on the Realworld spec and how realistic it actually is, as well as\nwhat a particular senior developer at Launchbadge currently considers to be best practices. Best practices are always\nin flux, and a major point of this project was to experiment with project architecture and suss out what those\nbest practices might look like.\n\nFeedback is appreciated!\n\n### Note: \"I\" vs \"we\"\n\nAll comments in this project were (currently) written by a single person, and represent primarily that person's opinions\nand observations. When a comment uses \"we\", it does not necessarily indicate an authoritative position taken by \nLaunchbadge, but rather an interpretation, by that one person, of the current consensus at Launchbadge, \nor an observation of a particular sentiment shared by several developers at Launchbadge.\n\n[Realworld]: https://github.com/gothinkster/realworld\n[Axum]: https://github.com/tokio-rs/axum/\n[SQLX]: https://github.com/launchbadge/sqlx/\n[PostgreSQL]: https://www.postgresql.org/\n\n## Project Structure\n\nThis project uses the 2015/1.0.0 module structure, with `mod.rs` files for modules with children,\nas opposed to the 2018 (or \"new\") module style introduced in [RFC 2126], where `mod.rs` files are optional\nand adding children to a module `foo.rs` is as simple as creating a `foo/` directory. \n\nThis is a style choice we vacillated on for a while at Launchbadge. However, we ultimately decided that the 2018\nmodule style results in a lot of papercuts during rapid development, which is antithetical to its original design.\n\nNamely, because most file management GUIs sort files separately from folders, you have to jump between two completely\ndifferent places in the visualized file tree when transitioning between a parent module and its children. This is highly\nconfusing to developers who were already used to the original module system when the 2018 style was introduced.\n\nOn its own, this would have been manageable, but it is made worse by the fact that the new style isn't\nrecommended by default in the 2018 edition and there is no lint in `rustc` to enforce consistency*, so it becomes really \neasy to mix and match styles accidentally when multiple developers with varying experience levels are contributing to a \nproject, or jumping back and forth between projects.\n\nIn retrospect, the 2018 edition should have involved a wholesale transition, banning `mod.rs` files by default and\nproviding a migration path with `cargo fix`, like with the other changes proposed in RFC 2126. \nI understand why the language team was hesitant to do this, as it had the weakest set of justifications of all\nthe changes proposed in the RFC, but their indecision resulted in, IMHO, a far, far worse situation.\n\n\\* Lints for this [were only recently added to Clippy][Clippy mod_module_files], \nseveral years after the 2018 style was introduced. As of writing, the `rust-lang/rust` repo itself mixes both\nstyles in various directories, which is frankly quite horrifying.\n\n[RFC 2126]: https://github.com/rust-lang/rfcs/blob/master/text/2126-path-clarity.md#the-modrs-file\n[Clippy mod_module_files]: https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/module_style.rs#L35\n\n### Code Tour\n\nIf you're familiar with SQL, I recommend starting in the `migrations/` directory, as that's what contains the SQL files\nthat define the schema of the PostgreSQL database, which is usually the first thing done when prototyping a new project. \nThe files there are filled with comments explaining the various decisions made while structuring the database,\nas well as advice on good practices for schema architecture and how this compares to the Realworld spec.\n\nNext, of course, is `main.rs` as the entrypoint for the application. It shows the typical boilerplate that goes\ninto spinning up a Rust backend application.\n\nI then recommend going to `lib.rs` and recursively exploring the modules as they're defined.\nComments on the module definitions will guide you from there.\n\n[`clap`]: https://github.com/clap-rs/clap/\n\n## Setup\n\n### Clone this Repository\n\n```shell\n$ git clone https://github.com/launchbadge/realworld-axum-sqlx\n$ cd realworld-axum-sqlx\n```\n\n### Installing Rust and Cargo\n\nInstall Rust as described in [The Rust Programming Language, chapter 1](https://doc.rust-lang.org/book/ch01-01-installation.html).\n\nThis is the official Rust language manual and is freely available on doc.rust-lang.org.\n\nThe latest stable version is fine.\n\n\n### Installing `sqlx-cli`\n\nSQLx provides a command-line tool for creating and managing databases as well as migrations. It is published\non the Cargo crates registry as `sqlx-cli` and can be installed like so:\n\n```shell\n$ cargo install sqlx-cli --features postgres\n```\n\n### Running Postgres\n\nBy far the easiest way to run Postgres these days is using a container with [a pre-built image][docker-postgres].\n\nThe following command will start version 14 of Postgres (the latest at time of writing) using [Docker] \n(this command should also work with [Podman], a daemonless FOSS alternative).\n\n```shell\n$ docker run -d --name postgres-14 -p 5432:5432 -e POSTGRES_PASSWORD={password} postgres:14\n```\n\nSet `{password}` to a password of your choosing.\n\nEnsure the Postgres server is running:\n```shell\n$ docker ps\n```\n```shell\nCONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS                                       NAMES\n621eb8962016   postgres:14   \"docker-entrypoint.s…\"   30 seconds ago   Up 30 seconds   0.0.0.0:5432-\u003e5432/tcp, :::5432-\u003e5432/tcp   postgres-14\n```\n\n[docker-postgres]: https://hub.docker.com/_/postgres\n[Docker]: https://www.docker.com/\n[Podman]: https://podman.io/\n\n### Configuring the Application\n\nConfiguring the backend application is done, preferentially, via environment variables. This is the easiest way\nto pass sensitive configuration data like database credentials and HMAC keys in a deployment environment such as \n[Kubernetes secrets].\n\nTo make working with environment variables easier during development, we can use [.env files] to avoid having\nto define the variables every time.\n\nAs a starting point, you can simply `cp .env.sample .env` in this repo and modify the `.env` file as described by\nthe comments there.\n\n[Kubernetes secrets]: https://kubernetes.io/docs/concepts/configuration/secret/\n[.env files]: https://github.com/dotenv-rs/dotenv\n\n### Setting Up the Application Database\n\nWith `sqlx-cli` installed and your `.env` file set up, you only need to run the following command to get the\nPostgres database ready for use:\n\n```\n$ sqlx db setup\n```\n\n### Starting the Application\n\nWith everything else set up, all you should have to do at this point is:\n\n```\n$ cargo run\n```\n\nIf successful, the Realworld-compatible API is now listening at port 8080.\n\n## License\n\nAll code in this project is licensed under the [GNU Affero General Public License (AGPL)][AGPL]. \n\nThe AGPL is an extension of the GPL which includes interacting with the application over a computer network in its \ndefinition of \"distribution\" for applying the license terms. If you modify this project and host it in a location that\nis accessible to the web, you must make the source available as per the terms of the license.\n\nSee [LICENSE](LICENSE) in this repository for the text of the AGPL.\n\n[AGPL]: https://www.gnu.org/licenses/agpl-3.0.en.html\n\n### Contributing\n\nBecause enforcement of the AGPL requires that we own the copyright on the whole project, any contributions\nto this project must be explicitly assigned copyright to Launchbadge, LLC. We're still researching the best\nroute to do this, so while we will allow PRs to be opened against this repository, they may not be merged right away.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspongejump%2Faxum-sqlx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspongejump%2Faxum-sqlx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspongejump%2Faxum-sqlx/lists"}