{"id":26233625,"url":"https://github.com/andytango/rust-todos-grpc-example","last_synced_at":"2025-06-14T14:34:48.335Z","repository":{"id":275355230,"uuid":"925841457","full_name":"andytango/rust-todos-grpc-example","owner":"andytango","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-12T03:09:14.000Z","size":77,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T03:29:38.591Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andytango.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-02-01T21:48:11.000Z","updated_at":"2025-04-12T03:09:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"ec89dd63-b4eb-488c-afd7-692cb17ebbbc","html_url":"https://github.com/andytango/rust-todos-grpc-example","commit_stats":null,"previous_names":["andytango/rust-todos-grpc-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/andytango/rust-todos-grpc-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andytango%2Frust-todos-grpc-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andytango%2Frust-todos-grpc-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andytango%2Frust-todos-grpc-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andytango%2Frust-todos-grpc-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andytango","download_url":"https://codeload.github.com/andytango/rust-todos-grpc-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andytango%2Frust-todos-grpc-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259831680,"owners_count":22918565,"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-03-13T01:16:53.008Z","updated_at":"2025-06-14T14:34:48.259Z","avatar_url":"https://github.com/andytango.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rust Todos gRPC Example Server\n\nThis repository provides a template for building a Rust service using Tonic for\ngRPC, SQLx for database interaction (PostgreSQL), and dotenv for environment\nvariable management.\n\n## Introduction\n\nThis template offers a basic structure for a Rust service, including database\nconnection management, environment configuration, and gRPC setup. It's designed\nto be a starting point for building more complex services.\n\n## Dependencies\n\n- [Rust toolchain](https://www.rust-lang.org/tools/install]). Rust is generally\n  backwards compatible, if you have encounter issues then v1.84.0 is\n  known to work.\n- A vanilla [PostgreSQL database](https://www.postgresql.org/download/), version\n  15 or above.\n- For linux (debian or ubuntu), the following APT packages: `build-essential`,\n  `lib-ssl-dev`, `pkg-config`\n- [Protocol Buffer Compiler](https://grpc.io/docs/protoc-installation). The\n  version from APT appears to work fine.\n- [Rust toolchain](https://www.rust-lang.org/tools/install). On mac OS this can be\n  installed using [homebrew](https://brew.sh).\n\n## Codebase Structure\n\nThis project follows a modular structure to organize the code and improve\nmaintainability. Here's a brief overview of the key directories and modules:\n\n* **`src/bin/server.rs`**: This file is the entry point for the application. It\n  initializes the common parts of the application, sets up the gRPC server, and\n  starts listening for incoming requests.\n* **`src/lib.rs`**:  Contains the core logic of the service. This is where the\n  gRPC server is defined and interactions with the database occur.\n* **`src/lib/common.rs`**:  Houses common utility functions and types used\n  across the project, promoting code reuse and consistency. For example, this\n  includes logging and environment variable utilities.\n* **`src/lib/database.rs`**:  Handles database interactions, including\n  connection management and schema migrations using SQLx. This module abstracts\n  database operations, making it easier to change database implementations or\n  configurations if needed.\n* **`src/lib/services`**: This directory contains modules related to specific\n  gRPC services. For example, `src/lib/services/todos` houses the implementation\n  of the To-Do service, including the gRPC service definition and the business\n  logic for managing to-do items.\n    * **`src/lib/services/todos/common.rs`**: Contains utilities related to the\n      To-Do service. For example, mapping database row format into the protocol\n      buffer format used by gRPC.\n    * **`src/lib/services/todos/create.rs`**: Contains the implementation to\n      handle creating a new To-Do item. Following this structure the To-Do\n      service also has modules named  `delete.rs`, `get.rs`, `list.rs` and\n      `update.rs` implementing the various gRPC server methods.\n* **`src/proto`**:  Contains the Protocol Buffer (protobuf) definitions for the\n  gRPC services. These files define the service interface and the structure of\n  the data exchanged between the client and server.\n* **`tests`**: This directory includes tests for different modules and\n  functionalities, ensuring code quality and reliability.\n* **`migrations`**: This directory contains SQL migration files used by\n  `sqlx migrate` to manage the database schema. These migrations allow for easy\n  schema updates and rollbacks.\n\nThis modular design separates concerns and makes it easier to maintain and\nextend the application.\n\nThe use of well-defined modules and the `services` directory allows you to\neasily add new gRPC services without impacting existing code, keeping the\nproject scalable and manageable.\n\n## Getting Started\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/your-username/rust-service-template.git\n   ```\n\n2. **Install dependencies:**\n\nYou will need to install the sqlx command line tool to run the database scripts:\n```bash\ncargo install sqlx-cli\n```\n\n3. **`.env` File:**\n\nThe `.env.example` contains all the environment variables you will need, \nalong with documentation for each one.\n\n4. **Database Management:**\n\nOnce you have updated the `.env` file with the database connection string, you \ncan use the following commands to set up the database:\n\n```\nsqlx database create\nsqlx migrate run\n```\n\n5. **Running the Server:**\n\nAfter setting up the database and the `.env` file, you can run the server:\n\n```bash\ncargo run --bin server\n```\n\n## Database Scripts\n\n* **`sqlx database create`**: Create a database based on the DATABASE\\_URL\n  (useful if it doesn't exist yet).\n* **`sqlx database drop`**: Drops the database associated with the\n  DATABASE\\_URL, use with extreme care.\n\n* **`sqlx migrate add \u003cname\u003e`**: Adds a new migration.\n* **`sqlx migrate run`**: Applies all pending migrations.\n* **`sqlx migrate info`**: Shows the current migration status.\n* **`sqlx migrate revert`**: Reverts the last applied migration.\n\nRefer to the SQLx documentation for more detailed information about the CLI and\nits capabilities.\n\n## Generating Protobuf Documentation\n\nThis repository includes a command-line interface (CLI) tool located at `src/bin/cli.rs` that can generate documentation for your Protocol Buffer (`.proto`) files. This documentation is generated in Markdown format and is particularly useful for understanding the structure and capabilities of your gRPC services.\n\n### How to use the CLI tool\n\nYou can run (and build, if needed) the CLI tool with the `generate-docs` command to create the documentation:\n\n```bash\ncargo run --bin cli -- generate-docs\n```\n\n### Understanding the process\n\n    When you run the `generate-docs` command, the following steps occur:\n\n*   **Downloads `protoc-gen-doc`:** The tool automatically downloads the `protoc-gen-doc` binary, a plugin for the Protocol Buffer compiler (`protoc`), from GitHub releases. The correct version for your operating system and architecture (Linux/macOS, x86\\_64/arm64) is selected automatically.\n*   **Extracts the Binary:** The downloaded file, which is a compressed archive (`.tar.gz`), is extracted to a temporary directory.\n*   **Locates `.proto` Files:** The tool searches for all `.proto` files within the `src/protocols` directory.\n*   **Generates Documentation:** It then uses `protoc` with the `protoc-gen-doc` plugin to generate Markdown documentation from these `.proto` files.\n*   **Outputs to `docs` Directory:** The generated documentation is saved in the `docs` directory at the root of the project. If the `docs` directory exists, it will be completely removed before the new documentation is generated.\n*   **Cleans up** The temporary directory used to extract `protoc-gen-doc` is deleted automatically.\n\n### Viewing the generated documentation\n\nAfter running the command, you can view the generated documentation in the `docs/index.md` file. This file will contain detailed information about your gRPC services, messages, and their fields, all nicely formatted in Markdown.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandytango%2Frust-todos-grpc-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandytango%2Frust-todos-grpc-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandytango%2Frust-todos-grpc-example/lists"}