GraphXR Database Proxy

Language: English | 中文

A secure middleware that connects GraphXR to various backend databases with zero trust architecture.

Features

• Zero Trust Security: Strict authentication and authorization at the proxy layer
• Direct Browser Connectivity: REST/GraphQL APIs for efficient data access
• Multi-Database Support: Spanner Graph, Neo4j, and more
• Open Source: Fully auditable and customizable
• Pure Python: Easy to deploy and maintain

⚡ Quick Start (Spanner Graph)

1. Run the following commands to start graphxr-database-proxy (requires uv, node.js)

git clone https://github.com/Kineviz/graphxr-database-proxy.git
cd graphxr-database-proxy
uv venv
uv pip install -r requirements.txt
npm run dev

2. Web UI should open automatically in your browser. Or visit http://localhost:8080/.
3. Click "Create New Project"
4. Project Name: "Test"
5. Database Type: "Google Cloud Spanner"
6. Authentication Type: "Service Account"
7. Upload the credential file you exported from GCP Console or gcloud CLI. Export Instructions
8. Select "Instance ID" e.g. "demo"
9. Select "Database ID" e.g. "cymbal"
10. Select "Property Graph" e.g. "ECommerceGraph"
11. Click "Create"
12. For the new project, under Actions, copy the API URL. e.g. "http://localhost:8080/api/spanner/Test"
13. Go back to GraphXR's Create Project wizard and paste the API URL into GraphXR for a project with a "Database Proxy" database type.

Adding authentication to the proxy

cp .env.example .env

Edit the .env file and add the following variables:

# Optional: Set a password for the admin interface
ADMIN_PASSWORD=your-admin-password-here

# Optional: Set a secure API key for the proxy API
# You can also generate an API key in the Web UI under Settings.
API_KEY=your-secure-api-key-here

Other ways to start graphxr-database-proxy

Install

# Install from PyPI
pip install graphxr-database-proxy[ui]

# Or from source
git clone https://github.com/Kineviz/graphxr-database-proxy.git
cd graphxr-database-proxy
uv venv
source .venv/bin/activate # or .venv/bin/activate on Windows
uv pip install -e ".[ui]"
uv pip install -r requirements.txt
cd frontend && npm install && npm run build && cd -
pip install -e .[ui]

Configure & Run

Option 1: Web UI (Recommended)

graphxr-proxy --ui

Open http://localhost:9080/admin for configuration

Option 2: Python Code with Service Account JSON

from graphxr_database_proxy import DatabaseProxy

proxy = DatabaseProxy()

service_account_json = {
    "type": "service_account",
    "project_id": "your-gcp-project-id",
    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n",
    "client_email": "your-service-account@your-gcp-project-id.iam.gserviceaccount.com",
    ...
}

project_id = proxy.add_project(
    project_name="project_name",
    database_type="spanner",
    project_id="gcp-project-id", 
    instance_id="spanner-instance-id",
    database_id="spanner-database-id",
    credentials=service_account_json,  
    graph_name="graph_name"  # Optional
)

proxy.start(
    host="0.0.0.0",     
    port=9080,          
    show_apis=True     
)

Option 3: Python Code with Google Cloud ADC

Your should have set up Google Application Default Credentials (ADC) on the machine running the proxy. See Google Cloud ADC Documentation.

from graphxr_database_proxy import DatabaseProxy
proxy = DatabaseProxy()

google_adc_credentials={
    "type": "google_ADC"
},  
 
project_id = proxy.add_project(
    project_name="project_name",
    database_type="spanner",
    project_id="gcp-project-id", 
    instance_id="spanner-instance-id",
    database_id="spanner-database-id",
    credentials=google_adc_credentials,  
    graph_name="graph_name"  # Optional
)

proxy.start(
    host="0.0.0.0",     
    port=9080,          
    show_apis=True     
)

🐳 Docker

docker run -d -p 9080:9080 \
--name graphxr-database-proxy \
-v ${HOME}/graphxr-database-proxy/config:/app/config \
kineviz/graphxr-database-proxy:latest

You can visit http://localhost:9080/admin for configuration after starting the container.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 🐛 Issue Tracker
• 📧 Email: support@kineviz.com

---

Built with ❤️ by Kineviz