{"id":50428861,"url":"https://github.com/jexp/aura-multi-db","last_synced_at":"2026-05-31T12:30:40.190Z","repository":{"id":357955534,"uuid":"1181346736","full_name":"jexp/aura-multi-db","owner":"jexp","description":"A script to create multidb instances, users and upload dump/backup files","archived":false,"fork":false,"pushed_at":"2026-05-15T02:26:20.000Z","size":43,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T02:43:32.465Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/jexp.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T02:54:20.000Z","updated_at":"2026-05-15T02:26:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jexp/aura-multi-db","commit_stats":null,"previous_names":["jexp/aura-multi-db"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jexp/aura-multi-db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jexp%2Faura-multi-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jexp%2Faura-multi-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jexp%2Faura-multi-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jexp%2Faura-multi-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jexp","download_url":"https://codeload.github.com/jexp/aura-multi-db/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jexp%2Faura-multi-db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33731998,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-31T12:30:38.221Z","updated_at":"2026-05-31T12:30:40.183Z","avatar_url":"https://github.com/jexp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Neo4j Aura Multi-Database Manager\n\nCLI tool for managing multiple databases on a single Neo4j Aura Business Critical instance via the v1beta6 API.\n\n**No external dependencies** — pure Python 3.9+ using only `urllib` and standard library modules.\n\n## Setup\n\n```bash\ncp env.example .env\n# Edit .env with your Aura API credentials and instance details\n```\n\nTo get API credentials, create an API key in the [Aura Console](https://console.neo4j.io) under Account \u003e API Keys.\n\n## Usage\n\n```\npython3 aura-multi-db.py \u003ccommand\u003e [args...]\n```\n\n### Commands\n\n| Command | Description | ~Time |\n|---------|-------------|-------|\n| `create-instance \u003cname\u003e` | Create a new multi-db BC instance | ~5 min |\n| `add-db \u003cdbname\u003e` | Create a database (async, returns immediately) | — |\n| `add-db \u003cdbname\u003e --wait` | Create + wait until running | ~1 min |\n| `add-db \u003cdbname\u003e --users [prefix]` | + create ro/rw users (implies --wait) | ~1 min |\n| `add-db \u003cdbname\u003e --dump \u003cfile\u003e` | + upload dump/backup (implies --users) | ~5 min |\n| `list-dbs` | List all databases with status and counts | — |\n| `add-users \u003cdbid\u003e[,\u003cdbid2\u003e,...] [dbname[,...]] --users \u003cuser1,user2,...\u003e` | Add named users to one or more databases | — |\n| `upload \u003cdbid\u003e \u003cfile\u003e` | Upload a .dump or .backup file | ~3 min |\n| `delete-db \u003cdbid\u003e` | Delete database + associated users/roles | ~1 min |\n| `remove-users \u003cdbid\u003e` | Remove users/roles without deleting the database | — |\n\n### Flags\n\n| Flag | Description |\n|------|-------------|\n| `--wait` | Poll until async operations complete |\n| `--yes` | Skip confirmation prompts (for scripting) |\n| `--users [prefix]` | (`add-db`) Create ro/rw users; prefix defaults to slugified dbname |\n| `--users \u003cuser1,user2,...\u003e` | (`add-users`) Comma-separated list of usernames to create |\n| `--ro` | (`add-users`) Create only read-only users |\n| `--rw` | (`add-users`) Create only read-write users |\n| `--dump \u003cfile\u003e` | Upload dump/backup after creating database |\n| `--creds \u003cfile\u003e` | Load credentials from file (overrides .env) |\n\n### User and role naming\n\nDatabase names passed to `add-db` are slugified (lowercase, alphanumeric, runs of other chars → `_`).\nRoles are always tied to the hex database ID. User names embed the db slug so they are unique across databases:\n\n| Command | Example users | Roles |\n|---------|--------------|-------|\n| `add-db c360_data --users` | `c360_data_ro`, `c360_data_rw` | `{dbid}_ro/rw` |\n| `add-db c360_data --users michael` | `michael_c360_data_ro`, `michael_c360_data_rw` | `{dbid}_ro/rw` |\n| `add-users \u003cdbid\u003e c360_data --users alice,bob` | `alice_c360_data_ro/rw`, `bob_c360_data_ro/rw` | `{dbid}_ro/rw` |\n| `add-users \u003cdbid\u003e c360_data --users alice --ro` | `alice_c360_data_ro` only | `{dbid}_ro` |\n| `add-users \u003cdbid\u003e --users alice,bob` | `alice_{dbid}_ro/rw`, `bob_{dbid}_ro/rw` | `{dbid}_ro/rw` |\n| `add-users \u003cdb1\u003e,\u003cdb2\u003e name1,name2 --users michael --ro` | `michael_ro` (home db = db1, access to db1+db2) | `{db1}_ro`, `{db2}_ro` |\n\n**Multi-database user behaviour:**\n- If the user does not yet exist it is created with a fresh password and a credential file is saved.\n- If the user already exists, only the new role grants are applied — the password is never changed and no new credential file is written.\n- In multi-db mode the username has no db slug (`{user}_ro/rw`) and `SET HOME DATABASE` is set to the first listed database so clients land there by default.\n\nAll `CREATE ROLE` statements use `IF NOT EXISTS` so the command is safe to re-run.\n\n### Credential files\n\n`create-instance`, `add-db --users`, and `add-users` (for new users) save credential files:\n\n```\nNeo4j-{instanceid}-{dbid}-{username}-readonly.txt\nNeo4j-{instanceid}-{dbid}-{username}-readwrite.txt\n```\n\nFor multi-db users the file is keyed to the first database and includes comment lines listing all databases and the granted roles:\n\n```\n# Additional databases: \u003cdb2id\u003e, \u003cdb3id\u003e\n# Roles: \u003cdb1id\u003e_ro, \u003cdb2id\u003e_ro\n```\n\nThese files can be passed to other commands via `--creds`:\n\n```bash\npython3 aura-multi-db.py create-instance MyInstance\npython3 aura-multi-db.py add-db mydb --users --creds Neo4j-abc123-Created-2026-03-14.txt\n```\n\n### Environment variables\n\nVariables are loaded with increasing priority: **shell env \u003c .env \u003c --creds file**.\n\n| Variable | Description |\n|----------|-------------|\n| `CLIENT_ID`, `CLIENT_SECRET` | Aura API credentials |\n| `PROJECT_ID` | Aura project/tenant ID |\n| `NEO4J_URI` | Instance bolt URI (`neo4j+s://...`) |\n| `NEO4J_USERNAME`, `NEO4J_PASSWORD` | Admin credentials |\n| `AURA_INSTANCEID` | Instance ID |\n| `NEO4J_DATABASES_DIR` | Folder containing dump files (default: `databases`); credential files go to `\u003cdir\u003e/users/` |\n| `NEO4J_CREDS_DIR` | Override credential file output dir directly (takes priority over `NEO4J_DATABASES_DIR`) |\n| `GCP_CHUNK_SIZE_MB` | GCP upload chunk size in MB (default: 1024) |\n\n## Examples\n\n```bash\n# Full lifecycle: create database with users and load data\npython3 aura-multi-db.py add-db sales --dump sales.dump --yes\n\n# Create database, wait, add specific named users (ro only)\npython3 aura-multi-db.py add-db analytics --wait --yes\npython3 aura-multi-db.py add-users c7511697 analytics --users alice,bob --ro\n\n# Add both ro and rw users to existing database (with friendly name for slug)\npython3 aura-multi-db.py add-users c7511697 c360_data --users michael,jane\n\n# Grant michael read-only access to two databases (single user account, home db = first)\n# Creates michael_ro with roles c7511697_ro and b9f63f7b_ro; home database = c7511697\npython3 aura-multi-db.py add-users c7511697,b9f63f7b c360_data,analytics --users michael --ro\n\n# Grant a team member ro+rw access across three databases\npython3 aura-multi-db.py add-users c7511697,b9f63f7b,0bf4a21f c360,analytics,reporting --users alice\n\n# Quick async create (returns immediately)\npython3 aura-multi-db.py add-db reporting\n\n# List all databases\npython3 aura-multi-db.py list-dbs\n\n# Upload data to an existing database\npython3 aura-multi-db.py upload abc123 data.dump\n\n# Delete a database (removes roles; named users from add-users remain)\npython3 aura-multi-db.py delete-db abc123 --wait --yes\n```\n\n## Bulk deployment\n\n`deploy-databases.sh` scans a folder for `*.backup` / `*.dump` files, creates or re-uploads each database in parallel, then assigns named users across all of them.\n\n```bash\n./deploy-databases.sh \u003cfolder\u003e \u003chome-db-slug\u003e \u003crw-users\u003e \u003cro-users\u003e\n```\n\n| Argument | Description | Default |\n|----------|-------------|---------|\n| `folder` | Directory containing dump/backup files | `./databases` |\n| `home-db-slug` | Slug of the database set as home DB for all named users | `c360` |\n| `rw-users` | Comma-separated usernames to receive ro+rw access | _(none)_ |\n| `ro-users` | Comma-separated usernames to receive ro-only access | _(none)_ |\n\n```bash\n# Deploy all dumps in ./databases, home db = mydb, with rw and ro user sets\n./deploy-databases.sh ./databases mydb \\\n    \"alice,bob\" \\\n    \"charlie,dana\"\n```\n\n- Per-database logs are written to `\u003cfolder\u003e/outputs/\u003cslug\u003e.log`\n- Credential files go to `\u003cfolder\u003e/users/`\n- Databases are created/uploaded in parallel; user assignment runs after all uploads complete\n- If some uploads fail, user assignment still runs for the successful ones\n- Safe to re-run: existing databases are re-uploaded rather than re-created; existing users get new role grants without a password change\n\n### Adding users to an existing deployment\n\nTo add more users to an already-deployed set of databases, run `add-users` directly with the comma-separated list of database IDs (home DB first):\n\n```bash\n# RO only\npython3 aura-multi-db.py add-users \u003chomeid\u003e,\u003cid2\u003e,\u003cid3\u003e,... --users alice,bob --ro --yes\n\n# RW (ro + rw accounts)\npython3 aura-multi-db.py add-users \u003chomeid\u003e,\u003cid2\u003e,\u003cid3\u003e,... --users alice,bob --yes\n```\n\nCredential files are written to `./databases/users/` by default (override with `NEO4J_DATABASES_DIR` or `NEO4J_CREDS_DIR`).\n\n## Integration test\n\n```bash\n./test-lifecycle.sh              # uses test.dump\n./test-lifecycle.sh mydata.dump  # custom dump file\n```\n\nRuns the full lifecycle: list → add-db --users → parallel user additions (ro-only, ro+rw, multi-db) → list → upload → query as ro user → delete-db → list.\n\nThe three `add-users` steps (single-db ro, single-db ro+rw, multi-db across two databases) run in parallel to keep total test time down.\n\n## Requirements\n\n- Python 3.9+\n- Neo4j Aura Business Critical instance with multi-database enabled\n- Aura API key (v1beta6)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjexp%2Faura-multi-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjexp%2Faura-multi-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjexp%2Faura-multi-db/lists"}