{"id":31322784,"url":"https://github.com/annie444/pgaapi","last_synced_at":"2026-05-18T04:35:40.444Z","repository":{"id":313487934,"uuid":"1051591864","full_name":"annie444/pgaapi","owner":"annie444","description":"A script‑friendly alternative to PGTune for generating sensible postgresql.conf settings","archived":false,"fork":false,"pushed_at":"2025-09-06T12:17:00.000Z","size":356,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T12:28:18.256Z","etag":null,"topics":["api","astro","config","postgres"],"latest_commit_sha":null,"homepage":"https://pgconfig.com","language":"Astro","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/annie444.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T10:14:46.000Z","updated_at":"2025-09-06T12:17:57.000Z","dependencies_parsed_at":"2025-09-06T12:28:20.141Z","dependency_job_id":"76fa10fe-073c-4ce3-9909-69fb21fd3372","html_url":"https://github.com/annie444/pgaapi","commit_stats":null,"previous_names":["annie444/pgaapi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/annie444/pgaapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annie444%2Fpgaapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annie444%2Fpgaapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annie444%2Fpgaapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annie444%2Fpgaapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/annie444","download_url":"https://codeload.github.com/annie444/pgaapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/annie444%2Fpgaapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276966735,"owners_count":25736855,"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","status":"online","status_checked_at":"2025-09-25T02:00:09.612Z","response_time":80,"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":["api","astro","config","postgres"],"created_at":"2025-09-25T19:14:29.601Z","updated_at":"2025-09-25T19:14:34.649Z","avatar_url":"https://github.com/annie444.png","language":"Astro","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostgreSQL Configuration API\n\n### A script‑friendly alternative to PGTune for generating sensible postgresql.conf settings\n\n[pgconfig.com](https://pgconfig.com) provides a deterministic REST API that recommends PostgreSQL configuration settings based on basic server characteristics. Instead of filling out a form or downloading a binary, you can call a single HTTP endpoint from your CI/CD pipeline, provisioning scripts or one‑liner and get human‑vetted defaults back as JSON.\n\nThe service returns exactly the same output for the same input, has no external dependencies and exposes only a single GET endpoint. It can be used directly with tools like curl, wget, Ansible, cloud‑init or Terraform.\n\n---\n\n## Features:\n\n- Deterministic – same inputs always produce the same recommendations, making the output easy to diff and commit .\n- Zero dependencies – no SDK or CLI to install; just call the endpoint with your server profile .\n- Human‑vetted defaults – sensible, conservative settings that are unlikely to surprise your cluster .\n- CI/CD friendly – built for automation; suitable for Ansible, cloud‑init, Terraform, or simple shell scripts .\n\n## Quickstart\n\nTo get recommendations you supply a few key parameters in a query string. At minimum you need to specify the operating system, total RAM, CPU count, storage type, workload type, number of disks, and projected database size. Optional parameters allow you to target a specific PostgreSQL version, customise max_connections, indicate the backup method, and include the number of replicas.\n\nHere’s a basic call for a web application running on a Linux host with 32 GB RAM and 8 CPUs on SSD storage:\n\n```shell\ncurl -sS \"https://pgconfig.com/api/v1/tune?\\\n  memory_gb=32\u0026cpus=8\u0026storage_type=ssd\u0026workload=webapp\u0026\\\n  num_disks=1\u0026num_replicas=0\u0026db_size_gb=1\u0026version=17\u0026os=linux\u0026\\\n  backup_method=pg_dump\"\n```\n\nThe response is JSON containing a config object with recommended settings and, optionally, a warnings array. Each value is formatted for direct inclusion in postgresql.conf.\n\n## Example response\n\n```json\n{\n  \"config\": {\n    \"checkpoint_timeout\": \"15min\",\n    \"checkpoint_completion_target\": 0.9,\n    \"wal_compression\": \"on\",\n    \"wal_buffers\": -1,\n    \"wal_writer_delay\": \"200ms\",\n    \"wal_writer_flush_after\": \"1MB\",\n    \"shared_preload_libraries\": \"'pg_stat_statements'\",\n    \"track_io_timing\": \"on\",\n    \"track_functions\": \"pl\",\n    \"max_worker_processes\": 8,\n    \"max_parallel_workers_per_gather\": 2,\n    \"max_parallel_workers\": 8,\n    \"bgwriter_delay\": \"200ms\",\n    \"bgwriter_lru_maxpages\": 100,\n    \"bgwriter_lru_multiplier\": 2.0,\n    \"bgwriter_flush_after\": 0,\n    \"enable_partitionwise_join\": \"on\",\n    \"enable_partitionwise_aggregate\": \"on\",\n    \"jit\": \"on\",\n    \"track_wal_io_timing\": \"on\",\n    \"wal_recycle\": \"on\",\n    \"max_slot_wal_keep_size\": \"1GB\",\n    \"archive_mode\": \"on\",\n    \"archive_command\": \"/bin/true\",\n    \"min_wal_size\": \"1GB\",\n    \"max_wal_size\": \"4GB\",\n    \"max_parallel_maintenance_workers\": 2,\n    \"wal_level\": \"minimal\",\n    \"max_wal_senders\": 0,\n    \"max_connections\": 100,\n    \"superuser_reserved_connections\": 3,\n    \"shared_buffers\": \"1GB\",\n    \"effective_cache_size\": \"3GB\",\n    \"maintenance_work_mem\": \"256MB\",\n    \"huge_pages\": \"try\",\n    \"default_statistics_target\": 100,\n    \"random_page_cost\": 1.1,\n    \"wal_keep_size\": \"3GB\",\n    \"effective_io_concurrency\": 200,\n    \"work_mem\": \"16MB\"\n  },\n  \"warnings\": [\n    \"WARNING this tool not being optimal for very high memory systems\"\n  ]\n}\n```\n\n## API Endpoint\n\nThe API exposes a single GET endpoint:\n\n```shell\nGET https://pgconfig.com/api/v1/tune\n```\n\nYou pass tuning parameters as query strings. If a required parameter is missing or invalid the service returns 400 Bad Request with an error message; unexpected failures return 500 Server Error.\n\n## Query parameters\n\n| Parameter     | Type   | Required | Description                                               |\n| ------------- | ------ | -------- | --------------------------------------------------------- |\n| version       | number | No       | PostgreSQL major version (default 17)                     |\n| os            | enum   | Yes      | linux, macos or windows                                   |\n| memory_gb     | number | Yes      | Total RAM in GB (e.g. 32)                                 |\n| cpus          | number | Yes      | Logical CPU count (e.g. 8)                                |\n| storage_type  | enum   | Yes      | hdd, ssd or network                                       |\n| workload      | enum   | Yes      | One of webapp, oltp, warehouse, desktop or mixed          |\n| max_conn      | number | No       | Target max_connections (derived automatically if omitted) |\n| num_disks     | number | Yes      | Number of disks in the cluster                            |\n| backup_method | enum   | No       | pg_dump, pg_basebackup or pglogical (defaults to pg_dump) |\n| num_replicas  | number | No       | Number of active replicas                                 |\n| db_size_gb    | number | Yes      | Projected database size in GB (e.g. 100)                  |\n\nAll values should be URL encoded. Omitted optional parameters fall back to sensible defaults derived from the other inputs.\n\n## Responses and errors\n\nThe service returns JSON with two top‑level keys:\n\n- config: an object whose keys correspond to postgresql.conf settings and whose values are strings or numbers formatted for direct inclusion .\n- warnings: an array of strings containing non‑fatal warnings, or omitted if there are none .\n\n## HTTP status codes:\n\n| Status           | Description                                                   |\n| ---------------- | ------------------------------------------------------------- |\n| 200 OK           | Request succeeded; returns recommended settings               |\n| 400 Bad Request  | Missing or invalid parameters; returns { \"error\": \"message\" } |\n| 500 Server Error | Unexpected failure; retry or report                           |\n\n## Examples\n\nHere are some sample invocations:\n\n- OLTP workload on SSD (32 GB RAM, 8 vCPU)\n\n```shell\ncurl -sS \"https://pgconfig.com/api/v1/tune?\\\n  memory_gb=32\u0026cpus=8\u0026storage_type=ssd\u0026workload=oltp\u0026\\\n  num_disks=1\u0026num_replicas=0\u0026db_size_gb=1\u0026version=17\u0026os=linux\u0026\\\n  backup_method=pg_dump\"\n```\n\n- Ansible snippet – fetch recommended settings and write a configuration file:\n\n```yaml\n- name: Fetch PG tuning\n  ansible.builtin.uri:\n    url: \"https://pgconfig.com/api/v1/tune?\\\n      memory_gb={{ ansible_memory_mb.real.total / 1024 }}\u0026\\\n      cpus={{ ansible_processor_vcpus }}\u0026\\\n      storage_type=ssd\u0026\\\n      workload={{ profile }}\u0026\\\n      num_disks={{ ansible_devices.keys() - 1 }}\u0026\\\n      num_replicas=2\u0026\\\n      db_size_gb=100\u0026\\\n      version=17\u0026os=linux\u0026\\\n      backup_method=pg_basebackup\"\n    method: GET\n    return_content: yes\n  register: pg_tune\n\n- name: Write postgresql.conf overrides\n  ansible.builtin.copy:\n    dest: /etc/postgresql/postgresql.conf\n    content: |\n      {% for setting in pg_tune.json | ansible.builtin.dict2items %}\n      {{ setting.key }} = {{ setting.value }}\n      {% endfor %}\n```\n\n---\n\n### Developing \u0026 contributing\n\nThis API is released under the MIT License. Pull requests and bug reports are welcome. If you’d like to contribute—whether by improving the tuning rules, adding new parameters, or enhancing the documentation—please open an issue or a PR on the upstream repository.\n\nFor local development or self‑hosting, consult the [astro.js](https://docs.astro.build/en/getting-started/) repository for build instructions. The project is written in TypeScript with `pnpm`.\n\n### Quickstart\n\n```shell\ngit clone git@github.com:annie444/pgapi.git\ncd pgapi\npnpm i\npnpm dev\n```\n\n---\n\n### License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannie444%2Fpgaapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fannie444%2Fpgaapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fannie444%2Fpgaapi/lists"}