0
# Database Monitoring
1

2
Automatic monitoring of database operations through instrumented Django database backends. Tracks connection counts, query execution times, errors, and bulk operations across different database vendors.
3

4
## Capabilities
5

6
### Instrumented Database Backends
7

8
Django-prometheus provides instrumented versions of Django's database backends that automatically collect metrics on database operations.
9

10
```python { .api }
11
# PostgreSQL backend
12
django_prometheus.db.backends.postgresql.base.DatabaseWrapper
13

14
# MySQL backend  
15
django_prometheus.db.backends.mysql.base.DatabaseWrapper
16

17
# SQLite backend
18
django_prometheus.db.backends.sqlite3.base.DatabaseWrapper
19

20
# SpatiaLite backend
21
django_prometheus.db.backends.spatialite.base.DatabaseWrapper
22

23
# PostGIS backend
24
django_prometheus.db.backends.postgis.base.DatabaseWrapper
25
```
26

27
### Database Metrics Functions
28

29
```python { .api }
30
from django_prometheus.db.common import DatabaseWrapperMixin
31

32
class DatabaseWrapperMixin:
33
    """
34
    Mixin that adds Prometheus monitoring to Django database backends.
35
    Automatically applied to all instrumented database backends.
36
    """
37
    
38
    def connect(self):
39
        """
40
        Instrumented database connection method.
41
        Tracks successful connections and connection errors.
42
        """
43
    
44
    def execute(self, sql, params=None):
45
        """
46
        Instrumented query execution.
47
        Tracks query count, execution time, and errors.
48
        
49
        Parameters:
50
        - sql: str, SQL query string
51
        - params: optional query parameters
52
        """
53
    
54
    def executemany(self, sql, param_list):
55
        """
56
        Instrumented bulk query execution.
57
        Tracks bulk operation count, execution time, and errors.
58
        
59
        Parameters:
60
        - sql: str, SQL query string
61
        - param_list: list of parameter sets for bulk execution
62
        """
63
```
64

65
## Monitored Metrics
66

67
### Connection Metrics
68
- `django_db_new_connections_total`: Counter of created connections by database alias and vendor
69
- `django_db_new_connection_errors_total`: Counter of connection failures by database alias and vendor
70

71
### Query Execution Metrics
72
- `django_db_execute_total`: Counter of executed statements by database alias and vendor (including bulk)
73
- `django_db_execute_many_total`: Counter of bulk operations by database alias and vendor
74
- `django_db_query_duration_seconds`: Histogram of query duration by database alias and vendor
75
- `django_db_errors_total`: Counter of execution errors by database alias, vendor, and exception type
76

77
## Configuration
78

79
### Settings Configuration
80

81
Configure database backends in Django settings:
82

83
```python
84
# settings.py
85
DATABASES = {
86
    'default': {
87
        'ENGINE': 'django_prometheus.db.backends.postgresql',  # Instead of 'django.db.backends.postgresql'
88
        'NAME': 'mydatabase',
89
        'USER': 'mydatabaseuser',
90
        'PASSWORD': 'mypassword',
91
        'HOST': '127.0.0.1',
92
        'PORT': '5432',
93
    },
94
    'cache_db': {
95
        'ENGINE': 'django_prometheus.db.backends.sqlite3',  # Instead of 'django.db.backends.sqlite3'
96
        'NAME': '/path/to/cache.db',
97
    }
98
}
99
```
100

101
### Multiple Database Support
102

103
```python
104
DATABASES = {
105
    'default': {
106
        'ENGINE': 'django_prometheus.db.backends.postgresql',
107
        'NAME': 'main_db',
108
        # ... connection settings
109
    },
110
    'analytics': {
111
        'ENGINE': 'django_prometheus.db.backends.mysql',
112
        'NAME': 'analytics_db',
113
        # ... connection settings
114
    },
115
    'cache': {
116
        'ENGINE': 'django_prometheus.db.backends.sqlite3',
117
        'NAME': '/tmp/cache.db',
118
    }
119
}
120

121
# Each database will be tracked separately with its alias as a label
122
```
123

124
## Usage Examples
125

126
### Basic Database Monitoring
127

128
```python
129
# With instrumented backends, all ORM operations are automatically monitored
130
from myapp.models import User, Product
131

132
# These operations will be tracked in database metrics:
133
users = User.objects.filter(is_active=True)  # SELECT query tracked
134
user = User.objects.create(username='john')  # INSERT query tracked
135
user.email = 'john@example.com'
136
user.save()  # UPDATE query tracked
137
User.objects.filter(username='old').delete()  # DELETE query tracked
138

139
# Bulk operations
140
Product.objects.bulk_create([
141
    Product(name='Product 1'),
142
    Product(name='Product 2'),
143
])  # Bulk INSERT tracked
144
```
145

146
### Raw SQL Queries
147

148
```python
149
from django.db import connection
150

151
# Raw queries are also monitored
152
with connection.cursor() as cursor:
153
    cursor.execute("SELECT COUNT(*) FROM myapp_user WHERE is_active = %s", [True])
154
    result = cursor.fetchone()
155
    
156
# Bulk raw queries
157
cursor.executemany("INSERT INTO logs (message) VALUES (%s)", [
158
    ('Log message 1',),
159
    ('Log message 2',),
160
])
161
```
162

163
### Database Routing with Monitoring
164

165
```python
166
# When using database routing, each database is monitored separately
167
class DatabaseRouter:
168
    def db_for_read(self, model, **hints):
169
        if model._meta.app_label == 'analytics':
170
            return 'analytics'
171
        return 'default'
172

173
# Queries will be tracked with appropriate database alias labels
174
analytics_data = AnalyticsModel.objects.all()  # Tracked under 'analytics' alias
175
user_data = User.objects.all()  # Tracked under 'default' alias
176
```
177

178
## Metric Labels
179

180
All database metrics include the following labels:
181
- `alias`: Database connection alias (e.g., 'default', 'analytics', 'cache')
182
- `vendor`: Database vendor (e.g., 'postgresql', 'mysql', 'sqlite')
183

184
Error metrics additionally include:
185
- `type`: Exception class name (e.g., 'OperationalError', 'IntegrityError')
186

187
## Supported Database Vendors
188

189
- **PostgreSQL**: Full support including PostGIS extension
190
- **MySQL**: Full support for MySQL and MariaDB
191
- **SQLite**: Full support including SpatiaLite extension
192
- **Oracle**: Not directly supported (would need custom backend)
193

194
## Performance Considerations
195

196
- Monitoring adds minimal overhead to database operations
197
- Query timing uses high-resolution timers for accuracy
198
- Connection pooling is compatible with monitoring
199
- Bulk operations are efficiently tracked without per-item overhead
200

201
## Error Monitoring
202

203
Database errors are categorized by exception type:
204

205
```python
206
# Common error types tracked:
207
# - OperationalError: Connection issues, syntax errors
208
# - IntegrityError: Constraint violations
209
# - DataError: Invalid data for field type
210
# - DatabaseError: General database errors
211
# - InterfaceError: Database interface errors
212
```