README
¶
xdb
Extensions around standard sql package
Usage
go get github.com/effective-security/xdb
Schema generator
Usage: xdbcli <command>
SQL schema tool
Flags:
-h, --help Show context-sensitive help.
-D, --debug Enable debug mode
--o="table" Print output format: json|yaml|table
--sql-source=STRING SQL sources, if not provided, will be used from XDB_DATASOURCE env var
Commands:
schema generate generate Go model for database schema
schema columns prints database schema
schema tables prints database tables and dependencies
schema views prints database views and dependencies
schema foreign-keys prints Foreign Keys
Run "xdbcli <command> --help" for more information on a command.
Examples:
export XDB_DATASOURCE="postgres://${XDB_PG_USER}:${XDB_PG_PASSWORD}@${XDB_PG_HOST}:${XDB_PG_PORT}?sslmode=disable"
Print tables:
bin/xdbcli schema tables --db testdb
public.org
public.orgmember
public.schema_migrations
public.user
Print columns
bin/xdbcli schema columns --db testdb --table orgmember --dependencies
Schema: public
Table: org
NAME | TYPE | NULL | MAX | REF
-----------------+--------------------------+------+-----+------
id | bigint | NO | |
name | character varying | NO | 64 |
email | character varying | NO | 160 |
billing_email | character varying | NO | 160 |
company | character varying | NO | 64 |
street_address | character varying | NO | 256 |
city | character varying | NO | 32 |
postal_code | character varying | NO | 16 |
region | character varying | NO | 16 |
country | character varying | NO | 16 |
phone | character varying | NO | 32 |
created_at | timestamp with time zone | YES | |
updated_at | timestamp with time zone | YES | |
quota | jsonb | YES | |
settings | jsonb | YES | |
Print FK
bin/xdbcli schema foreign-keys --db testdb
NAME | SCHEMA | TABLE | COLUMN | FK SCHEMA | FK TABLE | FK COLUMN
-------------------------+--------+-----------+---------+-----------+----------+------------
orgmember_org_id_fkey | public | orgmember | org_id | public | org | id
orgmember_user_id_fkey | public | orgmember | user_id | public | user | id
Generate model
xdbcli --sql-source=$(DATASOURCE) \
schema generate \
--dependencies \
--db=testdb \
--view=vwMembership \
--out-model=./testdata/e2e/postgres/model \
--out-schema=./testdata/e2e/postgres/schema
Documentation
¶
Index ¶
- Constants
- Variables
- func ExecuteListQuery[T any, TPointer RowPointer[T]](ctx context.Context, sql DB, query string, args ...any) ([]TPointer, error)
- func IDString(id uint64) string
- func IsNotFoundError(err error) bool
- func Merge(dst any, src any) error
- func NullTime(val *time.Time) sql.NullTime
- func Open(dataSource, database string) (*sql.DB, string, string, error)
- func ParseUint(id string) (uint64, error)
- func QueryRow[T any, TPointer RowPointer[T]](ctx context.Context, sql DB, query string, args ...any) (TPointer, error)
- func String(val *string) string
- func TimePtr(val Time) *time.Time
- func Validate(m any) error
- type Bool
- type DB
- type Float
- type ID
- func (v ID) Invalid() bool
- func (v ID) IsZero() bool
- func (v ID) MarshalJSON() ([]byte, error)
- func (v *ID) Reset()
- func (v *ID) Scan(value any) error
- func (v *ID) Set(val string) error
- func (v ID) String() string
- func (v ID) UInt64() uint64
- func (v *ID) UnmarshalJSON(data []byte) error
- func (v ID) Valid() bool
- func (v ID) Value() (driver.Value, error)
- type ID32
- type IDArray
- type IDGenerator
- type Int32
- type Int64
- type Metadata
- type MigrationConfig
- type NULLString
- type Provider
- type Result
- type Row
- type RowPointer
- type RowScanner
- type Rows
- type SQLProvider
- func (p *SQLProvider) BeginTx(ctx context.Context, _ *sql.TxOptions) (Provider, error)
- func (p *SQLProvider) Close() (err error)
- func (p *SQLProvider) Commit() error
- func (p *SQLProvider) DB() DB
- func (p *SQLProvider) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
- func (p *SQLProvider) IDTime(id uint64) time.Time
- func (p *SQLProvider) Name() string
- func (p *SQLProvider) NextID() ID
- func (p *SQLProvider) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
- func (p *SQLProvider) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
- func (p *SQLProvider) Rollback() error
- func (p *SQLProvider) Tx() Tx
- type Source
- type Strings
- type Time
- func (ns Time) Add(after time.Duration) Time
- func (ns Time) IsNil() bool
- func (ns Time) IsZero() bool
- func (ns Time) MarshalJSON() ([]byte, error)
- func (ns Time) Ptr() *time.Time
- func (ns *Time) Scan(value any) error
- func (ns Time) String() string
- func (ns Time) UTC() time.Time
- func (ns Time) UnixMilli() int64
- func (ns *Time) UnmarshalJSON(data []byte) error
- func (ns Time) Value() (driver.Value, error)
- type Tx
- type UUID
- type Validator
Constants ¶
const ( MaxLenForName = 64 MaxLenForEmail = 160 MaxLenForShortURL = 256 )
Max values, common for strings
const DefaultPageSize = 500
DefaultPageSize is the default page size
Variables ¶
var DefaultTimeFormat = "2006-01-02T15:04:05.999Z07:00"
DefaultTimeFormat is the default format for Time.String()
var DefaultTrucate = time.Millisecond
DefaultTrucate is the default time to truncate as Postgres time precision is default to 6 However, JavaScript and AWS accept time milliseconds only, 3 digits, so we truncate to 3
var MergeOpts = mergo.WithTransformers(transformers{})
MergeOpts is a mergo option to merge structs
Functions ¶
func ExecuteListQuery ¶ added in v0.7.0
func ExecuteListQuery[T any, TPointer RowPointer[T]](ctx context.Context, sql DB, query string, args ...any) ([]TPointer, error)
ExecuteListQuery runs a query and returns a list of models
func IsNotFoundError ¶
IsNotFoundError returns true, if error is NotFound
func QueryRow ¶ added in v0.6.0
func QueryRow[T any, TPointer RowPointer[T]](ctx context.Context, sql DB, query string, args ...any) (TPointer, error)
QueryRow runs a query and returns a single model
Types ¶
type Bool ¶ added in v0.8.0
type Bool bool
Bool represents SQL bool NULL
func (Bool) MarshalJSON ¶ added in v0.8.0
MarshalJSON implements json.Marshaler interface
func (*Bool) UnmarshalJSON ¶ added in v0.8.0
UnmarshalJSON implements the json.Unmarshaler interface.
type DB ¶
type DB interface {
// QueryContext executes a query that returns rows, typically a SELECT.
// The args are for any placeholder parameters in the query.
QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
// QueryRowContext executes a query that is expected to return at most one row.
// QueryRowContext always returns a non-nil value. Errors are deferred until
// Row's Scan method is called.
// If the query selects no rows, the *Row's Scan will return ErrNoRows.
// Otherwise, the *Row's Scan scans the first selected row and discards
// the rest.
QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
// ExecContext executes a query without returning any rows.
// The args are for any placeholder parameters in the query.
ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}
DB provides interface for Db operations It's an interface accepted by Query, QueryRow and Exec methods. Both sql.DB, sql.Conn and sql.Tx can be passed as DB interface.
type Float ¶ added in v0.8.0
type Float float64
Float represents SQL float64 NULL
func (Float) MarshalJSON ¶ added in v0.8.0
MarshalJSON implements json.Marshaler interface
func (*Float) UnmarshalJSON ¶ added in v0.8.0
UnmarshalJSON implements the json.Unmarshaler interface.
type ID ¶
type ID struct {
// contains filtered or unexported fields
}
ID defines a type to convert between internal uint64 and external string representations of ID
func TryParseID ¶ added in v0.8.0
TryParseID returns ID or empty if val is not valid ID
func (ID) MarshalJSON ¶
MarshalJSON implements json.Marshaler interface
func (*ID) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface.
type ID32 ¶ added in v0.8.0
type ID32 uint32
ID32 defines a type to convert between internal uint32 and NULL values in DB
func (ID32) MarshalJSON ¶ added in v0.8.0
MarshalJSON implements json.Marshaler interface
func (*ID32) UnmarshalJSON ¶ added in v0.8.0
UnmarshalJSON implements the json.Unmarshaler interface.
type IDArray ¶
type IDArray []ID
IDArray defines a list of IDArray
func NewIDArray ¶ added in v0.13.1
NewIDArray returns IDArray
type IDGenerator ¶
type IDGenerator interface {
// NextID generates a next unique ID.
NextID() ID
IDTime(id uint64) time.Time
}
IDGenerator defines an interface to generate unique ID accross the cluster
type Int32 ¶ added in v0.8.0
type Int32 int32
Int32 represents SQL int NULL
func (Int32) MarshalJSON ¶ added in v0.8.0
MarshalJSON implements json.Marshaler interface
func (*Int32) UnmarshalJSON ¶ added in v0.8.0
UnmarshalJSON implements the json.Unmarshaler interface.
type Int64 ¶ added in v0.8.1
type Int64 int64
Int64 represents SQL int64 NULL
func (Int64) MarshalJSON ¶ added in v0.8.1
MarshalJSON implements json.Marshaler interface
func (*Int64) UnmarshalJSON ¶ added in v0.8.1
UnmarshalJSON implements the json.Unmarshaler interface.
type Metadata ¶
Metadata de/encodes the string map to/from a SQL string.
type MigrationConfig ¶
MigrationConfig defines migration configuration
type NULLString ¶
type NULLString string
NULLString de/encodes the string a SQL string.
func (*NULLString) Scan ¶
func (ns *NULLString) Scan(value any) error
Scan implements the Scanner interface.
func (NULLString) String ¶ added in v0.13.1
func (ns NULLString) String() string
String returns string
type Provider ¶
type Provider interface {
IDGenerator
DB
Tx
// Name returns provider name: postgres, sqlserver, etc
Name() string
// DB returns underlying DB connection
DB() DB
// Tx returns underlying DB transaction
Tx() Tx
// Close connection and release resources
Close() (err error)
BeginTx(ctx context.Context, opts *sql.TxOptions) (Provider, error)
}
Provider provides complete DB access
func NewProvider ¶
func NewProvider(dataSource, dbName string, idGen flake.IDGenerator, migrateCfg *MigrationConfig) (Provider, error)
NewProvider creates a Provider instance
type Result ¶
type Result[T any, TPointer RowPointer[T]] struct { Rows []TPointer NextOffset uint32 Limit uint32 }
Result describes the result of a list query
type Row ¶
type Row interface {
// Scan copies the columns from the matched row into the values
// pointed at by dest. See the documentation on Rows.Scan for details.
// If more than one row matches the query,
// Scan uses the first row and discards the rest. If no row matches
// the query, Scan returns ErrNoRows.
Scan(dest ...any) error
// Err provides a way for wrapping packages to check for
// query errors without calling Scan.
// Err returns the error, if any, that was encountered while running the query.
// If this error is not nil, this error will also be returned from Scan.
Err() error
}
Row defines an interface for DB row
type RowPointer ¶
type RowPointer[T any] interface { *T RowScanner }
RowPointer defines a generic interface to scan a single row
type RowScanner ¶
RowScanner defines an interface to scan a single row
type Rows ¶
type Rows interface {
io.Closer
Row
// Next prepares the next result row for reading with the Scan method. It
// returns true on success, or false if there is no next result row or an error
// happened while preparing it. Err should be consulted to distinguish between
// the two cases.
//
// Every call to Scan, even the first one, must be preceded by a call to Next.
Next() bool
// NextResultSet prepares the next result set for reading. It reports whether
// there is further result sets, or false if there is no further result set
// or if there is an error advancing to it. The Err method should be consulted
// to distinguish between the two cases.
//
// After calling NextResultSet, the Next method should always be called before
// scanning. If there are further result sets they may not have rows in the result
// set.
NextResultSet() bool
}
Rows defines an interface for DB rows
type SQLProvider ¶
type SQLProvider struct {
// contains filtered or unexported fields
}
SQLProvider represents SQL client instance
func New ¶
func New(name string, db *sql.DB, idGen flake.IDGenerator) (*SQLProvider, error)
New creates a Provider instance
func (*SQLProvider) BeginTx ¶
BeginTx starts a transaction.
The provided context is used until the transaction is committed or rolled back. If the context is canceled, the sql package will roll back the transaction. Tx.Commit will return an error if the context provided to BeginTx is canceled.
The provided TxOptions is optional and may be nil if defaults should be used. If a non-default isolation level is used that the driver doesn't support, an error will be returned.
func (*SQLProvider) Close ¶
func (p *SQLProvider) Close() (err error)
Close connection and release resources
func (*SQLProvider) Commit ¶ added in v0.2.0
func (p *SQLProvider) Commit() error
func (*SQLProvider) ExecContext ¶ added in v0.2.0
func (p *SQLProvider) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
ExecContext executes a query without returning any rows. The args are for any placeholder parameters in the query.
func (*SQLProvider) IDTime ¶
func (p *SQLProvider) IDTime(id uint64) time.Time
IDTime returns time when ID was generated
func (*SQLProvider) Name ¶ added in v0.6.0
func (p *SQLProvider) Name() string
Name returns provider name
func (*SQLProvider) QueryContext ¶ added in v0.2.0
func (p *SQLProvider) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
QueryContext executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query.
func (*SQLProvider) QueryRowContext ¶ added in v0.2.0
QueryRowContext executes a query that is expected to return at most one row. QueryRowContext always returns a non-nil value. Errors are deferred until Row's Scan method is called. If the query selects no rows, the *Row's Scan will return ErrNoRows. Otherwise, the *Row's Scan scans the first selected row and discards the rest.
func (*SQLProvider) Rollback ¶ added in v0.2.0
func (p *SQLProvider) Rollback() error
type Source ¶ added in v0.2.2
type Source struct {
Source string
Driver string
Host string
User string
Password string
Database string
Params map[string]string
}
Source describes connection info
func ParseConnectionString ¶ added in v0.2.2
ParseConnectionString return parsed Source from sqlserver://username:password@host/instance?param1=value¶m2=value
type Strings ¶
type Strings []string
Strings de/encodes the string slice to/from a SQL string.
type Time ¶
Time implements sql.Time functionality and always returns UTC
func FromUnixMilli ¶
FromUnixMilli returns Time from Unix milliseconds elapsed since January 1, 1970 UTC.
func (Time) IsNil ¶
IsNil reports whether t represents the zero time instant, January 1, year 1, 00:00:00 UTC.
func (Time) IsZero ¶
IsZero reports whether t represents the zero time instant, January 1, year 1, 00:00:00 UTC.
func (Time) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface. The time is a quoted string in RFC 3339 format, with sub-second precision added if present.
func (Time) String ¶
String returns string in RFC3339 format, if it's Zero time, an empty string is returned
func (Time) UnixMilli ¶
UnixMilli returns t as a Unix time, the number of milliseconds elapsed since January 1, 1970 UTC.
func (*Time) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface. The time is expected to be a quoted string in RFC 3339 format.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
cli
Package cli provides CLI app and global flags
|
Package cli provides CLI app and global flags |
|
cli/clisuite
Package clisuite to test CLI commands
|
Package clisuite to test CLI commands |
|
cli/schema
Package schema provides CLI commands
|
Package schema provides CLI commands |
|
mocks
|
|
|
mockschema
Package mockschema is a generated GoMock package.
|
Package mockschema is a generated GoMock package. |
|
mockxdb
Package mockxdb is a generated GoMock package.
|
Package mockxdb is a generated GoMock package. |
|
pkg
|
|
|
flake
Package flake implements Snowflake, a distributed unique ID generator inspired by Twitter's Snowflake.
|
Package flake implements Snowflake, a distributed unique ID generator inspired by Twitter's Snowflake. |
|
print
Package print provides helper package to print objects.
|
Package print provides helper package to print objects. |
|
Package schema provides helper package to generate schema.
|
Package schema provides helper package to generate schema. |
|
Package xsql is an SQL statement builder and executor.
|
Package xsql is an SQL statement builder and executor. |