Skip to content

About

Go CLI to bulk-delete (archive) Notion database items, with rate limiting, retries, and parallel workers.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

CleanNotionDatabases

A Go script that deletes (archives) every item of a Notion database.

Notion has no bulk-delete endpoint: each page is archived individually via PATCH /v1/pages/{id} with {"archived": true}. Pages are discovered by paginating POST /v1/databases/{id}/query. Archiving is Notion's form of "deleting" — items can be restored manually from the trash.

Features

  • Respects API limits — a global rate limiter (token bucket) at ~3 req/s shared by all workers.
  • Backoff + Retry-After — handles 429/529 by honoring the Retry-After header, with exponential backoff and jitter; it also retries 5xx and network errors.
  • Parallelism — a worker pool deletes in parallel while listing is still in progress (producer/consumer over channels). Total throughput is still capped by the rate limiter.
  • Structured logs for the whole process (log/slog).
  • Dry-run mode and interactive confirmation for safety.
  • Minimal dependencies (standard library plus golang.org/x/sync and golang.org/x/time).

Prerequisites

  1. Create an internal integration at https://www.notion.so/my-integrations and copy the token.
  2. Share the target database with the integration (••• menu → Connections → your integration).
  3. Get the Database ID (the 32 characters in the database URL).

Usage

export NOTION_TOKEN="secret_xxx"
export NOTION_DATABASE_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 1. Preview — lists what would be deleted, without deleting anything:
go run . -dry-run

# 2. Delete for real (asks for a "yes" confirmation):
go run .

# No prompt (e.g. in automation):
go run . -yes

# Tune concurrency and rate:
go run . -workers 4 -rate 3

Flags

Flag Default Description
-token $NOTION_TOKEN Notion integration token
-database $NOTION_DATABASE_ID Database ID
-workers 3 Number of concurrent delete workers
-rate 3 Max requests per second (global)
-dry-run false Only list, don't delete
-yes false Skip the interactive confirmation

Variant: tarefas-ai ("Tarefas AI Database")

A specialized copy in cmd/tarefas-ai/ that acts only on the Tarefas AI Database and deletes only the items whose Event Id field is not empty.

  • The database ID is built in (2a2bca5d3ca880eeab9eddc4d56a7e5e), but can be overridden with -database / NOTION_DATABASE_ID.
  • The filter is applied server-side (Event Id is rich_text → is_not_empty), so empty items are never fetched or deleted.
  • The property is configurable via the -property flag (default "Event Id").
# Preview — lists only the items with Event Id filled in:
go run ./cmd/tarefas-ai -dry-run

# Delete for real (asks for confirmation):
go run ./cmd/tarefas-ai

Build

# generic tool
go build -o cleannotiondb .
./cleannotiondb -dry-run

# Tarefas AI variant
go build -o tarefas-ai ./cmd/tarefas-ai
./tarefas-ai -dry-run

Notes

  • Archiving does not delete permanently; items stay in the database's trash.
  • Ctrl-C gracefully cancels in-flight requests.

About

Go CLI to bulk-delete (archive) Notion database items, with rate limiting, retries, and parallel workers.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages