PolarDB for PostgreSQL

Deploying the VM

Launch the image from the Azure Marketplace as you would any other VM. The recommended size is Standard_D2s_v5 (2 vCPU / 8 GiB). A database needs sustained CPU, so choose the non-burstable D series over a B series, whose CPU credits run out under sustained load.

Sizing. The shipped configuration (shared_buffers 256 MB, max_connections 200) suits development, test, evaluation and small production workloads up to a few tens of GB. Beyond that, scale the VM up, raise shared_buffers towards 25 % of RAM, and move the data directory onto a managed data disk. Both are covered below.

The Azure network security group only needs TCP 22. PolarDB itself is bound to loopback and is reached over an SSH tunnel by default. Exposing 5432 is a deliberate opt-in and is covered in its own section below.

First boot

The captured image contains no database at all. It has no cluster, no roles and no configuration, and no password of any kind. initdb itself runs on your machine, at your first boot.

The first time the VM boots, polardb-firstboot.service runs once and then disables itself. It does the following:

• Generates this VM's superuser and application passwords from the kernel CSPRNG (32 characters each, independently generated).
• Runs initdb with scram-sha-256 host authentication and data checksums enabled.
• Appends the SecureAnyCloud security overrides so that PolarDB binds to loopback only.
• Writes pg_hba.conf whole: local peer, plus 127.0.0.1/32 and ::1/128 with scram-sha-256, and nothing else.
• Runs polar-initdb.sh ... primary localfs to lay the cluster out on PolarDB's shared-storage layout.
• Writes the credentials to /root/polardb-credentials.txt (mode 0600, owned by root).
• Starts polardb.service and verifies the whole appliance end to end before declaring success.

First boot takes roughly 30 to 60 seconds. Read what it did:

sudo journalctl -u polardb-firstboot.service --no-pager | tail -30

To watch first boot live on a boot in progress, add -f instead of | tail -30.

polardb.service cannot start until first boot has finished. It carries a start-time guard that refuses to run the database in any of these cases:

• The credentials file is missing, is not 0600 root:root, or is still the shipped sample.
• listen_addresses is anything but loopback.
• pg_hba.conf contains trust, md5, password or ident, or permits a non-loopback client.
• PolarVFS is not loaded.

If any of those is true, the database does not start at all.

Retrieving your per-VM credentials

Read the credentials file as root:

sudo cat /root/polardb-credentials.txt

The file is readable only by root and contains:

POLARDB_HOST=127.0.0.1 POLARDB_PORT=5432 POLARDB_SUPERUSER=polardb POLARDB_SUPERUSER_PASSWORD=<polardb-superuser-password> POLARDB_APP_ROLE=polarapp POLARDB_APP_PASSWORD=<polardb-app-password> POLARDB_APP_DATABASE=polarapp

The image has two roles, by design:

• polardb is the superuser. Use it for administration, such as creating extensions, tuning and backups.
• polarapp is an unprivileged login role that owns the polarapp database. It is NOSUPERUSER NOCREATEROLE NOCREATEDB NOBYPASSRLS. Point your application at this role.

This file holds the only copy of both passwords. Store them somewhere safe.

Checking service health

Check the service status and confirm that the server accepts connections:

sudo systemctl status polardb --no-pager /opt/polardb/bin/pg_isready -h 127.0.0.1 -p 5432

Connecting on the VM

psql is on the default PATH. Read the application password from the credentials file and connect over loopback:

APP_PASS=$(sudo sed -n 's/^POLARDB_APP_PASSWORD=//p' /root/polardb-credentials.txt) PGPASSWORD="$APP_PASS" psql -h 127.0.0.1 -p 5432 -U polarapp -d polarapp -c 'SELECT version();'

The version string shows that this is PolarDB and not stock PostgreSQL. The build accf02e2 suffix is the exact upstream commit that this image was compiled from.

Connecting from your workstation

PolarDB is bound to loopback, so the default access path is an SSH tunnel. You do not need to open anything in the network security group beyond the SSH port that you already have.

On your workstation, open the tunnel:

ssh -N -L 15432:127.0.0.1:5432 azureuser@<your-vm-public-ip>

Leave the tunnel running, and connect from another terminal:

psql -h 127.0.0.1 -p 15432 -U polarapp -d polarapp

Any PostgreSQL client works the same way. Point it at 127.0.0.1:15432. The connection string form is:

postgresql://polarapp:<polardb-app-password>@127.0.0.1:15432/polarapp

A real SQL round trip

Run a full round trip as the application role. The commands create a table, load 5,000 rows, add an index and aggregate the result:

APP_PASS=$(sudo sed -n 's/^POLARDB_APP_PASSWORD=//p' /root/polardb-credentials.txt) PGPASSWORD="$APP_PASS" psql -h 127.0.0.1 -p 5432 -U polarapp -d polarapp <<'SQL' CREATE TABLE demo_orders ( id bigserial PRIMARY KEY, region text NOT NULL, amount numeric(12,2) NOT NULL, placed timestamptz DEFAULT now() ); INSERT INTO demo_orders (region, amount) SELECT 'region-' || (g % 4), (g * 1.5)::numeric(12,2) FROM generate_series(1, 5000) g; CREATE INDEX ON demo_orders (region); ANALYZE demo_orders; SELECT region, count(*) AS orders, round(sum(amount), 2) AS revenue FROM demo_orders GROUP BY region ORDER BY region; SQL

What makes this PolarDB

Four settings distinguish PolarDB from stock PostgreSQL. Ask the server:

SUPER_PASS=$(sudo sed -n 's/^POLARDB_SUPERUSER_PASSWORD=//p' /root/polardb-credentials.txt) PGPASSWORD="$SUPER_PASS" psql -h 127.0.0.1 -p 5432 -U polardb -d polarapp <<'SQL' SHOW shared_preload_libraries; SHOW polar_datadir; SHOW polar_enable_shared_storage_mode; SHOW polar_vfs.localfs_mode; SQL

shared_preload_libraries contains polar_vfs, polar_io_stat, polar_monitor_preload and polar_worker. polar_datadir is file-dio:///var/lib/polardb/shared, and shared storage mode is on.

You can see the split on disk. The heap, the catalog and the WAL live in the PolarDB data directory, not in the local PGDATA:

ls /var/lib/polardb/shared
ls /var/lib/polardb/primary

/var/lib/polardb/shared holds base/, global/, pg_wal/, pg_logindex/, pg_xact/ and friends. /var/lib/polardb/primary keeps only node-local state. It has no pg_wal/ and no base/ content of its own. This is the PolarDB shared-storage layout, running over a local filesystem.

polar_monitor is PolarDB's own instrumentation extension and has no equivalent in stock PostgreSQL. Create it and list the installed extensions:

SUPER_PASS=$(sudo sed -n 's/^POLARDB_SUPERUSER_PASSWORD=//p' /root/polardb-credentials.txt) PGPASSWORD="$SUPER_PASS" psql -h 127.0.0.1 -p 5432 -U polardb -d polarapp \
  -c 'CREATE EXTENSION IF NOT EXISTS polar_monitor;' \
  -c "SELECT extname, extversion FROM pg_extension ORDER BY extname;"

The extension catalogue

Every extension is already compiled and installed. You only need to run CREATE EXTENSION. List the full catalog with:

cat /usr/share/polardb-postgresql/extensions.txt

Highlights beyond the standard PostgreSQL contrib set:

• pg_cron is an in-database job scheduler.
• pgaudit provides detailed session and object audit logging.
• pg_partman provides automated partition management.
• pg_repack removes table and index bloat without an exclusive lock.
• pg_squeeze removes table bloat automatically.
• pg_hint_plan gives planner hints through SQL comments.
• pg_profile provides historic workload reporting.
• pg_stat_kcache provides per-query kernel-level I/O and CPU statistics.
• hll provides HyperLogLog approximate distinct counts.
• roaringbitmap provides a compressed bitmap type and operations.
• ip4r provides indexed IPv4 and IPv6 address and range types.
• pase provides an approximate nearest-neighbor vector index.
• pg_bigm and pg_jieba provide bigram and Chinese full-text search.
• pgtap and pldebugger provide unit testing and PL/pgSQL debugging.
• polar_monitor, polar_io_stat and polar_smgrperf provide PolarDB engine instrumentation.

To enable one, run:

SUPER_PASS=$(sudo sed -n 's/^POLARDB_SUPERUSER_PASSWORD=//p' /root/polardb-credentials.txt) PGPASSWORD="$SUPER_PASS" psql -h 127.0.0.1 -p 5432 -U polardb -d polarapp \
  -c 'CREATE EXTENSION IF NOT EXISTS hll;'

A few extensions (pg_cron, pgaudit, pg_stat_kcache, pg_hint_plan) must also be added to shared_preload_libraries, and they need a restart. Append to the existing list rather than replacing it. polar_vfs and its siblings must stay, and the start-time guard refuses to start the database if polar_vfs is removed.

Exposing PostgreSQL to your network

By default PolarDB listens on loopback only, and the offer advertises only SSH. This is the safe default, and the SSH tunnel above is the recommended access path. If your application needs to reach the database directly, you must complete a deliberate, three-part opt-in. All three parts are required.

1. Restrict the network security group first, before anything else. Never open 5432 to the internet.

az network nsg rule create \
  --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-postgres-from-my-app \
  --priority 300 --direction Inbound --access Allow --protocol Tcp \
  --source-address-prefixes <your-app-subnet-or-office-cidr> \
  --destination-port-ranges 5432

Use your own subnet or office CIDR. A source prefix of * or Internet here puts a database on the public internet, so never use either.

2. Add a pg_hba.conf rule for exactly that range, and keep scram-sha-256:

echo 'host polarapp polarapp <your-app-subnet-cidr> scram-sha-256' \
  | sudo tee -a /var/lib/polardb/primary/pg_hba.conf

3. Bind the listener, and then restart:

sudo sed -i "s/^listen_addresses = 'localhost'/listen_addresses = '*'/" \
  /var/lib/polardb/primary/postgresql.conf
sudo systemctl restart polardb

The start-time guard enforces the first two parts. It refuses to start the database if pg_hba.conf contains trust, md5, password or ident. It also refuses a non-loopback host rule while listen_addresses is still localhost, which is why part 3 comes last.

Consider enabling TLS as well. PolarDB is built with OpenSSL. Put a certificate and key in the data directory, set ssl = on, ssl_cert_file and ssl_key_file, and change your pg_hba.conf line from host to hostssl so that plaintext connections are refused outright.

Moving the data directory to a managed disk

The shipped image keeps everything on the OS disk. For anything beyond evaluation, attach a managed data disk and move both PolarDB directories onto it. The comments in the following commands mark where the disk comes in:

# after attaching and mounting the disk at /data
sudo systemctl stop polardb
sudo rsync -aHAX /var/lib/polardb/ /data/polardb/
sudo mv /var/lib/polardb /var/lib/polardb.old
sudo ln -s /data/polardb /var/lib/polardb
sudo systemctl start polardb

Keep the polar_datadir path in postgresql.conf consistent with wherever shared/ ends up. The start-time guard checks that the directory exists and is populated, and it refuses to start the database if it is not.

Backup and restore

Back up and restore with standard PostgreSQL tooling, unchanged:

APP_PASS=$(sudo sed -n 's/^POLARDB_APP_PASSWORD=//p' /root/polardb-credentials.txt)
SUPER_PASS=$(sudo sed -n 's/^POLARDB_SUPERUSER_PASSWORD=//p' /root/polardb-credentials.txt)
# dump the application database PGPASSWORD="$APP_PASS" pg_dump -h 127.0.0.1 -p 5432 -U polarapp \
  -Fc -f /var/tmp/polarapp.dump polarapp
# restore it into a fresh database alongside the original PGPASSWORD="$SUPER_PASS" psql -h 127.0.0.1 -p 5432 -U polardb -d postgres \
  -c "SELECT 'CREATE DATABASE restored' WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname='restored')\gexec" PGPASSWORD="$SUPER_PASS" pg_restore -h 127.0.0.1 -p 5432 -U polardb \
  -d restored /var/tmp/polarapp.dump

For a physical copy, both pg_basebackup and polar_basebackup are installed.

Where things live

• /opt/polardb holds binaries, libraries and extensions (bin/, lib/postgresql/, share/postgresql/).
• /var/lib/polardb/primary is the local PGDATA, with configuration and node-local state.
• /var/lib/polardb/shared is the PolarDB data directory, with heap, catalog, WAL and LogIndex.
• /var/log/polardb holds the server logs (logging_collector is on).
• /run/polardb holds the Unix domain socket.
• /root/polardb-credentials.txt holds this VM's generated passwords, mode 0600.
• /usr/share/polardb-postgresql holds the license, provenance, extension list and dependency license inventory.
• /etc/systemd/system/polardb.service is the engine unit.
• /usr/local/sbin/polardb-preflight.sh is the start-time guard.

To read the logs, run:

sudo journalctl -u polardb -n 50 --no-pager sudo ls -la /var/log/polardb

Tuning

The shipped settings are deliberately modest. On a larger VM, raise the two settings that matter most:

SUPER_PASS=$(sudo sed -n 's/^POLARDB_SUPERUSER_PASSWORD=//p' /root/polardb-credentials.txt) PGPASSWORD="$SUPER_PASS" psql -h 127.0.0.1 -p 5432 -U polardb -d postgres \
  -c "ALTER SYSTEM SET shared_buffers = '2GB';" \
  -c "ALTER SYSTEM SET effective_cache_size = '6GB';"
sudo systemctl restart polardb

As rules of thumb, set shared_buffers to around 25 % of RAM and effective_cache_size to around 75 %. Raise max_connections only if you need it, because a connection pooler is almost always the better answer.

PolarDB adds its own settings on top, all prefixed polar_ and all visible with SHOW ALL. polar_logindex_mem_size, polar_xlog_queue_buffers and polar_xlog_page_buffers govern the replay machinery. Raise them alongside shared_buffers on a large instance.

Security checklist

• The image ships no database. initdb runs on your VM, so no default or blank password can exist.
• Both passwords are generated per VM from the kernel CSPRNG and written only to /root/polardb-credentials.txt (0600, root).
• password_encryption is scram-sha-256, and every login role carries a SCRAM verifier. There is no trust and no md5 anywhere.
• listen_addresses is localhost, and the offer advertises only SSH.
• polardb.service runs as an unprivileged system account with NoNewPrivileges, PrivateTmp, ProtectSystem=full, ProtectHome and a restricted address family set.
• The start-time guard refuses to start the engine if the credentials or the hardened configuration are missing or weakened.
• The application role is NOSUPERUSER NOCREATEROLE NOCREATEDB NOBYPASSRLS.
• No compiler, no headers and no build tree ship in the image.
• Rotate a password with ALTER ROLE ... PASSWORD '...', and update the credentials file to match.

Troubleshooting

polardb.service will not start. The guard is refusing it. To see why, run:

sudo /usr/local/sbin/polardb-preflight.sh; echo "exit=$?"

The script prints exactly which condition failed. The most common cause on a rebuilt VM is a missing or sample /root/polardb-credentials.txt.

First boot did not run. Check the sentinel and the unit:

ls -la /var/lib/sac/data/polardb-firstboot.done
sudo journalctl -u polardb-firstboot.service --no-pager | tail -40

Connection refused from your workstation. This is expected, because the database is on loopback. Use the SSH tunnel, or follow the exposure section above.

Password authentication failed. Read the credentials file again. The passwords are unique to this VM and are not the ones in any other document.

sudo sed -n 's/^POLARDB_APP_PASSWORD=//p' /root/polardb-credentials.txt

Checking what shipped. The build provenance and the full dependency license inventory are on the machine:

cat /usr/share/polardb-postgresql/BUILD-PROVENANCE.txt head -40 /usr/share/polardb-postgresql/dependency-licences.txt

License and provenance

PolarDB for PostgreSQL is licensed under the Apache License 2.0, over PostgreSQL, which is under the PostgreSQL License. Both texts ship on the image at /usr/share/polardb-postgresql/LICENSE and /usr/share/polardb-postgresql/COPYRIGHT, with upstream's NOTICE alongside them.

The image is built from the pinned upstream tag v17.10.1.0, commit accf02e2fda3d8e47e78afa61f42795e0c4065c4. That commit is compiled into the binary and is what SELECT version() reports. You can therefore verify on your own VM exactly which upstream source produced the engine that you are running.

Every vendored extension's own license artifact is preserved at /usr/share/polardb-postgresql/source-licences/. The complete OS dependency license inventory is at /usr/share/polardb-postgresql/dependency-licences.txt.

Further reading

• PolarDB for PostgreSQL documentation: https://polardb.github.io/polardb-pg-docs/
• PolarDB for PostgreSQL source: https://github.com/polardb/PolarDB-for-PostgreSQL
• PostgreSQL 17 documentation: https://www.postgresql.org/docs/17/

Support

This image is published by SecureAnyCloud. For help with the image itself, such as deployment, first boot, credentials and the start-time guard, contact SecureAnyCloud support at sales@secureanycloud.com. For questions about PolarDB the software, use upstream's documentation and GitHub discussions.

Deploy on Azure

Launch PolarDB for PostgreSQL on Ubuntu 24.04 on Azure with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com