# redbot-orm
Database ORM integration for Red-DiscordBot cogs using [Piccolo ORM](https://piccolo-orm.readthedocs.io/en/latest/). Supports both PostgreSQL and SQLite.
[](https://pypi.org/project/redbot-orm/)
[](https://pypi.org/project/redbot-orm/)
## Features
- Easy database integration for Red-DiscordBot cogs
- Support for both [PostgreSQL](https://piccolo-orm.readthedocs.io/en/latest/piccolo/engines/postgres_engine.html) and [SQLite](https://piccolo-orm.readthedocs.io/en/latest/piccolo/engines/sqlite_engine.html)
- Automatic database creation and [migration handling](https://piccolo-orm.readthedocs.io/en/latest/piccolo/migrations/create.html#auto-migrations)
- Clean separation of databases between different cogs
- Works with any Discord.py bot (not just Red)
## Installation
```bash
pip install redbot-orm
```
## File Structure
```
cog-folder/
├── db/
│ ├── migrations/
│ ├── piccolo_conf.py
│ ├── piccolo_app.py
│ ├── tables.py
├── __init__.py
├── cog.py
```
## Usage Examples
### PostgreSQL Example
```python
from redbot.core import commands
from redbot.core.bot import Red
from piccolo.engine.postgres import PostgresEngine
from redbot_orm.postgres import register_cog
from .db.tables import MyTable
class PostgresCog(commands.Cog):
def __init__(self, bot: Red):
self.bot = bot
self.db: PostgresEngine = None
async def cog_load(self):
config = await self.bot.get_shared_api_tokens("postgres")
# OR
config = { # Example
"database": "postgres",
"host": "localhost",
"port": "5432",
"user": "postgres",
"password": "postgres"
}
self.db = await register_cog(self, [MyTable], config)
async def cog_unload(self):
if self.db:
self.db.pool.terminate()
```
### SQLite Example
```python
from redbot.core import commands
from redbot.core.bot import Red
from piccolo.engine.sqlite import SQLiteEngine
from redbot_orm.sqlite import register_cog
from .db.tables import MyTable
class SQLiteCog(commands.Cog):
def __init__(self, bot: Red):
self.bot = bot
self.db: SQLiteEngine = None
async def cog_load(self):
self.db = await register_cog(self, [MyTable])
```
## Configuration
### PostgreSQL Configuration
Required shared API tokens for PostgreSQL:
```json
{
"database": "postgres",
"host": "127.0.0.1",
"port": "5432",
"user": "postgres",
"password": "postgres"
}
```
### Piccolo Configuration Files
#### piccolo_conf.py
```python
import os
from piccolo.conf.apps import AppRegistry
from piccolo.engine.postgres import PostgresEngine
DB = PostgresEngine(
config={
"database": os.environ.get("POSTGRES_DATABASE"),
"user": os.environ.get("POSTGRES_USER"),
"password": os.environ.get("POSTGRES_PASSWORD"),
"host": os.environ.get("POSTGRES_HOST"),
"port": os.environ.get("POSTGRES_PORT"),
}
)
APP_REGISTRY = AppRegistry(apps=["db.piccolo_app"])
```
#### piccolo_app.py
```python
import os
from piccolo.conf.apps import AppConfig, table_finder
CURRENT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))
APP_CONFIG = AppConfig(
app_name=os.getenv("APP_NAME"),
table_classes=table_finder(["db.tables"]),
migrations_folder_path=os.path.join(CURRENT_DIRECTORY, "migrations"),
)
```
## Development and Migrations
For local development, create an `.env` file in your cog's root:
```env
# Only for PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DATABASE=postgres
```
Create a `build.py` for managing migrations:
```python
import asyncio
import os
from pathlib import Path
from dotenv import load_dotenv
from redbot_orm import postgres
load_dotenv()
config = {
"user": os.environ.get("POSTGRES_USER"),
"password": os.environ.get("POSTGRES_PASSWORD"),
"database": os.environ.get("POSTGRES_DATABASE"),
"host": os.environ.get("POSTGRES_HOST"),
"port": os.environ.get("POSTGRES_PORT"),
}
root = Path(__file__).parent
async def main():
description = input("Enter a description for the migration: ")
print(await postgres.create_migrations(root, config, True, description))
print(await postgres.run_migrations(root, config, True))
if __name__ == "__main__":
asyncio.run(main())
```
## Notes
- Each cog gets its own database named after the cog's folder name (lowercase)
- For SQLite, databases are stored in the cog's data folder
- Migrations are handled automatically when the cog loads
Raw data
{
"_id": null,
"home_page": "https://github.com/vertyco/redbot-orm",
"name": "redbot-orm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "postgres, sqlite, piccolo, red, redbot, red-discordbot, red, bot, discord, database, async, asyncpg, aiosqlite, orm",
"author": "Vertyco",
"author_email": "alex.c.goble@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5f/cb/1ad5a07edee633539c76627aa085c352b9b7627de527725bdd27b31f5a79/redbot-orm-0.0.1.tar.gz",
"platform": null,
"description": "# redbot-orm\r\n\r\nDatabase ORM integration for Red-DiscordBot cogs using [Piccolo ORM](https://piccolo-orm.readthedocs.io/en/latest/). Supports both PostgreSQL and SQLite.\r\n\r\n[](https://pypi.org/project/redbot-orm/)\r\n[](https://pypi.org/project/redbot-orm/)\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n## Features\r\n\r\n- Easy database integration for Red-DiscordBot cogs\r\n- Support for both [PostgreSQL](https://piccolo-orm.readthedocs.io/en/latest/piccolo/engines/postgres_engine.html) and [SQLite](https://piccolo-orm.readthedocs.io/en/latest/piccolo/engines/sqlite_engine.html)\r\n- Automatic database creation and [migration handling](https://piccolo-orm.readthedocs.io/en/latest/piccolo/migrations/create.html#auto-migrations)\r\n- Clean separation of databases between different cogs\r\n- Works with any Discord.py bot (not just Red)\r\n\r\n## Installation\r\n\r\n```bash\r\npip install redbot-orm\r\n```\r\n\r\n## File Structure\r\n\r\n```\r\ncog-folder/\r\n \u251c\u2500\u2500 db/\r\n \u2502 \u251c\u2500\u2500 migrations/\r\n \u2502 \u251c\u2500\u2500 piccolo_conf.py\r\n \u2502 \u251c\u2500\u2500 piccolo_app.py\r\n \u2502 \u251c\u2500\u2500 tables.py\r\n \u251c\u2500\u2500 __init__.py\r\n \u251c\u2500\u2500 cog.py\r\n```\r\n\r\n## Usage Examples\r\n\r\n### PostgreSQL Example\r\n\r\n```python\r\nfrom redbot.core import commands\r\nfrom redbot.core.bot import Red\r\nfrom piccolo.engine.postgres import PostgresEngine\r\nfrom redbot_orm.postgres import register_cog\r\nfrom .db.tables import MyTable\r\n\r\nclass PostgresCog(commands.Cog):\r\n def __init__(self, bot: Red):\r\n self.bot = bot\r\n self.db: PostgresEngine = None\r\n\r\n async def cog_load(self):\r\n config = await self.bot.get_shared_api_tokens(\"postgres\")\r\n # OR\r\n config = { # Example\r\n \"database\": \"postgres\",\r\n \"host\": \"localhost\",\r\n \"port\": \"5432\",\r\n \"user\": \"postgres\",\r\n \"password\": \"postgres\"\r\n }\r\n self.db = await register_cog(self, [MyTable], config)\r\n\r\n async def cog_unload(self):\r\n if self.db:\r\n self.db.pool.terminate()\r\n```\r\n\r\n### SQLite Example\r\n\r\n```python\r\nfrom redbot.core import commands\r\nfrom redbot.core.bot import Red\r\nfrom piccolo.engine.sqlite import SQLiteEngine\r\nfrom redbot_orm.sqlite import register_cog\r\nfrom .db.tables import MyTable\r\n\r\nclass SQLiteCog(commands.Cog):\r\n def __init__(self, bot: Red):\r\n self.bot = bot\r\n self.db: SQLiteEngine = None\r\n\r\n async def cog_load(self):\r\n self.db = await register_cog(self, [MyTable])\r\n```\r\n\r\n## Configuration\r\n\r\n### PostgreSQL Configuration\r\nRequired shared API tokens for PostgreSQL:\r\n\r\n```json\r\n{\r\n \"database\": \"postgres\",\r\n \"host\": \"127.0.0.1\",\r\n \"port\": \"5432\",\r\n \"user\": \"postgres\",\r\n \"password\": \"postgres\"\r\n}\r\n```\r\n\r\n### Piccolo Configuration Files\r\n\r\n#### piccolo_conf.py\r\n```python\r\nimport os\r\nfrom piccolo.conf.apps import AppRegistry\r\nfrom piccolo.engine.postgres import PostgresEngine\r\n\r\nDB = PostgresEngine(\r\n config={\r\n \"database\": os.environ.get(\"POSTGRES_DATABASE\"),\r\n \"user\": os.environ.get(\"POSTGRES_USER\"),\r\n \"password\": os.environ.get(\"POSTGRES_PASSWORD\"),\r\n \"host\": os.environ.get(\"POSTGRES_HOST\"),\r\n \"port\": os.environ.get(\"POSTGRES_PORT\"),\r\n }\r\n)\r\n\r\nAPP_REGISTRY = AppRegistry(apps=[\"db.piccolo_app\"])\r\n```\r\n\r\n#### piccolo_app.py\r\n```python\r\nimport os\r\nfrom piccolo.conf.apps import AppConfig, table_finder\r\n\r\nCURRENT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))\r\n\r\nAPP_CONFIG = AppConfig(\r\n app_name=os.getenv(\"APP_NAME\"),\r\n table_classes=table_finder([\"db.tables\"]),\r\n migrations_folder_path=os.path.join(CURRENT_DIRECTORY, \"migrations\"),\r\n)\r\n```\r\n\r\n## Development and Migrations\r\n\r\nFor local development, create an `.env` file in your cog's root:\r\n\r\n```env\r\n# Only for PostgreSQL\r\nPOSTGRES_HOST=localhost\r\nPOSTGRES_PORT=5432\r\nPOSTGRES_USER=postgres\r\nPOSTGRES_PASSWORD=postgres\r\nPOSTGRES_DATABASE=postgres\r\n```\r\n\r\nCreate a `build.py` for managing migrations:\r\n\r\n```python\r\nimport asyncio\r\nimport os\r\nfrom pathlib import Path\r\nfrom dotenv import load_dotenv\r\nfrom redbot_orm import postgres\r\n\r\nload_dotenv()\r\n\r\nconfig = {\r\n \"user\": os.environ.get(\"POSTGRES_USER\"),\r\n \"password\": os.environ.get(\"POSTGRES_PASSWORD\"),\r\n \"database\": os.environ.get(\"POSTGRES_DATABASE\"),\r\n \"host\": os.environ.get(\"POSTGRES_HOST\"),\r\n \"port\": os.environ.get(\"POSTGRES_PORT\"),\r\n}\r\n\r\nroot = Path(__file__).parent\r\n\r\nasync def main():\r\n description = input(\"Enter a description for the migration: \")\r\n print(await postgres.create_migrations(root, config, True, description))\r\n print(await postgres.run_migrations(root, config, True))\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(main())\r\n```\r\n\r\n## Notes\r\n\r\n- Each cog gets its own database named after the cog's folder name (lowercase)\r\n- For SQLite, databases are stored in the cog's data folder\r\n- Migrations are handled automatically when the cog loads\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Postgres and SQLite extensions for Red-DiscordBot",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/vertyco/redbot-orm/issues",
"Changelog": "https://github.com/vertyco/redbot-orm/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/vertyco/redbot-orm"
},
"split_keywords": [
"postgres",
" sqlite",
" piccolo",
" red",
" redbot",
" red-discordbot",
" red",
" bot",
" discord",
" database",
" async",
" asyncpg",
" aiosqlite",
" orm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5fcb1ad5a07edee633539c76627aa085c352b9b7627de527725bdd27b31f5a79",
"md5": "615300a878f05d18705be968e62fcaf1",
"sha256": "2726cb5ffb1659d94eeb8a56166b6ac1d8655d564e9a597e2cc26d9d0f2cb42a"
},
"downloads": -1,
"filename": "redbot-orm-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "615300a878f05d18705be968e62fcaf1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9987,
"upload_time": "2025-01-19T17:20:02",
"upload_time_iso_8601": "2025-01-19T17:20:02.301861Z",
"url": "https://files.pythonhosted.org/packages/5f/cb/1ad5a07edee633539c76627aa085c352b9b7627de527725bdd27b31f5a79/redbot-orm-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-19 17:20:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vertyco",
"github_project": "redbot-orm",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "redbot-orm"
}
JSON
