ukue.com

A Job Queue in One SQLite File: ukue 0.1 Lets Small Teams Skip Redis

Tue, 06 Oct 2026 00:00:00 +0000

Sooner or later every web app needs to do something outside the request. Send the welcome email after the user has seen the page. Resize the photo while they carry on. Retry the webhook when the other side is down. The standard way to do that is a job queue, and the standard way to get a job queue is to run Redis or RabbitMQ next to your app.

ukue 0.1 puts the whole queue in one file instead. It’s a SQLite database with a documented layout, and it holds every queue, every waiting job, every retry and every job that failed for good. A Go program imports ukue as a library. Everything else uses the one small ukue binary, which runs a script for each job or serves a small HTTP API.

A Raspberry Pi on a Patchy Connection: Readings Wait in a ukue File Until the Internet Is Back

Tue, 06 Oct 2026 00:00:00 +0000

Think of a market garden with three greenhouses, each with temperature, humidity and soil sensors wired to a Raspberry Pi. Every minute the Pi reads the sensors and sends the numbers to a dashboard in the cloud, where the grower checks them on a phone and gets an alert if a greenhouse overheats. The internet comes from a 4G router on a pole, and it drops out: a few minutes in bad weather, half a day when the mast is down. A script that simply posts each reading loses every minute the connection is gone.

AI Transcription on a Rented GPU: Python Workers Pull Jobs From ukue Over HTTP

Tue, 06 Oct 2026 00:00:00 +0000

Say a small podcast-hosting service wants to offer transcripts. Speech-to-text models are quick on a GPU and painfully slow without one, and the service’s web server is a modest cloud machine with no GPU. So it rents a GPU server by the month from another provider, and needs a way to hand it work: here’s an episode, transcribe it, report back when it’s done. Episodes are long, so one job can take ten minutes. And the GPU server might be restarted, or swapped for a bigger one, at any time.

An Order and Its Receipt Email in One SQLite Transaction With ukue's EnqueueTx

Tue, 06 Oct 2026 00:00:00 +0000

Take a small online shop that runs as a single Go program with its data in SQLite: one file to back up and no database server to look after. When an order comes in, the shop saves it, and a receipt email goes out in the background.

The risk is in the gap between those two steps. If the order is saved and the program crashes before the email job is queued, the customer pays and never gets a receipt. If the job is queued first and saving the order then fails, the customer gets a receipt for an order that doesn’t exist. With a separate queue server, closing that gap takes real work, usually an “outbox” table in the database and a second process that copies its rows into the queue. With ukue, the queue can live inside the shop’s own database, so the order and its job go into the same transaction, and either both are saved or neither is.

Appointment Reminders With ukue: Jobs Scheduled Days Ahead, Deleted When a Booking Moves

Tue, 06 Oct 2026 00:00:00 +0000

Picture a hair salon in London that takes bookings online, weeks ahead, and texts every client a reminder 24 hours before the appointment. No-shows cost it money, so the reminders matter. The obvious way to send them is a cron job that wakes up every few minutes and searches the bookings for appointments about a day away. That works until two runs overlap and a client gets two texts, or the server is down at the wrong moment and an hour of reminders never goes out, or a booking moves and the reminder still names the old time.

Checking 300 Websites Every Night With ukue, Cron and a Shell Script

Tue, 06 Oct 2026 00:00:00 +0000

Say a two-person web agency looks after 300 client websites. Each morning they want to know which sites were down overnight and which TLS certificates are close to expiring, before a client calls about it. Monitoring services do this for a monthly fee per site. The agency already has a Linux server, a text file of domains and a shell script that checks one site, and would rather not add anything bigger than that.

How the ukue Job Queue Was Tested: 250 Killed Workers, 0 Lost Jobs

Tue, 06 Oct 2026 00:00:00 +0000

A job queue makes one promise above all others: a job that was added runs, even if the machine has a bad day. So the most important tests for ukue don’t check the happy path. They kill workers in the middle of their work and look at what’s left.

The tests run on every change to the code, on Linux and macOS, and the recorded output is published with the code in test/results. The numbers below come from the recorded run, on a two-core cloud machine.

Photo Upload Thumbnails With ukue: Previews First, Print Sizes When the CPU Is Free

Tue, 06 Oct 2026 00:00:00 +0000

Take a portfolio site where photographers upload full-size JPEGs after a shoot, a few hundred at a time and 20 or 30 megabytes each. Every photo needs three resized copies: a 400-pixel thumbnail for the gallery grid, a 1600-pixel version for the lightbox, and a 3000-pixel file for print orders. Resizing a big JPEG takes real CPU time, and doing it inside the upload request turns a 300-photo upload into a long wait behind a progress bar that seems stuck.

Signup Emails From a Python Web App, Sent in the Background With ukue

Tue, 06 Oct 2026 00:00:00 +0000

Say a three-person team runs a Flask app where people book cooking classes. Every new account gets a welcome email, and today the app sends it inside the signup request. On a good day that adds a second or two to the page. On a bad day the mail provider is slow or down, the request hangs, and a new customer sees an error on the first thing they ever tried to do on the site.

Webhook Delivery With ukue: A Day of Retries, Then Dead Letters Instead of Lost Events

Tue, 06 Oct 2026 00:00:00 +0000

Say a small company runs an invoicing service written in Go. Its customers want to hear about payments the moment they happen, so the service sends webhooks: an HTTP POST with the event to a URL each customer chooses. Those URLs point at servers the company doesn’t control. They go down for maintenance, get redeployed, hit rate limits and return errors. If the service sends each webhook once, straight from the code that records the payment, every one of those hiccups loses an event, and the customer finds out weeks later when their books don’t add up.

What Is a Job Queue? Background Jobs, Retries and Dead Letters Explained

Tue, 06 Oct 2026 00:00:00 +0000

A job queue is a to-do list for software. When something has to happen but doesn’t have to happen right now, a program writes it on the list and moves on. A separate worker takes items off the list and does them. That’s the whole idea, and almost every web app ends up needing it.

Take a sign-up form. When a user signs up, the app has to save the account, send a welcome email, and maybe tell the sales team’s CRM. Saving the account is quick. Talking to a mail server can take seconds, and it might be down. Making the user stare at a spinner while that happens is a poor trade, so the app saves the account, adds “send a welcome email to Dana” to a job queue, and shows the next page at once. A worker sends the email a moment later.

Why u Stands for Micro: How the ukue Job Queue Got Its Name

Tue, 06 Oct 2026 00:00:00 +0000

ukue is meant to be read as µkue, a micro queue. Plenty of people will say “you-queue” instead, and that’s fine. The u is a stand-in for the real sign of micro, the Greek letter μ, and the story of how one turned into the other is older than computers.

Micro comes from the Greek mikrós, “small”, and in Greek that word starts with μ, their letter m. When the metric system gave its prefixes one-letter symbols, the Latin m was already taken by milli, a thousandth. So micro, a millionth, got the Greek m. That’s why a microsecond is written µs and a microfarad µF.

About

Mon, 01 Jan 0001 00:00:00 +0000

ukue.com is the home of ukue, read µkue, a micro queue: a job queue that lives in one file. It keeps background jobs, their retries, their start times and the jobs that failed for good in a single SQLite file. A program can embed it as a library, or run the one small ukue binary when other programs, in any language, need the same queue.

Why It Exists

Most apps reach the point where some work has to happen later, or somewhere other than the web request: a welcome email, a resized photo, a webhook that must get through even if the other side is down for an hour. The usual answer is a queue server such as Redis or RabbitMQ. For a small team that’s one more service to install, secure, watch, back up and pay for, sometimes only to send a few emails. ukue does the same job with nothing running beside the app.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

ukue.com would like to hear from:

Anyone trying ukue out. What worked, what got in the way, and what you used before.
Anyone who found a bug. A job that ran when it shouldn’t have, one that didn’t run, an error you didn’t expect.
Anyone with an idea for something ukue should do, or a language it should have an example for.

Write to info@ukue.com.

Bug reports are also welcome on GitHub. It helps to include what ukue version prints, your operating system, and the steps that show the problem. Please don’t send real customer data: a few made-up jobs that show the same thing are enough.

Download ukue

Mon, 01 Jan 0001 00:00:00 +0000

The ukue command is one file with nothing else to install. Each archive below holds it with its license files. The links always point to the latest release.

System	Download
Linux, x86-64	ukue_linux_amd64.tar.gz
Linux, ARM64	ukue_linux_arm64.tar.gz
macOS, Apple silicon	ukue_darwin_arm64.tar.gz
macOS, Intel	ukue_darwin_amd64.tar.gz
Windows, x86-64	ukue_windows_amd64.zip

Checksums are in SHA256SUMS. Every release is listed on GitHub.

Install

On Linux or macOS:

tar -xzf ukue_linux_amd64.tar.gz
sudo mv ukue /usr/local/bin/
ukue version

The Linux binaries are static, so they run on any distribution. The macOS binaries aren’t signed by Apple, so macOS may block the first run; allow it in System Settings under Privacy & Security, or run xattr -d com.apple.quarantine ukue. On Windows, unzip the archive and put ukue.exe in a folder on your PATH.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

ukue is a job queue that lives in one file. This page takes you from nothing to jobs running in a few minutes, from the command line, from Go, and from any other language.

1. Get the ukue Command

Download the archive for your system from the download page, unpack it and put ukue somewhere on your PATH. Check it works:

ukue version

Go programmers who only want the library can skip this and go to step 4.

The ukue File Format

Mon, 01 Jan 0001 00:00:00 +0000

A ukue file is an SQLite database with two tables in it. Any program that can write SQLite can add jobs to it, and a program that follows the steps on this page can claim and finish them too, alongside the ukue command and the Go package. This is version 1 of the format. The complete description, with every SQL statement, is FORMAT.md on GitHub.

What stays the same. The version is stored in the file. Within version 1, later releases may add indexes, settings and columns with default values, but nothing is removed or renamed, and no column changes meaning. A change that older programs couldn’t handle safely gets a new version number, and ukue refuses to open a file whose version it doesn’t know.

The ukue HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

ukue serve puts a ukue file behind a small JSON API, so programs in any language, and on other machines, can add and run jobs. Go programs can mount the same API in their own HTTP server with the server package.

ukue serve jobs.ukue                              # listens on 127.0.0.1:7660
UKUE_TOKEN=s3cret ukue serve --addr :7660 jobs.ukue

The Basics

JSON in and out. Errors come back as {"error": "..."} with a 4xx or 5xx status.
Token. When the server has a token, from UKUE_TOKEN or --token-file, every request except /v1/health must send Authorization: Bearer <token>. The server won’t listen beyond your own machine without a token, unless you start it with --allow-no-token.
Durations can be a number of seconds, such as 30 or 0.5, or a string such as "90s" or "1h30m".
Times in answers are in UTC, such as "2026-10-06T09:00:00.000Z".
Payloads. A payload that is a JSON string is stored as its text, and any other JSON value is stored as compact JSON. Send binary data as payload_base64. Answers give the payload back as text when it is valid UTF-8, and as payload_base64 otherwise.
Size. A request may be up to 1 MiB, unless the server was started with a different --max-body.
Browsers. Requests that change something are refused when they come from a web page on another site. Without a token, the server also answers only requests addressed to localhost, 127.0.0.1 or ::1, so a web page can’t reach it through a DNS name that points at your machine.

Add a Job

POST /v1/jobs