From b896f2111c8db5fe0d513d2668394405fd933d6b Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 22 May 2025 11:17:41 -0700 Subject: [PATCH 1/8] #249 update documentation for NetBox v4.3 DATABASES config change --- README.md | 42 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5196850..816cf94 100644 --- a/README.md +++ b/README.md @@ -38,24 +38,54 @@ PLUGINS = [ ] ``` -5. Create `local_settings.py` (in the same directory as `settings.py`) to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support. +> [!NOTE] +> If using a version of NetBox older then v4.3, skip steps 5 and 6 below and instead do the following: +> +> Create `local_settings.py` (in the same directory as `settings.py`) to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support. +> +> ```python +> from netbox_branching.utilities import DynamicSchemaDict +> from .configuration import DATABASE +> +> # Wrap DATABASES with DynamicSchemaDict for dynamic schema support +> DATABASES = DynamicSchemaDict({ +> 'default': DATABASE, +> }) +> +> # Employ our custom database router +> DATABASE_ROUTERS = [ +> 'netbox_branching.database.BranchAwareRouter', +> ] +> ``` + +5. Add `DynamicSchemaDict` to `DATABASES` setting in `configuration.py`. ```python from netbox_branching.utilities import DynamicSchemaDict -from .configuration import DATABASE -# Wrap DATABASES with DynamicSchemaDict for dynamic schema support DATABASES = DynamicSchemaDict({ - 'default': DATABASE, + 'default': { + 'ENGINE': 'django.db.backends.postgresql', + 'NAME': 'netbox', # Database name + 'USER': 'netbox', # PostgreSQL username + 'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password + 'HOST': 'localhost', # Database server + 'PORT': '', # Database port (leave blank for default) + 'CONN_MAX_AGE': 300, # Max database connection age + } }) +``` + +6. Add `DATABASE_ROUTERS` to `configuration.py`. -# Employ our custom database router +```python DATABASE_ROUTERS = [ 'netbox_branching.database.BranchAwareRouter', ] ``` -6. Run NetBox migrations: + +7. Run NetBox migrations: ``` $ ./manage.py migrate From 33a7198edde0d393448c9cff91ed42a9f332686d Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 22 May 2025 11:31:44 -0700 Subject: [PATCH 2/8] #249 update documentation for NetBox v4.3 DATABASES config change --- README.md | 27 ++++----------------------- docs/index.md | 38 +++++++++++++++++++++++++++++++++----- 2 files changed, 37 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 816cf94..689ae37 100644 --- a/README.md +++ b/README.md @@ -38,26 +38,6 @@ PLUGINS = [ ] ``` -> [!NOTE] -> If using a version of NetBox older then v4.3, skip steps 5 and 6 below and instead do the following: -> -> Create `local_settings.py` (in the same directory as `settings.py`) to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support. -> -> ```python -> from netbox_branching.utilities import DynamicSchemaDict -> from .configuration import DATABASE -> -> # Wrap DATABASES with DynamicSchemaDict for dynamic schema support -> DATABASES = DynamicSchemaDict({ -> 'default': DATABASE, -> }) -> -> # Employ our custom database router -> DATABASE_ROUTERS = [ -> 'netbox_branching.database.BranchAwareRouter', -> ] -> ``` - 5. Add `DynamicSchemaDict` to `DATABASES` setting in `configuration.py`. ```python @@ -68,7 +48,7 @@ DATABASES = DynamicSchemaDict({ 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'netbox', # Database name 'USER': 'netbox', # PostgreSQL username - 'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password + 'PASSWORD': 'password', # PostgreSQL password 'HOST': 'localhost', # Database server 'PORT': '', # Database port (leave blank for default) 'CONN_MAX_AGE': 300, # Max database connection age @@ -76,7 +56,9 @@ DATABASES = DynamicSchemaDict({ }) ``` -6. Add `DATABASE_ROUTERS` to `configuration.py`. +Make sure to change the parameters as appropriate for your installation. + +1. Add `DATABASE_ROUTERS` to `configuration.py`. ```python DATABASE_ROUTERS = [ @@ -84,7 +66,6 @@ DATABASE_ROUTERS = [ ] ``` - 7. Run NetBox migrations: ``` diff --git a/docs/index.md b/docs/index.md index 200c688..c6de796 100644 --- a/docs/index.md +++ b/docs/index.md @@ -122,17 +122,23 @@ PLUGINS = [ #### 4. Configuration -This plugin employs dynamic schema resolution, which requires that we override two low-level Django settings. First, we'll wrap NetBox's configured `DATABASE` parameter with `DynamicSchemaDict` to support dynamic schemas. Second, we'll employ the plugin's custom database router. +This plugin employs dynamic schema resolution, which requires that we override two low-level Django settings. First, we'll wrap NetBox's configured `DATABASES` parameter with `DynamicSchemaDict` to support dynamic schemas. Second, we'll employ the plugin's custom database router. -Create a new file named `local_settings.py` in the same directory as `settings.py`, and add the content below. +Add `DynamicSchemaDict` to `DATABASES` setting in `configuration.py`. ```python from netbox_branching.utilities import DynamicSchemaDict -from .configuration import DATABASE -# Wrap DATABASES with DynamicSchemaDict for dynamic schema support DATABASES = DynamicSchemaDict({ - 'default': DATABASE, + 'default': { + 'ENGINE': 'django.db.backends.postgresql', + 'NAME': 'netbox', # Database name + 'USER': 'netbox', # PostgreSQL username + 'PASSWORD': 'password', # PostgreSQL password + 'HOST': 'localhost', # Database server + 'PORT': '', # Database port (leave blank for default) + 'CONN_MAX_AGE': 300, # Max database connection age + } }) # Employ our custom database router @@ -141,6 +147,28 @@ DATABASE_ROUTERS = [ ] ``` +Make sure to change the parameters as appropriate for your installation. + +!!! note + If using a version of NetBox older then v4.3, instead of adding these to `configuration.py` do the following: + + Create `local_settings.py` (in the same directory as `settings.py`) to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support. + + ```python + from netbox_branching.utilities import DynamicSchemaDict + from .configuration import DATABASE + + # Wrap DATABASES with DynamicSchemaDict for dynamic schema support + DATABASES = DynamicSchemaDict({ + 'default': DATABASE, + }) + + # Employ our custom database router + DATABASE_ROUTERS = [ + 'netbox_branching.database.BranchAwareRouter', + ] + ``` + #### 5. Database Migrations Run the included database migrations: From f2faa675016fcaa1887a7d3f1e531f8202ef4fd4 Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 22 May 2025 11:34:34 -0700 Subject: [PATCH 3/8] #249 update documentation for NetBox v4.3 DATABASES config change --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 689ae37..ad3a464 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ DATABASES = DynamicSchemaDict({ Make sure to change the parameters as appropriate for your installation. -1. Add `DATABASE_ROUTERS` to `configuration.py`. +6. Add `DATABASE_ROUTERS` to `configuration.py`. ```python DATABASE_ROUTERS = [ From cea7f1e01570b4d66cf5901211d686b33325aab1 Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 22 May 2025 11:36:16 -0700 Subject: [PATCH 4/8] #249 update documentation for NetBox v4.3 DATABASES config change --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ad3a464..5119d60 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,9 @@ PLUGINS = [ ] ``` -5. Add `DynamicSchemaDict` to `DATABASES` setting in `configuration.py`. +5. Make the following changes to `configuration.py`. + +Add `DynamicSchemaDict` to `DATABASES` setting: ```python from netbox_branching.utilities import DynamicSchemaDict @@ -56,9 +58,9 @@ DATABASES = DynamicSchemaDict({ }) ``` -Make sure to change the parameters as appropriate for your installation. +**Note:** Make sure to change the parameters as appropriate for your installation. -6. Add `DATABASE_ROUTERS` to `configuration.py`. +Add `DATABASE_ROUTERS` to `configuration.py`. ```python DATABASE_ROUTERS = [ @@ -66,7 +68,7 @@ DATABASE_ROUTERS = [ ] ``` -7. Run NetBox migrations: +6. Run NetBox migrations: ``` $ ./manage.py migrate From 597d3c56b4c71e105355c06948eda62b4f32e650 Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 22 May 2025 11:37:07 -0700 Subject: [PATCH 5/8] #249 update documentation for NetBox v4.3 DATABASES config change --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5119d60..7549597 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ PLUGINS = [ 5. Make the following changes to `configuration.py`. -Add `DynamicSchemaDict` to `DATABASES` setting: +Add `DynamicSchemaDict` to `DATABASES` setting (Make sure to change the parameters as appropriate for your installation): ```python from netbox_branching.utilities import DynamicSchemaDict @@ -58,8 +58,6 @@ DATABASES = DynamicSchemaDict({ }) ``` -**Note:** Make sure to change the parameters as appropriate for your installation. - Add `DATABASE_ROUTERS` to `configuration.py`. ```python @@ -68,7 +66,7 @@ DATABASE_ROUTERS = [ ] ``` -6. Run NetBox migrations: +1. Run NetBox migrations: ``` $ ./manage.py migrate From bcd48617bde632db13ac7c3c2184959915a2a4f4 Mon Sep 17 00:00:00 2001 From: Arthur Date: Thu, 22 May 2025 11:37:31 -0700 Subject: [PATCH 6/8] #249 update documentation for NetBox v4.3 DATABASES config change --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7549597..34991d8 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ DATABASE_ROUTERS = [ ] ``` -1. Run NetBox migrations: +6. Run NetBox migrations: ``` $ ./manage.py migrate From b6e010176ed49bb734966532129ba52f4f920b16 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Mon, 16 Jun 2025 15:52:19 -0400 Subject: [PATCH 7/8] Simplify quick start instructions --- README.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 34991d8..b6cd5d8 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This [NetBox](http://netboxlabs.com/oss/netbox/) plugin introduces branching fun ## Requirements -* NetBox v4.1 or later +* NetBox v4.3 or later * PostgreSQL 12 or later ## Installation @@ -38,9 +38,7 @@ PLUGINS = [ ] ``` -5. Make the following changes to `configuration.py`. - -Add `DynamicSchemaDict` to `DATABASES` setting (Make sure to change the parameters as appropriate for your installation): +5. Configure the database and router in `configuration.py`: ```python from netbox_branching.utilities import DynamicSchemaDict @@ -56,11 +54,7 @@ DATABASES = DynamicSchemaDict({ 'CONN_MAX_AGE': 300, # Max database connection age } }) -``` -Add `DATABASE_ROUTERS` to `configuration.py`. - -```python DATABASE_ROUTERS = [ 'netbox_branching.database.BranchAwareRouter', ] From 5e6fb05f9c06001554256b7c9d13f13d34787db9 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Mon, 16 Jun 2025 15:52:54 -0400 Subject: [PATCH 8/8] Restructure installation documentation --- docs/index.md | 74 +++++++++++++++++++++++++-------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/index.md b/docs/index.md index c6de796..68f9510 100644 --- a/docs/index.md +++ b/docs/index.md @@ -72,9 +72,9 @@ sequenceDiagram Branch->>Main: Merge branch ``` -## Getting Started +## Plugin Installation -### Database Preparation +### 1. Database Preparation Before installing this plugin, ensure that the PostgreSQL user as which NetBox authenticates has permission to create new schemas in the database. This can be achieved by issuing the following command in the PostgreSQL shell (substituting `$database` and `$user` with their respective values): @@ -82,9 +82,7 @@ Before installing this plugin, ensure that the PostgreSQL user as which NetBox a GRANT CREATE ON DATABASE $database TO $user; ``` -### Plugin Installation - -#### 1. Virtual Environment +### 2. Virtual Environment The plugin can be installed from [PyPI](https://pypi.org/project/netboxlabs-netbox-branching/). First, activate the Python virtual environment used by NetBox (which is typically located at `/opt/netbox/venv/`): @@ -95,7 +93,7 @@ source /opt/netbox/venv/bin/activate !!! note You may need to modify the `source` command above if your virtual environment has been installed in a different location. -#### 2. Python Package +### 3. Python Package Use `pip` to install the Python package: @@ -103,7 +101,7 @@ Use `pip` to install the Python package: pip install netboxlabs-netbox-branching ``` -#### 3. Enable Plugin +### 4. Enable Plugin Add `netbox_branching` to **the end** of the `PLUGINS` list in `configuration.py`. @@ -120,11 +118,14 @@ PLUGINS = [ !!! note If there are no plugins already installed, you might need to create this parameter. If so, be sure to define `PLUGINS` as a list _containing_ the plugin name as above, rather than just the name. -#### 4. Configuration +### 5. Configuration + +#### NetBox v4.3 and Later -This plugin employs dynamic schema resolution, which requires that we override two low-level Django settings. First, we'll wrap NetBox's configured `DATABASES` parameter with `DynamicSchemaDict` to support dynamic schemas. Second, we'll employ the plugin's custom database router. +Wrap your `DATABASES` configuration parameter with `DynamicSchemaDict` in `configuration.py`, as shown below. -Add `DynamicSchemaDict` to `DATABASES` setting in `configuration.py`. +!!! note + If upgrading from an earlier version of NetBox, you may need to replace the legacy `DATABASE` (singular) parameter with `DATABASES` (plural). ```python from netbox_branching.utilities import DynamicSchemaDict @@ -132,44 +133,43 @@ from netbox_branching.utilities import DynamicSchemaDict DATABASES = DynamicSchemaDict({ 'default': { 'ENGINE': 'django.db.backends.postgresql', - 'NAME': 'netbox', # Database name - 'USER': 'netbox', # PostgreSQL username - 'PASSWORD': 'password', # PostgreSQL password - 'HOST': 'localhost', # Database server - 'PORT': '', # Database port (leave blank for default) - 'CONN_MAX_AGE': 300, # Max database connection age + 'NAME': 'netbox', + 'USER': 'netbox', + ... } }) +``` -# Employ our custom database router +Additionally, declare `DATABASE_ROUTERS` to employ the plugin's custom database router to support branching. + +```python DATABASE_ROUTERS = [ 'netbox_branching.database.BranchAwareRouter', ] ``` -Make sure to change the parameters as appropriate for your installation. +#### NetBox v4.2 and Earlier -!!! note - If using a version of NetBox older then v4.3, instead of adding these to `configuration.py` do the following: - - Create `local_settings.py` (in the same directory as `settings.py`) to override the `DATABASES` & `DATABASE_ROUTERS` settings. This enables dynamic schema support. - - ```python - from netbox_branching.utilities import DynamicSchemaDict - from .configuration import DATABASE - - # Wrap DATABASES with DynamicSchemaDict for dynamic schema support - DATABASES = DynamicSchemaDict({ - 'default': DATABASE, - }) +If using NetBox v4.2 or earlier, these changes must be made in `local_settings.py`, as the `DATABASES` and `DATABASE_ROUTERS` configuration parameters were not introduced until NetBox v4.3. + +Create a file named `local_settings.py` in the same directory as `configuration.py`, and add the following content. - # Employ our custom database router - DATABASE_ROUTERS = [ - 'netbox_branching.database.BranchAwareRouter', - ] - ``` +```python +from netbox_branching.utilities import DynamicSchemaDict +from .configuration import DATABASE + +# Wrap DATABASES with DynamicSchemaDict for dynamic schema support +DATABASES = DynamicSchemaDict({ + 'default': DATABASE, +}) + +# Employ our custom database router +DATABASE_ROUTERS = [ + 'netbox_branching.database.BranchAwareRouter', +] +``` -#### 5. Database Migrations +### 6. Database Migrations Run the included database migrations: