Documentation
¶
Index ¶
- Constants
- Variables
- func Change(name string, fn func(driver *Driver))
- func ContextQueryExec[T any](ctx context.Context, driver string, query string, args []any, flags QueryFlag, ...) (T, error)
- func DBToDefaultGoType(dbType dbtype.Type) reflect.Type
- func DBType(field attrs.FieldDefinition) (dbType dbtype.Type, ok bool)
- func DatabaseError(driverOrName any, err error) (errors.DatabaseError, error, bool)
- func FieldType(field attrs.FieldDefinition) reflect.Type
- func LogSQL(ctx context.Context, from string, err error, query string, args ...any) (logged bool)
- func LogSQLScope(ctx context.Context, log bool, fn func(context.Context) error) (context.Context, error, bool)
- func Register(name string, driver Driver)
- func RegisterGoType(typeName string, typ any)
- func SetLogSQLContext(ctx context.Context, log bool) context.Context
- func StringForType(i any) string
- func TypeFromString(typeString string) (reflect.Type, bool)
- type BLOB
- type Bool
- type Bytes
- type Char
- type DB
- type Database
- type DateTime
- func (t DateTime) Add(d time.Duration) DateTime
- func (t DateTime) IsZero() bool
- func (t DateTime) MarshalJSON() ([]byte, error)
- func (t *DateTime) Scan(value any) error
- func (t DateTime) String() string
- func (t DateTime) Time() time.Time
- func (t *DateTime) UnmarshalJSON(data []byte) error
- func (t DateTime) Value() (driver.Value, error)
- type Driver
- type DriverMariaDB
- type DriverMySQL
- type DriverPostgres
- type DriverSQLite
- type Email
- type Float
- type Int
- type JSON
- type LocalTime
- func (t LocalTime) Add(d time.Duration) LocalTime
- func (t LocalTime) IsZero() bool
- func (t LocalTime) MarshalJSON() ([]byte, error)
- func (t *LocalTime) Scan(value any) error
- func (t LocalTime) String() string
- func (t LocalTime) Time() time.Time
- func (t *LocalTime) UnmarshalJSON(data []byte) error
- func (t LocalTime) Value() (driver.Value, error)
- type OpenOption
- type Query
- type QueryFlag
- type QueryInformation
- type SQLRow
- type SQLRows
- type String
- type SupportsReturningType
- type Text
- type Timestamp
- func (t Timestamp) Add(d time.Duration) Timestamp
- func (t Timestamp) IsZero() bool
- func (t Timestamp) MarshalJSON() ([]byte, error)
- func (t *Timestamp) Scan(value any) error
- func (t Timestamp) String() string
- func (t Timestamp) Time() time.Time
- func (t *Timestamp) UnmarshalJSON(data []byte) error
- func (t Timestamp) Value() (driver.Value, error)
- type Transaction
- type ULID
- func (id ULID) Bytes() []byte
- func (id ULID) Compare(other ulid.ULID) int
- func (id ULID) Entropy() []byte
- func (id ULID) IsZero() bool
- func (id ULID) MarshalBinary() ([]byte, error)
- func (id ULID) MarshalBinaryTo(dst []byte) error
- func (id ULID) MarshalText() ([]byte, error)
- func (id ULID) MarshalTextTo(dst []byte) error
- func (id *ULID) Scan(src interface{}) error
- func (id *ULID) SetEntropy(e []byte) error
- func (id *ULID) SetTime(ms uint64) error
- func (id ULID) String() string
- func (id ULID) Time() uint64
- func (id ULID) Timestamp() time.Time
- func (id *ULID) UnmarshalBinary(data []byte) error
- func (id *ULID) UnmarshalText(v []byte) error
- func (id ULID) Value() (driver.Value, error)
- type UUID
- type Uint
- type Unwrapper
Constants ¶
const MARIADB_DRIVER_NAME = "mariadb"
const MYSQL_DRIVER_NAME = "mysql"
const POSTGRES_DRIVER_NAME = "postgres"
const SQLITE3_DRIVER_NAME = "sqlite3"
Variables ¶
var ( LOG_SQL_QUERIES = true LOG_SQL_NAMESPACE = "SQL" )
Functions ¶
func Change ¶
Change allows you to change a driver's properties within a function.
This is only really useful for testing purposes, where you might want to change the behavior of a driver during tests.
func ContextQueryExec ¶
func DBToDefaultGoType ¶
DBToDefaultGoType converts a database type to its default Go representation.
This should only be used as a last resort, as it does not take into account the actual type that the value was first defined as.
I.E, if a field is defined as uuid.UUID, it will return a type of dbtype.UUID. This means that the value will be interpreted as UUID, and not as uuid.UUID.
Whenever possible, use TypeFromString to convert a type string to a Go type.
func DBType ¶
func DBType(field attrs.FieldDefinition) (dbType dbtype.Type, ok bool)
DBType returns the database type of the field definition.
It checks if the field implements [CanDBType] and calls its [CanDBType.DBType] method. If it does not implement [CanDBType], it will check the [TYPES] registry to find the database type based on the field's reflect.Type.
func DatabaseError ¶
DatabaseError converts a driver error to a errors.DatabaseError and a boolean indicating whether the driver was able to convert the error.
func FieldType ¶
func FieldType(field attrs.FieldDefinition) reflect.Type
FieldType returns the reflect.Type of the field definition.
It does so by calling attrs.FieldDefinition.Type on the field.
If the field is a relation, it will return the related models' primary field reflect.Type
func LogSQL ¶
LogSQL logs the SQL query and its arguments if logging is enabled in the context.
It logs the query with the source of the query (from) and the error if it exists.
If the error is not nil, it logs an error message; otherwise, it logs a debug message.
func LogSQLScope ¶
func LogSQLScope(ctx context.Context, log bool, fn func(context.Context) error) (context.Context, error, bool)
LogSQLScope takes a context, a bool and a function, and returns a new context with SQL logging enabled or disabled based on the bool value.
It returns three values: - A new context with the SQL logging flag set. - A possible error returned by the function. - A boolean indicating whether the SQL query was logged or not.
func Register ¶
Register registers a driver with the given database name.
This is used to: - determine the proper returning support for the driver - open a database connection using the registered opener
If your driver is not one of: - github.com/go-django-queries/src/drivers.DriverMariaDB - github.com/go-sql-driver/mysql.MySQLDriver - github.com/mattn/go-sqlite3.SQLiteDriver - github.com/jackc/pgx/v5/stdlib.Driver
Then it explicitly needs to be registered here.
func RegisterGoType ¶
RegisterGoType registers a Go type with a string identifier.
It stores the full package path and type name of the Go type, including pointer levels, in the registeredTypeConversions map.
After registering, the type can be retrieved using the full type name. This is useful, for example in engine_table.go where we need to convert default values from JSON to Go types.
This function is exposed in case you want to register custom Go types OR for types which have been migrated to another package, but the old type name is still used in migration files.
func SetLogSQLContext ¶
SetLogSQL sets the logging flag for SQL queries in the context.
It allows you to enable or disable SQL query logging for the current context.
func StringForType ¶
Types ¶
type DB ¶
type DB interface {
Unwrap() any
QueryContext(ctx context.Context, query string, args ...any) (SQLRows, error)
QueryRowContext(ctx context.Context, query string, args ...any) SQLRow
ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}
This interface is the base for all database interactions.
It is used to specify a unified way to interact with the database, regardless of the underlying driver or database type.
If a transaction was started, the queryset should return the transaction instead of the database connection when calling github.com/Nigel2392/go-django/queries/src.QuerySet.DB.
type Database ¶
type Database interface {
DB
Ping(context.Context) error
Driver() driver.Driver
Begin(ctx context.Context) (Transaction, error)
Close() error
}
Database interface represents a database connection.
It is used to interact with the database, execute queries, and manage transactions.
An implementation of this interface can be found in `db_impl_sql.go` for SQL databases, or for Postgress it is in `db_impl_pgx.go`.
func Open ¶
Open opens a database connection using the registered opener for the given driver name.
This should always be used instead of directly using sql.Open or pgx.Connect.
type DateTime ¶
func CurrentDateTime ¶
func CurrentDateTime() DateTime
func (DateTime) MarshalJSON ¶
func (*DateTime) UnmarshalJSON ¶
type Driver ¶
type Driver struct {
Name string
SupportsReturning SupportsReturningType
Driver driver.Driver
Open func(ctx context.Context, drv *Driver, dsn string, opts ...OpenOption) (Database, error)
BuildDatabaseError func(err error) errors.DatabaseError
ExplainQuery func(ctx context.Context, q DB, query string, args []any) (string, error)
}
type DriverMariaDB ¶
type DriverMariaDB struct {
mysql.MySQLDriver
}
func (DriverMariaDB) OpenConnector ¶
func (d DriverMariaDB) OpenConnector(dsn string) (driver.Connector, error)
type DriverMySQL ¶
type DriverMySQL = mysql.MySQLDriver
type DriverPostgres ¶
type DriverSQLite ¶
type DriverSQLite = sqlite3.SQLiteDriver
type Email ¶
func MustParseEmail ¶
func MustParseEmail(addr string) *Email
type LocalTime ¶
func CurrentLocalTime ¶
func CurrentLocalTime() LocalTime
func (LocalTime) MarshalJSON ¶
func (*LocalTime) UnmarshalJSON ¶
type OpenOption ¶
func SQLDBOption ¶
func SQLDBOption(opt func(driverName string, db *sql.DB) error) OpenOption
type Query ¶
type QueryInformation ¶
func ContextQueryInfo ¶
func ContextQueryInfo(ctx context.Context) (*QueryInformation, bool)
func ContextWithQueryInfo ¶
func ContextWithQueryInfo(ctx context.Context) (context.Context, *QueryInformation)
func (*QueryInformation) AverageTime ¶
func (q *QueryInformation) AverageTime() time.Duration
func (*QueryInformation) Slowest ¶
func (q *QueryInformation) Slowest() *Query
func (*QueryInformation) TotalExecutionTime ¶
func (q *QueryInformation) TotalExecutionTime() time.Duration
func (*QueryInformation) TotalTime ¶
func (q *QueryInformation) TotalTime() time.Duration
type SQLRow ¶
SQLRow interface represents a single row result from a database query.
It provides methods to check for errors and scan the row's data into destination variables.
SQLRow is typically returned by methods like QueryRowContext, allowing you to retrieve a single row of data.
type SQLRows ¶
type SQLRows interface {
SQLRow
Close() error
Next() bool
Columns() ([]string, error)
NextResultSet() bool
}
SQLRows interface represents a set of rows returned by a database query.
It provides methods to iterate over the rows, retrieve column names, and manage the result set.
It extends the SQLRow interface to include methods for iterating through multiple rows and managing the result set.
SQLRows is typically returned by methods like QueryContext, allowing you to process multiple rows of data.
type SupportsReturningType ¶
type SupportsReturningType string
const ( SupportsReturningNone SupportsReturningType = "" SupportsReturningLastInsertId SupportsReturningType = "last_insert_id" SupportsReturningColumns SupportsReturningType = "columns" )
func SupportsReturning ¶
func SupportsReturning(db interface{ Driver() driver.Driver }) SupportsReturningType
SupportsReturning returns the type of returning supported by the database. It can be one of the following:
- SupportsReturningNone: no returning supported - SupportsReturningLastInsertId: last insert id supported - SupportsReturningColumns: returning columns supported
type Timestamp ¶
func CurrentTimestamp ¶
func CurrentTimestamp() Timestamp
func (Timestamp) MarshalJSON ¶
func (*Timestamp) UnmarshalJSON ¶
type Transaction ¶
type Transaction interface {
DB
// Finished returns true if the transaction has been committed or rolled back.
Finished() bool
Commit(context.Context) error
Rollback(context.Context) error
}
Transaction interface represents a database transaction.
It extends the DB interface to include transaction management methods such as Commit and Rollback.
A transaction is a sequence of operations performed in a way that ensures data integrity and consistency. It allows multiple operations to be executed as a single unit of work, which can be committed or rolled back as a whole, depending on whether all operations succeed or if any operation fails.
Source Files
Directories