# Django Unmanaged Assistant
Django Unmanaged Assistant is a Django app that provides a management command
to create database tables for unmanaged models in your Django
project.
This app is intended for use in local development environments where you have
unmanaged models that need to be reflected in the local database(s).
This app is in an alpha state - meaning it is still in development and may
have bugs or issues. Please use with caution and report any issues you
encounter.
## Problem
When working with Django, you may have unmanaged models in your project whose
tables are not automatically created in the database. This can be problematic
when you need to work with these models in your local environment.
You may or may not have scripts to create these tables, but it can be
cumbersome to manage these scripts and ensure they are up-to-date with your
models.
## Solution
Instead of trying to 'make the models managed when running locally', which is
commonly suggested (and thus possibly creating/committing migrations you do
not want in your repo), you can use Django Unmanaged Assistant to dynamically
create tables for your unmanaged models.
Then you can use something like 'factory_boy' or other scripts to help
generate data for these tables if you need dummy data, or leave them blank.
The app scans through all locally installed apps in your Django project,
identifies unmanaged models, and creates tables for these models if they
don't already exist. It also checks existing tables for missing columns and
adds them if necessary.
This app is designed primarily to give you a quick/easy way to create tables
locally for unmanaged models in your local database(s) without having to
manually create them or manage scripts for the creation of those tables/views.
## Features
- Automatically creates tables for unmanaged models in your Django project based on the model definitions
- Checks for existing tables and columns before attempting to create them
- Provides informative output about the actions taken (if ran using `-d` or `--detailed` flag)
- Warns about potential type mismatches between model fields and database columns (if ran using `-d` or `--detailed` flag)
- Supports multiple databases
## Additional Features
- Create local database(s) command for your Django project (`create_databases`)
- This might be useful if you have multiple databases in your Django project and need to create them locally if they don't already exist.
## Requirements
These are most likely already handled by your Django project, but just in case:
- Python 3.6+
- Django 3.2+
- psycopg2 / psycopg2-binary (if using PostgreSQL)
- mssql-django (if using Microsoft SQL Server)
- pyodbc (if using Microsoft SQL Server)
- The MSSQL ODBC driver installed on the OS (if using Microsoft SQL Server)
## Installation
1. Install the package using pip:
```
pip install django-unmanaged-assistant
```
2. Add `'django_unmanaged_assistant'` to your `INSTALLED_APPS` setting in your
Django project's settings file:
```python
INSTALLED_APPS = [
...
'django_unmanaged_assistant',
...
]
```
3. Optional: Add the following to your `settings.py` file to exclude apps that
have a path containing the specified string:
- By default, the app will exclude any apps that have a path containing 'site-packages' (i.e., pip-installed packages).
- These are strings that are checked against the path of the app. If the path contains the string, the app is excluded from the scan.
```python
EXCLUDE_UNMANAGED_PATH = 'path/to/exclude' # default: 'site-packages'
```
4. Optional: Add the following to your `settings.py` file to map apps with
unmanaged models to the appropriate database:
```python
APP_TO_DATABASE_MAPPING = {"app": "default", "other_app": "additional_database"}
```
5. Optional: Add the following to your `settings.py` file to include unmanaged models from pip-installed packages:
- Specify specific app names that you want to include in the scan (i.e., pip-installed packages).
```python
ADDITIONAL_UNMANAGED_TABLE_APPS = ['app_name']
```
## Multiple Databases
If you have multiple databases in your Django project, you can add the following to your `settings.py` file:
There are currently no checks regarding custom dbrouters, so if you have a custom dbrouter, you may need to adjust the code to accommodate your setup.
```python
APP_TO_DATABASE_MAPPING = {"app": "default", "other_app": "additional_database_alias"}
```
This will allow us to make sure we create the apps model tables in the correct database.
## Additional pip-installed packages
By default, the app will only scan through locally installed apps in your Django project. Any app inside the virtual environment (if available) will not be scanned.
Should you want to have unmanaged models from a pip-installed package, you can add the following to your `settings.py` file:
```python
ADDITIONAL_UNMANAGED_TABLE_APPS = ['app_name']
```
## Usage
After installation and after the migration of your managed models with migrations, you can use the `create_unmanaged_tables` management command to create tables for your unmanaged models:
```
python manage.py create_unmanaged_tables
```
This command will:
1. Scan through all the locally installed apps in your Django project
2. Identify unmanaged models
3. Create tables for these models if they don't already exist
4. Check existing tables for missing columns and add them if necessary
5. Provide warnings about potential type mismatches between model fields and database columns (if ran using `-d` or `--detailed` flag)
## Assumptions
The app assumes that you have already created the database(s) in your local environment.
- If you haven't created the database(s) yet, you can use the `create_databases` command to create them:
The app assumes you have migrated all of your managed models already.
The app assumes two different styles of naming convention for your tables. If you have a different naming convention, you can reach out to us to see if we can help accommodate your style, or you can submit a Pull Request with the changes.
1. Unbracketed: `schema.table_name`
2. Bracketed: `[schema].[table_name]`
## How it works
The `create_unmanaged_tables` command performs the following steps for each unmanaged model:
1. Checks if the table for the model exists in the database
2. If the table doesn't exist, it creates the table
3. If the table exists, it checks each field in the model:
- If a column for the field doesn't exist, it adds the column
- If the column exists, it compares the column type with the expected type from the model field
- It provides warnings if there are potential type mismatches (if ran using `-d` or `--detailed` flag)
## Configuration
Install the app and add it to your `INSTALLED_APPS` setting in your Django project's settings file.
You can also configure the app by adding the following to your `settings.py` file:
- `EXCLUDE_UNMANAGED_PATH`: A string that is checked against the path of the app. If the path contains the string, the app is excluded from the scan. Default: 'site-packages'
- `APP_TO_DATABASE_MAPPING`: A dictionary that maps apps with unmanaged models to the appropriate database. Default: 'default'
- `ADDITIONAL_UNMANAGED_TABLE_APPS`: A list of app names that you want to include in the scan. Default: []
## Supported Databases
The app supports the following databases:
- SQLite (alpha stages)
- PostgreSQL (alpha stages)
- Microsoft SQL Server (alpha stages)
If you would like to add support for additional databases, please feel free to submit a Pull Request!
## Limitations
- This app is intended for use with unmanaged models in a local environment only. It will not affect managed models in your project in any way.
- This app should NEVER be used/ran in a staging/production environment as we assume any databases/schemas/tables already exist in those environments.
- While the app attempts to create appropriate database schema, complex model relationships or custom field types may require manual
intervention.
- The app provides warnings about potential type mismatches, but it does not automatically alter existing column types. Such changes should
be handled manually to prevent data loss.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License.
## Support
If you encounter any problems or have any questions, please open an issue on the GitHub repository.
Django Unmanaged Assistant is free and always will be. It's developed and maintained in an Open Source manner. Any support is greatly appreciated.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-unmanaged-assistant",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django, unmanaged, tables, models",
"author": null,
"author_email": "Hanny <github@hannylicious.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/ab/532f340dcfb1de4ea3903dfde314feea78a55c3344fad5ce36cb8997273c/django_unmanaged_assistant-2024.10.28.1.tar.gz",
"platform": null,
"description": "# Django Unmanaged Assistant\n\nDjango Unmanaged Assistant is a Django app that provides a management command \nto create database tables for unmanaged models in your Django\nproject.\n\nThis app is intended for use in local development environments where you have \nunmanaged models that need to be reflected in the local database(s).\n\nThis app is in an alpha state - meaning it is still in development and may \nhave bugs or issues. Please use with caution and report any issues you \nencounter.\n\n## Problem\n\nWhen working with Django, you may have unmanaged models in your project whose\ntables are not automatically created in the database. This can be problematic\nwhen you need to work with these models in your local environment.\n\nYou may or may not have scripts to create these tables, but it can be \ncumbersome to manage these scripts and ensure they are up-to-date with your \nmodels.\n\n## Solution\n\nInstead of trying to 'make the models managed when running locally', which is \ncommonly suggested (and thus possibly creating/committing migrations you do \nnot want in your repo), you can use Django Unmanaged Assistant to dynamically \ncreate tables for your unmanaged models. \n\nThen you can use something like 'factory_boy' or other scripts to help \ngenerate data for these tables if you need dummy data, or leave them blank.\n\nThe app scans through all locally installed apps in your Django project, \nidentifies unmanaged models, and creates tables for these models if they\ndon't already exist. It also checks existing tables for missing columns and \nadds them if necessary.\n\nThis app is designed primarily to give you a quick/easy way to create tables \nlocally for unmanaged models in your local database(s) without having to \nmanually create them or manage scripts for the creation of those tables/views.\n\n## Features\n\n- Automatically creates tables for unmanaged models in your Django project based on the model definitions\n- Checks for existing tables and columns before attempting to create them\n- Provides informative output about the actions taken (if ran using `-d` or `--detailed` flag)\n- Warns about potential type mismatches between model fields and database columns (if ran using `-d` or `--detailed` flag)\n- Supports multiple databases\n\n## Additional Features\n\n- Create local database(s) command for your Django project (`create_databases`)\n - This might be useful if you have multiple databases in your Django project and need to create them locally if they don't already exist.\n\n## Requirements \n\nThese are most likely already handled by your Django project, but just in case:\n\n- Python 3.6+\n- Django 3.2+\n- psycopg2 / psycopg2-binary (if using PostgreSQL)\n- mssql-django (if using Microsoft SQL Server)\n- pyodbc (if using Microsoft SQL Server)\n- The MSSQL ODBC driver installed on the OS (if using Microsoft SQL Server)\n\n## Installation\n\n1. Install the package using pip:\n\n ```\n pip install django-unmanaged-assistant\n ```\n\n2. Add `'django_unmanaged_assistant'` to your `INSTALLED_APPS` setting in your \nDjango project's settings file:\n\n ```python\n INSTALLED_APPS = [\n ...\n 'django_unmanaged_assistant',\n ...\n ]\n ```\n \n3. Optional: Add the following to your `settings.py` file to exclude apps that \nhave a path containing the specified string:\n - By default, the app will exclude any apps that have a path containing 'site-packages' (i.e., pip-installed packages).\n - These are strings that are checked against the path of the app. If the path contains the string, the app is excluded from the scan.\n\n ```python\n EXCLUDE_UNMANAGED_PATH = 'path/to/exclude' # default: 'site-packages'\n ```\n\n4. Optional: Add the following to your `settings.py` file to map apps with \nunmanaged models to the appropriate database:\n\n ```python\n APP_TO_DATABASE_MAPPING = {\"app\": \"default\", \"other_app\": \"additional_database\"}\n ```\n\n5. Optional: Add the following to your `settings.py` file to include unmanaged models from pip-installed packages:\n - Specify specific app names that you want to include in the scan (i.e., pip-installed packages).\n \n ```python\n ADDITIONAL_UNMANAGED_TABLE_APPS = ['app_name']\n ```\n\n## Multiple Databases\n\nIf you have multiple databases in your Django project, you can add the following to your `settings.py` file:\n\nThere are currently no checks regarding custom dbrouters, so if you have a custom dbrouter, you may need to adjust the code to accommodate your setup.\n\n```python\nAPP_TO_DATABASE_MAPPING = {\"app\": \"default\", \"other_app\": \"additional_database_alias\"}\n```\nThis will allow us to make sure we create the apps model tables in the correct database.\n\n## Additional pip-installed packages\n\nBy default, the app will only scan through locally installed apps in your Django project. Any app inside the virtual environment (if available) will not be scanned.\n\nShould you want to have unmanaged models from a pip-installed package, you can add the following to your `settings.py` file:\n\n```python\nADDITIONAL_UNMANAGED_TABLE_APPS = ['app_name']\n```\n\n## Usage\n\nAfter installation and after the migration of your managed models with migrations, you can use the `create_unmanaged_tables` management command to create tables for your unmanaged models:\n\n```\npython manage.py create_unmanaged_tables\n```\n\nThis command will:\n\n1. Scan through all the locally installed apps in your Django project\n2. Identify unmanaged models\n3. Create tables for these models if they don't already exist\n4. Check existing tables for missing columns and add them if necessary\n5. Provide warnings about potential type mismatches between model fields and database columns (if ran using `-d` or `--detailed` flag)\n\n## Assumptions\n\nThe app assumes that you have already created the database(s) in your local environment. \n - If you haven't created the database(s) yet, you can use the `create_databases` command to create them:\n\nThe app assumes you have migrated all of your managed models already.\n\nThe app assumes two different styles of naming convention for your tables. If you have a different naming convention, you can reach out to us to see if we can help accommodate your style, or you can submit a Pull Request with the changes.\n1. Unbracketed: `schema.table_name`\n2. Bracketed: `[schema].[table_name]`\n\n## How it works\n\nThe `create_unmanaged_tables` command performs the following steps for each unmanaged model:\n\n1. Checks if the table for the model exists in the database\n2. If the table doesn't exist, it creates the table\n3. If the table exists, it checks each field in the model:\n - If a column for the field doesn't exist, it adds the column\n - If the column exists, it compares the column type with the expected type from the model field\n - It provides warnings if there are potential type mismatches (if ran using `-d` or `--detailed` flag)\n\n## Configuration\n\nInstall the app and add it to your `INSTALLED_APPS` setting in your Django project's settings file.\n\nYou can also configure the app by adding the following to your `settings.py` file:\n\n- `EXCLUDE_UNMANAGED_PATH`: A string that is checked against the path of the app. If the path contains the string, the app is excluded from the scan. Default: 'site-packages'\n- `APP_TO_DATABASE_MAPPING`: A dictionary that maps apps with unmanaged models to the appropriate database. Default: 'default'\n- `ADDITIONAL_UNMANAGED_TABLE_APPS`: A list of app names that you want to include in the scan. Default: []\n\n## Supported Databases\n\nThe app supports the following databases:\n\n- SQLite (alpha stages)\n- PostgreSQL (alpha stages)\n- Microsoft SQL Server (alpha stages)\n\nIf you would like to add support for additional databases, please feel free to submit a Pull Request!\n\n## Limitations\n\n- This app is intended for use with unmanaged models in a local environment only. It will not affect managed models in your project in any way.\n- This app should NEVER be used/ran in a staging/production environment as we assume any databases/schemas/tables already exist in those environments.\n- While the app attempts to create appropriate database schema, complex model relationships or custom field types may require manual\n intervention.\n- The app provides warnings about potential type mismatches, but it does not automatically alter existing column types. Such changes should\n be handled manually to prevent data loss.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Support\n\nIf you encounter any problems or have any questions, please open an issue on the GitHub repository.\n\nDjango Unmanaged Assistant is free and always will be. It's developed and maintained in an Open Source manner. Any support is greatly appreciated.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Django app to create databases/schemas/tables for unmanaged models in the local environment.",
"version": "2024.10.28.1",
"project_urls": {
"Homepage": "https://github.com/hannylicious/django-unmanaged-assistant",
"Issues": "https://github.com/hannylicious/django-unmanaged-assistant/issues"
},
"split_keywords": [
"django",
" unmanaged",
" tables",
" models"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d938c21190a4e4feffc42b0d80ca991350ff5151311f76b53e1916aa14bec3e9",
"md5": "0459971f721b62a3b14ef94f73bcc14e",
"sha256": "4d5ca99e2737b44af68a7f93f49a1a69f947ffff83775019c2f690244614a333"
},
"downloads": -1,
"filename": "django_unmanaged_assistant-2024.10.28.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0459971f721b62a3b14ef94f73bcc14e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24463,
"upload_time": "2024-10-28T20:23:23",
"upload_time_iso_8601": "2024-10-28T20:23:23.163346Z",
"url": "https://files.pythonhosted.org/packages/d9/38/c21190a4e4feffc42b0d80ca991350ff5151311f76b53e1916aa14bec3e9/django_unmanaged_assistant-2024.10.28.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5ab532f340dcfb1de4ea3903dfde314feea78a55c3344fad5ce36cb8997273c",
"md5": "123b42eeb6748dca2d79b88c151b1e60",
"sha256": "138c9635627a0a41a803f36461b257ebbd6c8964cdbbfeaffd43e20b663faf3d"
},
"downloads": -1,
"filename": "django_unmanaged_assistant-2024.10.28.1.tar.gz",
"has_sig": false,
"md5_digest": "123b42eeb6748dca2d79b88c151b1e60",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31975,
"upload_time": "2024-10-28T20:23:24",
"upload_time_iso_8601": "2024-10-28T20:23:24.538129Z",
"url": "https://files.pythonhosted.org/packages/d5/ab/532f340dcfb1de4ea3903dfde314feea78a55c3344fad5ce36cb8997273c/django_unmanaged_assistant-2024.10.28.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 20:23:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hannylicious",
"github_project": "django-unmanaged-assistant",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-unmanaged-assistant"
}
JSON
