0
# PostgreSQL Configuration
1

2
PostgreSQL-specific configuration extension providing additional settings for transactional behavior and environment variable mapping.
3

4
## Capabilities
5

6
### PostgreSQL Configuration Extension
7

8
Configuration extension that adds PostgreSQL-specific settings to Flyway's configuration system.
9

10
```java { .api }
11
/**
12
 * PostgreSQL configuration extension
13
 */
14
public class PostgreSQLConfigurationExtension implements ConfigurationExtension {
15
    /**
16
     * Gets the transactional lock setting
17
     * @return true if transactional locking is enabled (default), false otherwise
18
     */
19
    public boolean isTransactionalLock();
20
    
21
    /**
22
     * Sets the transactional lock setting
23
     * @param transactionalLock Whether to use transactional locking
24
     */
25
    public void setTransactionalLock(boolean transactionalLock);
26
    
27
    /**
28
     * Maps environment variables to configuration parameters
29
     * @param environmentVariable Environment variable name
30
     * @return Configuration parameter name, or null if not mapped
31
     */
32
    public String getConfigurationParameterFromEnvironmentVariable(String environmentVariable);
33
    
34
    /**
35
     * Gets the configuration namespace for PostgreSQL settings
36
     * @return "postgresql"
37
     */
38
    public String getNamespace();
39
}
40
```
41

42
**Usage Examples:**
43

44
```java
45
import org.flywaydb.database.postgresql.PostgreSQLConfigurationExtension;
46
import org.flywaydb.core.api.configuration.ClassicConfiguration;
47

48
// Configuration is typically managed through Flyway's configuration system
49
Configuration config = Flyway.configure()
50
    .configuration(Map.of("flyway.postgresql.transactional.lock", "false"))
51
    .load()
52
    .getConfiguration();
53

54
// Access PostgreSQL-specific configuration
55
PostgreSQLConfigurationExtension pgConfig = 
56
    config.getPluginRegister().getPlugin(PostgreSQLConfigurationExtension.class);
57

58
boolean usesTransactionalLock = pgConfig.isTransactionalLock();
59
System.out.println("Transactional lock enabled: " + usesTransactionalLock);
60
```
61

62
### Transactional Model
63

64
Data model for transactional configuration settings.
65

66
```java { .api }
67
/**
68
 * Configuration model for transactional settings
69
 */
70
public class TransactionalModel {
71
    private Boolean lock;
72
    
73
    /**
74
     * Gets the lock setting
75
     * @return Lock setting (null for default)
76
     */
77
    public Boolean getLock();
78
    
79
    /**
80
     * Sets the lock setting  
81
     * @param lock Lock setting
82
     */
83
    public void setLock(Boolean lock);
84
}
85
```
86

87
## Configuration Options
88

89
### Transactional Lock
90

91
Controls whether PostgreSQL uses transactional advisory locks during migrations.
92

93
**Property**: `flyway.postgresql.transactional.lock`  
94
**Environment Variable**: `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK`  
95
**Default**: `true`  
96
**Type**: `boolean`
97

98
```java
99
// Enable transactional locking (default)
100
Flyway flyway = Flyway.configure()
101
    .configuration(Map.of("flyway.postgresql.transactional.lock", "true"))
102
    .dataSource("jdbc:postgresql://localhost:5432/mydb", "user", "password")
103
    .load();
104

105
// Disable transactional locking
106
Flyway flyway = Flyway.configure()
107
    .configuration(Map.of("flyway.postgresql.transactional.lock", "false"))
108
    .dataSource("jdbc:postgresql://localhost:5432/mydb", "user", "password")  
109
    .load();
110
```
111

112
**Impact on Connection Usage**:
113

114
```java
115
// When transactional.lock = true (default)
116
boolean useSingleConnection = database.useSingleConnection(); // returns false
117
// Uses separate connections for locking and migration execution
118

119
// When transactional.lock = false  
120
boolean useSingleConnection = database.useSingleConnection(); // returns true
121
// Uses single connection for all operations
122
```
123

124
## Environment Variable Mapping
125

126
The configuration extension maps environment variables to Flyway properties:
127

128
| Environment Variable | Configuration Property |
129
|---------------------|----------------------|
130
| `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK` | `flyway.postgresql.transactional.lock` |
131
132
**Usage Examples:**
133

134
```bash
135
# Set via environment variable
136
export FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false
137

138
# Flyway will automatically map this to flyway.postgresql.transactional.lock
139
flyway migrate
140
```
141

142
```java
143
// Programmatic environment variable handling
144
PostgreSQLConfigurationExtension extension = new PostgreSQLConfigurationExtension();
145

146
String configParam = extension.getConfigurationParameterFromEnvironmentVariable(
147
    "FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK");
148
// Returns: "flyway.postgresql.transactional.lock"
149

150
String unmappedParam = extension.getConfigurationParameterFromEnvironmentVariable(
151
    "SOME_OTHER_VAR");
152
// Returns: null
153
```
154

155
## Configuration Integration
156

157
### Plugin Registration
158

159
The configuration extension is automatically registered via the service provider interface:
160

161
```
162
META-INF/services/org.flywaydb.core.extensibility.Plugin
163
└── org.flywaydb.database.postgresql.PostgreSQLConfigurationExtension
164
```
165

166
### Flyway Integration
167

168
```java
169
import org.flywaydb.core.api.configuration.Configuration;
170

171
// Get PostgreSQL configuration from Flyway
172
Configuration flywayConfig = flyway.getConfiguration();
173
PostgreSQLConfigurationExtension pgConfig = 
174
    flywayConfig.getPluginRegister().getPlugin(PostgreSQLConfigurationExtension.class);
175

176
// Check current settings
177
if (pgConfig != null) {
178
    boolean transactionalLock = pgConfig.isTransactionalLock();
179
    System.out.println("PostgreSQL transactional lock: " + transactionalLock);
180
}
181
```
182

183
### Configuration Builder Pattern
184

185
```java
186
// Using Flyway's configuration builder
187
Flyway flyway = Flyway.configure()
188
    // Standard Flyway configuration
189
    .dataSource("jdbc:postgresql://localhost:5432/mydb", "user", "password")
190
    .locations("classpath:db/migration")
191
    
192
    // PostgreSQL-specific configuration
193
    .configuration(Map.of(
194
        "flyway.postgresql.transactional.lock", "false"
195
    ))
196
    .load();
197

198
// Migrate with custom PostgreSQL settings
199
flyway.migrate();
200
```
201

202
## Advanced Configuration
203

204
### Programmatic Configuration
205

206
```java
207
import org.flywaydb.database.postgresql.PostgreSQLConfigurationExtension;
208
import org.flywaydb.database.postgresql.TransactionalModel;
209

210
// Create configuration extension
211
PostgreSQLConfigurationExtension pgConfig = new PostgreSQLConfigurationExtension();
212

213
// Configure transactional settings
214
pgConfig.setTransactionalLock(false);
215

216
// Check configuration state
217
boolean isTransactional = pgConfig.isTransactionalLock(); // returns false
218

219
// Access internal model
220
TransactionalModel model = pgConfig.getTransactional();
221
if (model != null) {
222
    Boolean lockSetting = model.getLock(); // returns false
223
}
224
```
225

226
### Default Behavior
227

228
```java
229
// Default configuration behavior
230
PostgreSQLConfigurationExtension defaultConfig = new PostgreSQLConfigurationExtension();
231

232
// Default transactional setting
233
boolean defaultLock = defaultConfig.isTransactionalLock(); // returns true
234

235
// Namespace identification
236
String namespace = defaultConfig.getNamespace(); // returns "postgresql"
237
```
238

239
## Configuration Validation
240

241
```java
242
// Validate configuration settings
243
try {
244
    PostgreSQLConfigurationExtension pgConfig = 
245
        config.getPluginRegister().getPlugin(PostgreSQLConfigurationExtension.class);
246
        
247
    if (pgConfig == null) {
248
        System.err.println("PostgreSQL configuration extension not found");
249
    } else {
250
        boolean transactionalLock = pgConfig.isTransactionalLock();
251
        System.out.println("Transactional lock configured: " + transactionalLock);
252
    }
253
} catch (Exception e) {
254
    System.err.println("Configuration validation failed: " + e.getMessage());
255
}
256
```
257

258
## Impact on Database Operations
259

260
The configuration settings affect how the PostgreSQL database implementation behaves:
261

262
### Connection Management
263

264
```java
265
PostgreSQLDatabase database = (PostgreSQLDatabase) flyway.getConfiguration()
266
    .getDataSource()
267
    .getConnection();
268

269
// Configuration affects connection usage strategy
270
boolean singleConnection = database.useSingleConnection();
271

272
if (singleConnection) {
273
    System.out.println("Using single connection mode (transactional.lock = false)");
274
} else {
275
    System.out.println("Using multiple connection mode (transactional.lock = true)");
276
}
277
```
278

279
### Advisory Locking Behavior
280

281
```java
282
PostgreSQLConnection connection = (PostgreSQLConnection) database.getConnection();
283

284
// Locking behavior depends on configuration
285
Table migrationTable = database.getTable("flyway_schema_history");
286
connection.lock(migrationTable, () -> {
287
    // Lock implementation varies based on transactional.lock setting
288
    return "Migration operation completed";
289
});
290
```