{"id":31137168,"url":"https://github.com/ringsaturn/pg-tzf","last_synced_at":"2026-01-18T02:35:38.622Z","repository":{"id":291204989,"uuid":"976928249","full_name":"ringsaturn/pg-tzf","owner":"ringsaturn","description":"Fast PG extension to lookup timezone name by GPS coordinates ","archived":false,"fork":false,"pushed_at":"2026-01-17T09:03:05.000Z","size":140,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-17T20:19:32.292Z","etag":null,"topics":["postgresql-extension","timezone","timezone-library","tzf"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/ringsaturn.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-05-03T03:13:00.000Z","updated_at":"2026-01-17T09:02:12.000Z","dependencies_parsed_at":"2025-05-03T04:23:50.228Z","dependency_job_id":"12d2b182-b634-4227-825a-17da78508cdc","html_url":"https://github.com/ringsaturn/pg-tzf","commit_stats":null,"previous_names":["ringsaturn/tzf-pg","ringsaturn/pg-tzf"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ringsaturn/pg-tzf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Fpg-tzf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Fpg-tzf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Fpg-tzf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Fpg-tzf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ringsaturn","download_url":"https://codeload.github.com/ringsaturn/pg-tzf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringsaturn%2Fpg-tzf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"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":["postgresql-extension","timezone","timezone-library","tzf"],"created_at":"2025-09-18T08:15:38.656Z","updated_at":"2026-01-18T02:35:38.609Z","avatar_url":"https://github.com/ringsaturn.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tzf-rs' PG extension.\n\n## Installation from source\n\n### Prerequisites\n\n- Rust\n- Cargo\n- PostgreSQL development headers (version 14, 14, 15, 16, 17, 18)\n- [cargo-pgrx](https://github.com/pgcentralfoundation/pgrx), version should be\n  same as [`Cargo.toml`](Cargo.toml)\n\n### Installing cargo-pgrx\n\n```bash\n# Please see [Cargo.toml](Cargo.toml) for the version of cargo-pgrx.\ncargo install cargo-pgrx --version={version}\n\n# Please note that you may need to init for your real PostgreSQL version.\n# For example, if you are using PostgreSQL 15 on macOS and install it via Homebrew:\n# you may need to run `cargo pgrx init --pg15 \"$(brew --prefix postgresql@15)/bin/pg_config\"`.\ncargo pgrx init\n```\n\n### Build and install\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/ringsaturn/pg-tzf.git\n   cd pg-tzf\n   ```\n2. Build and install the extension:\n   ```bash\n   cargo pgrx install\n   ```\n3. Use in PostgreSQL:\n   ```sql\n   -- If you install old version of extension, you can drop it and install the new one.\n   -- DROP EXTENSION tzf CASCADE;\n   CREATE EXTENSION tzf;\n   ```\n\n## Installation from pre-built package\n\nPlease see [releases](https://github.com/ringsaturn/pg-tzf/releases) for the\npre-built packages.\n\nThe artifact is a tarball containing the following files:\n\n```\ntzf.so\ntzf.control\ntzf--{{ version }}.sql\n```\n\n## Usage\n\nA full schema is available at [`sql/tzf.sql`](sql/tzf.sql).\n\nThe extension provides functions to find timezone names for given coordinates:\n\n- Look up timezone for a coordinate (longitude, latitude):\n\n  ```sql\n  -- examples/query_a_coord.sql\n  SELECT tzf_tzname(116.3883, 39.9289) AS timezone;\n  ```\n\n  Output:\n\n  ```console\n     timezone\n  ---------------\n  Asia/Shanghai\n  (1 row)\n  ```\n\n- Look up timezone for a batch of coordinates(we use `unnest` to unroll the\n  array):\n\n  ```sql\n  -- examples/query_a_batch_coords.sql\n  SELECT unnest(\n     tzf_tzname_batch(\n        ARRAY[-74.0060, -118.2437, 139.6917],\n        ARRAY[40.7128, 34.0522, 35.6895]\n     )\n  ) AS timezones;\n  ```\n\n  Output:\n\n  ```console\n        timezone\n  ---------------------\n  America/New_York\n  America/Los_Angeles\n  Asia/Tokyo\n  (3 rows)\n  ```\n\n- Look up timezone for a point:\n\n  ```sql\n  -- examples/query_a_point.sql\n  SELECT tzf_tzname_point(point(-74.0060, 40.7128)) AS timezone;\n  ```\n\n  Output:\n\n  ```console\n     timezone\n  ------------------\n  America/New_York\n  (1 row)\n  ```\n\n- Look up timezone for a batch of points:\n\n  ```sql\n  -- examples/query_a_batch_points.sql\n  SELECT unnest(\n     tzf_tzname_batch_points(\n        ARRAY[\n              point(-74.0060, 40.7128),\n              point(-118.2437, 34.0522),\n              point(139.6917, 35.6895)\n        ]\n     )\n  ) AS timezones;\n  ```\n\n  Output:\n\n  ```console\n        timezones\n  ---------------------\n  America/New_York\n  America/Los_Angeles\n  Asia/Tokyo\n  (3 rows)\n  ```\n\nYou can see my blog post\n[Group world cities by timezone](https://blog.ringsaturn.me/en/posts/2025-05-04-world-city-group-by-timezone/)\nfor a more large scale usage of this extension.\n\n## Performance\n\nRuns under highly competitive CPU environment in GitHub Actions Runner:\n\n```console\nCREATE EXTENSION\nTesting tzf_tzname function:\nnumber of clients: 10\nnumber of threads: 1\nnumber of transactions actually processed: 177004\nlatency average = 0.564 ms\ntps = 17726.775670 (without initial connection time)\nTesting tzf_tzname_point function:\nnumber of clients: 10\nnumber of threads: 1\nnumber of transactions actually processed: 176147\nlatency average = 0.567 ms\ntps = 17629.349990 (without initial connection time)\nTesting tzf_tzname_batch function:\nnumber of clients: 10\nnumber of threads: 1\nnumber of transactions actually processed: 569\nlatency average = 193.407 ms\ntps = 51.704527 (without initial connection time)\nTesting tzf_tzname_batch_points function:\nnumber of clients: 10\nnumber of threads: 1\nnumber of transactions actually processed: 360\nlatency average = 313.814 ms\ntps = 31.866004 (without initial connection time)\n```\n\n| func                    | tps          | note                                   |\n| ----------------------- | ------------ | -------------------------------------- |\n| tzf_tzname              | 17726.775670 |                                        |\n| tzf_tzname_point        | 17629.349990 |                                        |\n| tzf_tzname_batch        | 51.704527    | batch size is 1000, means 51\\*1000 TPS |\n| tzf_tzname_batch_points | 31.866004    | batch size is 1000, means 31\\*1000 TPS |\n\nPlease note that the result is under highly competitive CPU environment, so in\nreal production environment, the result may be better.\n\n## LICENSE\n\n- This project is licensed under the MIT License. See the [LICENSE](LICENSE)\n  file for details.\n- The timezone data is licensed under the ODbL. See the\n  [LICENSE_DATA](LICENSE_DATA) file for details.\n  - Data source: \u003chttps://github.com/evansiroky/timezone-boundary-builder\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringsaturn%2Fpg-tzf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringsaturn%2Fpg-tzf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringsaturn%2Fpg-tzf/lists"}