Better Documentation #180

Activity

1. ayrton commented on Jul 19, 2024

   

   ayrton

   on Jul 19, 2024

   Contributor

   More actions

   Thank you for your feedback.

   The docs say that we can connect to our DB with connect and Client, but they don't explain why I would want to use one over the other apart from this line

   I agree that the usage between connect and Client is confusing. Let me try to provide some insights, and hopefully some answers.

   Using a global connection can lead to data inconsistencies, because a connection is not really meant to be shared across requests. In practice this means you'll almost certainly want to use Client over the current connect.

   We have talked internally about updating the connect function to return a Client instance.

   -export function connect(config: Config): Connection {
   -  return new Connection(config)
   +export function connect(config: Config): Client {
   +  return new Client(config)
   }

   But we hadn't yet because of backwards compatibility. Often people use database-js through an ORM eg. Drizzle, Prisma. Older versions of Drizzle (<0.29.4) (and Prisma) did not accept Client instances. This has been patched since and both now enforce the usage of a Client instance (ref).

   It's been almost half a year since Drizzle started to accept Client instances - we can start considering changing the defaults now. If people want a single global connection they'd still be able to instantiate one directly.

   The Client class has a execute function but also has another function called connection which returns a Connection object, which also has an execute function. Why are there two? Are they actually the same? When do I use one over the other?

   They are not the same. By design Client#execute instantiates a new connection for every query you run. Use Client when you don't want to share any connections, use Connection when you do.

   @mattrobenolt did a deep-dive into the nuances, I highly recommend reading it if you want to get a deeper understanding. drizzle-team/drizzle-orm#1743 (comment).

   There's also no mention of pooling, which I'm not even sure matters for serverless, but I feel like it should be addressed so I'm not overloading my DB with connections.

   Database-js is made for being used within serverless environments, you don't have to worry about managing your database connections.

   Connection instances are often mistaken for database connections, maybe there's a better name for them. Quoting @mattrobenolt

   Connection instances are used to track state, they are more synonymous with a "session". One underlying TCP connection is reused, but for multiplexing over that single TCP connection, the session is required to track state.
2. PeytonHanel commented on Jul 19, 2024

   

   PeytonHanel

   on Jul 19, 2024

   Author

   More actions

   This is super helpful. Thank you so much.

   Can you speak at all to the parameterized SQL calls and how you prevent SQL injections?

   Do you think you will add an API guide to the documentation? I have no plans to use an ORM and fully intend on writing all my own SQL queries and keeping them in my codebase.

   Thank you.
3. ayrton commented on Jul 19, 2024

   

   ayrton

   on Jul 19, 2024

   Contributor

   More actions

   Can you speak at all to the parameterized SQL calls and how you prevent SQL injections?

   You can either use the built-in escaping, or use an external library, like sqlstring. String interpolation would not be safe. (Ref)

   Do you think you will add an API guide to the documentation?

   What are you looking for exactly? The API surface is pretty small and should be fully covered with the README. We do welcome any contributions to make things better.

   I have no plans to use an ORM and fully intend on writing all my own SQL queries and keeping them in my codebase.

   This is perfectly reasonable.
4. PeytonHanel commented on Jul 20, 2024

   

   PeytonHanel

   on Jul 20, 2024

   Author

   More actions

   So just to be clear, doing this is safe against SQL injections:

   const results1 = await conn.execute('select 1 from dual where 1=?', [42])
   
5. mattrobenolt commented on Jul 20, 2024

   

   mattrobenolt

   on Jul 20, 2024

   Member

   More actions

   Correct.

   👍React with 👍1Reacted by Peyton Hanel