Documentation
¶
Index ¶
- Variables
- func CheckPIDFile(dataPath string) (exists bool, alive bool, pid int, err error)
- func GetFreePort() (int, error)
- func IsDataPathInitialized(dataPath string) (bool, error)
- func IsEmbeddedPGRunning(dataPath string) bool
- func IsFromLocalhost(req *http.Request) bool
- func IsPortListening(host string, port int, timeout time.Duration) bool
- func IsPostgresProcess(pid int) bool
- func IsProcessAlive(pid int) bool
- func KillEmbeddedPG(pid int) error
- func MapToStruct[T any](m map[string]any) *T
- func PrettyJSON(v any) json.RawMessage
- func ReadPostmasterPort(dataPath string) (int, error)
- func RequestHost(req *http.Request) string
- func ReuseEmbeddedPG(dataPath string) (running bool, port int)
- func StructToMap[T any](v *T) map[string]any
- func StructToMapLC(v any, opts ...Option) map[string]any
- func WriteJSONResponse(w http.ResponseWriter, status int, v any) error
- type Option
- type SplitLevelHandler
Constants ¶
This section is empty.
Variables ¶
var ErrNotPostgresProcess = errors.New("pid is not a postgres process")
ErrNotPostgresProcess is returned by KillEmbeddedPG when the target PID does not appear to be a Postgres process. Callers can use errors.Is to distinguish "skipped because not postgres" from other kill failures.
Functions ¶
func CheckPIDFile ¶ added in v0.4.0
CheckPIDFile reads the postmaster.pid file in the given data directory and determines whether the PostgreSQL process is still running. Returns:
- exists: true if the postmaster.pid file exists (even if unreadable)
- alive: true if the process referenced by the PID is currently running
- pid: the process ID from the file, or 0 if the file doesn't exist or is invalid
- err: non-nil for unexpected I/O errors (permission denied, etc.)
Note: os.FindProcess always succeeds on Unix; the Signal(0) probe is the actual liveness check. On Windows, this file is excluded via build constraint.
func GetFreePort ¶ added in v0.3.0
GetFreePort asks the OS to allocate an unused port on localhost. Note: There is a small race window between when the port is returned and when it is actually used by the caller. In high-contention scenarios, the port may be taken by another process.
func IsDataPathInitialized ¶ added in v0.4.0
IsDataPathInitialized checks if a PostgreSQL data directory has been initialized by verifying the existence of the PG_VERSION file created by initdb. Returns true if PG_VERSION exists, false if it does not exist. Returns an error for I/O or permission issues (distinct from "not initialized").
func IsEmbeddedPGRunning ¶ added in v0.4.0
IsEmbeddedPGRunning is a composite check that determines whether an embedded PostgreSQL instance is already running at the given data directory and port. It delegates to ReuseEmbeddedPG which checks PID file liveness and port. Returns true only if the process is alive AND the port is accepting connections.
func IsFromLocalhost ¶
func IsPortListening ¶ added in v0.4.0
IsPortListening checks if a TCP port is accepting connections on the given host. Returns true if a connection can be established within the specified timeout.
func IsPostgresProcess ¶ added in v0.6.0
IsPostgresProcess checks whether the process identified by pid is a Postgres process by inspecting its command name. This guards against PID reuse when force-killing embedded Postgres instances. Exported so that the postgres package can apply the same guard before sending SIGTERM via sendPostgresSIGTERM.
func IsProcessAlive ¶ added in v0.6.0
IsProcessAlive reports whether a process with the given pid exists and is reachable via Signal(0). On Unix, os.FindProcess always succeeds, so the Signal(0) probe is the real liveness check.
func KillEmbeddedPG ¶ added in v0.6.0
KillEmbeddedPG sends SIGKILL to the process identified by pid and waits for it to terminate. This is a last-resort fallback used when pg_ctl stop fails or times out during graceful shutdown. Before sending the signal, it verifies the target process is a Postgres process to avoid killing an unrelated process that may have reused the PID.
Returns ErrNotPostgresProcess when the target PID is dead or does not appear to be a Postgres process (callers should treat this as "nothing to kill"). Use errors.Is to distinguish from other kill failures.
func MapToStruct ¶
MapToStruct deserializes a map[string]any back into a typed struct pointer. Returns nil if m is nil or empty.
func PrettyJSON ¶
func PrettyJSON(v any) json.RawMessage
func ReadPostmasterPort ¶ added in v0.4.0
ReadPostmasterPort reads the TCP port number from line 4 of the postmaster.pid file in the given data directory. The postmaster.pid format is:
Line 1: PID Line 2: data directory path Line 3: timestamp Line 4: port number Line 5: Unix socket directory
func RequestHost ¶ added in v0.2.1
func ReuseEmbeddedPG ¶ added in v0.4.0
ReuseEmbeddedPG checks whether an embedded PostgreSQL instance is already running at the given data directory. If running, it returns (true, port) where port is read from the postmaster.pid file. Returns (false, 0) if no running instance is detected or the data path is empty.
func StructToMap ¶
StructToMap serializes a pointer to any json-tagged struct into a map[string]any. Returns nil if v is nil.
func StructToMapLC ¶ added in v0.1.0
StructToMapLC converts a struct to map[string]any using reflection, converting PascalCase field names to camelCase (first character lowercased). Embedded structs are flattened into the parent map. Optional behaviors (ID suffix conversion, omit-empty) can be enabled via Option. Returns nil if v is nil or not a struct.
func WriteJSONResponse ¶
func WriteJSONResponse(w http.ResponseWriter, status int, v any) error
Types ¶
type Option ¶ added in v0.1.1
type Option func(*options)
Option configures the behavior of StructToMapLC.
func WithIDSuffix ¶ added in v0.1.1
func WithIDSuffix() Option
WithIDSuffix converts field names ending in "ID" to end in "Id". e.g. "UserID" becomes "userId" instead of "userID".
func WithNilMapToEmpty ¶ added in v0.1.2
func WithNilMapToEmpty() Option
WithNilMapToEmpty converts nil map fields to empty maps {} instead of null.
func WithNilSliceToEmpty ¶ added in v0.1.2
func WithNilSliceToEmpty() Option
WithNilSliceToEmpty converts nil slice fields to empty slices [] instead of null.
func WithOmitEmpty ¶ added in v0.1.1
func WithOmitEmpty() Option
WithOmitEmpty skips fields with empty values: empty string, nil pointer, nil or zero-length slice. Numeric and boolean fields are never omitted.
type SplitLevelHandler ¶
SplitLevelHandler routes log records to stdout for levels below Error, and to stderr for Error and above.
Source Files