{"id":46597440,"url":"https://github.com/bluedynamics/zodb-pgjsonb-thumborblobloader","last_synced_at":"2026-03-07T15:01:27.046Z","repository":{"id":341584758,"uuid":"1170088351","full_name":"bluedynamics/zodb-pgjsonb-thumborblobloader","owner":"bluedynamics","description":"Thumbor 7.x image loader that reads blob data directly from the zodb-pgjsonb `blob_state` PostgreSQL table. No ZODB runtime needed — just SQL + optional S3.","archived":false,"fork":false,"pushed_at":"2026-03-02T12:49:10.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-02T16:37:38.066Z","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/bluedynamics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","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-01T17:24:22.000Z","updated_at":"2026-03-02T12:49:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bluedynamics/zodb-pgjsonb-thumborblobloader","commit_stats":null,"previous_names":["bluedynamics/zodb-pgjsonb-thumborblobloader"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bluedynamics/zodb-pgjsonb-thumborblobloader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fzodb-pgjsonb-thumborblobloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fzodb-pgjsonb-thumborblobloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fzodb-pgjsonb-thumborblobloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fzodb-pgjsonb-thumborblobloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluedynamics","download_url":"https://codeload.github.com/bluedynamics/zodb-pgjsonb-thumborblobloader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fzodb-pgjsonb-thumborblobloader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30219250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T14:02:48.375Z","status":"ssl_error","status_checked_at":"2026-03-07T14:02:43.192Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-03-07T15:01:26.425Z","updated_at":"2026-03-07T15:01:27.029Z","avatar_url":"https://github.com/bluedynamics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zodb-pgjsonb-thumborblobloader\n\nThumbor 7.x image loader that reads blob data directly from the [zodb-pgjsonb](https://github.com/bluedynamics/zodb-pgjsonb) `blob_state` PostgreSQL table.\n\n## Overview\n\nThis loader enables [Thumbor](https://www.thumbor.org/) to serve images stored as ZODB blobs in a `zodb-pgjsonb` PostgreSQL database -- without requiring a running ZODB/Zope instance. It supports:\n\n- **Two-tier storage**: PostgreSQL bytea (preferred) with optional S3 fallback\n- **Async connection pool**: psycopg3 `AsyncConnectionPool` for high concurrency\n- **Disk cache**: LRU-evicted local cache with deterministic filenames\n- **URL-based lookup**: `\u003czoid_hex\u003e/\u003ctid_hex\u003e` addressing for exact blob versions\n\n## Installation\n\n```bash\npip install zodb-pgjsonb-thumborblobloader\n\n# With S3 fallback support\npip install zodb-pgjsonb-thumborblobloader[s3]\n```\n\n## Configuration\n\nIn your `thumbor.conf`:\n\n```python\nLOADER = 'zodb_pgjsonb_thumborblobloader.loader'\n\n# Required\nPGTHUMBOR_DSN = 'dbname=zodb user=zodb password=zodb host=localhost port=5432'\n\n# Connection pool (optional)\nPGTHUMBOR_POOL_MIN_SIZE = 1\nPGTHUMBOR_POOL_MAX_SIZE = 10\n\n# Disk cache (optional)\nPGTHUMBOR_CACHE_DIR = '/var/cache/thumbor/blobs'\nPGTHUMBOR_CACHE_MAX_SIZE = 1073741824  # 1 GB\n\n# S3 fallback (optional, requires [s3] extra)\nPGTHUMBOR_S3_BUCKET = 'my-blob-bucket'\nPGTHUMBOR_S3_REGION = 'eu-central-1'\nPGTHUMBOR_S3_ENDPOINT = 'https://s3.example.com'  # for MinIO/Ceph\n```\n\n## URL Scheme\n\n```\nhttp://thumbor:8888/\u003csigning\u003e/\u003ctransforms\u003e/\u003czoid_hex\u003e/\u003ctid_hex\u003e\n```\n\nBoth `zoid_hex` and `tid_hex` are required. The loader fetches the exact blob version identified by the OID/TID pair.\n\n## How It Works\n\n```\nThumbor request\n  └-\u003e loader.load(context, path)\n       ├-\u003e disk cache hit?  → return cached bytes\n       ├-\u003e PostgreSQL query → blob_state.data (bytea)\n       ├-\u003e S3 fallback      → blob_state.s3_key → boto3 download\n       └-\u003e cache on disk    → LRU eviction by atime\n```\n\nThe `blob_state` table is owned and managed by [zodb-pgjsonb](https://github.com/bluedynamics/zodb-pgjsonb) -- this loader only reads from it.\n\n## Docker Image\n\nA pre-built OCI image is available on GHCR:\n\n```bash\ndocker pull ghcr.io/bluedynamics/zodb-pgjsonb-thumborblobloader:latest\n```\n\nPlatforms: `linux/amd64`, `linux/arm64`\n\n### Image tags\n\n- `thumbor-\u003cTHUMBOR_VERSION\u003e_loader-\u003cLOADER_VERSION\u003e` -- versioned (e.g. `thumbor-7.7.7_loader-0.3.0`)\n- `latest` -- always the newest build\n\nThe image is automatically rebuilt weekly when a new Thumbor version appears on PyPI.\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PGTHUMBOR_DSN` | `\"\"` | PostgreSQL connection string (required) |\n| `THUMBOR_SECURITY_KEY` | `\"CHANGE-ME\"` | Thumbor HMAC security key |\n| `ALLOW_UNSAFE_URL` | `\"False\"` | Allow unsigned URLs |\n| `RESULT_STORAGE_PATH` | `/tmp/thumbor/result_storage` | Result cache directory |\n| `PGTHUMBOR_POOL_MIN_SIZE` | `1` | Min DB pool connections |\n| `PGTHUMBOR_POOL_MAX_SIZE` | `4` | Max DB pool connections |\n| `PGTHUMBOR_CACHE_DIR` | `\"\"` | Local blob cache directory (empty = disabled) |\n| `PGTHUMBOR_CACHE_MAX_SIZE` | `0` | Max cache size in bytes (0 = disabled) |\n| `PGTHUMBOR_S3_BUCKET` | `\"\"` | S3 bucket for blob fallback (empty = disabled) |\n| `PGTHUMBOR_S3_REGION` | `us-east-1` | S3 region |\n| `PGTHUMBOR_S3_ENDPOINT` | `\"\"` | S3 endpoint for MinIO/Ceph (empty = AWS) |\n| `PGTHUMBOR_PLONE_AUTH_URL` | `\"\"` | Plone internal URL for auth (empty = disabled) |\n| `PGTHUMBOR_AUTH_CACHE_TTL` | `60` | Auth cache TTL in seconds |\n| `PGTHUMBOR_CACHE_CONTROL_AUTHENTICATED` | `private, max-age=86400` | Cache-Control for authenticated images (browser-only, no proxy caching) |\n| `PGTHUMBOR_CACHE_CONTROL_PUBLIC` | `\"\"` | Cache-Control for public images (empty = Thumbor default) |\n\nThe Plone auth handler (and Cache-Control overrides) is only loaded when `PGTHUMBOR_PLONE_AUTH_URL` is set.\n\n### Quick start\n\n```bash\ndocker run --rm -p 8888:8888 \\\n  -e PGTHUMBOR_DSN=\"dbname=zodb user=zodb password=zodb host=localhost\" \\\n  -e THUMBOR_SECURITY_KEY=\"my-secret\" \\\n  ghcr.io/bluedynamics/zodb-pgjsonb-thumborblobloader:latest\n\n# Healthcheck\ncurl http://localhost:8888/healthcheck\n```\n\n## Development\n\n```bash\ncd sources/zodb-pgjsonb-thumborblobloader\nuv pip install -e \".[test,s3]\"\n\n# Run tests (requires PostgreSQL on localhost:5433)\npytest\n```\n\n## Documentation\n\nThis package is documented together with [plone-pgthumbor](https://github.com/bluedynamics/plone-pgthumbor):\n**https://bluedynamics.github.io/plone-pgthumbor/**\n\n- [Architecture](https://github.com/bluedynamics/plone-pgthumbor/blob/main/docs/sources/explanation/architecture.md) -- request flow, loader integration\n- [Configuration Reference](https://github.com/bluedynamics/plone-pgthumbor/blob/main/docs/sources/reference/configuration.md) -- all thumbor.conf settings\n\n## Source Code and Contributions\n\nThe source code is managed in a Git repository, with its main branches hosted on GitHub.\nIssues can be reported there too.\n\nWe'd be happy to see many forks and pull requests to make this package even better.\nWe welcome AI-assisted contributions, but expect every contributor to fully understand and be able to explain the code they submit.\nPlease don't send bulk auto-generated pull requests.\n\nMaintainers are Jens Klein and the BlueDynamics Alliance developer team.\nWe appreciate any contribution and if a release on PyPI is needed, please just contact one of us.\nWe also offer commercial support if any training, coaching, integration or adaptations are needed.\n\n## License\n\nZPL-2.1 (Zope Public License)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluedynamics%2Fzodb-pgjsonb-thumborblobloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluedynamics%2Fzodb-pgjsonb-thumborblobloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluedynamics%2Fzodb-pgjsonb-thumborblobloader/lists"}