1package database
 2
 3import "context"
 4
 5// StoreExtender is an extension of the Store interface that provides optional optimizations and
 6// database-specific features. While not required by the core goose package, implementing these
 7// methods can improve performance and functionality for specific databases.
 8//
 9// IMPORTANT: This interface may be expanded in future versions. Implementors MUST be prepared to
10// update their implementations when new methods are added, either by implementing the new
11// functionality or returning [errors.ErrUnsupported].
12//
13// The goose package handles these extended capabilities through a [controller.StoreController],
14// which automatically uses optimized methods when available while falling back to default behavior
15// when they're not implemented.
16//
17// Example usage to verify implementation:
18//
19//	var _ StoreExtender = (*CustomStoreExtended)(nil)
20//
21// In short, it's exported to allows implementors to have a compile-time check that they are
22// implementing the interface correctly.
23type StoreExtender interface {
24	Store
25
26	// TableExists checks if the migrations table exists in the database. Implementing this method
27	// allows goose to optimize table existence checks by using database-specific system catalogs
28	// (e.g., pg_tables for PostgreSQL, sqlite_master for SQLite) instead of generic SQL queries.
29	//
30	// Return [errors.ErrUnsupported] if the database does not provide an efficient way to check
31	// table existence.
32	TableExists(ctx context.Context, db DBTxConn) (bool, error)
33}