embedded-postgres 18.6.0__py3-none-win_amd64.whl

embedded_postgres/pginstall/share/tsearch_data/xsyn_sample.rules

@@ -0,0 +1,6 @@
+# Sample rules file for eXtended Synonym (xsyn) dictionary
+# format is as follows:
+#
+# word synonym1 synonym2 ...
+#
+supernova sn sne 1987a

embedded_postgres/postgres_server.py

@@ -0,0 +1,291 @@
+from pathlib import Path
+from typing import Optional, Dict, Union
+import shutil
+import atexit
+import subprocess
+import os
+import logging
+import platform
+import psutil
+import time
+
+from ._commands import POSTGRES_BIN_PATH, initdb, pg_ctl
+from .utils import find_suitable_port, find_suitable_socket_dir, DiskList, PostmasterInfo, process_is_running
+
+if platform.system() != 'Windows':
+    from .utils import ensure_user_exists, ensure_prefix_permissions, ensure_folder_permissions
+
+_logger = logging.getLogger('embedded_postgres')
+
+class PostgresServer:
+    """ Provides a common interface for interacting with a server.
+    """
+    import platformdirs
+    import fasteners
+
+    _instances : Dict[Path, 'PostgresServer'] = {}
+
+    # NB home does not always support locking, eg NFS or LUSTRE (eg some clusters)
+    # so, use user_runtime_path instead, which seems to be in a local filesystem
+    runtime_path : Path = platformdirs.user_runtime_path('python_PostgresServer')
+    lock_path = platformdirs.user_runtime_path('python_PostgresServer') / '.lockfile'
+    _lock  = fasteners.InterProcessLock(lock_path)
+
+    def __init__(self, pgdata : Path, *, cleanup_mode : Optional[str] = 'stop'):
+        """ Initializes the postgresql server instance.
+            Constructor is intended to be called directly, use get_server() instead.
+        """
+        assert cleanup_mode in [None, 'stop', 'delete']
+
+        self.pgdata = pgdata
+        self.log = self.pgdata / 'log'
+
+        # postgres user name, NB not the same as system user name
+        self.system_user = None
+
+        # note os.geteuid() is not available on windows, so must go after
+        if platform.system() != 'Windows' and os.geteuid() == 0:
+            # running as root
+            # need a different system user to run as
+            self.system_user = 'embedded_postgres'
+            ensure_user_exists(self.system_user)
+
+        self.postgres_user = "postgres"
+        list_path = self.pgdata / '.handle_pids.json'
+        self.global_process_id_list = DiskList(list_path)
+        self.cleanup_mode = cleanup_mode
+        self._postmaster_info : Optional[PostmasterInfo] = None
+        self._count = 0
+
+        atexit.register(self._cleanup)
+        with self._lock:
+            self._instances[self.pgdata] = self
+            self.ensure_pgdata_inited()
+            self.ensure_postgres_running()
+            self.global_process_id_list.get_and_add(os.getpid())
+
+    def get_postmaster_info(self) -> PostmasterInfo:
+        assert self._postmaster_info is not None
+        return self._postmaster_info
+
+    def get_pid(self) -> Optional[int]:
+        """ Returns the pid of the postgresql server process.
+            (First line of postmaster.pid file).
+            If the server is not running, returns None.
+        """
+        return self.get_postmaster_info().pid
+
+    def get_uri(self, database : Optional[str] = None) -> str:
+        """ Returns a connection string for the postgresql server.
+        """
+        return self.get_postmaster_info().get_uri(database=database)
+
+    def ensure_pgdata_inited(self) -> None:
+        """ Initializes the pgdata directory if it is not already initialized.
+        """
+        if platform.system() != 'Windows' and os.geteuid() == 0:
+            import pwd
+            import stat
+            assert self.system_user is not None
+            ensure_prefix_permissions(self.pgdata)
+            ensure_prefix_permissions(POSTGRES_BIN_PATH)
+
+            read_perm = stat.S_IRGRP | stat.S_IROTH
+            execute_perm = stat.S_IXGRP | stat.S_IXOTH
+            # for envs like cibuildwheel docker, where the user is has no permission otherwise
+            ensure_folder_permissions(POSTGRES_BIN_PATH, execute_perm | read_perm)
+            ensure_folder_permissions(POSTGRES_BIN_PATH.parent / 'lib', read_perm)
+
+
+            os.chown(self.pgdata, pwd.getpwnam(self.system_user).pw_uid,
+                        pwd.getpwnam(self.system_user).pw_gid)
+
+        if not (self.pgdata / 'PG_VERSION').exists(): # making a new PGDATA
+            # First ensure there are no left-over servers on a previous version of the same pgdata path,
+            # which does happen on Mac/Linux if the previous pgdata was deleted without stopping the server process
+            # (the old server continues running for some time, sometimes indefinitely)
+            #
+            # It is likely the old server could also corrupt the data beyond the socket file, so it is best to kill it.
+            # This must be done before initdb to ensure no race conditions with the old server.
+            #
+            # Since we do not know PID information of the old server, we stop all servers with the same pgdata path.
+            # way to test this: python -c 'import pixeltable as pxt; pxt.Client()'; rm -rf ~/.pixeltable/; python -c 'import pixeltable as pxt; pxt.Client()'
+            _logger.info(f'no PG_VERSION file found within {self.pgdata}. Initializing pgdata')
+            for proc in psutil.process_iter(attrs=['name', 'cmdline']):
+                if proc.info['name'] == 'postgres':
+                    if proc.info['cmdline'] is not None and str(self.pgdata) in proc.info['cmdline']:
+                        _logger.info(f"Found a running postgres server with same pgdata: {proc.as_dict(attrs=['name', 'pid', 'cmdline'])=}.\
+                                            Assuming it is a leftover from a previous run on a different version of the same pgdata path, killing it.")
+                        proc.terminate()
+                        try:
+                            proc.wait(2) # wait at most a second
+                        except psutil.TimeoutExpired:
+                            pass
+                        if proc.is_running():
+                            proc.kill()
+                        assert not proc.is_running()
+
+            initdb(['--auth=trust', '--auth-local=trust', '--encoding=utf8', '-U', self.postgres_user], pgdata=self.pgdata,
+                    user=self.system_user)
+        else:
+            _logger.info('PG_VERSION file found, skipping initdb')
+
+    def ensure_postgres_running(self) -> None:
+        """ pre condition: pgdata is initialized, being run with lock.
+            post condition: self._postmaster_info is set.
+        """
+
+        postmaster_info = PostmasterInfo.read_from_pgdata(self.pgdata)
+        if postmaster_info is not None and postmaster_info.is_running():
+            _logger.info(f"a postgres server is already running: {postmaster_info=} {postmaster_info.process=}")
+            self._postmaster_info = postmaster_info
+        else:
+            if postmaster_info is not None and not postmaster_info.is_running():
+                _logger.info(f"found a postmaster.pid file, but the server is not running: {postmaster_info=}")
+            if postmaster_info is None:
+                _logger.info(f"no postmaster.pid file found in {self.pgdata}")
+
+            if platform.system() != 'Windows':
+                # use sockets to avoid any future conflict with port numbers
+                socket_dir = find_suitable_socket_dir(self.pgdata, self.runtime_path)
+
+                if self.system_user is not None and socket_dir != self.pgdata:
+                    ensure_prefix_permissions(socket_dir)
+                    socket_dir.chmod(0o777)
+
+                pg_ctl_args = ['-w',  # wait for server to start
+                        '-o', '-h ""',  # no listening on any IP addresses (forwarded to postgres exec) see man postgres for -hj
+                        '-o',  f'-k {socket_dir}', # socket option (forwarded to postgres exec) see man postgres for -k
+                        '-l', str(self.log), # log location: set to pgdata dir also
+                        'start' # action
+                ]
+            else: # Windows,
+                socket_dir = None
+                # socket.AF_UNIX is undefined when running on Windows, so default to a port
+                host = "127.0.0.1"
+                port = find_suitable_port(host)
+                pg_ctl_args = ['-w',  # wait for server to start
+                        '-o', f'-h "{host}"',
+                        '-o', f'-p {port}',
+                        '-l', str(self.log), # log location: set to pgdata dir also
+                        'start' # action
+                ]
+
+            try:
+                _logger.info(f"running pg_ctl... {pg_ctl_args=}")
+                pg_ctl(pg_ctl_args,pgdata=self.pgdata, user=self.system_user, timeout=10)
+            except subprocess.CalledProcessError as err:
+                _logger.error(f"Failed to start server.\nShowing contents of postgres server log ({self.log.absolute()}) below:\n{self.log.read_text()}")
+                raise err
+            except subprocess.TimeoutExpired as err:
+                _logger.error(f"Timeout starting server.\nShowing contents of postgres server log ({self.log.absolute()}) below:\n{self.log.read_text()}")
+                raise err
+
+            while True:
+                # in Windows, when there is a postmaster.pid,  init_ctl seems to return
+                # but the file is not immediately updated, here we wait until the file shows
+                # a new running server. see test_stale_postmaster
+                _logger.info(f'waiting for postmaster info to show a running process')
+                pinfo =  PostmasterInfo.read_from_pgdata(self.pgdata)
+                _logger.info(f'running... checking if ready {pinfo=}')
+                if pinfo is not None and pinfo.is_running() and pinfo.status == 'ready':
+                    self._postmaster_info = pinfo
+                    break
+
+                _logger.info(f'not ready yet... waiting a bit more...')
+                time.sleep(1.)
+
+        _logger.info(f"Now asserting server is running {self._postmaster_info=}")
+        assert self._postmaster_info is not None
+        assert self._postmaster_info.is_running()
+        assert self._postmaster_info.status == 'ready'
+
+    def _cleanup(self) -> None:
+        with self._lock:
+            pids = self.global_process_id_list.get_and_remove(os.getpid())
+            _logger.info(f"exiting {os.getpid()} remaining {pids=}")
+            if pids != [os.getpid()]: # includes case where already cleaned up
+                return
+
+            _logger.info(f"cleaning last handle for server: {self.pgdata}")
+            # last handle is being removed
+            del self._instances[self.pgdata]
+            if self.cleanup_mode is None: # done
+                return
+
+            assert self.cleanup_mode in ['stop', 'delete']
+            if self._postmaster_info is not None:
+                if self._postmaster_info.process.is_running():
+                    try:
+                        pg_ctl(['-w', 'stop'], pgdata=self.pgdata, user=self.system_user)
+                        stopped = True
+                    except subprocess.CalledProcessError:
+                        stopped = False
+                        pass # somehow the server is already stopped.
+
+                    if not stopped:
+                        _logger.warning(f"Failed to stop server, killing it instead.")
+                        self._postmaster_info.process.terminate()
+                        try:
+                            self._postmaster_info.process.wait(2)
+                        except psutil.TimeoutExpired:
+                            pass
+                        if self._postmaster_info.process.is_running():
+                            self._postmaster_info.process.kill()
+
+            if self.cleanup_mode == 'stop':
+                return
+
+            assert self.cleanup_mode == 'delete'
+            shutil.rmtree(str(self.pgdata))
+            atexit.unregister(self._cleanup)
+
+    def psql(self, command : str) -> str:
+        """ Runs a psql command on this server. The command is passed to psql via stdin.
+        """
+        executable = POSTGRES_BIN_PATH / 'psql'
+        stdout = subprocess.check_output(f'{executable} {self.get_uri()}',
+                                         input=command.encode(), shell=True)
+        return stdout.decode("utf-8")
+
+    def __enter__(self):
+        self._count += 1
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._count -= 1
+        if self._count <= 0:
+            self._cleanup()
+
+    def cleanup(self) -> None:
+        """ Stops the postgresql server and removes the pgdata directory.
+        """
+        self._cleanup()
+
+
+def get_server(pgdata : Union[Path,str] , cleanup_mode : Optional[str] = 'stop' ) -> PostgresServer:
+    """ Returns handle to postgresql server instance for the given pgdata directory.
+    Args:
+        pgdata: pddata directory. If the pgdata directory does not exist, it will be created, but its
+        parent must exists and be a valid directory.
+        cleanup_mode: If 'stop', the server will be stopped when the last handle is closed (default)
+                        If 'delete', the server will be stopped and the pgdata directory will be deleted.
+                        If None, the server will not be stopped or deleted.
+
+        To create a temporary server, use mkdtemp() to create a temporary directory and pass it as pg_data,
+        and set cleanup_mode to 'delete'.
+    """
+    if isinstance(pgdata, str):
+        pgdata = Path(pgdata)
+    pgdata = pgdata.expanduser().resolve()
+
+    if not pgdata.parent.exists():
+        raise FileNotFoundError(f"Parent directory of pgdata does not exist: {pgdata.parent}")
+
+    if not pgdata.exists():
+        pgdata.mkdir(parents=False, exist_ok=False)
+
+    if pgdata in PostgresServer._instances:
+        return PostgresServer._instances[pgdata]
+
+    return PostgresServer(pgdata, cleanup_mode=cleanup_mode)

embedded_postgres/utils.py

@@ -0,0 +1,278 @@
+from pathlib import Path
+import typing
+from typing import Optional, List, Dict
+import subprocess
+import json
+import logging
+import hashlib
+import socket
+import platform
+import stat
+import psutil
+import datetime
+import shutil
+
+_logger = logging.getLogger('embedded_postgres')
+
+class PostmasterInfo:
+    """Struct with contents of the PGDATA/postmaster.pid file, contains information about the running server.
+    Example of file contents: (comments added for clarity)
+    cat /Users/orm/Library/Application Support/Postgres/var-15/postmaster.pid
+        ```
+        3072        # pid
+        /Users/orm/Library/Application Support/Postgres/var-15 # pgdata
+        1712346200  # start_time
+        5432    # port
+        /tmp # socker_dir, where .s.PGSQL.5432 is located
+        localhost # listening on this hostname
+        8826964     65536 # shared mem size?, shmget id (can deallocate with sysv_ipc.remove_shared_memory(shmget_id))
+        ready # server status
+        ```
+    """
+
+    def __init__(self, lines : List[str]):
+        _lines = ['pid', 'pgdata', 'start_time', 'port', 'socket_dir', 'hostname', 'shared_memory_info', 'status']
+        assert len(lines) == len(_lines), f"_lines: {_lines=} lines: {lines=}"
+        clean_lines = [ line.strip() for line in lines ]
+
+        raw : Dict[str,str] = dict(zip(_lines, clean_lines))
+
+        self.pid = int(raw['pid'])
+        self.pgdata = Path(raw['pgdata'])
+        self.start_time = datetime.datetime.fromtimestamp(int(raw['start_time']))
+
+        if raw['socket_dir']:
+            self.socket_dir = Path(raw['socket_dir'])
+        else:
+            self.socket_dir = None
+
+        if raw['hostname']:
+            self.hostname = raw['hostname']
+        else:
+            self.hostname = None
+
+        if raw['port']:
+            self.port = int(raw['port'])
+        else:
+            self.port = None
+
+        # not sure what this is in windows
+        self.shmem_info = raw['shared_memory_info']
+        self.status = raw['status']
+
+        self.process = None # will be not None if process is running
+        self._init_process_meta()
+
+    def _init_process_meta(self) -> Optional[psutil.Process]:
+        if self.pid is None:
+            return
+        try:
+            process = psutil.Process(self.pid)
+        except psutil.NoSuchProcess:
+            return
+
+        self.process = process
+        # exact_create_time = datetime.datetime.fromtimestamp(process.create_time())
+        # if abs(self.start_time - exact_create_time) <= datetime.timedelta(seconds=1):
+
+    def is_running(self) -> bool:
+        return self.process is not None and self.process.is_running()
+
+    @classmethod
+    def read_from_pgdata(cls, pgdata : Path) -> Optional['PostmasterInfo']:
+        postmaster_file = pgdata / 'postmaster.pid'
+        if not postmaster_file.exists():
+            return None
+
+        lines = postmaster_file.read_text().splitlines()
+        return cls(lines)
+
+    def get_uri(self, user : str = 'postgres', database : Optional[str] = None) -> str:
+        """ Returns a connection uri string for the postgresql server using the information in postmaster.pid"""
+        if database is None:
+            database = user
+
+        if self.socket_dir is not None:
+            return f"postgresql://{user}:@/{database}?host={self.socket_dir}"
+        elif self.port is not None:
+            assert self.hostname is not None
+            return f"postgresql://{user}:@{self.hostname}:{self.port}/{database}"
+        else:
+            raise RuntimeError("postmaster.pid does not contain port or socket information")
+
+    @property
+    def shmget_id(self) -> Optional[int]:
+        if platform.system() == 'Windows':
+            return None
+
+        if not self.shmem_info:
+            return None
+        raw_id = self.shmem_info.split()[-1]
+        return int(raw_id)
+
+    @property
+    def socket_path(self) -> Optional[Path]:
+        if self.socket_dir is not None:
+            # TODO: is the port always 5432 for the socket? or does it depend on the port in postmaster.pid?
+            return self.socket_dir / f'.s.PGSQL.{self.port}'
+        return None
+
+    def __repr__(self) -> str:
+        return f"PostmasterInfo(pid={self.pid}, pgdata={self.pgdata}, start_time={self.start_time}, hostname={self.hostname} port={self.port}, socket_dir={self.socket_dir} status={self.status}, process={self.process})"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+def process_is_running(pid : int) -> bool:
+    assert pid is not None
+    return psutil.pid_exists(pid)
+
+if platform.system() != 'Windows':
+    def ensure_user_exists(username : str) -> Optional['pwd.struct_passwd']:
+        """ Ensure system user `username` exists.
+            Returns their pwentry if user exists, otherwise it creates a user through `useradd`.
+            Assume permissions to add users, eg run as root.
+        """
+        import pwd
+
+        try:
+            entry = pwd.getpwnam(username)
+        except KeyError:
+            entry = None
+
+        if entry is None:
+            subprocess.run(["useradd", "-s", "/bin/bash", username], check=True, capture_output=True, text=True)
+            entry = pwd.getpwnam(username)
+
+        return entry
+
+    def ensure_prefix_permissions(path: Path):
+        """ Ensure target user can traverse prefix to path
+            Permissions for everyone will be increased to ensure traversal.
+        """
+        # ensure path exists and user exists
+        assert path.exists()
+        prefix = path.parent
+        # chmod g+rx,o+rx: enable other users to traverse prefix folders
+        g_rx_o_rx = stat.S_IRGRP |  stat.S_IROTH | stat.S_IXGRP | stat.S_IXOTH
+        while True:
+            curr_permissions = prefix.stat().st_mode
+            ensure_permissions = curr_permissions | g_rx_o_rx
+            # TODO: are symlinks handled ok here?
+            prefix.chmod(ensure_permissions)
+            if prefix == prefix.parent: # reached file system root
+                break
+            prefix = prefix.parent
+
+    def ensure_folder_permissions(path: Path, flag : int):
+        """ Ensure target user can read,  and execute the folder.
+            Permissions for everyone will be increased to ensure traversal.
+        """
+        # read and traverse folder
+        g_rx_o_rx = stat.S_IRGRP |  stat.S_IROTH | stat.S_IXGRP | stat.S_IXOTH
+
+        def _helper(path: Path):
+            if path.is_dir():
+                path.chmod(path.stat().st_mode | g_rx_o_rx )
+                for child in path.iterdir():
+                    _helper(child)
+            else:
+                path.chmod(path.stat().st_mode | flag)
+
+        _helper(path)
+
+class DiskList:
+    """ A list of integers stored in a file on disk.
+    """
+    def __init__(self, path : Path):
+        self.path = path
+
+    def get_and_add(self, value : int) -> List[int]:
+        old_values = self.get()
+        values = old_values.copy()
+        if value not in values:
+            values.append(value)
+            self.put(values)
+        return old_values
+
+    def get_and_remove(self, value : int) -> List[int]:
+        old_values = self.get()
+        values = old_values.copy()
+        if value in values:
+            values.remove(value)
+            self.put(values)
+        return old_values
+
+    def get(self) -> List[int]:
+        if not self.path.exists():
+            return []
+        return json.loads(self.path.read_text())
+
+    def put(self, values : List[int]) -> None:
+        self.path.write_text(json.dumps(values))
+
+
+def socket_name_length_ok(socket_name : Path):
+    ''' checks whether a socket path is too long for domain sockets
+        on this system. Returns True if the socket path is ok, False if it is too long.
+    '''
+    if socket_name.exists():
+        return socket_name.is_socket()
+
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    try:
+        sock.bind(str(socket_name))
+        return True
+    except OSError as err:
+        if 'AF_UNIX path too long' in str(err):
+            return False
+        raise err
+    finally:
+        sock.close()
+        socket_name.unlink(missing_ok=True)
+
+def find_suitable_socket_dir(pgdata, runtime_path) -> Path:
+    """ Assumes server is not running. Returns a suitable directory for used as pg_ctl -o '-k ' option.
+        Usually, this is the same directory as the pgdata directory.
+        However, if the pgdata directory exceeds the maximum length for domain sockets on this system,
+        a different directory will be used.
+    """
+    # find a suitable directory for the domain socket
+    # 1. pgdata. simplest approach, but can be too long for unix socket depending on the path
+    # 2. runtime_path. This is a directory that is intended for storing runtime data.
+
+    # for shared folders, use a hash of the path to avoid collisions of different folders
+    # use a hash of the pgdata path combined with inode number to avoid collisions
+    string_identifier = f'{pgdata}-{pgdata.stat().st_ino}'
+    path_hash = hashlib.sha256(string_identifier.encode()).hexdigest()[:10]
+
+    candidate_socket_dir = [
+        pgdata,
+        runtime_path / path_hash,
+    ]
+
+    ok_path = None
+    for path in candidate_socket_dir:
+        path.mkdir(parents=True, exist_ok=True)
+        # name used by postgresql for domain socket is .s.PGSQL.5432
+        if socket_name_length_ok(path / '.s.PGSQL.5432'):
+            ok_path = path
+            _logger.info(f"Using socket path: {path}")
+            break
+        else:
+            _logger.info(f"Socket path too long: {path}. Will try a different directory for socket.")
+
+    if ok_path is None:
+        raise RuntimeError("Could not find a suitable socket path")
+
+    return ok_path
+
+def find_suitable_port(address : Optional[str] = None) -> int:
+    """Find an available TCP port."""
+    if address is None:
+        address = '127.0.0.1'
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.bind((address, 0))
+    port = sock.getsockname()[1]
+    sock.close()
+    return port

embedded_postgres-18.6.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: embedded-postgres
+Version: 18.6.0
+Summary: PostgreSQL server binaries as a pip-installable wheel, with a small Python layer to init, start and stop it
+Author: Valeriy V. Pushkar
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/kainpl/embedded-postgres
+Project-URL: Issues, https://github.com/kainpl/embedded-postgres/issues
+Keywords: postgresql,postgres,embedded,pgvector,wheel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: fasteners>=0.19
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Requires-Dist: psycopg2-binary; extra == "test"
+Requires-Dist: sqlalchemy>=2; extra == "test"
+Requires-Dist: sqlalchemy-utils; extra == "test"
+Dynamic: license-file
+
+# embedded-postgres
+
+PostgreSQL server binaries as a pip-installable wheel, plus a small Python
+layer that runs `initdb`, starts and stops the server, and hands you a
+connection URI. No system PostgreSQL, no root, no Docker.
+
+```python
+import embedded_postgres
+
+with embedded_postgres.get_server("/path/to/pgdata") as pg:
+    uri = pg.get_uri()          # postgresql://postgres:@localhost:PORT/postgres
+    pg.psql("create extension vector")
+```
+
+## Status
+
+Early. This project started on 2026-09-07 as a fork of
+[pgserver](https://github.com/orm011/pgserver), which had stopped at
+PostgreSQL 16.2 in mid-2024. The goals that justify a separate project:
+
+- **current PostgreSQL** (18.6 today), with minor releases picked up as they ship;
+- **Linux aarch64** (and later armv7l) wheels next to x86_64, macOS and Windows;
+- **one wheel per platform** (`py3-none-<platform>`) instead of one per Python version;
+- **contrib** modules such as `pg_stat_statements` shipped alongside `pgvector`.
+
+Current state (2026-09-07): PostgreSQL 18.6 + pgvector 0.8.6 build and pass
+the test suite on all five targets — `manylinux_2_28` x86_64 and aarch64,
+`macosx_11_0` arm64 and x86_64, `win_amd64` — 12–17 MB per wheel. Until the
+first release is tagged, wheels are only available as workflow artifacts from
+the GitHub Actions runs.
+
+## Windows and Administrator accounts
+
+PostgreSQL's tools refuse to run with Administrator rights: `initdb`,
+`pg_ctl` and `postgres` re-launch themselves with a *restricted token* in which
+the Administrators group is deny-only. Any directory that is reachable only
+through that group is then invisible to them — including the binaries
+themselves. Since CPython 3.12.4, `tempfile.mkdtemp()` on Windows creates
+exactly such directories (SYSTEM, Administrators and the owner; for an
+administrator the owner *is* Administrators). Symptom:
+
+```
+invalid binary "...\embedded_postgres\pginstallin\initdb.exe": Permission denied
+initdb: error: program "postgres" is needed by initdb but was not found in the same directory as "initdb"
+```
+
+If you run as Administrator, keep the package and the data directory out of
+`mkdtemp()`-created trees, or grant your user an explicit ACE
+(`icacls <dir> /grant "%USERNAME%:(OI)(CI)F" /T`). Regular user accounts and
+directories created with `os.mkdir()` / `python -m venv` are unaffected.
+
+## Versioning
+
+The package version mirrors the bundled PostgreSQL release: `MAJOR.MINOR` are
+PostgreSQL's, the third number counts this package's own revisions for that
+PostgreSQL version. `18.6.0` is the first packaging of PostgreSQL 18.6.
+
+## How it is built
+
+`pgbuild/Makefile` downloads the official PostgreSQL source tarball and
+`pgvector`, builds `world-bin` (server, client tools and contrib, no docs)
+with `configure && make`, and installs the result into
+`src/embedded_postgres/pginstall/`. `cibuildwheel` runs that build once per
+platform in CI and packages the tree into a wheel. Nothing is compiled on the
+user's machine.
+
+Configure flags: `--without-readline --without-icu`. No OpenSSL — the server
+is meant to listen on localhost or a Unix socket.
+
+## License
+
+Apache License 2.0 for this project's own code. The bundled PostgreSQL and
+pgvector binaries are distributed under the PostgreSQL License. See `NOTICE`
+and `THIRD_PARTY_NOTICES.md`.