Documentation
¶
Index ¶
- Constants
- func CSVOutputPath(path string) string
- func CountCSVDataRows(path string, hasHeader bool) int
- func DumpDatabase(dbURL, dumpPath string) error
- func DumpDatabaseWithConnection(profile config.Profile, dumpPath string) error
- func DumpDatabaseWithConnectionAndOptions(profile config.Profile, dumpPath string, options *DumpOptions) error
- func DumpDatabaseWithOptions(dbURL, dumpPath string, options *DumpOptions) error
- func ExportCSVWithOptions(db *sql.DB, table, exportPath string, options *CSVOptions) error
- func ExportCSVWithQuery(db *sql.DB, query, exportPath string, includeHeaders bool) (int, error)
- func FormatCSVValue(v interface{}) string
- func ImportCSVWithOptions(db *sql.DB, table, importPath string, options *CSVOptions) error
- func MigrateDatabaseWithConnection(opts *MigrationOptions) error
- func QuoteTable(table string) string
- func RestoreDatabaseSmart(dbURL, dumpPath string) error
- func RestoreDatabaseSmartWithOptions(dbURL, dumpPath string, options *RestoreOptions) error
- func RestoreDatabaseWithConnection(profile config.Profile, dumpPath string) error
- func RestoreDatabaseWithConnectionAndOptions(profile config.Profile, dumpPath string, options *RestoreOptions) error
- type Bar
- type CSVOptions
- type DryRunReport
- type DumpOptions
- type MigrationOptions
- type RestoreOptions
- type TableReport
- type TypeConflict
Constants ¶
const CSVExtension = ".csv"
CSVExtension is the suffix appended to an export path that has none.
const DefaultBatchSize = 20000
DefaultBatchSize is the number of rows read or written per batch.
It is deliberately much larger than the historical value of 500. Export used to slice the table with LIMIT/OFFSET, where a small batch meant thousands of round trips each rescanning the table from the start; that pattern is gone, but a small batch is still costly because every batch is a separate query. Measured on 5,000,000 rows: batch 500 took 15.3s, batch 20000 took 7.5s, with a server-side COPY at 5.3s. 20000 rows is a few megabytes of CSV, so memory stays flat while the per-batch overhead shrinks to something negligible.
Variables ¶
This section is empty.
Functions ¶
func CSVOutputPath ¶ added in v1.2.1
CSVOutputPath returns the path an export will actually write.
Export appends ".csv" when the caller omits an extension. Callers that check whether they are about to overwrite a file must resolve the path the same way, otherwise "pgtransfer export csv prod users users" checks for a file called "users" and silently writes "users.csv" over an existing one.
func CountCSVDataRows ¶
CountCSVDataRows best-effort counts records in a CSV file, optionally excluding the header row.
This counts records rather than lines. A CSV record can span several lines when a quoted field contains a newline, so counting newline bytes overstates the row count for any table with multiline text in it.
func DumpDatabase ¶
DumpDatabase writes a plain SQL dump of dbURL to dumpPath.
The CLI and MCP server both reach the database through a profile, so they go through DumpDatabaseWithConnection{,AndOptions}; this is the direct form for callers that already hold a connection string. It is also the path the integration tests exercise, because it needs no profile.
func DumpDatabaseWithConnection ¶
DumpDatabaseWithConnection performs a database dump using a DBConnection (supports SSH tunnels)
func DumpDatabaseWithConnectionAndOptions ¶
func DumpDatabaseWithConnectionAndOptions(profile config.Profile, dumpPath string, options *DumpOptions) error
DumpDatabaseWithConnectionAndOptions performs a database dump with advanced options using DBConnection
func DumpDatabaseWithOptions ¶
func DumpDatabaseWithOptions(dbURL, dumpPath string, options *DumpOptions) error
DumpDatabaseWithOptions performs a database dump with advanced options
func ExportCSVWithOptions ¶
func ExportCSVWithOptions(db *sql.DB, table, exportPath string, options *CSVOptions) error
ExportCSVWithOptions exports a PostgreSQL table to CSV with batch processing for better memory efficiency
func ExportCSVWithQuery ¶
ExportCSVWithQuery runs an arbitrary SELECT and writes the results to a CSV file. It returns the number of data rows written (headers excluded).
func FormatCSVValue ¶
func FormatCSVValue(v interface{}) string
formatCSVValue properly formats a value for CSV export
func ImportCSVWithOptions ¶
func ImportCSVWithOptions(db *sql.DB, table, importPath string, options *CSVOptions) error
ImportCSVWithOptions imports data from a CSV file with batch processing for better performance
func MigrateDatabaseWithConnection ¶
func MigrateDatabaseWithConnection(opts *MigrationOptions) error
MigrateDatabaseWithConnection performs database migration using DBConnection objects for SSH support
func QuoteTable ¶ added in v1.2.1
QuoteTable is quoteTable for callers outside this package.
func RestoreDatabaseSmart ¶
RestoreDatabaseSmart automatically detects dump format and uses appropriate tool
func RestoreDatabaseSmartWithOptions ¶
func RestoreDatabaseSmartWithOptions(dbURL, dumpPath string, options *RestoreOptions) error
RestoreDatabaseSmartWithOptions detects the dump format and restores it, honouring the supplied RestoreOptions.
func RestoreDatabaseWithConnection ¶
RestoreDatabaseWithConnection performs a database restore using a DBConnection (supports SSH tunnels) RestoreDatabaseWithConnection performs a database restore using a DBConnection (supports SSH tunnels)
func RestoreDatabaseWithConnectionAndOptions ¶
func RestoreDatabaseWithConnectionAndOptions(profile config.Profile, dumpPath string, options *RestoreOptions) error
RestoreDatabaseWithConnectionAndOptions performs a database restore using a DBConnection (supports SSH tunnels), honouring the supplied RestoreOptions.
Types ¶
type Bar ¶ added in v1.2.1
type Bar struct {
*progressbar.ProgressBar
// contains filtered or unexported fields
}
Bar is a progress bar whose elapsed-time goroutine is tied to its lifetime.
The elapsed-time suffix is driven by a goroutine that polls the bar. Stopping it on IsFinished alone leaves that goroutine alive for any caller that never finishes the bar — an error return, a cancelled command — for the rest of the process. A CLI that runs one command and exits does not care; a process that hosts the MCP tools, or a test binary running thousands of cases, accumulates one leaked goroutine per bar.
Wrapping the progress bar means every existing Finish call releases the goroutine, because Finish is the method being called.
func NewProgressBarWithTimer ¶
NewProgressBarWithTimer creates a progress bar (or a spinner when the total is unknown/non-positive) and starts a goroutine that continuously appends an elapsed-time suffix to the bar's description.
Call Finish on the returned bar, normally with defer, so the goroutine ends on every path out of the function.
type CSVOptions ¶
type CSVOptions struct {
BatchSize int // Number of rows to process in each batch
HasHeader bool // Whether the first row of the CSV contains column headers
}
CSVOptions contains configuration for CSV operations
func DefaultCSVOptions ¶
func DefaultCSVOptions() *CSVOptions
DefaultCSVOptions returns default CSV configuration
type DryRunReport ¶ added in v1.3.0
type DryRunReport struct {
Source string `json:"source"`
Target string `json:"target"`
SchemaOnly bool `json:"schema_only"`
DataOnly bool `json:"data_only"`
Overwrite bool `json:"overwrite"`
Strict bool `json:"strict"`
Tables []TableReport `json:"tables"`
OnlyInSource []string `json:"only_in_source"`
OnlyInTarget []string `json:"only_in_target"`
TypeConflicts []TypeConflict `json:"type_conflicts"`
Warnings []string `json:"warnings"`
}
DryRunReport is what a migration would do, without doing it.
func DryRunMigration ¶ added in v1.3.0
func DryRunMigration(opts *MigrationOptions) (*DryRunReport, error)
DryRunMigration reports what MigrateDatabaseWithConnection would do: which tables it would copy, which existing target tables --overwrite would drop, and which columns have incompatible types.
It is read-only. Both databases are queried for table lists, approximate row counts and column types; nothing is dumped and nothing is written. The counts come from the planner's statistics, so they are estimates on a busy database.
func (*DryRunReport) Lines ¶ added in v1.3.0
func (r *DryRunReport) Lines() []string
Lines renders the report as plain text lines, one per printed row. It returns text rather than writing it so the caller owns colour and destination, and so the plan can be asserted on.
type DumpOptions ¶
type DumpOptions struct {
Format string // plain, custom, directory, tar
Compress bool // Enable compression
SchemaOnly bool // Export schema only
DataOnly bool // Export data only
Tables []string // Specific tables to include
ExcludeTables []string // Tables to exclude
Schema string // Specific schema
Verbose bool // Verbose output
Timeout int // Command timeout in seconds
}
DumpOptions contains advanced options for pg_dump
type MigrationOptions ¶
type MigrationOptions struct {
SourceProfile config.Profile
TargetProfile config.Profile
SchemaOnly bool
DataOnly bool
Tables []string
Validate bool
EnableRollback bool
Verbose bool
Timeout int
Overwrite bool
Strict bool
BatchSize int
}
MigrationOptions defines options for database migration
type RestoreOptions ¶
type RestoreOptions struct {
// Clean drops database objects before recreating them (pg_restore only).
Clean bool
// Timeout, when > 0, aborts the restore after the given number of seconds.
Timeout int
// Strict makes any restore error fatal. By default restore tolerates
// non-fatal errors reported by pg_restore (e.g. minor client/server
// version mismatches such as "unrecognized configuration parameter").
// Note that pg_restore exits with code 1 when it encounters ignorable
// errors, so the default (Strict == false) keeps restores resilient to
// version skew.
Strict bool
// Verbose prints the underlying command, with the password redacted.
Verbose bool
}
RestoreOptions controls restore behaviour for pg_restore/psql.
type TableReport ¶ added in v1.3.0
type TableReport struct {
Table string `json:"table"`
Rows int64 `json:"rows"`
Exists bool `json:"exists_in_target"` // false means the restore creates it
Dropped bool `json:"would_drop"` // true when --overwrite drops a target table
}
TableReport is one table that would be migrated.
type TypeConflict ¶ added in v1.3.0
type TypeConflict struct {
Table string `json:"table"`
Column string `json:"column"`
Source string `json:"source_type"`
Target string `json:"target_type"`
}
TypeConflict is a column whose type differs between source and target. The restore does not fix this: an existing target column keeps its type and the copy fails, or silently coerces.
Source Files