{"id":14483547,"url":"https://github.com/alloc/tusken","last_synced_at":"2025-05-03T00:31:35.900Z","repository":{"id":58744969,"uuid":"529241654","full_name":"alloc/tusken","owner":"alloc","description":"100% type-safe query builder compatible with any Postgres client 🐘 Generated table/function types, tree-shakable, implicit type casts, and more","archived":true,"fork":false,"pushed_at":"2024-05-31T20:27:37.000Z","size":879,"stargazers_count":223,"open_issues_count":37,"forks_count":3,"subscribers_count":7,"default_branch":"alpha","last_synced_at":"2025-04-19T23:33:05.821Z","etag":null,"topics":["postgres","query-builder","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alloc.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-26T12:05:25.000Z","updated_at":"2024-11-11T16:57:49.000Z","dependencies_parsed_at":"2024-06-19T02:47:31.554Z","dependency_job_id":"25f93ac6-c12a-4f0f-a472-70a7f49867f1","html_url":"https://github.com/alloc/tusken","commit_stats":{"total_commits":291,"total_committers":3,"mean_commits":97.0,"dds":0.07903780068728528,"last_synced_commit":"c4f723deebe5b621019e35620613beff2a6ad82e"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alloc%2Ftusken","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alloc%2Ftusken/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alloc%2Ftusken/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alloc%2Ftusken/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alloc","download_url":"https://codeload.github.com/alloc/tusken/tar.gz/refs/heads/alpha","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251787176,"owners_count":21643833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["postgres","query-builder","typescript"],"created_at":"2024-09-03T00:01:51.276Z","updated_at":"2025-05-03T00:31:33.921Z","avatar_url":"https://github.com/alloc.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"⚠️ This library is currently in alpha. Contributors wanted!\n\n---\n\n# tusken\n\nPostgres client from a galaxy far, far away.\n\n- your database is the source-of-truth for TypeScript generated types\n- type safety for all queries (even subqueries)\n  - all built-in Postgres functions are available and type-safe\n  - implicit type casts are accounted for\n- minimal, intuitive SQL building\n  - shortcuts for common tasks (eg: `get`, `put`, and more)\n  - identifiers are case-sensitive\n- lightweight, largely tree-shakeable\n- works with [`@tusken/cli`] to easily import CSV files, wipe data, generate a type-safe client, dump the schema for migrations, and more\n- you control the [`pg`] version as a peer dependency\n- query streaming with the `.stream` method (just install [`pg-query-stream`] and run `tusken generate`)\n\n[`pg`]: https://www.npmjs.com/package/pg\n[`pg-query-stream`]: https://www.npmjs.com/package/pg-query-stream\n[`@tusken/cli`]: https://github.com/alloc/tusken/tree/master/packages/tusken-cli\n\n### Migrations?\n\nUse [graphile-migrate](https://github.com/graphile/migrate).\n\n## Install\n\n```sh\npnpm i tusken@alpha pg postgres-range postgres-interval\npnpm i @tusken/cli@alpha -D\n```\n\n## Usage\n\nFirst, you need a `tusken.config.ts` file in your project root, unless you plan on using the default config. By default, the Postgres database is assumed to exist at `./postgres` relative to the working directory (customize with `dataDir` in your config) and the generated types are emitted into the `./src/generated` folder (customize with `schemaDir` in your config).\n\n```ts\nimport { defineConfig } from 'tusken/config'\n\nexport default defineConfig({\n  dataDir: './postgres',\n  schemaDir: './src/generated',\n  connection: {\n    host: 'localhost',\n    port: 5432,\n    user: 'postgres',\n    password: ' ',\n  },\n  pool: {\n    /* node-postgres pooling options */\n  },\n})\n```\n\nAfter running `pnpm tusken generate -d \u003cdatabase\u003e` in your project root, you can import the database client from `./src/db/\u003cdatabase\u003e` as **the default export.**\n\n```ts\nimport db, { t, pg } from './db/\u003cdatabase\u003e'\n```\n\nThe `t` export contains your user-defined Postgres tables and many native types. The `pg` export contains your user-defined Postgres functions and many built-in functions.\n\n### Creating, updating, deleting one row\n\nSay we have a basic `user` table like this…\n\n```sql\ncreate table \"user\" (\n  \"id\" serial primary key,\n  \"name\" text,\n  \"password\" text\n)\n```\n\nTo create a user, use the `put` method…\n\n```ts\n// Create a user\nawait db.put(t.user, { name: 'anakin', password: 'padme4eva' })\n\n// Update a user (merge, not replace)\nawait db.put(t.user, 1, { name: 'vader', password: 'darkside4eva' })\n\n// Delete a user\nawait db.put(t.user, 1, null)\n```\n\n### Getting a row by primary key\n\nHere we can use the `get` method…\n\n```ts\nawait db.get(t.user, 1)\n```\n\nSelections are supported…\n\n```ts\nawait db.get(\n  t.user(u =\u003e [u.name]),\n  1\n)\n```\n\nSelections can have aliases…\n\n```ts\nawait db.get(\n  t.user(u =\u003e [{ n: u.name }]),\n  1\n)\n\n// You can omit the array if you don't mind giving\n// everything an alias.\nawait db.get(\n  t.user(u =\u003e ({ n: u.name })),\n  1\n)\n```\n\nSelections can contain function calls…\n\n```ts\nawait db.get(\n  t.user(u =\u003e ({\n    name: pg.upper(u.name),\n  })),\n  1\n)\n```\n\nTo select all but a few columns…\n\n```ts\nawait db.get(t.user.omit('id', 'password'), 1)\n```\n\n### Inner joins\n\n```ts\n// Find all books with \u003e= 100 likes and also get the author of each.\nawait db.select(t.author).innerJoin(\n  t.book.where(b =\u003e b.likes.gte(100)),\n  t =\u003e t.author.id.eq(t.book.authorId)\n)\n```\n\n\u0026nbsp;\n\n## What's planned?\n\nThis is a vague roadmap. Nothing here is guaranteed to be implemented soon, but they will be at some point (contributors welcome).\n\n- math operators\n- enum types\n- domain types\n- composite types\n- more geometry types\n- array-based primary key\n- `ANY` and `SOME` operators\n- transactions\n- explicit [locking](https://www.postgresql.org/docs/current/explicit-locking.html)\n- views \u0026 [materialized views](https://www.postgresql.org/docs/14/rules-materializedviews.html)\n- table [inheritance](https://www.postgresql.org/docs/current/tutorial-inheritance.html)\n- window functions\n- plugin packages\n  - these plugins can do any of:\n    - alter your schema\n    - seed your database\n    - extend the runtime API\n  - auto-loading of packages with `tusken-plugin-abc` or `@xyz/tusken-plugin-abc` naming scheme\n  - add some new commands\n    - `tusken install` (merge plugin schemas into your database)\n    - `tusken seed` (use plugins to seed your database)\n- `NOTIFY`/`LISTEN` support (just copy `pg-pubsub`?)\n- define Postgres functions with TypeScript\n- more shortcuts for common tasks\n\n## What could be improved?\n\nThis is a list of existing features that aren't perfect yet. If you find a good candidate for this list, please add it and open a PR.\n\nContributions are extra welcome in these places:\n\n- comprehensive \"playground\" example\n- subquery support is incomplete\n  - bug: selectors cannot treat single-column set queries like an array of scalars\n- type safety of comparison operators\n  - all operators are allowed, regardless of data type\n  - see `.where` methods and `is` function\n- the `jsonb` type should be generic\n  - with option to infer its subtype at build-time from current row data\n- missing SQL commands\n  - `WITH`\n  - `GROUP BY`\n  - `UPDATE`\n  - `MERGE`\n  - `USING`\n  - `HAVING`\n  - `DISTINCT ON`\n  - `INTERSECT`\n  - `CASE`\n  - etc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falloc%2Ftusken","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falloc%2Ftusken","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falloc%2Ftusken/lists"}