Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/msolli/proletarian/llms.txt

Use this file to discover all available pages before exploring further.

The JobIdStrategy protocol decouples job ID generation from the core Proletarian machinery, allowing you to adapt ID handling to your database backend and schema. It covers three concerns: generating a new ID when a job is enqueued, encoding that ID for the database column type used in your schema (e.g. UUID, BINARY(16), BIGSERIAL), and decoding the raw database value back into the application representation. Namespace: proletarian.protocols

​
Protocol Definition

(defprotocol JobIdStrategy
  "Strategy for generating and handling job IDs. Supports both app-generated
   IDs (like UUID, ULID) and database-generated IDs (like BIGSERIAL)."
  (generate-id [_]
    "Generate a new job ID for enqueueing. Returns nil if the database should
     generate the ID (e.g., BIGSERIAL). Returns a value (e.g., UUID) if the
     application generates the ID.")
  (encode-id [_ job-id]
    "Encode the job ID for database storage. For app-generated IDs, this may
     transform the ID for the specific database. For DB-generated IDs, this
     receives nil and returns nil.")
  (decode-id [_ job-id]
    "Decode the job ID after reading from the database. Transforms the database
     representation back to the application representation."))

​
Methods

​
generate-id
function
Called by proletarian.job/enqueue! before the INSERT statement is executed.
  • Arguments: _ (the strategy instance)
  • Returns: a new job ID (e.g. a java.util.UUID), or nil if the database should generate the ID (e.g. BIGSERIAL / AUTO_INCREMENT)
​
encode-id
function
Called to prepare the job ID for use as a JDBC parameter in INSERT, UPDATE, DELETE, and SELECT statements.
  • Arguments: _ (the strategy instance), job-id (the value returned by generate-id, or nil for DB-generated strategies)
  • Returns: the encoded value suitable for PreparedStatement.setObject — e.g. a java.util.UUID for PostgreSQL, or a byte[] for MySQL
​
decode-id
function
Called after reading a job ID from the database ResultSet.
  • Arguments: _ (the strategy instance), job-id (the raw JDBC value)
  • Returns: the application-level ID value — e.g. a java.util.UUID

​
Built-in Strategies

Two production-ready strategies ship with Proletarian in the proletarian.job-id-strategies namespace:

​
->postgresql-uuid-strategy (default)

(proletarian.job-id-strategies/->postgresql-uuid-strategy)
Generates a random java.util.UUID via UUID/randomUUID. Passes the UUID directly to PostgreSQL’s native UUID column type — no binary encoding needed. This is the default strategy used by both enqueue! and create-queue-worker.

​
->mysql-uuid-strategy

(proletarian.job-id-strategies/->mysql-uuid-strategy)
Generates a random java.util.UUID and encodes it as a 16-byte BINARY(16) value for storage in MySQL. Decodes the byte[] back to a UUID when reading from the database.

​
->db-generated-strategy

(proletarian.job-id-strategies/->db-generated-strategy)
Signals that the database is responsible for generating the job ID (e.g. a BIGSERIAL or AUTO_INCREMENT column). generate-id returns nil; the database assigns the ID on insert.

​
Using the MySQL Strategy

(require '[proletarian.job-id-strategies :as job-id-strategies]
         '[proletarian.job :as job]
         '[proletarian.worker :as worker])

(def mysql-strategy (job-id-strategies/->mysql-uuid-strategy))

;; Must be set on BOTH enqueue! and create-queue-worker
(job/enqueue! conn :myapp/process-order {:order-id 99}
              :proletarian/job-id-strategy mysql-strategy)

(def queue-worker
  (worker/create-queue-worker datasource handle-job
    {:proletarian/job-id-strategy mysql-strategy}))

​
Implementing a Custom Strategy

​
Database-generated BIGSERIAL IDs

For schemas that use BIGSERIAL (PostgreSQL) or AUTO_INCREMENT (MySQL), generate-id should return nil to instruct Proletarian to omit the job_id column from the INSERT, letting the database assign it: 
(require '[proletarian.protocols :as p])

(defn create-bigserial-strategy []
  (reify p/JobIdStrategy
    (generate-id [_]
      ;; nil signals "let the database generate this"
      nil)
    (encode-id [_ job-id]
      ;; job-id is nil on INSERT; a Long on UPDATE/DELETE/SELECT
      job-id)
    (decode-id [_ job-id]
      ;; The database returns a Long for BIGSERIAL
      job-id)))

​
Application-generated ULID IDs

(require '[proletarian.protocols :as p])
;; Assuming a ULID library is available

(defn create-ulid-strategy []
  (reify p/JobIdStrategy
    (generate-id [_]
      (generate-ulid))          ; returns a ULID string
    (encode-id [_ job-id]
      job-id)                   ; store as TEXT in PostgreSQL
    (decode-id [_ job-id]
      job-id)))                 ; read back as-is
The JobIdStrategy must be identical (in terms of encode/decode behaviour) on both the enqueue! side and the create-queue-worker side. Proletarian does not store metadata about which strategy was used per job — a mismatched strategy will cause ID decode errors and job lookup failures at processing time.

​
generate-id Returning nil

When generate-id returns nil, Proletarian’s db/enqueue! function passes nil to encode-id and uses the result as the job_id parameter in the PreparedStatement. Your database schema must have job_id configured with a default-generating expression (e.g. DEFAULT gen_random_uuid(), BIGSERIAL, or AUTO_INCREMENT) for this to work correctly. The enqueue! public function will return nil as the job-id in this case.

Build docs developers (and LLMs) love

Get started for freeTalk to us