{"id":19005291,"url":"https://github.com/f3ath/dart-pg-job-queue","last_synced_at":"2026-04-21T11:30:21.529Z","repository":{"id":256335318,"uuid":"851419646","full_name":"f3ath/dart-pg-job-queue","owner":"f3ath","description":"A simple job queue on top of PostgreSQL","archived":false,"fork":false,"pushed_at":"2024-09-17T02:14:36.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-01T19:27:59.672Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","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/f3ath.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-09-03T04:15:32.000Z","updated_at":"2024-09-17T02:14:24.000Z","dependencies_parsed_at":"2024-09-17T05:54:02.985Z","dependency_job_id":null,"html_url":"https://github.com/f3ath/dart-pg-job-queue","commit_stats":null,"previous_names":["f3ath/dart-pg-job-queue"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f3ath%2Fdart-pg-job-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f3ath%2Fdart-pg-job-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f3ath%2Fdart-pg-job-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f3ath%2Fdart-pg-job-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f3ath","download_url":"https://codeload.github.com/f3ath/dart-pg-job-queue/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240027433,"owners_count":19736212,"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","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":"2024-11-08T18:27:00.991Z","updated_at":"2026-04-21T11:30:21.484Z","avatar_url":"https://github.com/f3ath.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pg_job_queue\nA simple job queue on top of PostgreSQL.\n\n## Configuration\nThe only required configuration is the PostgreSQL connection object. The bare minimum configuration would look like this:\n\n```dart\nimport 'package:pg_job_queue/pg_job_queue.dart';\nimport 'package:postgres/postgres.dart';\n\nvoid main() async {\n  /// To run locally, start postgres:\n  /// `docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres`\n  final connection = await Connection.open(\n      Endpoint(\n        host: 'localhost',\n        database: 'postgres',\n        username: 'postgres',\n        password: 'postgres',\n      ),\n      settings: ConnectionSettings(sslMode: SslMode.disable));\n\n  /// Create a new job queue with default settings.\n  final jobs = PgJobQueue(connection);\n\n  /// Initialize the DB tables. This is idempotent.\n  await jobs.init();\n  \n  /// At this point, the job queue is ready to use.\n  \n  /// Close the connection when done.\n  await connection.close();\n}\n```\nThe code above creates a new job queue with default settings. The `init` method creates the necessary tables in the database,\nand is idempotent, so it can be called multiple times without any issues. It is safe to call `init` every time the application starts.\nWhen a new minor version is released, the `init` method is expected to automatically update the database schema to the new version.\n\nBy default, the job queue uses the `jobs` table in the `public` schema. The default queue name is `default`. \nThis configuration can be changed by passing the relevant parameters to the `PgJobQueue` constructor.\n\nThe generated job ids are UUIDs v4. This can be changed by passing a custom `idGenerator` function to the `PgJobQueue` constructor.\n\n## Schedule a job\nTo schedule a job, use the `schedule` method. It returns the id of the job that was scheduled.\nProvide the JSON payload that will be passed to the job handler. You can also provide a custom `queue` if you want to use a different queue.\nEach job may also be assigned a `priority` value. The default priority is `0`. Negative values are allowed. Jobs with higher priority values are executed first.\n\n```dart\nfinal jobId = await jobs.schedule(\n  payload: {'key': 'value'},\n  queue: 'default',\n  priority: 0,\n);\n```\n\nWhen a job is scheduled, it is inserted into the `jobs` table with the status `scheduled`.\n\n## Check the status of a job\nTo check the status of a job, use the `fetch` method. It returns a `Job` object.\n\n```dart\nfinal job = await jobs.fetch(jobId);\nprint(job.status);\n```\n\n## Process jobs\nTo acquire the next job in the queue, use the `acquire` method. It returns a `Job` object.\nYou may provide a custom `queue` to acquire a job from a different queue. \nAnother optional parameter is `worker`, which is an arbitrary string that identifies the worker that is processing the job.\nThe latter is useful for debugging and monitoring purposes.\n\nAfter the processing is done, send the result to the job queue using either the `complete` or `fail` method.\n\n```dart\nfinal job = await jobs.acquire(queue: 'emails', worker: 'worker1');\nprint(job.payload);\nawait jobs.complete(job.id, result: {'key': 'value'});\n```\n\n## Clean up\nTo remove completed jobs from the database, use the `deleteCompleted` method. It removes all completed jobs that are older than the specified duration.\nUse the `deleteFailed` parameter to remove the failed jobs as well. The `limit` can be specified to delete jobs in smaller chunks.\nIt is recommended to run this method periodically for better performance.\n\n```dart\nawait jobs.deleteCompleted(Duration(days: 30), limit: 1000);\n```\n\n## Statistics\nSome basic statistics are available through the `countByQueueByStatus` method. It returns a map with the number of jobs in each queue and status.\n\n```dart\nfinal stats = await jobs.countByQueueByStatus();\nprint(stats);\n```\n\n## Performance considerations\nThe job queue is designed to be simple and efficient. It uses a single database connection and a single transaction for each operation.\nHowever, for larger volumes you may consider:\n- Limiting the number or named queues. Queues sharing the same table affect each other's performance.\n- Using a separate table for each queue. This can be achieved by passing custom `schema` and `table` to the `PgJobQueue` constructor.\n- Using a separate database connection for each queue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff3ath%2Fdart-pg-job-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff3ath%2Fdart-pg-job-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff3ath%2Fdart-pg-job-queue/lists"}