\n\n# Table of contents\n\n- [🔌 Usage: As a proxy](#-usage-as-a-proxy)\n- [💻 Usage: As a Postgres server emulator](#-usage-as-a-postgres-server-emulator)\n- [📚 Some literature](#-some-literature)\n\n\n\n# 🔌 Usage: As a proxy\n\nLet's say that you want to proxy a real postgres server instance, and let filter only requests that access a given table.\n\npg-server contains a small utility that abstracts away most of the heavy lifting and which lets you listen/intercept requests.\n\n```typescript\nimport {createSimpleProxy, ISimpleProxySession} from 'pg-server';\n\n\nconst server = createSimpleProxy(\n // The DB that must be proxied\n { port: 5432, host: 'localhost' }\n\n // A new session context\n // (one will be constructed for each connection)\n , class implements ISimpleProxySession {\n // An optional handler which will be called\n // on each new connection\n onConnect(socket: Socket) {\n console.log('👤 Client connected, IP: ', socket.remoteAddress);\n }\n // A handler which will be called for each sql query\n onQuery(query: string) {\n\n // Ok, proceed to this query, unmodified.\n // You could also choose to modify the query.\n return query;\n // ... or return an error\n return { error: 'Forbidden !' };\n }\n});\n\n\n// listen on localhost:1234\n// ... which will now appear as a postgres db server !\nsever.listen(1234, 'localhost');\n```\n\n## Example: Analyze & Intercept some queries\n\nYou can use [pgsql-ast-parser](https://github.com/oguimbal/pgsql-ast-parser), another library of mine, to parse the inbound requests in order to decide if you'd like to forward them to the actual sql server.\n\nFor instance, to only allow simple select requests without joins on a given set of tables, you could do something like that:\n\n```typescript\nimport {createSimpleProxy, ISimpleProxySession} from 'pg-server';\nimport {parse, astVisitor} from 'pgsql-ast-parser';\n\n\nconst server = createSimpleProxy(\n // The DB that must be proxied\n { port: 5432, host: 'localhost' }\n , class implements ISimpleProxySession {\n onQuery(query: string) {\n\n // parse the query & check it has only one query\n const parsed = parse(query);\n if (parsed.length !== 1) {\n return { error: 'Only single queries accepted' };\n }\n\n // check that it is a select\n const [first] = parsed\n if (first.type !== 'select') {\n return { error: 'Only SELECT queries accepted' };\n }\n\n // check that it selects data from \"some_public_table\" only\n let authorized = true;\n astVisitor(m => ({\n tableRef: r => authorized = authorized\n && !r.schema\n && r.name === 'some_public_table',\n })).statement(first);\n if (!authorized) {\n return { error: `You're note supposed to be here :/` };\n }\n\n // ok, proceed to this query, unmodified.\n return query;\n }\n});\n\nserver.listen(1234, '127.0.0.1');\n```\n\nTest it:\n\n```typescript\nconst client = new require('pg')\n .Client('postgresql://user:pwd@localhost:1234/mydb')\n\n// this works:\nawait client.query('select * from some_public_table')\n// this fails:\nawait client.query('select * from other_table')\n```\n## Advanced proxy\n\nThe `createSimpleProxy` abstracts away lots of things.\nIf you wish to have a more fine grained control over which data is exchanged, you can use `createAdvancedProxy()` (refer to the types, and to the [\"Some literature\"](#-some-literature) section below to understand how it works).\n\n# 💻 Usage: As a Postgres server emulator\n\nYou could expose a brand new fake postgres server to the world, without an actual postgres datbase server. As [a Honeypot](https://en.wikipedia.org/wiki/Honeypot_(computing)), for instance.\n\nYou could also simulate a postgres db, for which you could use [pg-mem](https://github.com/oguimbal/pg-mem), another lib of mine which simulates a db in memory.\n\n## Simplified interface\n\nTODO\n\n## Advanced interface\n\n`createAdvancedServer()` gives you full control over commands received/responses sent. Only use this if you know the pg protocol a bit.\n\nExample:\n\n```typescript\nconst server = createAdvancedServer(class implements IAdvanceServerSession {\n // An optional handler which will be called\n // on each new connection\n onConnect(socket: Socket) {\n console.log('👤 Client connected, IP: ', socket.remoteAddress);\n }\n\n // A handler which will be called on each received instuction.\n onCommand({ command }: DbRawCommand, response: IResponseWriter) {\n // use the \"response\" writer\n // to react to the \"command\" argument\n }\n})\n\nserver.listen(1234, '127.0.0.1');\n\n```\n\n\nIf you would like your postgres server on a custom already open socket, you can also use the `bindSocket()`, of which `createAdvancedServer()` is just a wrapper.\n\n## With pg-mem\n\nTODO\n\n\n# 📚 Some literature\n\n- [awesome-honeypots](https://github.com/paralax/awesome-honeypots) A list of honeypots\n- [simple & extended queries](https://blog.hackeriet.no/Simple-and-Extended-postgresql-queries/) A very short explanation about query modes\n- [postgres on the wire](https://www.pgcon.org/2014/schedule/attachments/330_postgres-for-the-wire.pdf) 55 slides about the postgres protocol\n- [Protocol flow](https://www.postgresql.org/docs/13/protocol-flow.html) The official procol explanation\n\n\n# Todo\n\n- SSL support (protocol version 1234.5679 on init)\n- Simplified interface\n","readmeFilename":"readme.md"}
![](\"http://img.shields.io/npm/v/pg-server.svg\")
\n ![](\"https://img.shields.io/npm/dm/pg-server.svg\")
\n \n