0
# jOOQ-meta
1

2
jOOQ-meta is a comprehensive database metadata abstraction library that provides unified access to schema information across 15+ database vendors. It serves as the foundation for jOOQ's code generation system, offering a complete API for analyzing and extracting metadata from relational databases including tables, columns, constraints, relationships, user-defined types, and stored procedures.
3

4
## Package Information
5

6
- **Package Name**: jooq-meta
7
- **Package Type**: maven
8
- **Group ID**: org.jooq
9
- **Artifact ID**: jooq-meta
10
- **Language**: Java
11
- **Installation**: Add Maven dependency with coordinates `org.jooq:jooq-meta:3.20.3`
12

13
## Core Imports
14

15
```java
16
import org.jooq.meta.Database;
17
import org.jooq.meta.Databases;
18
import org.jooq.meta.Definition;
19
import org.jooq.meta.TableDefinition;
20
import org.jooq.meta.ColumnDefinition;
21
import org.jooq.meta.SchemaDefinition;
22
import org.jooq.meta.CatalogDefinition;
23
import org.jooq.meta.Relations;
24
```
25

26
For database-specific implementations:
27

28
```java
29
import org.jooq.meta.postgres.PostgresDatabase;
30
import org.jooq.meta.mysql.MySQLDatabase;
31
import org.jooq.meta.h2.H2Database;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.jooq.meta.Database;
38
import org.jooq.meta.Databases;
39
import org.jooq.meta.SchemaDefinition;
40
import org.jooq.meta.TableDefinition;
41
import org.jooq.meta.ColumnDefinition;
42
import org.jooq.SQLDialect;
43
import java.sql.Connection;
44
import java.sql.DriverManager;
45

46
// Create database connection
47
Connection connection = DriverManager.getConnection(
48
    "jdbc:postgresql://localhost:5432/mydb", "user", "password");
49

50
// Create database metadata abstraction
51
Database database = Databases.database(SQLDialect.POSTGRES);
52
database.setConnection(connection);
53

54
// Explore schema structure
55
List<SchemaDefinition> schemas = database.getSchemata();
56
for (SchemaDefinition schema : schemas) {
57
    System.out.println("Schema: " + schema.getName());
58
    
59
    List<TableDefinition> tables = database.getTables(schema);
60
    for (TableDefinition table : tables) {
61
        System.out.println("  Table: " + table.getName());
62
        
63
        List<ColumnDefinition> columns = table.getColumns();
64
        for (ColumnDefinition column : columns) {
65
            System.out.println("    Column: " + column.getName() + 
66
                             " (" + column.getType().getType() + ")");
67
        }
68
    }
69
}
70

71
// Clean up
72
database.close();
73
```
74

75
## Architecture
76

77
jOOQ-meta is built around several key architectural components:
78

79
- **Database Interface**: Central abstraction for all metadata operations providing unified access across different database vendors
80
- **Definition Hierarchy**: Type-safe object model representing all database objects (tables, columns, constraints, etc.) with consistent API
81
- **Vendor-Specific Implementations**: Optimized database drivers for 15+ database systems (PostgreSQL, MySQL, Oracle, etc.)
82
- **Configuration System**: Flexible XML-based configuration supporting include/exclude patterns, type mapping, and synthetic objects
83
- **Type Resolution**: Sophisticated system for mapping database types to Java types with customization support
84
- **Relationship Management**: Comprehensive constraint and foreign key relationship tracking and navigation
85

86
## Capabilities
87

88
### Database Connection and Management
89

90
Core database abstraction and connection management providing the entry point for all metadata operations.
91

92
```java { .api }
93
static Database database(SQLDialect dialect);
94
static Class<? extends Database> databaseClass(SQLDialect dialect);
95
void setConnection(Connection connection);
96
Connection getConnection();
97
SQLDialect getDialect();
98
void setDialect(SQLDialect dialect);
99
DSLContext create();
100
void close();
101
```
102

103
[Database Management](./database-management.md)
104

105
### Schema Structure Discovery
106

107
Complete schema exploration including catalogs, schemas, tables, and columns with comprehensive metadata extraction.
108

109
```java { .api }
110
List<CatalogDefinition> getCatalogs();
111
List<SchemaDefinition> getSchemata();
112
List<TableDefinition> getTables(SchemaDefinition schema);
113
TableDefinition getTable(SchemaDefinition schema, String name);
114
```
115

116
[Schema Discovery](./schema-discovery.md)
117

118
### Table and Column Analysis
119

120
Detailed table structure analysis including columns, data types, nullability, defaults, and special properties.
121

122
```java { .api }
123
List<ColumnDefinition> getColumns();
124
ColumnDefinition getColumn(String name);
125
DataTypeDefinition getType();
126
boolean isIdentity();
127
boolean isNullable();
128
String getDefaultValue();
129
```
130

131
[Table Analysis](./table-analysis.md)
132

133
### Constraint and Relationship Management
134

135
Complete constraint discovery and relationship navigation including primary keys, foreign keys, unique constraints, and check constraints.
136

137
```java { .api }
138
UniqueKeyDefinition getPrimaryKey();
139
List<UniqueKeyDefinition> getUniqueKeys();
140
List<ForeignKeyDefinition> getForeignKeys();
141
List<CheckConstraintDefinition> getCheckConstraints();
142
Relations getRelations();
143
```
144

145
[Constraints and Relationships](./constraints-relationships.md)
146

147
### User-Defined Types and Advanced Objects
148

149
Support for complex database objects including user-defined types, enums, domains, arrays, and stored procedures.
150

151
```java { .api }
152
List<UDTDefinition> getUDTs(SchemaDefinition schema);
153
List<EnumDefinition> getEnums(SchemaDefinition schema);
154
List<DomainDefinition> getDomains(SchemaDefinition schema);
155
List<RoutineDefinition> getRoutines(SchemaDefinition schema);
156
List<SequenceDefinition> getSequences(SchemaDefinition schema);
157
```
158

159
[Advanced Database Objects](./advanced-objects.md)
160

161
### Configuration and Customization
162

163
Flexible configuration system supporting include/exclude patterns, forced types, synthetic objects, and advanced customization options.
164

165
```java { .api }
166
void setIncludes(String[] includes);
167
void setExcludes(String[] excludes);
168
void setConfiguredForcedTypes(List<ForcedType> forcedTypes);
169
void setConfiguredSyntheticObjects(SyntheticObjectsType syntheticObjects);
170
```
171

172
[Configuration](./configuration.md)
173

174
### Multi-Database Support
175

176
Vendor-specific implementations optimized for different database systems with consistent API across all supported databases.
177

178
```java { .api }
179
class PostgresDatabase extends AbstractDatabase { }
180
class MySQLDatabase extends AbstractDatabase { }
181
class H2Database extends AbstractDatabase { }
182
class SQLiteDatabase extends AbstractDatabase { }
183
```
184

185
[Database Implementations](./database-implementations.md)
186

187
## Types
188

189
```java { .api }
190
interface Database extends AutoCloseable {
191
    List<CatalogDefinition> getCatalogs();
192
    CatalogDefinition getCatalog(String name);
193
    List<SchemaDefinition> getSchemata();
194
    List<SchemaDefinition> getSchemata(CatalogDefinition catalog);
195
    SchemaDefinition getSchema(String name);
196
    List<TableDefinition> getTables();
197
    List<TableDefinition> getTables(SchemaDefinition schema);
198
    TableDefinition getTable(SchemaDefinition schema, String name);
199
    TableDefinition getTable(SchemaDefinition schema, String name, boolean ignoreCase);
200
    Relations getRelations();
201
    List<SequenceDefinition> getSequences(SchemaDefinition schema);
202
    List<UDTDefinition> getUDTs(SchemaDefinition schema);
203
    List<RoutineDefinition> getRoutines(SchemaDefinition schema);
204
    List<EnumDefinition> getEnums(SchemaDefinition schema);
205
    List<DomainDefinition> getDomains(SchemaDefinition schema);
206
    Connection getConnection();
207
    void setConnection(Connection connection);
208
    SQLDialect getDialect();
209
    void setDialect(SQLDialect dialect);
210
    DSLContext create();
211
    void close();
212
}
213

214
interface Definition {
215
    String getName();
216
    String getInputName();
217
    String getOutputName();
218
    String getComment();
219
    String getQualifiedName();
220
    Database getDatabase();
221
    SchemaDefinition getSchema();
222
    CatalogDefinition getCatalog();
223
}
224

225
interface TableDefinition extends Definition {
226
    List<ColumnDefinition> getColumns();
227
    ColumnDefinition getColumn(String name);
228
    UniqueKeyDefinition getPrimaryKey();
229
    List<UniqueKeyDefinition> getUniqueKeys();
230
    List<ForeignKeyDefinition> getForeignKeys();
231
    boolean isView();
232
    boolean isMaterializedView();
233
}
234

235
interface ColumnDefinition extends TypedElementDefinition<TableDefinition> {
236
    TableDefinition getContainer();
237
    DataTypeDefinition getType();
238
    boolean isIdentity();
239
    boolean isNullable();
240
    boolean isHidden();
241
    String getDefaultValue();
242
    int getPosition();
243
}
244

245
interface SchemaDefinition extends Definition {
246
    CatalogDefinition getCatalog();
247
    List<TableDefinition> getTables();
248
    List<SequenceDefinition> getSequences();
249
    List<UDTDefinition> getUDTs();
250
    List<RoutineDefinition> getRoutines();
251
}
252

253
interface CatalogDefinition extends Definition {
254
    List<SchemaDefinition> getSchemata();
255
}
256

257
interface Relations {
258
    UniqueKeyDefinition getPrimaryKey(TableDefinition table);
259
    List<ForeignKeyDefinition> getForeignKeys(TableDefinition table);
260
    List<ForeignKeyDefinition> getExportedKeys(TableDefinition table);
261
}
262

263
class Databases {
264
    static Database database(SQLDialect dialect);
265
    static Class<? extends Database> databaseClass(SQLDialect dialect);
266
}
267
```