{"id":15041145,"url":"https://github.com/paypal/hera","last_synced_at":"2025-05-15T20:07:06.696Z","repository":{"id":37793902,"uuid":"184614293","full_name":"paypal/hera","owner":"paypal","description":"High Efficiency Reliable Access to data stores","archived":false,"fork":false,"pushed_at":"2025-03-24T10:24:44.000Z","size":16605,"stargazers_count":294,"open_issues_count":22,"forks_count":84,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-08T02:41:18.685Z","etag":null,"topics":["databases","mux","mysql","oracle","scalability"],"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/paypal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-02T16:24:38.000Z","updated_at":"2025-04-04T02:17:46.000Z","dependencies_parsed_at":"2023-02-14T12:31:40.002Z","dependency_job_id":"483ffb1e-4c1f-4094-a4a9-3df2438d52bc","html_url":"https://github.com/paypal/hera","commit_stats":{"total_commits":369,"total_committers":39,"mean_commits":9.461538461538462,"dds":0.6449864498644986,"last_synced_commit":"850f18c4306d2e8343a7c7ae940e2819608db75f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fhera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fhera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fhera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Fhera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paypal","download_url":"https://codeload.github.com/paypal/hera/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"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":["databases","mux","mysql","oracle","scalability"],"created_at":"2024-09-24T20:45:40.354Z","updated_at":"2025-05-15T20:07:01.551Z","avatar_url":"https://github.com/paypal.png","language":"Go","readme":"[![Go Build](https://github.com/paypal/hera/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/paypal/hera/actions/workflows/go.yml)\n[![Java CI with Maven](https://github.com/paypal/hera/actions/workflows/jdbc-ci-maven.yml/badge.svg?branch=main)](https://github.com/paypal/hera/actions/workflows/jdbc-ci-maven.yml)\n[![Functional Tests](https://github.com/paypal/hera/actions/workflows/manual-ft.yml/badge.svg?branch=main)](https://github.com/paypal/hera/actions/workflows/manual-ft.yml)\n[![License](http://img.shields.io/:license-Apache%202-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.txt)\n\n\u003cimg src=\"docs/hera.png\" height=\"240\" width=\"340\"\u003e\n\n# Hera - High Efficiency Reliable Access to data stores\n\nHera multiplexes connections for MySQL, Oracle and\nPostgreSQL databases. It supports sharding the databases for horizontal scaling.\n\n  * [Overview](docs/overview.md)\n  * [Configuration](docs/configuration.md)\n  * [Sharding](docs/sharding.md)\n  * [Transparent failover](docs/taf.md)\n  * [Bind Eviction](docs/bindevict.md)\n  * [History](docs/history.md)\n  * [Contributing](docs/contributing.md)\n\n# What is Hera\n\nHera is Data Access Gateway that helps to enable scaling and improving the availability of databases.\n* Protects the database from resource exhaustion by evicting poorly performing queries\n* Intelligently routes read/write traffic appropriately for better load balancing\n* Improves tolerance to database outages\n* Provides high performance secured connections between applications and Hera\n* Provides domain agnostic database sharding for horizontal database scaling\n* Automatic transaction application failover between replica databases\n* And many more site resiliency features\n\n# Getting Started\n\nYou can build mux using either [Docker](#docker-build) or [manual](#manual-build) build.\n\n## Docker Build\n\nFor development, the following docker commands for the appropriate environment can help get started\n\nLinux\n\n    git clone https://github.com/paypal/hera.git\n    docker run --network host --name mysql-11 -e MYSQL_ROOT_PASSWORD=62-AntHill -d mysql:latest\n    cd hera/tests/devdocker\n    docker exec -i mysql-11 mysql -u root -h 127.0.0.1 -p62-AntHill -t \u003c sample.sql\n    mkdir -p src/github.com/paypal/hera\n    rsync -av --exclude tests/devdocker ../.. src/github.com/paypal/hera\n    docker build -t hera-oss .\n    docker run -it --rm --name testRunHeraOss --network host -e password=62-AntHill hera-oss\n\nMac\n\n    git clone https://github.com/paypal/hera.git\n    docker network create my-network\n    docker run --network my-network --name mysql-11 -e MYSQL_ROOT_PASSWORD=62-AntHill -d mysql:latest\n    cd hera/tests/devdocker\n    docker exec -i mysql-11 mysql -u root -h 127.0.0.1 -p62-AntHill -t \u003c sample.sql\n    mkdir -p src/github.com/paypal/hera\n    rsync -av --exclude tests/devdocker ../.. src/github.com/paypal/hera\n    sed -i.bak -e 's/127.0.0.1/mysql-11/g' srv/start.sh\n    docker build -t hera-oss .\n    docker run -it --rm --name testRunHeraOss --network my-network -p 10101:10101 -e password=62-AntHill hera-oss\n\n\nTo test it, in a separate terminal:\n\n    docker exec -it testRunHeraOss /bin/bash\n    cd /go/src\n    go run github.com/paypal/hera/client/gosqldriver/tls/example/sample_main.go\n\n## Manual Build\n\nThe following sections explain the process for manually building mux without Docker. We only tested on RedHat and Ubuntu.\n\n### Install Dependencies\n\n1.  [Install Go 1.10+](http://golang.org/doc/install).\n2.  Install [MySQL](http://dev.mysql.com/downloads/mysql), [Oracle](https://www.oracle.com/index.html) or [PostgresSQL](https://www.postgresql.org/download/).\n3.  Install the [MySQL driver](https://github.com/go-sql-driver/mysql), [Oracle driver](https://github.com/go-goracle/goracle) and the [PostgreSQL driver](https://github.com/lib/pq)\n4.  Install Oracle instant client.\n5.  Install GCC.\n\n### Build Binaries\n\n1.  Navigate to the working directory.\n    ```\n    cd $WORKSPACE\n    export GOPATH=$WORKSPACE\n    ```\n2. Option 1\n\n    Clone the source code from [github](https://github.com/paypal/hera)\n    ```\n    git clone https://github.com/paypal/hera src/github.com/paypal/hera\n    ```\n    Option 2\n\n    (a) GO 1.12 is prerequisite\n\n    (b) export GO111MODULE=on ( to enable the go mod feature)\n    ```\n    go get github.com/paypal/hera\n    ```\n3.  Install the dependencies: MySQL, Oracle and PostgreSQL driver\n    ```\n    cd src/github.com/paypal/hera\n    go get github.com/go-sql-driver/mysql\n    go get github.com/godror/godror\n    go get github.com/lib/pq\n    ```\n4.  Build server binaries\n    ```\n    go install github.com/paypal/hera/mux github.com/paypal/hera/worker/mysqlworker github.com/paypal/hera/worker/oracleworker github.com/paypal/hera/worker/postgresworker\n    ```\n5.  Build Go test client\n    ```\n    go install github.com/paypal/hera/tests/e2e/client\n    ```\n6.  Build Java test client under the client/java directory\n\n7.  Build the C++ oracleworker\n    ```\n    cd worker/cppworker/worker\n    make -f ../build/makefile19\n    ```\n### Running the server\n\nTo run mux there is minimal configuration required. Please see examples for running with [MySQL](https://github.com/paypal/hera/tree/master/tests/e2e/srvmysql) or [Oracle](https://github.com/paypal/hera/tree/master/tests/e2e/srvoracle).\nThe main configuration file is hera.txt, which must contain the TCP port where the server listens and the number of workers. The user name, password and the data source are passed via environment parameters.\n```bash\n    # the proxy executable\n    ln -s $GOPATH/bin/mux .\n    # the MySQL worker\n    ln -s $GOPATH/bin/mysqlworker mysqlworker\n    # to use the Oracle worker use oracleworker instead of mysqlworker\n\n    # create the configuration file with the required configuration\n    echo 'bind_ip=127.0.0.1' \u003e hera.txt\n    echo 'bind_port=11111' \u003e\u003e hera.txt\n    echo 'opscfg.hera.server.max_connections=2' \u003e\u003e hera.txt\n    # if using mysql run this\n    # echo 'database_type=mysql' \u003e\u003e hera.txt\n    # if using postgres run this\n    # echo 'database_type=postgres' \u003e\u003e hera.txt\n\n    # create minimal CAL configuration, needed by ops config\n    echo 'cal_pool_name=stage_hera' \u003e cal_client.txt\n\n    # the database user name\n    export username='user'\n    # the database password\n    export password='pass'\n    # the data source\n    export TWO_TASK='tcp(127.0.0.1:3306)/myschema'\n    # for Oracle the datasource can be like '(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=hostname)\n    #    (PORT=12345)))(CONNECT_DATA=(SERVICE_NAME=sn)))'.\n    # for Oracle only add to LD_LIBRARY_PATH environment variable the path to the shared libraries of the\n    #    Oracle instant client\n    # for postgress format can be like : export TWO_TASK='127.0.0.1:5432/user?connect_timeout=60'\n\n    # start\n    ./mux --name hera-test\n    \n    # to validate HERA is running fine tail 'state-log' file and check 2 connections in 'acpt' state.\n    # 01/07/2022 18:28:39: -----------  init  acpt  wait  busy  schd  fnsh  quce  asgn  idle  bklg  strd\n    # 01/07/2022 18:28:39: hera            0     2     0     0     0     0     0     0     0     0     0\n    \n    # incase connections are not in accept state, check the hera.log file for errors\n```    \nFor details about the parameters see [configuration](docs/configuration.md)\n\n## Running the client\n\nThere is a Java client implemented as JDBC driver. Please see the [documentation](https://github.com/paypal/hera/tree/master/client/java) for how to install and use it.\n\nThere is also a Go client implemented as [SQL driver](client/gosqldriver). Please see the [example](tests/e2e/client).\n\n## License\n\nHera is licensed under Apache 2.0.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaypal%2Fhera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaypal%2Fhera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaypal%2Fhera/lists"}