Getting Started with Telebase
Telebase is a production-grade serverless database and file storage engine that uses Telegram as the ultimate, free persistent storage backend and Cloudflare KV as an ultra-fast edge cache.
Document Summary
What it does
Repurposes Telegram channel endpoints into a serverless database with Cloudflare KV edge query layers.
When to use it
Hobby apps, hackathons, staging web tools, and student assignments requiring a free, persistent database.
Example usage
Connect using our official JavaScript client, perform SQL CRUD commands, and manage files under a single dashboard console.
Why Telebase?
- 1. Infinite Free Storage: Leverage Telegram's infrastructure to store multi-gigabyte files.
- 2. Ultra-Low Latency: Cloudflare KV caches your SQL/NoSQL responses globally, delivering sub-15ms reads.
- 3. Zero-Knowledge Encryption: AES-256-GCM is applied before data leaves your application. Telegram sees only ciphertext.
Quick Start
All API requests to your Telebase instance must include your API Key.
{
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
}Frequently Asked Questions (FAQ)
What is Telebase?
Telebase is an open-source serverless database layer using Telegram API for storage, cached globally via Cloudflare KV for sub-15ms reads.
How does Telebase work?
Your application queries are captured by a Cloudflare Edge Worker. Write requests upload serialized data packets to private Telegram channels. Read requests fetch global indexes instantly from Cloudflare KV.
Is Telebase a Firebase alternative?
Yes! It is a fully featured free alternative to Firebase for students and hobby builders who want database and file hosting features without billing caps or cold starts.
Is Telebase a Supabase alternative?
Yes. Unlike Supabase's free databases that pause after 1 week of inactivity, Telebase uses Telegram and Cloudflare edge computing, keeping your staging database active and online permanently.
Can Telebase store files?
Absolutely. Telebase automatically splits files larger than 19MB into separate packets, records their hashes, and merges them dynamically when retrieved.
Can Telebase be used with Next.js?
Yes. Telebase exposes a standard HTTP API that works with Next.js server components, client components, API routes, or standard node services.
How do I install the Telebase CLI?
You can install the Telebase CLI globally via npm using the command: npm install -g telebase-cli
What commands does the Telebase CLI support?
The CLI supports: init (link project credentials), status (check server connectivity), query <sql> (run SQL queries directly), upload <path> (upload files to Telegram), and download <uuid> (retrieve files by UUID).
Can I execute SQL queries directly from the command line?
Yes, you can run SQL queries by executing: telebase query "SELECT * FROM users". The results are formatted and displayed as a clean console table.
How does the CLI handle large file uploads?
When executing telebase upload <filePath>, the CLI automatically chunks any file larger than 19MB into individual packets, uploads them to the Telegram channel, and outputs a unique Asset UUID that allows you to download and reconstruct the file later.
How do I diagnose connection errors in Telebase?
Simply execute telebase diagnose in your terminal. This runs an integrated diagnostic suite checking Node.js compatibility, local .env configurations, API latency, mock query health, and version freshness.
How do I check if my Telebase CLI is up to date?
Running telebase status or telebase diagnose checks your local version against the latest package on the NPM registry. A notification banner is printed if an update is recommended.