0
# Database Management
1

2
Core database lifecycle management functionality providing the foundational services for creating, managing, and controlling Neo4j database instances with full multi-database support.
3

4
## Capabilities
5

6
### Database Management Service Builder
7

8
Primary builder for creating Neo4j database management services with comprehensive configuration options and event listener support.
9

10
```java { .api }
11
/**
12
 * Builder for creating DatabaseManagementService instances with configuration
13
 * @param databaseDirectory - Path to the database directory
14
 */
15
public final class DatabaseManagementServiceBuilder 
16
    implements Neo4jDatabaseManagementServiceBuilder {
17
    
18
    /**
19
     * Create a new builder for the specified database directory
20
     * @param databaseDirectory Path where database files will be stored
21
     */
22
    public DatabaseManagementServiceBuilder(Path databaseDirectory);
23
    
24
    /**
25
     * Set a configuration setting with type safety
26
     * @param setting The configuration setting to set
27
     * @param value The value for the setting
28
     * @return This builder for method chaining
29
     */
30
    public <T> DatabaseManagementServiceBuilder setConfig(Setting<T> setting, T value);
31
    
32
    /**
33
     * Load configuration from a properties file
34
     * @param path Path to the properties file
35
     * @return This builder for method chaining
36
     */
37
    public DatabaseManagementServiceBuilder loadPropertiesFromFile(Path path);
38
    
39
    /**
40
     * Set configuration from a map
41
     * @param config Map of settings to values
42
     * @return This builder for method chaining
43
     */
44
    public DatabaseManagementServiceBuilder setConfig(
45
        Map<Setting<?>, Object> config);
46
    
47
    /**
48
     * Set a custom log provider for user-level logging
49
     * @param userLogProvider The log provider to use
50
     * @return This builder for method chaining
51
     */
52
    public DatabaseManagementServiceBuilder setUserLogProvider(LogProvider userLogProvider);
53
    
54
    /**
55
     * Add a database event listener
56
     * @param listener The listener to add
57
     * @return This builder for method chaining
58
     */
59
    public DatabaseManagementServiceBuilder addDatabaseListener(
60
        DatabaseEventListener listener);
61
    
62
    /**
63
     * Build the database management service
64
     * @return Configured DatabaseManagementService instance
65
     */
66
    public DatabaseManagementService build();
67
}
68
```
69

70
**Usage Examples:**
71

72
```java
73
import org.neo4j.dbms.api.DatabaseManagementService;
74
import org.neo4j.dbms.api.DatabaseManagementServiceBuilder;
75
import org.neo4j.configuration.GraphDatabaseSettings;
76
import java.nio.file.Paths;
77
import java.time.Duration;
78

79
// Basic database service creation
80
DatabaseManagementService service = new DatabaseManagementServiceBuilder(
81
    Paths.get("/path/to/database"))
82
    .build();
83

84
// Advanced configuration
85
DatabaseManagementService service = new DatabaseManagementServiceBuilder(
86
    Paths.get("/path/to/database"))
87
    .setConfig(GraphDatabaseSettings.transaction_timeout, Duration.ofMinutes(5))
88
    .setConfig(GraphDatabaseSettings.data_directory, Paths.get("/custom/data"))
89
    .loadPropertiesFromFile(Paths.get("/path/to/neo4j.conf"))
90
    .addDatabaseListener(new MyDatabaseEventListener())
91
    .build();
92
```
93

94
### Database Management Service
95

96
Interface for managing databases and providing access to managed database services with full multi-database support and lifecycle control.
97

98
```java { .api }
99
/**
100
 * Service for managing multiple databases within a Neo4j instance
101
 */
102
public interface DatabaseManagementService extends AutoCloseable {
103
    
104
    /**
105
     * Get access to a specific database by name
106
     * @param databaseName Name of the database (e.g., "neo4j", "system")
107
     * @return GraphDatabaseService instance for the specified database
108
     * @throws DatabaseNotFoundException if database doesn't exist
109
     */
110
    GraphDatabaseService database(String databaseName);
111
    
112
    /**
113
     * Create a new database with the specified name
114
     * @param databaseName Name for the new database
115
     * @throws DatabaseAlreadyExistsException if database already exists
116
     */
117
    void createDatabase(String databaseName);
118
    
119
    /**
120
     * Create a new database with specific configuration
121
     * @param databaseName Name for the new database
122
     * @param databaseSpecificSettings Database-specific configuration
123
     * @throws DatabaseAlreadyExistsException if database already exists
124
     */
125
    void createDatabase(String databaseName, Configuration databaseSpecificSettings);
126
    
127
    /**
128
     * Delete an existing database
129
     * @param databaseName Name of the database to drop
130
     * @throws DatabaseNotFoundException if database doesn't exist
131
     * @throws DatabaseAliasExistsException if database has aliases that prevent dropping
132
     */
133
    void dropDatabase(String databaseName);
134
    
135
    /**
136
     * Start a stopped database
137
     * @param databaseName Name of the database to start
138
     */
139
    void startDatabase(String databaseName);
140
    
141
    /**
142
     * Stop a running database
143
     * @param databaseName Name of the database to shutdown
144
     */
145
    void shutdownDatabase(String databaseName);
146
    
147
    /**
148
     * List all available databases
149
     * @return List of database names
150
     */
151
    List<String> listDatabases();
152
    
153
    /**
154
     * Shutdown the entire database management service
155
     * This will shutdown all managed databases
156
     */
157
    void shutdown();
158
    
159
    /**
160
     * Close the database management service (same as shutdown)
161
     */
162
    @Override
163
    void close();
164
    
165
    /**
166
     * Register a database event listener
167
     * @param listener Database event listener to register
168
     */
169
    void registerDatabaseEventListener(DatabaseEventListener listener);
170
    
171
    /**
172
     * Unregister a database event listener
173
     * @param listener Database event listener to unregister
174
     */
175
    void unregisterDatabaseEventListener(DatabaseEventListener listener);
176
    
177
    /**
178
     * Register a transaction event listener for a specific database
179
     * @param databaseName Name of the database
180
     * @param listener Transaction event listener to register
181
     */
182
    void registerTransactionEventListener(String databaseName, TransactionEventListener<?> listener);
183
    
184
    /**
185
     * Unregister a transaction event listener for a specific database
186
     * @param databaseName Name of the database
187
     * @param listener Transaction event listener to unregister
188
     */
189
    void unregisterTransactionEventListener(String databaseName, TransactionEventListener<?> listener);
190
}
191
```
192

193
**Usage Examples:**
194

195
```java
196
// Database lifecycle management
197
DatabaseManagementService managementService = new DatabaseManagementServiceBuilder(dbPath)
198
    .build();
199

200
// Create and manage multiple databases
201
managementService.createDatabase("userdata");
202
managementService.createDatabase("analytics");
203

204
// List all databases
205
List<String> databases = managementService.listDatabases();
206
System.out.println("Available databases: " + databases);
207

208
// Get access to specific databases
209
GraphDatabaseService mainDb = managementService.database("neo4j");
210
GraphDatabaseService userData = managementService.database("userdata");
211

212
// Stop and start databases
213
managementService.shutdownDatabase("analytics");
214
managementService.startDatabase("analytics");
215

216
// Cleanup
217
managementService.shutdown();
218
```
219

220
### Database Event Context
221

222
Context information provided to database event listeners containing metadata about database operations.
223

224
```java { .api }
225
/**
226
 * Context information for database lifecycle events
227
 */
228
public interface DatabaseEventContext {
229
    /**
230
     * Get the name of the database involved in the event
231
     * @return Database name
232
     */
233
    String getDatabaseName();
234
    
235
    /**
236
     * Get additional metadata about the event
237
     * @return Event metadata map
238
     */
239
    Map<String, Object> getEventData();
240
}
241
```
242

243
### Exception Handling
244

245
Common exceptions thrown during database management operations.
246

247
```java { .api }
248
/**
249
 * Thrown when attempting to access a database that doesn't exist
250
 */
251
public class DatabaseNotFoundException extends RuntimeException {
252
    public DatabaseNotFoundException(String message);
253
}
254

255
/**
256
 * Thrown when attempting to create a database that already exists
257
 */
258
public class DatabaseAlreadyExistsException extends RuntimeException {
259
    public DatabaseAlreadyExistsException(String message);
260
}
261

262
/**
263
 * Thrown when a database operation fails
264
 */
265
public class DatabaseManagementException extends RuntimeException {
266
    public DatabaseManagementException(String message, Throwable cause);
267
}
268

269
/**
270
 * Thrown when attempting to drop a database that has aliases
271
 */
272
public class DatabaseAliasExistsException extends RuntimeException {
273
    public DatabaseAliasExistsException(String message);
274
}
275

276
/**
277
 * Configuration settings for database creation
278
 */
279
public interface Configuration {
280
    /**
281
     * Get a configuration value
282
     * @param setting Setting to get value for
283
     * @return Configuration value
284
     */
285
    <T> T get(Setting<T> setting);
286
    
287
    /**
288
     * Create a configuration from a map of settings
289
     * @param settings Map of settings to values
290
     * @return Configuration instance
291
     */
292
    static Configuration from(Map<Setting<?>, Object> settings) {
293
        // Implementation
294
    }
295
}
296
```
297

298
**Error Handling Example:**
299

300
```java
301
try {
302
    GraphDatabaseService db = managementService.database("nonexistent");
303
} catch (DatabaseNotFoundException e) {
304
    System.err.println("Database not found: " + e.getMessage());
305
    // Handle missing database
306
}
307

308
try {
309
    managementService.createDatabase("neo4j"); // Default database already exists
310
} catch (DatabaseAlreadyExistsException e) {
311
    System.err.println("Database already exists: " + e.getMessage());
312
    // Handle duplicate database creation
313
}
314
```