{"id":15658914,"url":"https://github.com/dcdunkan/tgdb","last_synced_at":"2025-05-04T08:10:10.898Z","repository":{"id":40379540,"uuid":"488361467","full_name":"dcdunkan/tgdb","owner":"dcdunkan","description":"Use Telegram channel as a database (Just for fun)","archived":false,"fork":false,"pushed_at":"2022-05-12T15:20:55.000Z","size":30,"stargazers_count":42,"open_issues_count":1,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-04T08:10:07.213Z","etag":null,"topics":["database","gramjs","telegram","telegram-db","tgdb"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcdunkan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-03T20:59:16.000Z","updated_at":"2025-01-17T12:22:38.000Z","dependencies_parsed_at":"2022-09-15T06:50:24.848Z","dependency_job_id":null,"html_url":"https://github.com/dcdunkan/tgdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdunkan%2Ftgdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdunkan%2Ftgdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdunkan%2Ftgdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdunkan%2Ftgdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcdunkan","download_url":"https://codeload.github.com/dcdunkan/tgdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252305242,"owners_count":21726623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","gramjs","telegram","telegram-db","tgdb"],"created_at":"2024-10-03T13:14:24.479Z","updated_at":"2025-05-04T08:10:10.859Z","avatar_url":"https://github.com/dcdunkan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **WARNING: unstable**. This is a concept and the **work is still in\n\u003e progress**. You should expect breaking changes.\n\n\u003cdiv align=\"center\"\u003e\n\n---\n  \n\u003cimg width=\"250px\" src=\"https://user-images.githubusercontent.com/70066170/167955253-22b0f766-c1ab-446f-b2f3-b67a08e6c8e2.png\"\u003e\n\n# Project TGDB\n\n**Telegram channels as databases!**\n\n---\n\n\u003c/div\u003e\n\nUsing this library you can use your private or public Telegram channels as\nminimal database service. It is fast, free, secure and unlimited. A channel can\ncontain multiple databases, and it is possible to retrieve, insert, modify, and\ndelete records. You may also want to look at\n[\"Is this a good choice for my projects?\"](#is-this-a-good-choice-for-my-projects).\n\n## Installation\n\nInstall the package using NPM (via GitHub)\n\n```bash\nnpm install dcdunkan/tgdb#main\n```\n\n## Usage\n\nHere's a minimal example on using this library. But to initialize a TGDB\ninstance, you have to go to https://my.telegram.org/ and login with your\naccount. You'll get a API ID and API hash from there. Store it somewhere secure.\n\n\u003cdetails\u003e\n  \u003csummary\u003eOptional steps (Will be prompted anyway)\u003c/summary\u003e\u003chr\u003e\n\nGet string session by running\n[this](https://painor.gitbook.io/gramjs/#installation) installation example of\n[GramJS](https://github.com/gram-js/gramjs) and save it somewhere. You can use\nthe API ID and API hash you got earlier from https://my.telegram.org.\n\n\u003e Installation example: https://painor.gitbook.io/gramjs/#installation\n\nCreate a private or public Telegram channel.\n\n- Send a message to the channel with the text: \"_tgdb:entry_\".\n- Get the channel **chat_id** and **message_id** of that message you just sent.\n\n\u003e You may use [@jsoonbot](https://telegram.me/jsoonbot),\n\u003e [@ForwardInfoBot](https://telegram.me/ForwardInfoBot) or bots like that to get\n\u003e the **chat_id** and **message_id**, by forwarding that message you just sent\n\u003e in the channel.\n\n\u003chr\u003e\n\u003c/details\u003e\n\n### Create a TelegramDB instance\n\nImport the `TelegramDB` class from the library.\n\n```ts\nimport { TelegramDB } from \"tgdb-core\";\n```\n\nCreate an instance:\n\n```ts\nconst tgdb = new TelegramDB({\n  apiId: 123456, // API ID from https://my.telegram.org/\n  apiHash: \"ABCD\", // API hash from https://my.telegram.org/\n\n  stringSession: \"...\", // String session you got from GramJS\n  channelId: -100071801131325, // Channel `chat_id`\n  entryPoint: 4, // `message_id` of the message \"tgdb:entry\"\n});\n```\n\nAll of the above parameters are required to initialize a `TelegramDB` instance.\nHowever, it is possible to start the program by only providing your `apiId` and\n`apiHash`. When you call the `TelegramDB.connect()` as shown below, the program\nwill prompt you to enter some details to generate the rest of the parameters.\nYou have to store them in a safe place and use them when you're running the\nprogram again to avoid further unnecessary logins and channel creations. Now\nconnect to the instance call:\n\n```ts\nawait tgdb.connect(); // connect to the instance\n```\n\n### Working with a database\n\nCurrently you have two operations related with the instance and four basic\noperations related to records.\n\n#### Creating and deleting databases\n\nTo create a new database or to choose an existing one:\n\n```ts\nconst db = await tgdb.database(\"employees\");\n```\n\nTo delete a database:\n\n```ts\nawait tgdb.deleteDatabase(\"employees\");\n```\n\n#### Working with records\n\nAt the moment, you are only allowed to pass an JavaScript object as the value.\nYou can expect this to change in any future update.\n\n```ts\n// Add a record to the database\nawait db.add(\"12345678\", { first_name: \"Linus\" });\n\n// Get a record data using\nconst data = await db.get(\"12345678\");\nconsole.log(data);\n\n// Modify an existing record data\nawait db.edit(\"12345678\", { ...data, second_name: \"Torvalds\" });\n\n// Delete a record\nawait db.delete(\"12345678\");\n\n// Clear the whole database\nawait db.clear();\n```\n\n- Querying the data is still in the TODO list.\n- While modifying (`Database.edit(key: string, value: any)`) the data, you have\n  to pass a full value. You cannot yet update a particular key-value pair in the\n  JSON object.\n- Clearing the database using `Database.clear()` will not delete the database.\n  It will only delete all of the records, and the database name will still be in\n  the `entryPoint` message of the channel.\n\n### TODO\n\n- Method to query data\n- Allow storing not only as JSON objects\n- Schema and Types\n- Allow modifying a single key-value in the JSON object\n\n---\n\n## FAQ\n\n(Or at least I expect these questions will be asked)\n\n### How this works?\n\nActually the concept is pretty simple. We store the data in a particular format\nas Telegram messages. For reading, the data is retrieved and parsed back in to\nthe JSON object. Internally, we use [GramJS](https://github.com/gram-js/gramjs)\nto work with the User account.\n\n### Why User accounts? Not bots?\n\nTelegram bots cannot read the past messages. Ironically, in order to do that,\nthey need another database. You can cross-check with the\n[Official Bot API documentation](https://core.telegram.org/bots/api) if you want\nto. Since this library need to read and edit and delete the old messages, it is\nnecessary to use an User account for this project.\n\n\u003e #### Can my account get banned or suspended?\n\u003e\n\u003e Hopefully, **no**. At least, I used my main account for testing while\n\u003e developing this, and nothing happened yet :) I have hit the API limits\n\u003e multiple times, and still nothing happened.\n\n### Why channels, not group or private chats?\n\nIt's called spamming, if you sent a lot of messages in a short period of time :)\nAnd as I believe, sending messages in channels like that, is not restricted as\nsending in groups and private chats.\n\n### Is this a good choice for my projects?\n\nThat is something I am not totally sure about. For small projects, believe me,\nit won't be a problem at all. But for a large-scale thingy, I am not sure. Sure,\nthis library can handle it, but Telegram rate limits are the only thing that\ncould be an issue. And sending a lot of messages (storing data) in a small time\nperiod can also be considered as spamming - and for that your account might get\nbanned or suspended.\n\nThis project is still in it's early stage. Maybe, we can have proper answer for\nthis after testing in large scale. After the first stable release though.\n\n## Related repositories\n\n### Under development\n\n- Web UI for manage the database\n\n### Ideas\n\n- HTTP API server\n- Backups (A normal bot, maybe?)\n- Data migration\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csamp\u003e\u003ca href=\"LICENSE\"\u003eMIT License (C) 2022, Dunkan\u003c/a\u003e\u003c/samp\u003e\u003cbr\u003e\n  \u003csamp\u003e\u003cb\u003e\u0026lt; ♥️ \u0026 ☕ \u0026gt;\u003c/b\u003e\u003c/samp\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcdunkan%2Ftgdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcdunkan%2Ftgdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcdunkan%2Ftgdb/lists"}