Simplifying TIMESTAMP Queries with `?_loc=UTC`
Nobody has claimed this yet.
- Dominant language
- C
- Stars
- 9.2k
- Forks
- 1.2k
- Avg merge
- 19m
- Merged PRs (30d)
- 4
Description
First and foremost, thank you for the excellent go-sqlite3 package! I use it frequently in my projects and truly appreciate the effort you've put into it. I have a quick suggestion I'd like to propose and would be interested to know if it makes sense.
As we know, storing and querying time.Time values in SQLite3 can be challenging. To make this easier, I've adopted a two-step approach. First, I enforce that every TIMESTAMP column stores only UTC timestamps.
I accomplish this using a CHECK constraint:
CREATE TABLE users(created TIMESTAMP CHECK(created LIKE concat(datetime(created), '%')));
This constraint ensures that only valid UTC timestamps are stored, as shown below:
sqlite> INSERT INTO users(created) VALUES('2025-07-27 03:37:44.556599+09:00');
Runtime error: CHECK constraint failed: created LIKE concat(datetime(created), '%') (19)
sqlite> INSERT INTO users(created) VALUES('2025-07-26 18:54:54.318724+00:00');
sqlite>
With this in place, we can safely assume that every TIMESTAMP field in our database is in the UTC timezone.
Second, when I query with time.Time values, I also have to ensure that they are in UTC. Currently, I have two options:
var start, end time.Time
// Option 1:
db.QueryContext(ctx, `SELECT * FROM users WHERE created >= datetime(?) AND created < datetime(?)`, start, end)
// Option 2:
db.QueryContext(ctx, `SELECT * FROM users WHERE created >= ? AND created < ?`, start.UTC(), end.UTC())
Unfortunately, neither of these options is ideal because it's easy to forget to call datetime() or .UTC(). I am hoping for a more automatic solution.
I noticed the ?_loc=UTC parameter for the Go sqlite3 driver, which at first glance seemed promising. As you know, however, it is currently only used for retrieving timestamp values from the database. I would like to propose extending this parameter to also automatically convert time.Time values to UTC when they are used in a query with created >= ?.
This change would significantly simplify the process and reduce the potential for errors. What are your thoughts on this suggestion?
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing how the _loc=UTC parameter is handled for timestamp retrieval and how time.Time values are bound in query parameters. Determine the intended behavior for UTC conversion in comparisons, then add focused coverage showing that queries using time.Time values behave correctly when _loc=UTC is enabled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, sqlite
- Domain
- database
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100