## django-bigtrill
**django-bigtrill** is a Django utility to help you migrate from the default Django `User` model to a custom user model in an existing project. It automates the process, making it safer and easier to switch without manual errors.
---
### Features
- Detects and updates references to the default Django `User` model
- Creates a new custom user model in an app with a name you choose
- Updates settings and migrations automatically
- Provides admin integration for the new user model
- Automatically creates backups of files before modification
- Allows you to restore files from backup with a flag
- Supports a dry run mode to preview changes without modifying files
---
### Installation
```bash
pip install django-bigtrill
```
or clone into your project root directory:
```bash
git clone https://github.com/alexander-any7/django-bigtrill
```
---
**Important**: Your `INSTALLED_APPS` must be a list or this will not work.
### Usage
1. **Configure**: Create a file named `bigtrill_settings.py` in the directory where you will run the start command. This file is required and must contain the following variables:
- `PYTHON`: Your Python command (e.g., `python` or `python3`)
- `MANAGE_PY_FILE`: Path to your `manage.py`
- `COPY_MODEL`: Desired name for your custom user model
- `NEW_AUTH_APP_LABEL`: App label for the new user model
- `INSTALLED_APPS_SETTINGS_FILE_PATH`: Absolute or relative path to your main `settings.py` or where the `INSTALLED_APPS` is defined. (Relative paths will be converted automatically)
- `AUTH_USER_MODEL_PATH`: Absolute or relative path to where the `AUTH_USER_MODEL` variable is or will be defined
- `DEFAULT_DJANGO_USER_MODEL_FILE_PATHS`: List of files referencing the default user model (absolute or relative paths; optional)
- `BASE_DIR`: Absolute or relative path to your project root. You are advised to run `pwd` and provide the output of the command.
- `GITIGNORE_PATH`: Path to your `.gitignore` file. This MUST be relative to `BASE_DIR`. The folders in the gitignore will not be searched for references to the default `User` model.
Example:
```python
# bigtrill_settings.py
PYTHON = "python"
MANAGE_PY_FILE = "manage.py"
COPY_MODEL = "CustomUser"
NEW_AUTH_APP_LABEL = "accounts"
INSTALLED_APPS_SETTINGS_FILE_PATH = "<absolute or relative path to your settings.py>"
AUTH_USER_MODEL_PATH = INSTALLED_APPS_SETTINGS_FILE_PATH
FILES_TO_SEARCH = [] # absolute or relative paths
BASE_DIR = "<absolute or relative path to your project root>"
GITIGNORE_PATH = ".gitignore" # MUST BE RELATIVE to BASE_DIR
```
2. **Run the start script**:
If installed via pip:
```bash
bigtrill-start
```
or
```bash
python -m bigtrill.start
```
or
If cloned from git:
```bash
python django-bigtrill/bigtrill/start.py
```
Flags:
- `--dry_run` : Show which files would be modified without making any changes.
- `--restore` : Restore files from backup and exit.
- `--skip_pause` : Skips the pause that allows you to check everything before proceeding to rename the model
Follow the prompts. The script will:
- Search for references to the default user model
- Create a new app and custom user model
- Update settings and run migrations
- Update imports and references
3. **Review and test**:
- Check your code and migrations
- Test your application thoroughly after using this.
---
### Notes
- **Backup your project and database before running!**
- Do not run on production without testing.
- After migration, update any manual references to the old user model.
- Remove temporary files and update your main settings as needed.
- Remove temporary files (such as `bigtrill_temp_settings.py`) and move any definitions from them (e.g., `AUTH_USER_MODEL`) to your desired location in your main `settings.py` file to follow Django project conventions.
- You might also want to remove the `bigtrill_settings.py` file you created.
- You might also want to remove `bigtrill` from `INSTALLED_APPS`. You can do this by going to the end of the file provided in `INSTALLED_APPS_SETTINGS_FILE_PATH` and there you will see:
```python
# Added by bigtrill.start
INSTALLED_APPS += [..., 'bigtrill']
```
Simply remove bigtrill from the list. Optionally you can move the first item (the new app label where the new User model resides) to the actual `INSTALLED_APPS` list or definition and remove this comment and the lines below all together.
- **Performance**: Migration performance may vary depending on project size and number of users. For large datasets, consider running during low-traffic periods. Feel free to implement any optimization improvements you deem fit for your specific use case.
---
### TODO
- **Improve logging**: Add detailed logging for each step of the migration process with proper stdout output to help users track progress and debug issues
- **Improve model rename detection**
Use a more robust method (e.g., analyzing the generated migration files) to confirm that Django has detected the rename.
---
### License
MIT
---
### Author
Alexander Anyaegbunam (<alexander.any7@gmail.com>)
Raw data
{
"_id": null,
"home_page": "https://github.com/alexander-any7/django-bigtrill.git",
"name": "django-bigtrill",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "django, auth, custom user, migration, bigtrill, bigtrill migration, default user model, custom user model, django custom user model, django auth user model, django user model migration, existing project, django existing project",
"author": "Alexander Anyaegbunam",
"author_email": "Alexander Anyaegbunam <alexander.any7@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/94/6b/c7060eebf31c72899f30427c2473bd6e35731bc05e08fd631f906c52b07f/django_bigtrill-2.0.2.tar.gz",
"platform": null,
"description": "## django-bigtrill\r\n\r\n**django-bigtrill** is a Django utility to help you migrate from the default Django `User` model to a custom user model in an existing project. It automates the process, making it safer and easier to switch without manual errors.\r\n\r\n---\r\n\r\n### Features\r\n\r\n- Detects and updates references to the default Django `User` model\r\n- Creates a new custom user model in an app with a name you choose\r\n- Updates settings and migrations automatically\r\n- Provides admin integration for the new user model\r\n- Automatically creates backups of files before modification\r\n- Allows you to restore files from backup with a flag\r\n- Supports a dry run mode to preview changes without modifying files\r\n\r\n---\r\n\r\n### Installation\r\n\r\n```bash\r\npip install django-bigtrill\r\n```\r\n\r\nor clone into your project root directory:\r\n\r\n```bash\r\ngit clone https://github.com/alexander-any7/django-bigtrill\r\n```\r\n\r\n---\r\n\r\n**Important**: Your `INSTALLED_APPS` must be a list or this will not work.\r\n\r\n### Usage\r\n\r\n1. **Configure**: Create a file named `bigtrill_settings.py` in the directory where you will run the start command. This file is required and must contain the following variables:\r\n\r\n - `PYTHON`: Your Python command (e.g., `python` or `python3`)\r\n - `MANAGE_PY_FILE`: Path to your `manage.py`\r\n - `COPY_MODEL`: Desired name for your custom user model\r\n - `NEW_AUTH_APP_LABEL`: App label for the new user model\r\n - `INSTALLED_APPS_SETTINGS_FILE_PATH`: Absolute or relative path to your main `settings.py` or where the `INSTALLED_APPS` is defined. (Relative paths will be converted automatically)\r\n - `AUTH_USER_MODEL_PATH`: Absolute or relative path to where the `AUTH_USER_MODEL` variable is or will be defined\r\n - `DEFAULT_DJANGO_USER_MODEL_FILE_PATHS`: List of files referencing the default user model (absolute or relative paths; optional)\r\n - `BASE_DIR`: Absolute or relative path to your project root. You are advised to run `pwd` and provide the output of the command.\r\n - `GITIGNORE_PATH`: Path to your `.gitignore` file. This MUST be relative to `BASE_DIR`. The folders in the gitignore will not be searched for references to the default `User` model.\r\n\r\n Example:\r\n\r\n ```python\r\n # bigtrill_settings.py\r\n PYTHON = \"python\"\r\n MANAGE_PY_FILE = \"manage.py\"\r\n COPY_MODEL = \"CustomUser\"\r\n NEW_AUTH_APP_LABEL = \"accounts\"\r\n INSTALLED_APPS_SETTINGS_FILE_PATH = \"<absolute or relative path to your settings.py>\"\r\n AUTH_USER_MODEL_PATH = INSTALLED_APPS_SETTINGS_FILE_PATH\r\n FILES_TO_SEARCH = [] # absolute or relative paths\r\n BASE_DIR = \"<absolute or relative path to your project root>\"\r\n GITIGNORE_PATH = \".gitignore\" # MUST BE RELATIVE to BASE_DIR\r\n\r\n ```\r\n\r\n2. **Run the start script**:\r\n\r\n If installed via pip:\r\n\r\n ```bash\r\n bigtrill-start\r\n ```\r\n\r\n or\r\n\r\n ```bash\r\n python -m bigtrill.start\r\n ```\r\n\r\n or\r\n\r\n If cloned from git:\r\n\r\n ```bash\r\n python django-bigtrill/bigtrill/start.py\r\n ```\r\n\r\n Flags:\r\n\r\n - `--dry_run` : Show which files would be modified without making any changes.\r\n - `--restore` : Restore files from backup and exit.\r\n - `--skip_pause` : Skips the pause that allows you to check everything before proceeding to rename the model\r\n\r\n Follow the prompts. The script will:\r\n\r\n - Search for references to the default user model\r\n - Create a new app and custom user model\r\n - Update settings and run migrations\r\n - Update imports and references\r\n\r\n3. **Review and test**:\r\n - Check your code and migrations\r\n - Test your application thoroughly after using this.\r\n\r\n---\r\n\r\n### Notes\r\n\r\n- **Backup your project and database before running!**\r\n- Do not run on production without testing.\r\n- After migration, update any manual references to the old user model.\r\n- Remove temporary files and update your main settings as needed.\r\n\r\n - Remove temporary files (such as `bigtrill_temp_settings.py`) and move any definitions from them (e.g., `AUTH_USER_MODEL`) to your desired location in your main `settings.py` file to follow Django project conventions.\r\n - You might also want to remove the `bigtrill_settings.py` file you created.\r\n - You might also want to remove `bigtrill` from `INSTALLED_APPS`. You can do this by going to the end of the file provided in `INSTALLED_APPS_SETTINGS_FILE_PATH` and there you will see:\r\n ```python\r\n # Added by bigtrill.start\r\n INSTALLED_APPS += [..., 'bigtrill']\r\n ```\r\n Simply remove bigtrill from the list. Optionally you can move the first item (the new app label where the new User model resides) to the actual `INSTALLED_APPS` list or definition and remove this comment and the lines below all together.\r\n\r\n- **Performance**: Migration performance may vary depending on project size and number of users. For large datasets, consider running during low-traffic periods. Feel free to implement any optimization improvements you deem fit for your specific use case.\r\n\r\n---\r\n\r\n### TODO\r\n\r\n- **Improve logging**: Add detailed logging for each step of the migration process with proper stdout output to help users track progress and debug issues\r\n- **Improve model rename detection** \r\n Use a more robust method (e.g., analyzing the generated migration files) to confirm that Django has detected the rename.\r\n\r\n---\r\n\r\n### License\r\n\r\nMIT\r\n\r\n---\r\n\r\n### Author\r\n\r\nAlexander Anyaegbunam (<alexander.any7@gmail.com>)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple Django package that will aid you to switch from using the default Django Auth User model to a custom User model in an existing Django project.",
"version": "2.0.2",
"project_urls": {
"Homepage": "https://github.com/alexander-any7/django-bigtrill.git"
},
"split_keywords": [
"django",
" auth",
" custom user",
" migration",
" bigtrill",
" bigtrill migration",
" default user model",
" custom user model",
" django custom user model",
" django auth user model",
" django user model migration",
" existing project",
" django existing project"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85da5ea1d2e532aeb23e5600f70bb6bc9291394f2ad4f645cc8296d8f9ed88ed",
"md5": "099e16b0085f74ce39ba95e075310cd9",
"sha256": "655cc845604ee6ee816fc0b52c6b587b6958fdb8435d7f42d2d0908033a2bbed"
},
"downloads": -1,
"filename": "django_bigtrill-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "099e16b0085f74ce39ba95e075310cd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 11486,
"upload_time": "2025-07-16T16:45:59",
"upload_time_iso_8601": "2025-07-16T16:45:59.238227Z",
"url": "https://files.pythonhosted.org/packages/85/da/5ea1d2e532aeb23e5600f70bb6bc9291394f2ad4f645cc8296d8f9ed88ed/django_bigtrill-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "946bc7060eebf31c72899f30427c2473bd6e35731bc05e08fd631f906c52b07f",
"md5": "dff196e0ecd25fc784dbeb3e40528d64",
"sha256": "2e672e5d34fbdf9ac69f7bd8a586fc0dd15cc589c0947416cd170f38cd5f59ff"
},
"downloads": -1,
"filename": "django_bigtrill-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "dff196e0ecd25fc784dbeb3e40528d64",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 12641,
"upload_time": "2025-07-16T16:46:00",
"upload_time_iso_8601": "2025-07-16T16:46:00.111497Z",
"url": "https://files.pythonhosted.org/packages/94/6b/c7060eebf31c72899f30427c2473bd6e35731bc05e08fd631f906c52b07f/django_bigtrill-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 16:46:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexander-any7",
"github_project": "django-bigtrill",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-bigtrill"
}
JSON
