{"id":17473728,"url":"https://github.com/zgsolucoes/zg-data-guard","last_synced_at":"2026-01-28T16:39:11.616Z","repository":{"id":257858703,"uuid":"869167931","full_name":"zgsolucoes/zg-data-guard","owner":"zgsolucoes","description":"ZG Data Guard is a centralized tool designed to streamline and secure the management of multiple databases across various environments. It simplifies administration by providing a unified platform to handle database ecosystems, technologies, instances, predefined roles, databases, users, and access control. All secured through JWT-protected API.","archived":false,"fork":false,"pushed_at":"2024-10-25T19:11:58.000Z","size":269,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-10T05:03:31.950Z","etag":null,"topics":["access-management","clusters-management","cryptography","database-management","docker","go","go-chi","godotenv","golang","golang-migrate","jwt-auth","keycloak","postgresql","rest-api","swagger2","swaggo","testify","users-management"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zgsolucoes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-07T20:43:50.000Z","updated_at":"2025-01-27T15:21:12.000Z","dependencies_parsed_at":"2024-10-26T00:55:41.014Z","dependency_job_id":"b28838d2-b4b1-4b55-914c-334bf30b9e8b","html_url":"https://github.com/zgsolucoes/zg-data-guard","commit_stats":{"total_commits":88,"total_committers":2,"mean_commits":44.0,"dds":"0.011363636363636354","last_synced_commit":"7c7051ca596cf4e2260af8b15941c534fa18ea37"},"previous_names":["zgsolucoes/zg-data-guard"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zgsolucoes/zg-data-guard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgsolucoes%2Fzg-data-guard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgsolucoes%2Fzg-data-guard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgsolucoes%2Fzg-data-guard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgsolucoes%2Fzg-data-guard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zgsolucoes","download_url":"https://codeload.github.com/zgsolucoes/zg-data-guard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zgsolucoes%2Fzg-data-guard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28847021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["access-management","clusters-management","cryptography","database-management","docker","go","go-chi","godotenv","golang","golang-migrate","jwt-auth","keycloak","postgresql","rest-api","swagger2","swaggo","testify","users-management"],"created_at":"2024-10-18T18:06:46.427Z","updated_at":"2026-01-28T16:39:11.601Z","avatar_url":"https://github.com/zgsolucoes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![ZG Data Guard](logo.png)\nZG Data Guard is a centralized tool designed to streamline and secure the management of multiple databases across various environments. It simplifies administration by providing a unified platform to handle database ecosystems, technologies, instances, predefined roles, databases, users, and access control. All secured through JWT-protected API.\nBy using this tool organizations can effectively centralize database access management simplifying administration, improve operational efficiency, maintain compliance through detailed auditing and logging and promoting good security practices.\n\n\u003e A practical use case is to manage access to database instances (clusters) and their databases in development, staging, and production environments, ensuring that only authorized users (people or applications) have access to connect and perform specific operations on database objects based on their roles.\n\n## Features\n\n---\n1. [**Ecosystem Management**](#ecosystem-management)\n1. [**Database Technologies Management**](#database-technologies-management)\n1. [**Database Instances (Clusters) Management**](#database-instances-clusters-management)\n1. [**Predefined Roles**](#predefined-roles)\n1. [**Databases Management**](#databases-management)\n1. [**Database Users Management**](#database-users-management)\n1. [**Access Control Management**](#access-control-management)\n1. [**API Secured by JWT Tokens**](#api-secured-by-jwt-tokens)\n\n#### Ecosystem Management\n\nManage ecosystems where database instances (clusters) are running, such as AWS, Cloud, or On-premises environments.\n\n#### Database Technologies Management\n\nHandle various database technologies, like Elasticsearch 6.2, PostgreSQL 13, PostgreSQL 16, etc.\n\n#### Database Instances (Clusters) Management\n\nManage database instances (clusters) within specific ecosystems. Initially supports PostgreSQL instances, with future extensibility for other technologies.\n\n- **Operations:** Create, Read, Update\n- **Additional Functions:**\n  - **Test Connection:** Verify connectivity to the database instance.\n  - **Synchronize Databases:** Update the list of databases within the instance.\n  - **Create Predefined Roles:** Set up predefined roles in the instance context.\n  - **Enable/Disable Instance:** Remove all defined accesses from all users when disabling; also disables all databases within the cluster.\n\n#### Predefined Roles\n\nUtilize predefined roles assigned to users in specific databases to enforce the principle of least privilege. The roles are defined as follows:\n\n- **Roles:**\n  - **User Read Only:** Read-only permissions on all schemas of the database.\n  - **Developer:** DML permissions (SELECT, INSERT, UPDATE, DELETE) and usage of sequences, functions, and types in all schemas.\n  - **DevOps:** DML and DDL permissions (CREATE, ALTER, TRUNCATE, DROP) on tables, functions, sequences, triggers, types, etc., in all schemas.\n  - **Application:** Same as DevOps, intended for application users.\n- **Notes:**\n  - No role can grant or revoke privileges to itself or other roles.\n  - No role has SUPERUSER permission.\n  - Roles are designed following the **Principle of Least Privilege**.\n\n#### Databases Management\n\nManage existing databases within instances and apply predefined roles to establish permissions on database objects like schemas, tables, functions, views, sequences, and types.\n\n#### Database Users Management\n\nManage users who can be assigned to database instances or databases with specific roles (e.g., `foo.bar`, `john.doe`). It can be a user for a person or an application.\n\n- **Operations:** Create, Read, Update, Enable/Disable Users\n\n#### Access Control Management\n\nControl users' access to instances/databases by granting or revoking connect permission, with comprehensive logging for auditing purposes.\n\n- **Operations:**\n  - **Grant Access:** Provide users access to one or more instances.\n  - **Revoke Access:** Remove users' access from instances.\n  - **Logging:** Record and display the results of binding and unbinding operations.\n\n#### API Secured by JWT Tokens\n\nThe API is protected using JWT (JSON Web Tokens) for secure authentication and authorization, ensuring safe communication between clients and the server.\n\n## Technologies Used\n\n---\n\n- GoLang 1.22+\n- PostgreSQL 16+\n- [Keycloak 26+](https://www.keycloak.org/) for OAuth2 and JWT\n- AES-256 encryption for sensitive data protection\n- Swagger for API documentation\n- Makefile for task automation\n\n The following dependencies are used in this project (generated using [Glice](https://github.com/ribice/glice)):\n\n```bash\n+--------------------------------------+-------------------------------------------+--------------+\n|              DEPENDENCY              |                  REPOURL                  |   LICENSE    |\n+--------------------------------------+-------------------------------------------+--------------+\n| github.com/go-chi/chi/v5             | https://github.com/go-chi/chi             | MIT          |\n| github.com/go-chi/jwtauth            | https://github.com/go-chi/jwtauth         | MIT          |\n| github.com/golang-migrate/migrate/v4 | https://github.com/golang-migrate/migrate | Other        |\n| github.com/google/uuid               | https://github.com/google/uuid            | bsd-3-clause |\n| github.com/joho/godotenv             | https://github.com/joho/godotenv          | MIT          |\n| github.com/lib/pq                    | https://github.com/lib/pq                 | MIT          |\n| github.com/stretchr/testify          | https://github.com/stretchr/testify       | MIT          |\n| github.com/swaggo/http-swagger       | https://github.com/swaggo/http-swagger    | MIT          |\n| github.com/swaggo/swag               | https://github.com/swaggo/swag            | MIT          |\n| golang.org/x/oauth2                  | https://go.googlesource.com/oauth2        |              |\n+--------------------------------------+-------------------------------------------+--------------+\n```\n\n1. Go-chi - HTTP Middleware Router\n1. JWT Auth - JWT Authentication\n1. Golang Migrate - Database Migrations\n1. Google UUID - UUID generator\n1. Godotenv - Environment variables\n1. lib/pq - PostgreSQL driver\n1. Testify/Assert - Asserting test results\n1. Swaggo - Swagger documentation\n1. OAuth2 - OAuth2 library\n\n## Usage\n\n---\n\n### 1. Installation\n- [**Docker**](#docker)\n- [**Docker Compose**](#docker-compose)\n\n### 2. Setup Project\n\n#### Environment Variables\n1. Configure the environment variables by creating a `.env` file in the root directory. Use the `.env.example` file as a template.\n```sh\n   cp .env.example .env\n```\n2. Update the `.env` file envs according to your preferences.\n\n### 3. Running the API\n- `docker-compose build --no-cache`: Build the services defined in the `docker-compose.yml` file.\n- `docker-compose up`: Run the services defined in the `docker-compose.yml` file.\n\nTo stop and remove containers, networks, and volumes defined in the `docker-compose.yml` file, run:\n\n```sh\ndocker-compose down\n```\n\n### 4. How to Interact with the API\n\n- **Home Page:**  \n  Access the application's home page at [http://localhost:8081](http://localhost:8081).\n\n- **Health Check Endpoint:**  \n  Access the health check endpoint at [http://localhost:8081/healthcheck/info](http://localhost:8081/healthcheck/info).\n\n- **Authentication for Testing Purposes:**\n    - Click on the **`Login - internal user`** button to authenticate using the `zg-services` user.\n        - This user is intended **just for testing and interacting with API endpoints**.\n    - After logging in, you will receive a **JWT token**.\n\n- **Using the JWT Token:**\n    - **Copy** the JWT token provided after authentication.\n    - Use this token to **interact with the API endpoints** that require authentication.\n\n- **Accessing Swagger UI:**\n    - You can use Swagger UI to interact with the API endpoints.\n    - Open Swagger UI by clicking on the **`Open Swagger UI`** button or navigating to [http://localhost:8081/docs/index.html](http://localhost:8081/docs/index.html).\n\n- **Authorizing in Swagger UI:**\n    - In Swagger UI, click on the **`Authorize`** button (usually represented by a lock icon).\n    - In the modal that appears, enter the JWT token in the **`Value`** field.\n    - Click **`Authorize`** to authenticate your session.\n    - You can now make authenticated requests to the API endpoints directly from Swagger UI.\n    - Try accessing the [http://localhost:8081/api/v1/database-roles](http://localhost:8081/api/v1/database-roles) endpoint to list all predefined roles. Don't forget the `Authorization` header with the JWT token.\n\n**Additional Notes:**\n\n- Ensure that the API is **running properly** before attempting to access the home page or Swagger UI.\n- The `zg-services` user is meant **for testing purposes and internal routines only** and should **not be used in production environments**.\n\n#### (TODO) Keycloak to Secure the API\n\n1. Visit http://localhost:8080.\n2. Log in with the credentials defined for Keycloak in the `.env` file.\n3. Create a new realm, e.g., `zg-data-guard`.\n4. Create a new client, e.g., `zg-data-guard-api`.\n5. Configure the client with the following settings:\n    - **Access Type:** Confidential\n    - **Valid Redirect URIs:** `http://localhost:8081/*`\n    - **Web Origins:** `http://localhost:8081`\n    - **Client Protocol:** `openid-connect`\n    - **Service Accounts Enabled:** On\n    - **Authorization Enabled:** On\n    - **Direct Access Grants Enabled:** On\n    - **Standard Flow Enabled:** On\n6. Create a new user and assign the user to the client.\n7. Update the `.env` file with the Keycloak settings.\n8. Restart the API server.\n9. Access the API at [http://localhost:8081](http://localhost:8081).\n10. Authenticate using the Keycloak credentials.\n11. Access the protected endpoints. Use the Swagger documentation to test the API endpoints.\n\n## Development Guide\n\n---\n\n### Installation of Tools\n\nTo set up the development environment, you need to install the following tools:\n\n- [**GoLang 1.22+**](#golang-122)\n- [**Docker**](#docker)\n- [**Docker Compose**](#docker-compose)\n- [**GolangCI-Lint**](#golangci-lint)\n- [**Migrate**](#migrate)\n- [**Swaggo**](#swaggo)\n- [**Make**](#make)\n\n#### GoLang 1.22+\n\nDownload and install GoLang from the [official website](https://go.dev/dl/). Follow the instructions for your operating system. After installation, verify the installation by running:\n\n```bash\ngo version\n```\n\n#### Docker\n\nDownload and install Docker from the [official Docker website](https://www.docker.com/get-started). Follow the installation guide for your operating system. Verify the installation with:\n\n```bash\ndocker --version\n```\n\n#### Docker Compose\n\nDocker Compose is included with Docker Desktop for Windows and macOS. For Linux, install it separately by following the [official instructions](https://docs.docker.com/compose/install/). Verify the installation:\n\n```bash\ndocker-compose --version\n```\n\n#### GolangCI-Lint\n\nInstall [GolangCI-Lint](https://golangci-lint.run/) for linting Go code:\n\n```bash\ncurl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s latest\n```\n\nAlternatively, you can use Homebrew on macOS:\n\n```bash\nbrew install golangci-lint\n```\n\nVerify the installation:\n\n```bash\ngolangci-lint --version\n```\n\nUsage:\n\n```bash\nmake lint\n```\n\n#### Migrate\n\nInstall [Migrate](https://github.com/golang-migrate/migrate/) for database migrations:\n\n```bash\ngo install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest\n```\n\nEnsure that your `GOPATH/bin` is in your `PATH` environment variable. Verify the installation:\n\n```bash\nmigrate --version\n```\n\nTo create a new migration, run:\n\n```bash\nmake create_migration\n```\n\n#### Swaggo\n\nInstall [Swaggo](https://github.com/swaggo/swag) to generate Swagger documentation:\n\n```bash\ngo install github.com/swaggo/swag/cmd/swag@latest\n```\n\nVerify the installation:\n\n```bash\nswag --version\n```\n\n#### Make\n\nEnsure that `make` is installed on your system to use the provided `Makefile` for task automation.\n\n- **On macOS** (if not already installed):\n\n  ```bash\n  xcode-select --install\n  ```\n\n- **On Linux** (using apt):\n\n  ```bash\n  sudo apt-get install build-essential\n  ```\n\n- **On Windows**:\n\n  Install [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm) or use a Unix-like environment like Git Bash.\n\nVerify the installation:\n\n```bash\nmake --version\n```\n\nAfter installing all the tools, you should be ready to set up and run the project.\n\n### Directory Structure\n\n---\n```\n.\n├── cmd\n│   ├── zg-data-guard\n│       └── main.go     //main function start the server\n├── config              //configurations for the project\n├── docs                //swagger API documentation\n├── internal\n│   ├── database        //connector, migrations, sql files and storages\n│   ├── dto             //data transfer objects\n│   ├── entity          //database entities, models\n│   ├── usecase         //business logic\n│   ├── webserver       //http server, routes, handlers, middlewares\n├── pkg                 //shared packages, utilities, security functions like crypto and jwt\n└── testdata            //test data for unit tests, mocks\n...\n```\n\n### Set up the Project\n\n---\n1. Fork this repo and `git clone` it to your local machine.\n1. Configure the environment variables by creating a `.env` file in the root directory. Use the `.env.example` file as a template.\n```sh\n   cp .env.example .env\n```\n1. Update the `.env` file with your database connection details, [Keycloak settings](#setup-keycloak-to-secure-the-api), and other configurations.\n1. To install dependencies, run:\n```bash\nmake install\n```\n\n### Build\n\n---\n1. To build the project and generate the executable, run:\n\n```bash\nmake build\n```\n\n2. To clean the project, run:\n\n```bash\nmake clean\n```\n\n### Running API\n\n--- \n* To run the app, execute:\n\n```bash\nmake run\n```\n\n* To generate the API Swagger documentation and execute, run:\n\n```bash\nmake run-with-docs\n```\n\n* If you want to generate docs without running the server, run:\n\n```bash\nmake docs\n```\n\n* By default, the server will be available at: [http://localhost:8081](http://localhost:8081)\n* The Swagger documentation will be available at: [http://localhost:8081/docs/index.html](http://localhost:8081/docs/index.html)\n* Health check endpoint: [http://localhost:8081/healthcheck/info](http://localhost:8081/healthcheck/info)\n\n### About Tests\n\n--- \n\nTo run the project tests, run in the terminal:\n\n```bash\nmake test\n```\n\nTo run the tests with more details, run:\n\n```bash\nmake test-verbose\n```\n\nTo run the project tests without cache and return the total number of tests executed:\n\n```bash\nmake test-count\n```\n\nTo run the tests and generate an HTML file with a complete coverage report for each file, run:\n\n```bash\nmake test-cover-report\n```\n\nTo validate the total test coverage percentage of all files, run:\n\n```bash\nmake coverage\n```\n\nTo validate the total test coverage percentage of business logic files, run:\n\n```bash\nmake core-coverage\n```\n\nThe minimum test coverage percentage is configured in the `Makefile` file in the `MIN_COVERAGE` and `MIN_CORE_COVERAGE` variables.\n\n### Release\n\n--- \n\nThe `make release=\u003cversion\u003e` command was created to be used by CI/CD pipeline. Example:\n\n```bash\nmake release=1.2.3\n```\nIt will generate a release tag with the version `v1.2.3` in the `dist` folder.\n\n## Contributing\n\n--- \n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Credits\n\n--- \n\nThis project was created by the [ZG Soluções](https://www.linkedin.com/company/zg-solucoes/) team.\n\nEnjoy!\n\n![ZG Soluções](logo-zg.png)\n\n[https://zgsolucoes.com.br/](https://zgsolucoes.com.br/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzgsolucoes%2Fzg-data-guard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzgsolucoes%2Fzg-data-guard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzgsolucoes%2Fzg-data-guard/lists"}