249 Update documentation for NetBox v4.3 DATABASES config change (#266)

arthanson · jeremystretch · web-flow · commit 47891cc0eddb · 2025-06-17T09:30:18.000-04:00
* #249 update documentation for NetBox v4.3 DATABASES config change * #249 update documentation for NetBox v4.3 DATABASES config change * #249 update documentation for NetBox v4.3 DATABASES config change * #249 update documentation for NetBox v4.3 DATABASES config change * #249 update documentation for NetBox v4.3 DATABASES config change * #249 update documentation for NetBox v4.3 DATABASES config change * Simplify quick start instructions * Restructure installation documentation --------- Co-authored-by: Jeremy Stretch <jstretch@netboxlabs.com>
diff --git 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,18 +38,23 @@ 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.
+5. Configure the database and router 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
 DATABASE_ROUTERS = [
     'netbox_branching.database.BranchAwareRouter',
 ]
diff --git a/docs/index.md b/docs/index.md
@@ -72,19 +72,17 @@ 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):
 
 ```postgresql
 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,15 +93,15 @@ 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:
 
 ```
 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,12 +118,42 @@ 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
+
+Wrap your `DATABASES` configuration parameter with `DynamicSchemaDict` in `configuration.py`, as shown below.
+
+!!! 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
+
+DATABASES = DynamicSchemaDict({
+    'default': {
+        'ENGINE': 'django.db.backends.postgresql',
+        'NAME': 'netbox',
+        'USER': 'netbox',
+        ...
+    }
+})
+```
+
+Additionally, declare `DATABASE_ROUTERS` to employ the plugin's custom database router to support branching.
+
+```python
+DATABASE_ROUTERS = [
+    'netbox_branching.database.BranchAwareRouter',
+]
+```
 
-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.
+#### NetBox v4.2 and Earlier
 
-Create a new file named `local_settings.py` in the same directory as `settings.py`, and add the content below.
+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.
+    
 ```python
 from netbox_branching.utilities import DynamicSchemaDict
 from .configuration import DATABASE
@@ -141,7 +169,7 @@ DATABASE_ROUTERS = [
 ]
 ```
 
-#### 5. Database Migrations
+### 6. Database Migrations
 
 Run the included database migrations:
 
