db/postgres_url.ts

The libpq side of a Postgres DATABASE_URL: the database it names, the maintenance connection a client program like createdb or dropdb reaches its server through, the environment that carries the URL's password, and the argv those programs get. Pure functions, shared by the dev setup helpers (dev/setup.ts) and the cross-backend test setup (testing/cross_backend/postgres_database.ts).

URL rewrites edit the raw query pairs, never URLSearchParams, which reserializes every value form-encoded: a space becomes +, which libpq reads as a literal plus (options=-c%20search_path%3Dapp would arrive broken).

view source

Declarations
#

8 declarations

is_createdb_already_exists
#

db/postgres_url.ts view source

(stderr: string, database: string): boolean import {is_createdb_already_exists} from '@fuzdev/fuz_app/db/postgres_url.js';

Whether createdb's stderr is its refusal of a database that already exists — Postgres's database "<name>" already exists, which createdb prints after database creation failed: ERROR:. The text is the server's, in its lc_messages, so only an English refusal is recognized.

stderr

what createdb wrote to stderr

type string

database

the database it was asked to create

type string

returns

boolean

parse_db_name
#

db/postgres_url.ts view source

(url: string): string | null import {parse_db_name} from '@fuzdev/fuz_app/db/postgres_url.js';

Extract the database name from a PostgreSQL URL, percent-decoded.

url

a DATABASE_URL

type string

returns

string | null

the database name, or null if the URL isn't a valid postgres:// / postgresql:// URL or names no database

rewrite_query_pairs
#

db/postgres_url.ts view source

(url: URL, rewrite: (pair: string, key: string | null) => string | null): void import {rewrite_query_pairs} from '@fuzdev/fuz_app/db/postgres_url.js';

Rewrite a URL's query pair by pair, leaving every pair the rewrite keeps byte for byte as it was.

url

the URL to rewrite

type URL

rewrite

each raw pair and its decoded key to its replacement, or null to drop it

type (pair: string, key: string | null) => string | null

returns

void

mutates

  • url — replaces its `search`

to_createdb_args
#

db/postgres_url.ts view source

(database: string, server_url?: string | undefined): string[] import {to_createdb_args} from '@fuzdev/fuz_app/db/postgres_url.js';

The argv for createdb to create database: never prompting (--no-password), on the server server_url names when given (through --maintenance-db, to_maintenance_database_url) or else the server the libpq environment names, with -- ahead of the name so a name beginning with - stays an operand.

database

the database to create

type string

server_url?

a postgres:// URL on the target server

type string
optional

returns

string[]

to_dropdb_args
#

db/postgres_url.ts view source

(database: string, server_url: string): string[] import {to_dropdb_args} from '@fuzdev/fuz_app/db/postgres_url.js';

The argv for dropdb to drop database if it exists, on the server server_url names, as to_createdb_args builds it.

database

the database to drop

type string

server_url

a postgres:// URL on the target server

type string

returns

string[]

to_maintenance_database_name
#

db/postgres_url.ts view source

(database: string): string import {to_maintenance_database_name} from '@fuzdev/fuz_app/db/postgres_url.js';

The maintenance database a client program connects to in order to create or drop database: postgres, or template1 when database is postgres itself — a database can't be dropped over a connection to it, and dropdb falls back to template1 the same way when given no maintenance database.

database

the database being created or dropped

type string

returns

string

to_maintenance_database_url
#

db/postgres_url.ts view source

(server_url: string, database: string): string import {to_maintenance_database_url} from '@fuzdev/fuz_app/db/postgres_url.js';

The URL a client program connects through to create or drop database on the server server_url names: server_url with its database replaced by the maintenance database (to_maintenance_database_name) and its password removed, from the userinfo and the password query parameter, and any fragment dropped. Host, port, role, and every other query parameter are kept as written. The password reaches the program in its environment instead (to_postgres_password_env), never its argv, which any local user can read from the process list.

server_url

a postgres:// URL on the target server; its database name is ignored

type string

database

the database being created or dropped

type string

returns

string

the maintenance URL, with no password

to_postgres_password_env
#

db/postgres_url.ts view source

(database_url: string): Record<string, string> | null import {to_postgres_password_env} from '@fuzdev/fuz_app/db/postgres_url.js';

The environment that hands a client program the password database_url carries: {PGPASSWORD} when it has one, {} when it has none. libpq reads PGPASSWORD as it reads a password connection parameter, ahead of ~/.pgpass. A password query parameter wins over the userinfo's, as in libpq, which applies query parameters after the URI's components.

database_url

a postgres:// URL

type string

returns

Record<string, string> | null

the environment to add, or null when the password has a malformed percent-escape

Depends on
#

Imported by
#